Skip to content

python: update README #415

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SprGrf merged 3 commits into from
Dec 2, 2025
Merged

python: update README #415

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b05d4b8
fix: README
SprGrf Nov 27, 2025
37529f1
fix: restructure
SprGrf Dec 1, 2025
0c523b4
fix: argument order
SprGrf Dec 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 39 additions & 30 deletions python/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,36 @@ The AICA API client module provides simple functions for interacting with the AI

Refer to https://docs.aica.tech for more information about the AICA System.

## Authentication with an API key

For connecting to AICA Core v4.3.0 and later, an API key is required for authentication.

API keys can be generated in AICA Studio with configurable access scopes. Note that available scopes are limited to
those of the currently logged-in user. A generated API key is only shown once and should be kept secret. For example, it
may be exported as an environment variable. The following example key is shown for demonstrative purposes only:

```shell
export AICA_API_KEY=64ce9e8f-aa46-4ba7-814f-f169c01c957e.RwoH6A1Ti5poNKSizoWrcBEYzh7AkB0kpMq1TR59t6os
```

The API key must then be provided to the constructor with the `api_key` keyword argument:

```python
import os
from aica_api.client import AICA

AICA_API_KEY = os.getenv('AICA_API_KEY')
aica = AICA(api_key=AICA_API_KEY)
```

## Basic usage

```python
import os
from aica_api.client import AICA

aica = AICA()
AICA_API_KEY = os.getenv('AICA_API_KEY')
aica = AICA(api_key=AICA_API_KEY)

if aica.check():
print(f"Connected to AICA Core version {aica.core_version()}")
Expand Down Expand Up @@ -57,43 +81,24 @@ conflict with reserved ports. Use the "Open in browser" button from Launcher to
the port from the url.

```python
import os
from aica_api.client import AICA

AICA_API_KEY = os.getenv('AICA_API_KEY')

# connect to a non-default port on the local network
aica = AICA(port=55000)
aica = AICA(api_key=AICA_API_KEY, url='http://localhost:55005/api')

# or connect to a different host address entirely
aica = AICA(url='192.168.0.1', port=55005)
aica = AICA(api_key=AICA_API_KEY, url='http://192.168.0.1:55005/api')
```

## Authentication with an API key

For connecting to AICA Core v4.3.0 and later, an API key is required for authentication.

API keys can be generated in AICA Studio with configurable access scopes. Note that available scopes are limited to
those of the currently logged-in user. A generated API key is only shown once and should be kept secret. For example, it
may be exported as an environment variable. The following example key is shown for demonstrative purposes only:

```shell
export AICA_API_KEY=64ce9e8f-aa46-4ba7-814f-f169c01c957e.RwoH6A1Ti5poNKSizoWrcBEYzh7AkB0kpMq1TR59t6os
```

The API key can then be provided to the constructor with the `api_key` keyword argument:

```python
import os
from aica_api.client import AICA

AICA_API_KEY = os.getenv('AICA_API_KEY')
aica = AICA(api_key=AICA_API_KEY)
```

## Compatability table
## Compatibility table

The latest version of this AICA API client will generally support the latest AICA Core version.
Major version changes to the API client or to AICA Core indicate breaking changes and are not always backwards
compatible. To interact with older versions of AICA Core, it may be necessary to install older versions of the client.
Use the following compatability table to determine which client version to use.
Use the following compatibility table to determine which client version to use.

| AICA Core version | API protocol version | Matching Python client version |
|-------------------|----------------------|--------------------------------|
Expand Down Expand Up @@ -135,12 +140,14 @@ AICA Core versions `v5` and later change some endpoints paths, methods and paylo

### Checking compatibility

Recent client versions include a `check()` method to assess the client version and API compatability.
Recent client versions include a `check()` method to assess the client version and API compatibility.

```python3
import os
from aica_api.client import AICA

aica = AICA()
AICA_API_KEY = os.getenv('AICA_API_KEY')
aica = AICA(api_key=AICA_API_KEY)

# check compatability between the client version and API version
if aica.check():
Expand All @@ -152,9 +159,11 @@ else:
The latest client versions also include the following functions to check the configuration details manually.

```python3
import os
from aica_api.client import AICA

aica = AICA()
AICA_API_KEY = os.getenv('AICA_API_KEY')
aica = AICA(api_key=AICA_API_KEY)

# get the current version of this client
print(aica.client_version())
Expand Down