Metadata-Version: 2.4
Name: sqai
Version: 0.1.4
Summary: SQAI (Structured Query AI) — the deterministic, read-only structured-data SDK for AI agents, with full 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
Requires-Dist: grpcio>=1.60
Requires-Dist: protobuf>=4
Description-Content-Type: text/markdown

# sqai

**SQAI (Structured Query AI)** — the deterministic, read-only structured-data SDK for AI
agents, with full provenance. Python twin of [`@thyn-ai/sqai`](https://github.com/thyn-ai/sqai):
same vocabulary, same error codes, same golden numbers, **byte-identical cross-language 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("sales.csv", name="sales")

# Query plane — in-process, no key
outcome = sq.ask({"metric": "revenue", "aggregation": "sum",
                  "group_by": "region", "source_name": "sales"})

# Compute plane — one of 4,778 read-only capabilities; same value + hashes as TypeScript
result = sq.compute(module="finance", function="npv", args=[0.1, [-1000, 300, 420, 560, 680]])
print(result["value"], result["computation_hash"])
# 505.020148896933 b74f67d0d7a594aa7ac91f6291612452aa8ccdf603351ebc8d801a6fddd91bc8
```

- **Query plane** — `connect` / `resolve` / `query` / `verify` / `ask`, in-process, no daemon or key.
- **Compute plane** — validated against the embedded capability contract, dispatched to the
  managed runtime (it provisions once, then stays warm — no per-query cold start); results pass
  through verbatim with a determinism envelope (`invocation_hash` before execution,
  `computation_hash` after).
- **Policy** — allow-lists for sources, fields, and functions; the surface is read-only
  deterministic capabilities, and policy can only narrow it.
- **Errors** — engine codes pass through verbatim (`source="engine"`); 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_runtime`) bypasses every guarantee
above and is deliberately not exported from the package root.

Apache-2.0.
