SQAI — deterministic, read-only structured data

SQAI — Structured Query AI

SQAI is the deterministic, read-only structured-data tool for AI agents, with governed execution and replayable provenance.

Apache-2.0 · TypeScript + Python · built on Algenta as the underlying substrate · a Thyn product

The model proposes meaning. SQAI controls execution: typed intent in, policy-checked deterministic execution, replayable results with full provenance out. No raw SQL, no eval, no write path.

Architecture

Layer	Package	What it is
AI SDK tools	@thyn-ai/sqai-ai-sdk (npm)	Three Vercel AI SDK 7 tools — listSources, queryData, explainQuery
Product SDK	@thyn-ai/sqai (npm)	SQAI query plane + full computation plane
Product SDK	sqai (PyPI)	Same SQAI surface, 1:1 vocabulary
CLI	@thyn-ai/sqai-cli (npm, bin sqai)	sqai doctor --parity, sqai runtime install/verify/status/stop
Capability contract	Embedded SQAI contract	The generated, hash-pinned inventory of every capability SQAI exposes
Execution substrate	Algenta (exact-pinned)	Underlying deterministic execution substrate and managed signed runtime bundle

Quickstart (AI SDK)

import { generateText } from "ai";
import { createSQAI } from "@thyn-ai/sqai-ai-sdk";

const sqai = createSQAI({ sources: [{ data: "./data/sales.csv", name: "sales" }] });

const { text } = await generateText({
  model: "openai/gpt-5-mini",
  tools: sqai.tools(),
  prompt: "Which region had the highest total revenue?",
});

No server. No daemon for the query plane. The computation plane provisions a signed managed runtime transparently on first use.

MCP server

The same four governed tools are available to any MCP host (Claude Desktop, Cursor, …) as a stdio server — descriptions, Zod schemas, and execute functions are read straight off the AI-SDK tool objects, never forked:

npx @thyn-ai/sqai-mcp

{
  "mcpServers": {
    "sqai": {
      "command": "npx",
      "args": ["-y", "@thyn-ai/sqai-mcp"],
      "env": {
        "SQAI_SOURCES": "[{\"data\": \"./data/sales.csv\", \"name\": \"sales\"}]"
      }
    }
  }
}

Introspection (initialize / tools/list) needs no credentials — zero environment is a valid configuration. Executing any of the four tools requires a free community login (sqai login once / device registration, or SQAI_API_KEY) — fully offline thereafter; without it every tools/call returns a structured login_required error. SQAI_DEPLOYMENT_URL keeps its usual semantics from @thyn-ai/sqai.

Tool	What it does
listSources	Discovery: sources with exact field names, types, and allowed operations; computation-catalog search; per-module signatures.
queryData	One deterministic, read-only query or computation; truncated results stay retrievable via result_id.
explainQuery	Dry-run: resolved plan, plan_hash, validation — or a computation-signature check with a preview invocation_hash.

All three are annotated readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false. All three execute under the one uniform license gate: free on 1 machine with a one-time device registration (sqai login) — licensing moves a signed token, never your data; without it, every tool call — local CSV reads included — returns a structured login_required error by design.

What works today

• Query plane (connect / resolve / query / verify / ask) — in-process, both languages
• Full SQAI computation plane behind capability-contract validation
• Policy allow-lists (sources, fields, functions) the model can never override
• Cross-language conformance: identical values, plan_hash, intent_signature
• Model-context truncation with opaque result handles

Repository layout

contracts/        generated capability contract + tested version pair
packages/sdk/     @thyn-ai/sqai (TypeScript product SDK)
packages/ai-sdk/  @thyn-ai/sqai-ai-sdk (Vercel AI SDK tools)
packages/cli/     sqai CLI (doctor, runtime verbs)
packages/mcp/     @thyn-ai/sqai-mcp (MCP stdio server)
packages/python-sdk/  sqai (PyPI)
examples/         runnable examples (AI SDK registry example)
scripts/          contract sync + parity gate
docs/             GitBook (docs.sqai.com)

Key documents

Doc	Purpose
docs/quickstart-ts.md	TypeScript quickstart
docs/quickstart-python.md	Python quickstart
docs/ai-sdk-tools.md	Tool schemas and truncation contract
docs/determinism.md	Hashes, envelopes, "deterministic within the declared execution scope"
docs/licensing.md	Free developer tier, entitlements, runtime bundle trust
SECURITY.md	Security policy