@cogitator-ai/ 神经符号

用于混合神经-同义推理的神经-同义AI包. 将基于LLM的理解与可核查,可解释AI的正式方法相融合.

安装

pnpm add @cogitator-ai/neuro-symbolic

Z3 SMT支持是一种可选的依赖. 如果没有自动安装,请明确添加:

pnpm add z3-solver

没有了Z3,软件包会倒回内置的解析器(精确地搜索有限度域,否则本地搜索).

Postgres和Neo4j图适配器需要它们的驱动程序(可选的对等依赖性):

pnpm add pg            # createPostgresGraphAdapter
pnpm add neo4j-driver  # createNeo4jGraphAdapter

网站文件 : 神经系统。 。 。 .

特征

• 逻辑编程 - 具有ISO操作员优先的Prolog引擎, 剪接, 假换, 否定, findall/3, (中文(简体) ), between/3 和证明树
• 知识图查询 - 类似SPARQL的查询语言、自然语言问题、路径查找和基于规则的推断
• 约束解决 - SAT/SMT用Z3(WASM)或纯-TS倒置,包括优化和软约束
• 计划核查 - 类似PDDL的动作计划,包括验证、命令-威胁检测、变化无常的检查和自动修理

快速启动

import { createNeuroSymbolic } from '@cogitator-ai/neuro-symbolic';

const ns = createNeuroSymbolic();

ns.loadLogicProgram(`
  parent(tom, mary).
  parent(mary, ann).
  grandparent(X, Z) :- parent(X, Y), parent(Y, Z).
`);

const result = ns.queryLogic('grandparent(tom, X)?');
console.log(result.data?.solutions[0].get('X')); // { type: 'atom', value: 'ann' }
console.log(ns.getLogicSolutions('grandparent(tom, X)')); // "X = ann."

const builder = ns.createConstraintProblem('sum');
const x = builder.int('x', 1, 10);
const y = builder.int('y', 1, 10);
builder.assert(x.add(y).eq(15));
builder.maximize(x);

const solution = await ns.solve(builder.build());
if (solution.data?.status === 'sat') {
  console.log(solution.data.model.assignments); // { x: 10, y: 5 }
}

逻辑编程

Prolog-tyle逻辑编程与SLD解析,统一和标准操作员语法.

装入程序

ns.loadLogicProgram(`
  % Facts
  human(socrates).
  human(plato).

  % Rules
  mortal(X) :- human(X).

  % Arithmetic uses ISO precedence: * binds tighter than +
  total(Price, Qty, T) :- T is Price * Qty + 5.

  % Cut is local to the clause that executes it
  grade(S, a) :- S >= 90, !.
  grade(S, b) :- S >= 75, !.
  grade(_, c).

  % If-then-else commits to the condition
  label(S, L) :- ( S >= 50 -> L = pass ; L = fail ).
`);

loadLogicProgram 返回时 { success, errors };语法错误包括行和列.

查询

查询可以使用或没有跟踪 .编号 :? 和可选 ?- 前缀.

const result = ns.queryLogic('mortal(X)?');
for (const solution of result.data?.solutions ?? []) {
  console.log(solution.get('X')); // socrates, plato
}

ns.proveLogic('mortal(socrates)').data; // true
ns.getLogicSolutions('append(X, Y, [1, 2])');
// "X = [], Y = [1, 2] ;\nX = [1], Y = [2] ;\nX = [1, 2], Y = []."

ns.queryLogic('findall(X, human(X), L), length(L, N)', { maxSolutions: 1 });

变量开始于 _ (包括匿名人士) _答复中未报告。 当查询时间或深度耗尽时, result.error 编号 : result.data.explanation 这么说的.

证明树

启用 traceExecution 以捕获证明树 :

import {
  createNeuroSymbolic,
  formatProofTree,
  proofTreeToMermaid,
} from '@cogitator-ai/neuro-symbolic';

const traced = createNeuroSymbolic({ config: { logic: { traceExecution: true } } });
traced.loadLogicProgram(
  'parent(tom, mary). parent(mary, ann). grandparent(X, Z) :- parent(X, Y), parent(Y, Z).'
);

const proof = traced.queryLogic('grandparent(tom, X)').data?.proofTree;
if (proof) {
  console.log(formatProofTree(proof));
  console.log(proofTreeToMermaid(proof));
}

内建预测

