Metadata-Version: 2.4
Name: aitoai
Version: 1.2.0
Summary: Aito.ai Python SDK
Home-page: https://github.com/AitoDotAI/aito-python-tools
Author: aito.ai
Author-email: admin@aito.ai
Project-URL: Documentation, https://aito.ai/docs/api/v2/python-sdk/
Project-URL: Source, https://github.com/AitoDotAI/aito-python-tools
Project-URL: Tracker, https://github.com/AitoDotAI/aito-python-tools/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX
Classifier: Operating System :: POSIX :: BSD
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: requests<4,>=2.22
Requires-Dist: packaging>=21.0
Requires-Dist: aiohttp<4.0,>=3.6.1
Requires-Dist: ndjson>=0.2.0
Requires-Dist: jsonschema<5,>=3
Provides-Extra: cli
Requires-Dist: pandas~=2.0; extra == "cli"
Requires-Dist: langdetect<2.0,>=1.0.7; extra == "cli"
Requires-Dist: argcomplete<4.0,>=1.11.1; extra == "cli"
Requires-Dist: xlrd<3.0,>=1.1; extra == "cli"
Requires-Dist: openpyxl>=3.0.7; extra == "cli"
Requires-Dist: fastparquet>=0.8; extra == "cli"
Provides-Extra: mcp
Requires-Dist: mcp>=1.10; python_version >= "3.10" and extra == "mcp"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

Aito Python SDK
===============

:Info: Check `Github <https://github.com/AitoDotAI/aito-python-tools>`_ for the latest source code and `documentation <https://aito-python-sdk.readthedocs.io/en/latest/>`__ 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 <https://aito.ai/>`_ quicker and more efficiently.

The SDK also includes the `Aito Command Line Interface (CLI) <https://aito-python-sdk.readthedocs.io/en/latest/cli.html>`_ 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:

  .. code-block:: python

    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]'``.

Run Aito locally
----------------

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

  .. code-block:: console

    $ 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``.

  .. code-block:: console

    $ 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
<https://aito.ai/docs/articles/use-aito-from-claude-code-and-other-ai-assistants/>`__. When Aito
fits and when not: `When to use Aito, and when not
<https://aito.ai/docs/articles/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 <https://aito.ai/join-slack/>`__.

Installation
------------

Aito Python SDK can be installed with `pip <http://pypi.python.org/pypi/pip>`_

  .. code-block:: console

    $ pip install aitoai

Check our `installation guide <https://aito-python-sdk.readthedocs.io/en/latest/install.html>`_ for more information

Documentation
-------------

You will need `sphinx <https://www.sphinx-doc.org/en/master/>`_ installed to generate the documentation.

    $ pip install sphinx
    $ pip install sphinx_rtd_theme

Documentation can be generated by:

  .. code-block:: console

    $ 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:

  .. code-block:: console

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

You can use our test cli to run tests:

  .. code-block:: console

    $ python -m tests -h

.. note::

  Some tests require some environment variables to be setup. Use the test CLI list command to discover and display the test suites and cases

There are multiple test suites:

1. CLI suite:

  .. code-block:: console

    $ python -m tests -v suite cli

  .. note::

    You need an Aito instance and set up the credentials with ```AITO_INSTANCE_URL``` and ```AITO_API_KEY``` to test some functions.

2. SDK suite:

  .. code-block:: console

    $ python -m tests -v suite sdk

  .. note::

    You need an Aito instance and set up the credentials with ```AITO_INSTANCE_URL``` and ```AITO_API_KEY``` to test some functions

3. SQL functions tests:

  - Test against Postgres:

    .. code-block:: console

        $ 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:

    .. code-block:: console

      $ python -m tests -v case sql_functions.test_connection.TestMySQLConnection
      $ python -m tests -v case sql_functions.test_cli_sql_functions.TestMySQLFunctions

  .. note::

    To test the SQL functions, you need to install `pyodbc <https://pypi.org/project/pyodbc/>`_ and the specific database ODBC driver.

4. Build and test built package:

  - To build the package:

    .. code-block:: console

        $ 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:

    .. code-block:: console

        $ pip install dist/aitoai-<version>.whl

  - To test the built package, create an environment variable ```TEST_BUILT_PACKAGE``` and run the above tests

5. Test the documentation:

  - To test the inline documentation:

    .. code-block:: console

      $ python -m tests -v suite inline_docs

  - To test the code blocks in rst files:

    .. code-block:: console

      $ 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)

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

.. note::

  Remember to update the `autodoc_mock_imports` in conf.py file if there are additional requirements

5. Update the version in aito/__init__ to e.g. '1.2.3rc1' and write release notes in docs/changelog.rst
6. Check CircleCI and issue a PR
7. Deploy to production (scripts/deploy) with the appropriate version after the PR is reviewed


.. |PyPI| image:: https://img.shields.io/pypi/v/aitoai?style=plastic
  :target: https://pypi.org/project/aitoai/
.. |PyPI version| image:: https://img.shields.io/pypi/pyversions/aitoai?style=plastic
  :target: https://github.com/AitoDotAI/aito-python-tools
