Metadata-Version: 2.4
Name: sqai
Version: 0.1.2
Summary: SQAI — the deterministic, read-only structured-data SDK for AI agents, powered by Algenta execution and provenance.
Project-URL: Homepage, https://sqai.com
Project-URL: Repository, https://github.com/thyn-ai/sqai
Author-email: Thyn <eng@thyn.ai>
License-Expression: Apache-2.0
Keywords: agents,ai,algenta,deterministic,read-only,sqai,structured-data
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: algenta-core==1.0.6
Description-Content-Type: text/markdown

# sqai

SQAI — the deterministic, read-only structured-data SDK for AI agents, powered by
Algenta execution and provenance. Python twin of [`@thyn-ai/sqai`](https://github.com/thyn-ai/sqai):
same vocabulary, same error codes, same golden numbers, cross-language-identical hashes.

```python
from sqai import create_sqai

sq = create_sqai()  # zero-config: SQAI_ENGINE_URL -> self_hosted, SQAI_API_KEY -> api, else local
sq.connect(orders, name="orders")

outcome = sq.ask({"metric": "revenue", "aggregation": "sum", "group_by": "region",
                  "source_name": "orders"})

result = sq.compute(module="stats", function="median", args=[[1.0, 2.0, 3.0], 3])
print(result["value"], result["invocation_hash"], result["computation_hash"])
```

- **Query plane** — `connect` / `resolve` / `query` / `verify` / `ask`, in-process via Algenta.
- **Computation plane** — validated against the embedded capability contract, delegated to
  the managed runtime; results pass through verbatim with a two-hash determinism envelope
  (`invocation_hash` before execution, `computation_hash` after).
- **Policy** — allow-lists for sources, fields, and functions; the default surface is
  read-only deterministic capabilities, and policy can only narrow it.
- **Errors** — Algenta codes pass through verbatim (`source="algenta"`); SQAI codes share the
  same snake_case vocabulary (`source="sqai"`). Messages never leak absolute paths.

The unsafe escape hatch (`from sqai.unsafe import get_unsafe_algenta_runtime`) bypasses every
guarantee above and is deliberately not exported from the package root.

Apache-2.0.