算术遵循ISO 语义(-7 mod 3 =:= 2, (中文(简体) ), -7 // 2 =:= -3, (中文(简体) ), div,位点 /\ \/ xor << >>, (中文(简体) ), gcd, (中文(简体) ), min, (中文(简体) ), max, (中文(简体) ), abs三角测量, pi, (中文(简体) ), e(中文(简体) ). 未定义结果, 如 sqrt(-1) 失败而不是绑定 NaN启用 getBuiltinList() 编号 : isControlConstruct() 在运行时检查支持.

知识图查询

类似SPARQL的有自然语言界面的查询语言. 与任何 GraphAdapter (记忆中、Postgres、Neo4j或适配器) @cogitator-ai/memory) (中文(简体) ).

查询构建器

import {
  GraphQueryBuilder,
  graphVariable as variable,
  executeQuery,
} from '@cogitator-ai/neuro-symbolic';

const query = GraphQueryBuilder.select()
  .where(variable('person'), 'works_at', variable('company'))
  .where(variable('company'), 'located_in', 'Berlin')
  .filter('person.name', 'startsWith', 'A')
  .orderBy('person.name', 'asc')
  .limit(10)
  .build();

const result = await executeQuery(query, {
  adapter: graphAdapter,
  agentId: 'agent-1',
  variables: new Map(),
});

• 模式在共享变量上相接;双向边缘在双向相接.
• ?x a person 编号 : ?x type person 匹配节点实体类型.
• describe 查询与主题周围任意方向的边缘相匹配.
• 过滤器可以处理嵌入属性 : person.properties.profile.level。 。 。 .
• count('*', 'total') 数起所有的束缚.

查询字符串

import { parseQueryString } from '@cogitator-ai/neuro-symbolic';

const parsed = parseQueryString(`
  SELECT ?p WHERE { ?p works_at ?c . ?c located_in Berlin }
  FILTER(?p.confidence >= 0.5)
  ORDER BY DESC(?p.name)
  LIMIT 5
`);

支持的过滤操作符 : = != > >= < <= contains startsWith endsWith regex in notIn。 。 。 .

自然语言查询

const answer = await ns.askGraph('Who works at "Acme"?');
console.log(answer.data?.naturalLanguageResponse);

NeuroSymbolic 荣誉 config.knowledgeGraph.enableNaturalLanguage 并适用 defaultQueryLimit 对无明确限制的询问.

原因引擎

import { createReasoningEngine } from '@cogitator-ai/neuro-symbolic';

const engine = createReasoningEngine(graphAdapter, 'agent-1', { maxHops: 3, minConfidence: 0.5 });

const path = await engine.findPath(aliceId, companyId);
const hops = await engine.multiHopQuery(aliceId, ['works_at', 'located_in']);
const inferred = await engine.infer(); // transitive, inverse and composed relations, de-duplicated

约束解决

以流利的DSL进行SAT/SMT解析. 可变声明返回表达式;在构建器中添加限制.

建立制约因素

import { ConstraintBuilder, allDifferent, solve } from '@cogitator-ai/neuro-symbolic';

const builder = ConstraintBuilder.create('example');
const a = builder.bool('a');
const b = builder.bool('b');
const x = builder.int('x', 0, 100);
const y = builder.int('y', 0, 100);
const z = builder.real('z', 0, 1);

builder.assert(a.or(b));
builder.assert(x.add(y).lte(50));
builder.assert(z.mul(2).gt(0.5));
builder.assert(allDifferent(x, y));
builder.soft(x.eq(10), 2);
builder.maximize(x.add(y));

const result = await solve(builder.build());
if (result.status === 'sat') {
  console.log(result.model.assignments, result.model.objectiveValue);
}

声明同一变量两次或一个空域(min > max)掷出.

解析选择

solve(problem, { solver: 'z3' }) (默认)当 z3-solver 可以被加载,否则会倒入内置的解析器.

import { isZ3Available, solveWithZ3, solveSAT } from '@cogitator-ai/neuro-symbolic';

const result = (await isZ3Available()) ? await solveWithZ3(problem) : solveSAT(problem);

• Z3 电话:整数,实数,布尔数和位变量(无符号语义);混合的Int/Real表达式是被自动胁迫的;目标和软约束使用Z3的可选用.
• 内建解析器: 当每个变量都有有限域时进行详尽搜索( ^ 2^ 20 任务) —— 准确 sat编号 :unsat,最佳客观,最小程度的软约束违规;本地搜索真实或无约束变量(可能返回) unknown) (中文(简体) ).

表达式类型

x.add(y);
x.sub(5);
x.mul(2);
x.div(3);
x.mod(7);
x.pow(2);
x.abs();
x.min(y);
x.max(y);
a.and(b);
a.or(b);
a.not();
a.implies(b);
a.iff(b);
x.eq(10);
x.neq(y);
x.gt(0);
x.gte(0);
x.lt(100);
x.lte(100);

