Algenta 是一套用于构建 AI 应用的自托管基础组件，本仓库提供其 Python 和 TypeScript 客户端库以及官方 MCP 服务器。这些 SDK 是 Python 和 TypeScript 调用 Algenta 引擎的方式，提供对受治理数据查询、蒙特卡洛模拟与推荐、带执行凭证的决策记忆、带人工审批的智能体运行、托管连接器以及完整审计追踪的类型化访问。这些能力由引擎强制执行，而非依赖客户端约定。
主要能力：引擎的计算内核（模拟、评分、本地查询执行）以 Mojo 编写并专有，通过签名后的 algenta-runtime-native wheel 分发，不在本仓库中。6000 多个确定性函数位于自定义 Mojo 内核之上，统一在一个 API、SDK 和 MCP 接口之后。决策记忆会以执行凭证固定每次运行所依据的策略和模式快照，智能体运行支持人在回路审批。
使用方式：MCP 服务器位于本仓库 packages/mcp/ 目录（实现为 packages/mcp/algenta_mcp，默认 stdio 传输，可选 Streamable HTTP）。可通过 pip install algenta-mcp 安装并运行 algenta-mcp 命令，也在官方 MCP Registry 上以 io.github.thyn-ai/algenta 注册。内省（initialize / tools/list）无需凭据；执行工具需要免费社区登录——在 algenta.ai 进行设备注册（免费），运行 algenta login，或在 https://app.algenta.ai/dashboard/api-keys 创建密钥，然后设置 ALGENTA_API_KEY。两个客户端都从环境变量读取 ALGENTA_API_KEY，默认指向托管 API https://api.algenta.ai。自托管引擎可指向自己的部署：Python 使用 AlgentaClient(base_url="http://localhost:8000")，TypeScript 使用 new AlgentaClient({ baseUrl: "http://localhost:8000" })，并使用运营方提供的 API 密钥。self_hosted 和 air_gapped 部署配置会失败关闭，绝不静默回退到 Algenta 云端。框架集成（LangChain、LlamaIndex、Vercel AI SDK 等）位于配套仓库 thyn-ai/algenta-integrations，采取自托管优先的默认策略，从 ALGENTA_BASE_URL 或显式 base_url 解析端点，不默认或回退到托管 API。完整 API 面（受治理查询、连接器、模拟、作业、触发器、智能体运行、决策、仓库智能以及 TypeScript 本地 Runtime 门面）记录在 packages/python-sdk/README.md 和 packages/ts-sdk/README.md 中，可运行项目位于 examples/。
错误处理：两个 SDK 抛出相同的异常分类，每个错误携带 HTTP 状态、引擎可读的 error_code，Python 中还有引擎分配的 request_id；验证失败额外通过 field_errors（Python）/ fieldErrors（TypeScript）暴露逐字段细节。瞬时网络错误按与 5xx 响应相同的策略重试；Python SDK 额外永不重试某个速率限制码 inline_preview_rate_limited。
命名兼容：SDK 在历史中曾更名。PyPI 包为 algenta-sdk，但可导入模块仍为 decision_engine：from decision_engine import AlgentaClient。CodnaClient（及 Python 的 AsyncCodnaClient）仍作为 AlgentaClient 的别名导出。环境变量 DE_API_KEY、DE_BASE_URL 和 ALGENTA_API_URL 仍与规范名称 ALGENTA_API_KEY 和 ALGENTA_BASE_URL 一同接受。已发布 API 契约保证任何旧名称移除前有 90 天弃用窗口（DEPRECATION_WINDOW_DAYS）。
开放性：本仓库包含 Algenta 的 Python 和 TypeScript 客户端 SDK 以及官方 MCP 服务器（packages/mcp/），采用 Apache-2.0 许可。Algenta 引擎本身闭源，不在本仓库中；引擎许可、设备权利、工作线程限制、并发限制和 Server Compute Units 由引擎独立强制执行，受单独的 Algenta Engine 许可约束。SDK 是纯 HTTP 客户端，不持有许可签名密钥、无权利执行逻辑，也不与引擎共享秘密；修改或替换 SDK 不会改变许可给 Algenta 引擎的执行容量。Algenta 执行不要求托管推理或遥测；付费许可扩展本地执行与治理容量，而非按 SDK 调用收费。
版本与发布验证：每个由 release.yml 构建的发布都与受保护的 sdk-vX.Y.Z 源代码标签、该标签指向的确切提交，以及引擎测试套件验证该提交后由内部发布流水线签名的发布授权记录绑定。release.yml 除非上述全部独立一致，否则拒绝构建或发布。自 2026 年 9 月加入签名以来，每个 GitHub Release 除 wheel、sdist 和 release-manifest.json 外，还携带每个资产的无密钥 Sigstore 签名包（<asset>.sigstore.json），由 release.yml 运行本身签名，以及覆盖全部三个资产的 SLSA 构建来源（multiple.intoto.jsonl）。通过 release.yml 的 workflow_dispatch 路径发布的版本从分派分支签名，其证书身份以 @refs/heads/main 结尾而非标签。
版本管理：两个包共享一个版本号，因为它们封装同一份 API 契约，并遵循语义化版本：补丁版为缺陷修复和文档，无 API 面变化；次版本为向后兼容新增（新方法、新可选字段）；主版本为对导出符号、必需字段或行为的破坏性变更，通过上述弃用窗口提前公告。发布历史在 CHANGELOG.md 中。
适用场景：适合需要在自有基础设施上构建具备治理数据查询、决策记忆、模拟推荐和带审批智能体运行的 AI 应用的团队。限制：引擎闭源且专有；执行工具需要免费社区登录与 API 密钥；执行容量受引擎许可约束；付费许可的具体收费、价格信息暂未提供；自托管与气隙部署的配置细节暂未提供。
