Skip to main content

Aito Python SDK

Info:

Check Github for the latest source code and documentation for more information.

Maintainer:

Aito <admin@aito.ai>

PyPI PyPI version

About

The Aito Python SDK is an open-source library that helps you to integrate your Python application to Aito quicker and more efficiently.

The SDK also includes the Aito Command Line Interface (CLI) that enables you to interact with Aito using commands in your command-line shell, e.g: infer a table schema from a file or upload a file to Aito.

API versions

Each Aito API version has its own package, whose meaning never changes:

from aito.v2 import Client      # the v2 API  (`from aito.v1 import Client` for v1)

# the public read-only sandbox; use your own instance URL and key in production
client = Client('https://shared.aito.ai/db/aito-demo',
                'yg4rTlXkqDzm4y8gPeY75HCKaNwfbTQ2si64ONTi', env='v2')
prediction = client.predict(
    from_table='invoices', where={'Description': 'cloud services'}, predict='GLCode')
print(prediction.first.value, prediction.first.probability)   # E002 0.83...

aito.Client is the default version, and moves only on a major release of this package: since aitoai 1.0 it is the v2 client (0.x: v1). Quickstarts can use it; production code should import the version it means, aito.v1 or aito.v2, so an upgrade cannot change the API underneath it. To stay on v1: from aito.v1 import Client, or pin aitoai<1.

The pre-0.7 paths (aito.client, aito.client.v2, aito.api) were removed in 1.0; importing one raises an ImportError naming its replacement. The command-line tool still talks to the v1 API in 1.x: v2 support arrives as an opt-in in a 1.x minor release, and the CLI’s default moves to v2 only in 2.0. The design is written up in docs/versioned-namespaces.md.

pip install aitoai installs the API clients. The command-line tool, schema inference and file conversion need the dataframe toolchain: pip install 'aitoai[cli]'.

Errors and retries

A v2 error is an AitoV2Error with the server’s code and status_code; branch on those, not on the message. is_not_found is a missing table or collection.

The client repeats a request only when that is safe, waiting the server’s Retry-After plus jitter:

  • 409 write.contention: a write that lost to concurrent writes on the same table and committed nothing. Up to 3 retries (write_contention_retries=; 0 turns it off). Other 409s are never repeated.

  • 429: the server was busy and turned the request away. Up to 3 retries, and at most 60 s of waiting for one request (rate_limit_retries=; 0 turns it off).

It does not repeat a job’s status or result (a stored result does not change: submit the job again), or a 503: a write answered 503 may or may not have been applied, so read before repeating it. With the retries off, or after the last one, err.is_retryable says whether repeating the same request later is safe:

from aito.v2 import Client, AitoV2Error

client = Client(url, key, rate_limit_retries=0)   # this caller queues its own retries
try:
    prediction = client.predict(from_table='invoices', where=invoice, predict='GLCode')
except AitoV2Error as err:
    if not err.is_retryable:
        raise
    queue_for_later(invoice)

Transient failures (a 502, 503 or 504, a dropped connection, a timeout) are retried only if you opt in, and only for requests that change nothing: reads, queries and optimize, never a write: a batch insert sent twice stores its rows twice. The exception is an upsert into a collection with a primary key, create_collection(name, columns, primary_key='id') and then upload_entries(name, rows, on_conflict='update'): it lands once however often it’s sent, so it’s retried too. Client(url, key, retries=3, backoff=0.5) waits up to backoff * 2**n seconds before retry n. The default is retries=0. What each client does on each failure, and how to resume a failed upload: docs/client-resilience.md.

Run Aito locally

With Docker installed, aito start runs a local Aito and stores its keys, so the client needs no arguments:

$ pip install aitoai
$ aito start          # pulls a pinned image, listens on http://127.0.0.1:9005, prints the keys
$ python -c "import aito; print(aito.Client().get_schema())"

aito stop stops it (data and keys are kept), aito status checks it, aito keys prints the keys again (--rotate replaces them), aito logs shows its log and aito upgrade moves to the engine version this package pins. These work without the [cli] extra. From Python, aito.Client() with no arguments uses AITO_URL and AITO_API_KEY if set, else the local server’s profile.

examples/v2_quickstart.py is a runnable end-to-end example that creates a collection, loads it, predicts, explains, evaluates and drops it again.

Use Aito from an AI assistant (MCP)

pip install 'aitoai[mcp]' (Python 3.10+) adds aito-mcp, an MCP server for coding agents and assistants. Its tools are predict, recommend, relate, match, search, query, evaluate and schema/upload. Each tool’s description says when Aito fits and when another tool (a language model, a trained model, a search engine) is the better choice. Results carry $p and a flattened $why. The server finds the instance the same way as aito.Client(). It is read-only unless started with AITO_MCP_ALLOW_WRITES=1.

$ claude mcp add aito -- aito-mcp      # Claude Code; any MCP client runs `aito-mcp` over stdio

Setup for Claude Code and other assistants: Use Aito from Claude Code and other AI assistants. When Aito fits and when not: When to use Aito, and when not.

claude-plugin/ is a Claude Code plugin with this server and a skill, add-predictive-feature. The skill walks an agent through a fit check, a schema from an existing table, a first prediction, a threshold chosen with _evaluate, and act / assist / abstain wiring.

Support / Feedback

For issues with, questions about, or feedback, please join our support channels.

Installation

Aito Python SDK can be installed with pip

$ pip install aitoai

Check our installation guide for more information

Documentation

You will need sphinx installed to generate the documentation.

$ pip install sphinx $ pip install sphinx_rtd_theme

Documentation can be generated by:

$ cd docs
$ make clean html