ite(a, x, y);
sum(x, y, z);
allDifferent(x, y, z);
atMost(2, a, b, c);
atLeast(1, a, b, c);
exactly(1, a, b, c);

计划核查

类似PDDL的规划与核查和维修。 参数引用使用 ?name 语法.

动作外观

import { ActionSchemaBuilder, ActionRegistry } from '@cogitator-ai/neuro-symbolic';

const move = ActionSchemaBuilder.create('move')
  .describe('Move robot from one location to another')
  .param('from', 'string')
  .param('to', 'string')
  .preSimple('robotAt', '?from')
  .preCompare('battery', 'gt', 10)
  .assign('robotAt', '?to')
  .decrement('battery', 5)
  .setCost(5)
  .build();

const registry = new ActionRegistry();
registry.register(move);

先决条件平等是结构性的(按数值比较阵列和对象). 条件效应对照国家评估其状况 在此之前 行动.

计划验证

import { createAction, validatePlan, formatValidationResult } from '@cogitator-ai/neuro-symbolic';

const plan = {
  id: 'plan-1',
  actions: [
    createAction('move', { from: 'A', to: 'B' }),
    createAction('move', { from: 'B', to: 'C' }),
  ],
  initialState: { id: 's0', variables: { robotAt: 'A', battery: 100 } },
  goalConditions: [{ type: 'simple' as const, variable: 'robotAt', value: 'C' }],
};

const result = validatePlan(plan, registry, { maxSteps: 50 });
console.log(formatValidationResult(result));

验证报告有先决条件的违反、缺失/未知参数、未实现的目标、多余的行动和命令威胁(一项删除以后行动需要的变量的行动).

异常检查

import { createInvariantChecker, formatInvariantResults } from '@cogitator-ai/neuro-symbolic';

const checker = createInvariantChecker(registry);
checker.addInvariant('battery-non-negative', {
  type: 'comparison',
  variable: 'battery',
  operator: 'gte',
  value: 0,
});
checker.addNever('danger', { type: 'simple', variable: 'robotAt', value: 'danger-zone' });
checker.addEventually('arrived', { type: 'simple', variable: 'robotAt', value: 'C' });

console.log(formatInvariantResults(checker.checkPlan(plan)));

轨迹止于没有先决条件的第一次行动.

修复计划

import { createPlanRepairer, formatRepairResult } from '@cogitator-ai/neuro-symbolic';

const repairer = createPlanRepairer(registry, { maxInsertions: 3, maxRemovals: 2 });
const repair = repairer.repair(plan);

if (repair.success) {
  console.log('Repaired plan:', repair.repairedPlan);
} else {
  console.log(formatRepairResult(repair));
}

插入建议通过模拟进行验证(只有在应用时才建议动作确定失败条件);缺失的参数由默认或当前状态来填充.

主兽形

这个 NeuroSymbolic 类集所有模块。 每个方法返回 a NeuroSymbolicResult (单位:千美元){ success, data?, error?, duration })而不是掷出.

import { createNeuroSymbolic } from '@cogitator-ai/neuro-symbolic';

const ns = createNeuroSymbolic({
  graphAdapter: myGraphAdapter,
  agentId: 'agent-1',
  config: {
    knowledgeGraph: { enableNaturalLanguage: true, defaultQueryLimit: 100 },
    logic: { maxDepth: 50, maxSolutions: 10, timeout: 5000 },
    constraints: { timeout: 10000, solver: 'z3' },
    planning: { maxPlanLength: 100, enableRepair: true, verifyInvariants: true },
  },
});

ns.loadLogicProgram('...');
ns.queryLogic('...');

await ns.solve(problem);

await ns.queryGraph(query);
await ns.askGraph('natural language question');
await ns.findPath(startNodeId, endNodeId);

ns.registerAction(actionSchema);
ns.validatePlan(plan);
ns.repairPlan(plan);
ns.checkInvariants(plan);
await ns.validateAndRepair(plan);

ns.getConfig() 返回 a ResolvedNeuroSymbolicConfig: 每节logic, (中文(简体) ), constraints, (中文(简体) ), planning, (中文(简体) ), knowledgeGraph)存在所填的默认值,因此不需要可选的链条. ns.updateConfig(partial) 将更改合并到运行中的实例.

const { logic, constraints } = ns.getConfig();
console.log(logic.maxDepth, constraints.timeout);

ns.updateConfig({ logic: { maxSolutions: 5 } });

代理工具

暴露出神经同位素能力作为AI剂的工具.

