Metadata-Version: 2.5
Name: aice-data-brain
Version: 0.2.0
Summary: Python SDK for the AICE Data Brain multi-source data connection + query layer
Author-email: Adanian Labs <engineering@adanianlabs.io>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: aice-core<0.5,>=0.3.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# aice-data-brain

Python SDK for the [Data Brain](../../../aice_packages/data_brain/) a
multi-source connection layer that preprocesses, inspects, and answers
questions over arbitrary data sources without exposing raw credentials to the
model.

```python
import os

from aice_data_brain import DataBrainClient

client = DataBrainClient(
    base_url="https://db.example.com",
    api_key="…",           # your project key
    user_id="<user uuid>",  # X-User-Id, recorded in the query log
)

# Query a database: the connection travels with every query (nothing is stored)
result = client.connections.query(
    "postgresql",
    data={"host": "db.internal", "port": 5432, "database": "analytics", "user": "reader", "password": "…"},
    query="SELECT count(*) FROM orders",
)
print(result["rows"], result["error"])  # query errors come back in `error`

# Upload a file, then query it by the table name Data Brain gave it
with open("sales.csv", "rb") as f:
    uploaded = client.files.upload("csv_v2", file=f.read(), filename="sales.csv")
details = uploaded["file_details"]
table = details[0]["tables"][0]["table_name"]
rows = client.files.query("csv_v2", details, f'SELECT * FROM "{table}" LIMIT 10')["rows"]

# Or read files in place from your own S3 bucket: nothing is uploaded or deleted
bucket = {
    "bucket": "acme-data", "region": "eu-west-1", "prefix": "exports/",
    "accessKeyId": "…", "secretAccessKey": "…",
    # "endpoint": "minio.example.com:9000"  # for S3-compatible stores; default is AWS
}
objects = client.s3.list_objects(bucket)["objects"]          # also a connection test
described = client.s3.describe(bucket, ["exports/sales.csv"])
rows = client.s3.query(bucket, described["file_details"], "SELECT count(*) AS n FROM sales")["rows"]

# Or call any HTTP API: reads and writes, by method and path
api = {
    "baseUrl": "https://api.example.com/v1",
    "auth": {"type": "bearer", "token": os.environ["SHOP_TOKEN"]},
    "allowedMethods": ["GET", "POST"],          # the only limits, agents included
    "allowedPaths": ["/orders*"],
    "pagination": {"type": "cursor", "cursorPath": "meta.next"},
}
client.rest.check(api)                          # reachable with these credentials?
orders = client.rest.request(api, "GET", "/orders", params={"status": "open"}, select="data")["rows"]
client.rest.request(api, "POST", "/orders", body={"sku": "A-1", "qty": 2})   # sent once, no undo

# Every connector and the fields its connection needs
descriptors = client.descriptors.list()
```

File connectors: `csv_v2` (csv, tsv, parquet, json, ndjson, jsonl), `excel`
(xlsx), `parquet`, `json`. `files.upload` sends the file straight to Data
Brain's storage with a form the service signs, then has it described. Each
upload gets its own key, so the same name never replaces an earlier file.

The `s3` connector reads csv/tsv, parquet, json and xlsx files from a bucket you own.
The bucket details travel with every call and Data Brain stores nothing; use a
read-only key (`s3:ListBucket`, `s3:GetObject`). Bad credentials, a wrong
region or an endpoint on a private network come back as a `ValidationError`
with a readable message. `list_objects` returns at most the service's
`S3_CONNECTOR_LIST_LIMIT` files.

The `rest_api` connector calls the API itself, so a GET returns the API's
records as rows (`select` is JMESPath; paging follows the connection's
`pagination` unless `paginate=False`). Anything other than GET, HEAD or OPTIONS
changes data immediately and is sent once, never auto-retried. `allowedMethods`
and `allowedPaths` are the only limits, for your code and for agents alike, so
use a least-privilege API credential. `auth` is `bearer`, `basic`, `header`,
`query` or `oauth2_client_credentials`; add `openapi: {"specUrl": ...}` and
`rest.inspect(api)` lists the operations a query may call. API errors come back
in `error`. Pass `connection_id=` to let Data Brain cache reads (writes drop
them).

Endpoints covered (see `data_brain/app/api/routes/`):

* `GET  /health`
* `GET  /v1/datasource-descriptors`
* `POST /v1/plugin/{connection_type}/preprocess`
* `POST /v1/plugin/{connection_type}/process`
* `POST /v1/plugin/{connection_type}/cleanup`
* `POST /v1/plugin/{connection_type}/query`
* `POST /v1/plugin/{connection_type}/inspect`
* `POST /v1/plugin/{connection_type}/uploads` (a signed form for one file)
* `POST /v1/plugin/{connection_type}/uploads/{upload_id}/complete`
