@aid-framework/ir

中间代表 AID 框架: 一个 规范化,堆栈独立,版本化的应用程序形式,每个代码生成器都使用.

发电机从不读字 此软件包解决 spec 一次 进入一个IR, 所以一个Python目标和一个 TypeScript 目标正在查看相同的程序——相同的名称,相同的默认,相同的解析 参考文献.

spec.yaml ──buildIR──▶ IR ──runGates──▶ buildable ──▶ generator plan ──▶ code

安装

npm install @aid-framework/ir

要求节点.js 24或更新. 仅取决于 @aid-framework/spec。 。 。 .

快开始

import { checkSpecText, formatDiagnostics } from '@aid-framework/spec';
import { buildIR, runGates, serializeIR } from '@aid-framework/ir';

const checked = checkSpecText(source, { file: 'app/app.spec.yaml' });
if (!checked.ok) throw new Error(formatDiagnostics(checked.diagnostics));

const built = buildIR(checked.value, { file: 'app/app.spec.yaml' });
if (built.diagnostics.some((d) => d.severity === 'error')) {
  throw new Error(formatDiagnostics(built.diagnostics));
}

const gates = runGates(built.ir, { file: 'app/app.spec.yaml' });
if (!gates.ok) throw new Error(formatDiagnostics(gates.diagnostics));

const canonical = serializeIR(built.ir);

buildIR 急切地解决每一个类型、模型、迅速和工具参考,实现每一个默认,并产生 每一个稳定的身份都来自身份而不是内容——所以编辑一个提示不会重新编号一个无关的 输油管.

爱尔兰

IR_VERSION 实值 "0.1.0"。 。 。 . specVersion 所以消费者总是能分辨 光谱修正产生了IR. 两者是独立的:两者都不意味着另一方.

一个IR总是携带所有20个顶级密钥,即使一个收藏是空的:

irVersion, specVersion, project, types, models, prompts, tools, retrievers, embeddings,
stores, memory, agents, pipelines, evals, guardrails, decisions, deployments,
observability, runtime, requiredCapabilities

空藏是契约

这里的空数组不是“ 丢失” —— 而是声明 。 藏品是现成的,是计划要求的 即使是空的,所以以后的版本也可以在不碰一个消费者的情况下填写一个:

• agents, (中文(简体) ), guardrails, (中文(简体) ), memory, (中文(简体) ), deployments, (中文(简体) ), decisions ——由 spec 语言声明但被本文件未使用.
• embeddings - 完全没有谱分 一个 spec 宣告嵌入能力通过给出模型 embeddings 能力,并指向一个检索器 它,所以这个收藏 来源 从内容。 空意味着 应用程序没有嵌入.

observability 财务报告和审定财务报表 runtime 是带有默认而非数组的物体: 跟踪和运行时间描述符 命名纯同步控制流.

建造时间的大门

盖茨在发出单一字节代码之前,决定一个IR是否可以被构建. 有十六个,一个跑 报告 runGates。它们都发出诊断,而不是扔出, 以同样的编译器风格形状 @aid-framework/spec,所以一个用户会得到一个报告,无论哪个层拒绝输入.

禁忌是明确的. 检查此建筑是否真的无法执行 suppressed 有说明的 而不是被悄悄地跳过,因为跳出支票和过路支票看起来都是一样的 外边.

能力设置闸门检查来自IR本身的内容并写回到 requiredCapabilities,所以生成器读取的值是实际检查的值:

const result = runGates(ir, {
  targetCapabilities: {
    'py-fastapi': ['http-trigger', 'json-schema', 'otel'],
  },
});

result.ok;         // false when any gate emitted an error
result.byGate;     // per-gate diagnostics
result.suppressed; // what was not enforced, and why

政策Expr

工具认证策略以小表达式语言写出. 这个包裹把他们分为一个简单的JSON AST,所以 aST可以活在IR中,序列化地将神话化,并被任何目标用任何语言评价.

or         := and ('or' and)*
and        := comparison ('and' comparison)*
comparison := unary (('==' | '!=' | '<' | '<=' | '>' | '>=') unary)?
unary      := 'not' unary | primary
primary    := 'true' | 'false' | builtin '(' args ')' | '(' or ')'
builtin    := hasRole | hasScope | isAuthenticated

import { parsePolicyExpr, formatPolicyExpr } from '@aid-framework/ir';

const parsed = parsePolicyExpr("hasRole('admin') or hasScope('tickets:write')");
if (parsed.ok) console.log(formatPolicyExpr(parsed.value));

解析是一个总函数:它返回 AST 或定位诊断,从不丢弃例外. 此语法之外的任何事物都是验证错误,包括未知的内建. 这是失败的封闭规则—— 无法评估的运行时间政策绝不能被视为 true。 。 。 .

Eval上游使用具有相同属性的伴生语法(parsePredicateExpr, (中文(简体) ), PREDICATE_BUILTINS),这样 大门条件与认证政策一样严格.

条形序列化

serializeIR 所以再生是可复制的 金色文件是稳定的:

• 对象键排序, LF 结尾, 双相距缩进, 正好是一条正后方的新行;
• 没有 NaN, (中文(简体) ), Infinity 或者说 undefined; 缺漏字段而不是写入为 null· ;
• 保留了数组顺序,因为数组的顺序是有意义的,对象的顺序不是.

两种仅以按键顺序或白空相差的文档因此产生字节-等同的IR.

模型目录

该目录是模型定价和限值的构建时间的真理来源,用于 cost 财务报告和审定财务报表 normalize 大门.

import {
  CATALOG_VERSION, catalogCostProfile, catalogCostProfiles, catalogModel,
} from '@aid-framework/ir';

目录 JSON 也导出为 @aid-framework/ir/catalog/models.json,而IR计划作为 @aid-framework/ir/ir.schema.json。 。 。 .

能力

import {
  DEFERRED_CAPABILITIES, MODEL_CAPABILITIES, REQUIRED_CAPABILITIES,
  deriveRequiredCapabilities, isRequiredCapability,
} from '@aid-framework/ir';

deriveRequiredCapabilities(ir) 返回IR本身内容所需的能力,按词汇顺序排列. runGates 所以闸门和发电机 从来不会对需要什么有异议.

API 密码

许可证

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