import { createNeuroSymbolicTools, MemoryGraphAdapter } from '@cogitator-ai/neuro-symbolic';
import { Agent, Cogitator } from '@cogitator-ai/core';

const nsTools = createNeuroSymbolicTools({ graphAdapter: new MemoryGraphAdapter() });

nsTools.instance.loadLogicProgram(`
  parent(tom, mary).
  parent(mary, ann).
  grandparent(X, Z) :- parent(X, Y), parent(Y, Z).
`);

const agent = new Agent({
  name: 'reasoning-agent',
  model: 'openai/gpt-6.1-sol',
  tools: nsTools.all,
  instructions:
    'Use query_logic for Prolog queries, solve_constraints for SAT/SMT problems and validate_plan to verify action sequences.',
});

const cogitator = new Cogitator({
  llm: { providers: { openai: { apiKey: process.env.OPENAI_API_KEY! } } },
});
const result = await cogitator.run(agent, { input: 'Who are the grandparents of ann?' });

可用工具

* 当一个 graphAdapter 已经通过或提供了 instance 有一个.

工厂选项

interface NeuroSymbolicToolsOptions {
  instance?: NeuroSymbolic;
  graphAdapter?: GraphAdapter;
  config?: Partial<NeuroSymbolicConfig>;
  agentId?: string;
}

何时 agentId 被设置, 图形工具读取并写入该代理的图形; 否则它们会使用工具上下文中的调用代理的id . createGraphTools(adapter, { agentId }) 可自行使用.

图形适配器

import {
  MemoryGraphAdapter,
  createPostgresGraphAdapter,
  createNeo4jGraphAdapter,
} from '@cogitator-ai/neuro-symbolic';

const memory = new MemoryGraphAdapter();
await memory.addNode({
  agentId: 'agent-1',
  name: 'Alice',
  type: 'person',
  aliases: [],
  properties: { age: 30 },
  confidence: 1,
  source: 'user',
});

const postgres = createPostgresGraphAdapter({ connectionString: process.env.DATABASE_URL! });
await postgres.connect();

const neo4j = createNeo4jGraphAdapter({
  uri: 'bolt://localhost:7687',
  username: 'neo4j',
  password: 'secret',
});
await neo4j.connect();

所有适配器范围向请求代理进行穿行和最短路径搜索,将双向边缘视为可双向移动,并拒绝合并为包含在自己来源中的节点.

Postgres 适配器使用 pgvector 扩展名 searchNodesSemantic()它索引嵌入了 HNSW 的节点, 不需要训练数据, 因此, 建立在空表上的索引会随着图表的增长找到每个节点 。 早期版本已创建 ivfflat 在那里的索引,一旦Postgres使用它,它就错过了节点(在3000回31的图表中搜索了60个节点)。 第一个 connect() 升级后将该索引替换为 HNSW,在大图上需要一段时间. 为了避免等待,在部署前先用 CREATE INDEX CONCURRENTLY idx_graph_nodes_embedding_new ON cogitator_graph.graph_nodes USING hnsw (embedding vector_cosine_ops),然后将旧索引降为 idx_graph_nodes_embedding。现有的HNSW指数保持不变。 每次搜索都会增加 hnsw.ef_search 答复 limit (最多为1000个),在pgvector上0.8或后期,会开启迭接扫描,所以是一个很大的极限或一个 entityTypes 过滤器仍然得到每个匹配的节点. 同样相似的节点由id订购.

模块导入

每个模块可单独导入:

import {
  KnowledgeBase,
  SLDResolver,
  parseQuery,
  formatSolutions,
} from '@cogitator-ai/neuro-symbolic/logic';
import {
  GraphQueryBuilder,
  executeQuery,
  ReasoningEngine,
} from '@cogitator-ai/neuro-symbolic/knowledge-graph';
import { ConstraintBuilder, solve, Z3WASMSolver } from '@cogitator-ai/neuro-symbolic/constraints';
import {
  ActionSchemaBuilder,
  PlanValidator,
  InvariantChecker,
} from '@cogitator-ai/neuro-symbolic/planning';
import { createNeuroSymbolicTools } from '@cogitator-ai/neuro-symbolic/tools';

类型参考

import type {
  Term,
  Clause,
  Substitution,
  ProofTree,
  LogicQueryResult,
  GraphQuery,
  GraphQueryResult,
  NaturalLanguageQueryResult,
  ConstraintProblem,
  ConstraintVariable,
  SolverResult,
  ActionSchema,
  Plan,
  PlanState,
  PlanValidationResult,
  SafetyProperty,
  InvariantCheckResult,
} from '@cogitator-ai/types';

许可证

麻省理工学院