SQAI — deterministic, read-only structured data

Name: SQAI — deterministic, read-only structured data
Author: thyn-ai

本地服务

sqai.com数据库04 周前更新

代码仓库访问官网

关于 SQAI — deterministic, read-only structured data

SQAI 是面向 AI Agent 的只读结构化数据服务，通过策略检查执行确定性查询并保留可重放的来源记录，适合需要受控数据访问且不允许原始 SQL 或写入操作的团队。

主要功能

01确定性结构化数据查询
02数据与操作的策略允许列表
03查询与计算执行
04可重放的结果来源记录
05按 ID 获取截断结果

适用场景

01让 Agent 检查获准的数据源
02执行可重复的只读数据查询
03执行前验证查询计划

MCP 相关

通过 stdio 服务向 MCP 客户端提供受策略管控的数据发现、查询与计算、查询说明工具。执行工具需要 SQAI 登录或 API 密钥。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "thyn-ai-sqai": {
      "command": "npx",
      "args": [
        "-y",
        "@thyn-ai/sqai-mcp"
      ],
      "env": {
        "SQAI_API_KEY": "<SQAI_API_KEY>",
        "SQAI_DEPLOYMENT_URL": "<SQAI_DEPLOYMENT_URL>",
        "SQAI_SOURCES": "<SQAI_SOURCES>"
      }
    }
  }
}

启动命令npx -y @thyn-ai/sqai-mcp

需要配置的环境变量

SQAI_API_KEY密钥API key for licensing / API mode (semantics owned by @thyn-ai/sqai). Introspection (initialize/tools/list) needs no credentials; executing tools requires a free community login (`sqai login` device registration) or this key — fully offline thereafter.

SQAI_DEPLOYMENT_URLPrivate deployment endpoint; selects deployment mode when present. Optional.

SQAI_SOURCESJSON array of SqaiSourceInput (path/URL string, array of row objects, or { "data": …, "name": "…" }). Sources connect lazily on the first tool call. Optional.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@thyn-ai/sqai-mcp0.1.20stdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
module	string	否	列出模块的函数及其准确签名。
capabilitySearch	string	否	搜索计算能力目录；返回匹配的模块。

详细介绍

SQAI — 结构化查询 AI

SQAI 是面向 AI Agent 的确定性只读结构化数据工具，具备受治理的执行能力和可重放的溯源信息。

Apache-2.0 · TypeScript + Python · 基于 Algenta 底层基质构建 · Thyn 产品

模型提出含义。SQAI 控制执行：输入类型化意图，经过策略检查的确定性执行，输出可重放且包含完整溯源信息的结果。不使用原始 SQL、不执行 eval，也没有写入路径。

架构

层	包	说明
AI SDK 工具	`@thyn-ai/sqai-ai-sdk` (npm)	三个 Vercel AI SDK 7 工具 — `listSources`、`queryData`、`explainQuery`
产品 SDK	`@thyn-ai/sqai` (npm)	SQAI 查询平面 + 完整计算平面
产品 SDK	`sqai` (PyPI)	相同的 SQAI 接口，词汇 1:1 对应
CLI	`@thyn-ai/sqai-cli` (npm, bin `sqai`)	`sqai doctor --parity`、`sqai runtime install/verify/status/stop`
能力契约	内嵌 SQAI 契约	SQAI 提供的所有能力的生成式、固定哈希清单
执行基质	Algenta (精确锁定版本)	底层确定性执行基质和托管签名运行时包

快速入门（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?",
});

无需服务端。查询平面无需守护进程。计算平面会在首次使用时以透明方式配置签名托管运行时。

MCP 服务

四个受治理的工具同样可作为 stdio 服务供任意 MCP 主机（Claude Desktop、 Cursor 等）使用 — 描述、Zod 架构和执行函数直接从 AI-SDK 工具对象读取，绝不分叉：

npx @thyn-ai/sqai-mcp

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

内省（initialize / tools/list）无需凭据 — 零环境变量也是有效配置。执行这四个工具中的任意一个都需要免费社区登录（执行一次 sqai login / 设备注册，或使用 SQAI_API_KEY）— 此后可完全离线；未登录时，每次 tools/call 都会返回结构化的 login_required 错误。SQAI_DEPLOYMENT_URL 保持其在 @thyn-ai/sqai 中的常规语义。

工具	功能
`listSources`	发现：列出数据源及其准确字段名称、类型和允许的操作；搜索计算目录；查看各模块签名。
`queryData`	执行一次确定性的只读查询或计算；截断的结果仍可通过 `result_id` 获取。
`explainQuery`	试运行：返回解析后的计划、`plan_hash` 和验证结果 — 或检查计算签名并预览 `invocation_hash`。

这三个工具均标注为 readOnlyHint: true、destructiveHint: false、 idempotentHint: true、openWorldHint: false。三者均受同一个统一许可证门控：在 1 台机器上免费使用，只需一次性设备注册（sqai login）— 许可证流程传输的是签名令牌，绝不传输你的数据；未注册时，每次工具调用（包括读取本地 CSV）都会按设计返回结构化的 login_required 错误。

当前可用功能

查询平面（连接 / 解析 / 查询 / 验证 / 提问）— 进程内运行，支持两种语言
经过能力契约验证的完整 SQAI 计算平面
策略允许列表（数据源、字段、函数），模型无法覆盖
跨语言一致性：值、plan_hash、intent_signature 完全相同
模型上下文截断及不透明结果句柄

仓库布局

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)

关键文档

文档	用途
docs/quickstart-ts.md	TypeScript 快速入门
docs/quickstart-python.md	Python 快速入门
docs/ai-sdk-tools.md	工具架构和截断契约
docs/determinism.md	哈希、信封、“在声明的执行范围内具有确定性”
docs/licensing.md	免费开发者层级、授权权益、运行时包信任
SECURITY.md	安全策略