Generated documentation can be found in the docs/build/html/* directory.

Dependencies:

The Python SDK SQL integration and the tests depend on the ODBC db drivers and the postgres and mysql functionality.

The main drivers can be installed in Debian based Linuxes with:

` sudo apt install unixodbc-dev odbc-postgresql postgresql-client default-mysql-client pip install pyodbc `

You can find more information about installing the MySQL ODBC drivers [here](https://dev.mysql.com/doc/connector-odbc/en/connector-odbc-installation.html)

Also note: that the database integration tests require local postgres / mySQL servers.

Environment:

To run the test, you need to have the following environment variables defined:

  • AITO_GROCERY_DEMO_INSTANCE_URL

  • AITO_GROCERY_DEMO_API_KEY

  • AITO_INSTANCE_URL

  • AITO_API_KEY

Testing

Install the required packages:

$ pip install -r requirements/build.txt
$ pip install -r requirements/test.txt

You can use our test cli to run tests:

$ python -m tests -h

The live tests run against a local Aito loaded with a fixture they own (tests/fixtures/grocery), as CI does. Run one with your own test keys, load the fixture, and point the variables at it:

$ docker run -d -p 127.0.0.1:9005:9005 -e READ_WRITE_APIKEY=<rw-test-key> -e APIKEY=<ro-test-key> \
    ghcr.io/aitohq/aito:v2.12.0
$ export AITO_INSTANCE_URL=http://localhost:9005 AITO_API_KEY=<rw-test-key>
$ export AITO_GROCERY_DEMO_INSTANCE_URL=$AITO_INSTANCE_URL AITO_GROCERY_DEMO_API_KEY=<rw-test-key>
$ python tests/fixtures/grocery/seed.py

The seed replaces the database’s schema, so it refuses any host but localhost. A local engine has no S3, so the file-upload tests take the batch fallback there; the S3 path itself runs against a cloud instance in CI’s release-branch smoke. AITO_SKIP_LIVE_TESTS=1 skips the live tests when no instance is set, as the Windows CI job does.

There are multiple test suites:

  1. CLI suite:

$ python -m tests -v suite cli
  1. SDK suite:

$ python -m tests -v suite sdk
  1. SQL functions tests:

  • Test against Postgres:

    $ python -m tests -v case sql_functions.test_connection.TestPostgresConnection
    $ python -m tests -v case sql_functions.test_cli_sql_functions.TestPostgresFunctions
  • Test against MySQL:

    $ python -m tests -v case sql_functions.test_connection.TestMySQLConnection
    $ python -m tests -v case sql_functions.test_cli_sql_functions.TestMySQLFunctions
  1. Build and test built package:

  • To build the package:

    $ pip install -r requirements/deploy.txt
    $ ./scripts/deploy test.pypi --no-publish -b dev

    WARNING: This will update the version in ‘aito/__init__’ file. DO NOT commit this to Git!

  • The built wheel should be at `dist/`. To install:

    $ pip install dist/aitoai-<version>.whl
  • To test the built package, create an environment variable `TEST_BUILT_PACKAGE` and run the above tests

  1. Test the documentation:

  • To test the inline documentation:

    $ python -m tests -v suite inline_docs
  • To test the code blocks in rst files:

    $ cd docs
    $ curl -o reddit_sample.csv https://raw.githubusercontent.com/AitoDotAI/kickstart/master/reddit_sample.csv
    $ export SPHINX_DISABLE_MOCK_REQUIREMENTS=TRUE
    $ make doctest

Contributing

  1. Making changes

  2. Add unittest to the appropriate test suite (e.g: test case for Aito Schema: tests/sdk/test_aito_schema.py) or create a new test suite inside the tests folder

  3. Add documentation:

  • Inline documentation if applicable

  • Update .rst file in docs/source folder (e.g: Add a new Client function to docs/source/sdk.rst)

  1. Add inline doc test if applicable (e.g: inline doc test for Aito Client: tests/inline_docs/test_client_inline_docs.py)

  1. Update the version in aito/__init__ to e.g. ‘1.2.3rc1’ and write release notes in docs/changelog.rst

  2. Check CircleCI and issue a PR

  3. Deploy to production (scripts/deploy) with the appropriate version after the PR is reviewed

Metadata

Release files for aitoai 1.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aitoai 1.3.0
File Size Uploaded Provenance Actions
aitoai-1.3.0.tar.gz 122.6 kB With provenance Details for aitoai-1.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aitoai 1.3.0
File Interpreter ABI Platform Actions
aitoai-1.3.0-py3-none-any.whl Python 3 none any Details for aitoai-1.3.0-py3-none-any.whl

Total release size: 259.2 kB

Release files / aitoai-1.3.0.tar.gz

Download URL aitoai-1.3.0.tar.gz
Size 122.6 kB
Tags Source
SHA-256 checksum
How to use checksums
b91111a196c98074f01835302aca5c925978e44ad938d89e0b9b61f66d6d9f36
BLAKE2b-256 checksum
How to use checksums
2d4da44c500bbd5c9402a0bbe5685bc736294b0dc58ad858433eadbda6634e57
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.

Transparency log

Release files / aitoai-1.3.0-py3-none-any.whl

Download URL aitoai-1.3.0-py3-none-any.whl
Size 136.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4dd65a597b796c141f9458b20437383624674da1d50e26542608c5ba4af4e2bb
BLAKE2b-256 checksum
How to use checksums
e47bb05d0f20d9320d235950dc764c3ee6f3c9305fcffcfc4922530b696b2423
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.

Transparency log

Security for aitoai 1.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for aitoai-1.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.3.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page