@aid-framework/spec

语言 AID 框架JSON斯克马,一个 位置意识 YAML 解析器和结构验证器。 此软件包决定文档是否 是一个 结构良好 AID谱.

一个 AID 应用程序从一个声明的 YAML 文件开始 。 那个文件是真相的来源:模型,提示, 工具、检索、代理、输油管和电压被宣布一次,下游的一切——IR、代码 发电机,运行时间——就是从它衍生出来的.

specVersion: "0.1"
project:
  name: support-copilot

models:
  fast:
    provider: openai-compatible
    model: gpt-4o-2024-08-06
    capabilities: [tool-calling, json-schema]

prompts:
  answer:
    template: |
      Answer the customer's question.
      Question: {{ question }}

pipelines:
  answer:
    steps:
      - generate:
          model: fast
          prompt: answer
          input:
            question: "{{ request.question }}"

安装

npm install @aid-framework/spec

要求节点.js 24或更新. 与类型脚本申报一起作为无害环境管理运输.

它会做什么

• 参数 YAML 输入一个键入文档,可以记住每个节点来自何处,因此一个诊断可以指向 file:line:column 而不是只命名一个密钥.
• 验证 用于编辑器自动完成的 Spec v0.1 JSON Schema 文档 和CI验证.
• 讲述版本的真相. 定义语言的构造,但无法使用此构造报告为 spec/not-supported 命名可以使用的版本——绝不是像打字一样读取的通用图案失败.

快开始

import { checkSpecText, formatDiagnostics } from '@aid-framework/spec';

const { ok, diagnostics } = checkSpecText(source, { file: 'app/app.spec.yaml' });

if (!ok) {
  process.stderr.write(formatDiagnostics(diagnostics));
  process.exit(1);
}

checkSpecText 一步一步分析并验证. 故意短路:当YAML本身不能 解析、语义验证被跳过, 因为关于半解析文档的语义信息是噪音 .

向下工作一层 :

import { parseSpecDocument, validateSpec, formatDiagnostics } from '@aid-framework/spec';

const parsed = parseSpecDocument(source, { file: 'app/app.spec.yaml' });
const diagnostics = [
  ...parsed.diagnostics,
  ...validateSpec(parsed.value, { file: 'app/app.spec.yaml' }),
];

文件

构建读取 spec 版本 0.1 结束 0.9。列出为 0.2 在一个0.1文件中被拒绝, 并有一个诊断 命名接受它的版本. deployments[].image 是一个0.4的构造和需求 target: container两种规则均在 deployments.<id>.image。 。 。 . guardrails[].decision 为 0.7 构造:它用 choice 决定而不是探测器政策,被拒绝 在较早的文件中。 A 类 decision eval 度量衡是一个0.8的构造:它用一个 已声明 score ,并在先前的文件中被驳回。 这个 route 步骤是一个0.9的构造: 从一个 choice 裁决的答复,并在先前的文件中被驳回.

管道步骤类型

管道步骤包含完全一种步骤。 验证人执行十二:

generate, (中文(简体) ), retrieve, (中文(简体) ), tool, (中文(简体) ), emit, (中文(简体) ), branch, (中文(简体) ), route, (中文(简体) ), parallel, (中文(简体) ), map, (中文(简体) ), reduce, (中文(简体) ), rerank, (中文(简体) ), guard, (中文(简体) ), agent。 。 。 .

branch, (中文(简体) ), route, (中文(简体) ), parallel, (中文(简体) ), map 财务报告和审定财务报表 reduce 它们是复合型——唯一可能搭起另一步骤的种类——和 入巢为界. emit 可能不会出现在复合步骤中,因为它会终止管道. branch 在认证的呼叫器上选择; route 通过询问 a 选择数据 choice 决定和决定 将答案匹配到 on。 。 。 .

本建筑中不推迟任何步骤类型. human 曾经 退休人员 而不是推迟: 人行即止是 代理人的财产(agents[].humanInTheLoop)),故旧拼法产生诊断性命名 替换“未知密钥”.

诊断

诊断是公共合同,而不是执行细节。 每个代码在 DIAGNOSTIC_CODES 被指称为 测试套件,由 aid validate,所以它是安全的匹配 在CI。 改头换面是一个突破性的变化.

import {
  countBySeverity, formatDiagnostics, hasErrors, sortDiagnostics,
} from '@aid-framework/spec';

const { ok, diagnostics } = checkSpecText(source, { file: 'app/app.spec.yaml' });
const failing = hasErrors(diagnostics); // only error severity fails a check; warnings do not
const counts = countBySeverity(diagnostics);

代码被命名为空格 spec/*有两个值得召唤,因为它们很容易交错:

• spec/not-supported ——语言定义了这个构造,但这个构造还没有服务它. 讯息 命名该版本.
• spec/unknown-key - 这把钥匙没有定义 几乎总是一个打字.

让他们保持区别是刻意的:一个“不支持”关于拼错的密钥的信息会让读者知道 寻找不存在的缺失特性.

杰森·斯克马

Schema是包导出,所以编辑器和外部工具使用验证器使用的同一种:

{
  "yaml.schemas": {
    "./node_modules/@aid-framework/spec/dist/schema/spec.schema.json": "app.spec.yaml"
  }
}

import schema from '@aid-framework/spec/spec.schema.json' with { type: 'json' };

此软件包没有做什么

它孤立地验证了一份文件。 它执行 没有 跨部门分析:无优惠完整性,无 能力谈判,没有费用 理智,没有安全检查。 他们需要看整个节目 所以他们住在 建造时的大门 @aid-framework/ir。 。 。 .

层为单向 : spec ← ir ← generator-sdk ← generators ← cli。这里没有导入以上包 这个.

API 密码

许可证

阿帕奇 - 2.0。由 AID 框架生成的代码是 不受该许可证的限制.