@darkhorseprojects/circuitry 0.3.9 → 0.4.0

package/dist/node.js

@@ -9,165 +9,142 @@ import YAML2 from "yaml";
 
 // src/graph.ts
 import YAML from "yaml";
-var CIRCUITRY_SPEC_VERSION = "0.3.2";
-var DEFAULT_CIRCUITRY_VALIDATION_RULES = [
-  "no-self-loops",
-  "no-unknown-edge-endpoints",
-  "require-executable-inputs",
-  "no-cycles"
-];
+var CIRCUITRY_SPEC_VERSION = "0.4";
 var DEFAULT_CIRCUITRY_VALIDATION_STANDARD = {
   version: CIRCUITRY_SPEC_VERSION,
-  requireSpecVersion: true,
-  rules: DEFAULT_CIRCUITRY_VALIDATION_RULES,
-  executableKinds: ["agent", "tool", "output"]
+  requireSpecVersion: true
 };
-var runtimeInputToText = (value) => {
-  if (typeof value === "string") return value;
-  if (value === void 0) return "";
-  return YAML.stringify(value).trimEnd();
+var createCircuitryValidationStandard = (standard = {}) => ({
+  version: standard.version || DEFAULT_CIRCUITRY_VALIDATION_STANDARD.version,
+  requireSpecVersion: standard.requireSpecVersion ?? DEFAULT_CIRCUITRY_VALIDATION_STANDARD.requireSpecVersion
+});
+var getResourceInputs = (resource) => {
+  const inputs = resource.inputs;
+  if (!inputs) return [];
+  if (Array.isArray(inputs)) return inputs.map((from) => ({ from, to: "" }));
+  return Object.entries(inputs).map(([name, from]) => ({ from, to: "", name }));
 };
-var applyCircuitryRuntimeInputs = (graph, inputs = {}) => {
-  const next = { ...graph, resources: graph.resources ? { ...graph.resources } : graph.resources };
-  for (const [id, value] of Object.entries(inputs)) {
-    const resource = next.resources?.[id];
-    if (!resource) throw new Error(`unknown arg: ${id}`);
-    if (resource.type !== "text") throw new Error(`arg is not text: ${id}`);
-    next.resources[id] = { ...resource, value: runtimeInputToText(value) };
+var resourceInputIds = (resource) => getResourceInputs(resource).map((dependency) => dependency.from);
+var getCircuitryDependencies = (graph) => {
+  const dependencies = [];
+  for (const [to, resource] of Object.entries(graph.resources || {})) {
+    for (const dependency of getResourceInputs(resource)) dependencies.push({ ...dependency, to });
   }
-  return next;
+  return dependencies;
 };
-var ruleName = (rule) => typeof rule === "string" ? rule : rule.rule;
-var executableKindsFromRules = (rules) => rules.find((rule) => typeof rule !== "string" && rule.rule === "require-executable-inputs")?.executableKinds;
-var createCircuitryValidationStandard = (standard = {}, graph) => {
-  const rules = [...DEFAULT_CIRCUITRY_VALIDATION_RULES, ...graph?.validation?.rules || [], ...standard.rules || []];
-  return {
-    version: standard.version || DEFAULT_CIRCUITRY_VALIDATION_STANDARD.version,
-    requireSpecVersion: standard.requireSpecVersion ?? DEFAULT_CIRCUITRY_VALIDATION_STANDARD.requireSpecVersion,
-    rules,
-    executableKinds: standard.executableKinds || executableKindsFromRules(rules) || [...DEFAULT_CIRCUITRY_VALIDATION_STANDARD.executableKinds]
+var getCircuitryRunSet = (graph, entry = graph.entry) => {
+  if (!entry) return [];
+  const visited = /* @__PURE__ */ new Set();
+  const visit = (id) => {
+    if (visited.has(id)) return;
+    const resource = graph.resources?.[id];
+    if (!resource) return;
+    for (const input of resourceInputIds(resource)) visit(input);
+    visited.add(id);
   };
+  visit(entry);
+  return [...visited];
 };
-var expandResources = (resources) => {
-  const nodes = [];
-  const edges = [];
-  for (const [id, resource] of Object.entries(resources)) {
-    if (resource.type === "text") {
-      nodes.push({ id, kind: "input", label: resource.label || id, input: { type: "text", value: resource.value } });
-    } else if (resource.type === "agent") {
-      const agent = resource;
-      nodes.push({
-        id,
-        kind: "agent",
-        label: agent.label || agent.identity || id,
-        agent: {
-          identity: agent.identity || agent.label || id,
-          model: agent.model,
-          tools: agent.tools,
-          instructions: agent.instructions,
-          personality: agent.personality,
-          context: agent.context
-        },
-        skills: agent.skills,
-        expect: agent.expect
-      });
-      for (const input of agent.inputs || []) edges.push({ from: input, to: id, kind: "dependency" });
-    } else if (resource.type === "tool") {
-      const tool = resource;
-      nodes.push({ id, kind: "tool", label: tool.label || id, agent: { instructions: tool.instructions } });
-      for (const input of tool.inputs || []) edges.push({ from: input, to: id, kind: "dependency" });
-    } else {
-      const input = resource;
-      nodes.push({ id, kind: "input", label: input.label || id, input: { type: input.type, value: input.value, uri: input.uri || input.path, mimeType: input.mimeType, data: input.data } });
+var toposortCircuitryResources = (graph, entry) => {
+  const ids = entry ? new Set(getCircuitryRunSet(graph, entry)) : new Set(Object.keys(graph.resources || {}));
+  const visiting = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new Set();
+  const ordered = [];
+  const visit = (id) => {
+    if (!ids.has(id) || visited.has(id)) return;
+    if (visiting.has(id)) throw new Error(`Circuitry resource dependency cycle at ${id}`);
+    visiting.add(id);
+    const resource = graph.resources?.[id];
+    if (resource) for (const input of resourceInputIds(resource)) visit(input);
+    visiting.delete(id);
+    visited.add(id);
+    ordered.push(id);
+  };
+  for (const id of ids) visit(id);
+  return ordered;
+};
+var runtimeInputToText = (value) => {
+  if (typeof value === "string") return value;
+  if (value === void 0) return "";
+  return YAML.stringify(value).trimEnd();
+};
+var resolveCircuitrySource = (graph) => {
+  const inputs = graph.inputs || graph.args || {};
+  const resources = { ...graph.resources || {} };
+  for (const [id, input] of Object.entries(inputs)) {
+    if (!resources[id]) {
+      resources[id] = {
+        type: "input",
+        from: id,
+        label: input.label,
+        description: input.description,
+        mime: input.mime || input.mimeType
+      };
     }
   }
-  return { nodes, edges };
+  return { ...graph, circuitry: CIRCUITRY_SPEC_VERSION, imports: graph.imports || [], inputs, resources };
 };
-var normalizeCircuitryGraph = (graph) => {
-  if (!graph.resources) return { ...graph };
-  return { ...graph, ...expandResources(graph.resources) };
+var applyCircuitryRuntimeInputs = (graph, inputs = {}) => {
+  const next = resolveCircuitrySource(graph);
+  const resources = { ...next.resources || {} };
+  for (const [id, value] of Object.entries(inputs)) {
+    const resource = resources[id];
+    if (!resource) throw new Error(`unknown input: ${id}`);
+    if (resource.type === "input") resources[id] = { ...resource, value, from: resource.from || id };
+    else resources[id] = { ...resource, value: runtimeInputToText(value) };
+  }
+  return { ...next, resources };
 };
-var validateCircuitryGraphInternal = (graph, standard = {}, source) => {
-  const resolved = createCircuitryValidationStandard(standard, graph && typeof graph === "object" && !Array.isArray(graph) ? graph : void 0);
+var validateCircuitrySource = (graph, standard = {}) => {
+  const resolvedStandard = createCircuitryValidationStandard(standard);
   const errors = [];
   const issue = (code, message = code, path2) => errors.push({ code, message, ...path2 ? { path: path2 } : {} });
-  if (!graph || typeof graph !== "object" || Array.isArray(graph)) return { ok: false, errors: [{ code: "invalid_graph", message: "invalid graph" }], standard: resolved };
+  if (!graph || typeof graph !== "object" || Array.isArray(graph)) {
+    return { ok: false, errors: [{ code: "invalid_graph", message: "invalid graph" }], standard: resolvedStandard };
+  }
   const g = graph;
-  if (resolved.requireSpecVersion && g.circuitry !== resolved.version) issue("invalid_version", "invalid version", ["circuitry"]);
-  if (source) {
-    const raw = g;
-    if (!g.resources || Object.keys(g.resources).length === 0) issue("missing_resources", "missing resources", ["resources"]);
-    if (raw.agents) issue("forbidden_agents", "forbidden agents", ["agents"]);
-    if (raw.inputs) issue("forbidden_inputs", "forbidden inputs", ["inputs"]);
-    if (g.nodes?.length) issue("forbidden_nodes", "forbidden nodes", ["nodes"]);
-    if (g.edges?.length) issue("forbidden_edges", "forbidden edges", ["edges"]);
-    if (raw.links) issue("forbidden_links", "forbidden links", ["links"]);
-  }
-  const rules = new Set(resolved.rules.map(ruleName));
-  const normalized = normalizeCircuitryGraph(g);
-  const ids = /* @__PURE__ */ new Set();
-  for (const [index, node] of (normalized.nodes || []).entries()) {
-    if (!node.id) {
-      issue("missing_node_id", "missing node id", ["nodes", index, "id"]);
-      continue;
-    }
-    if (ids.has(node.id)) issue("duplicate_node_id", "duplicate node id", ["nodes", index, "id"]);
-    ids.add(node.id);
-    if (!node.kind) issue("missing_node_kind", "missing node kind", ["nodes", index, "kind"]);
-  }
-  const adjacency = /* @__PURE__ */ new Map();
-  const incoming = /* @__PURE__ */ new Map();
-  for (const id of ids) {
-    adjacency.set(id, []);
-    incoming.set(id, 0);
-  }
-  for (const [index, edge] of (normalized.edges || []).entries()) {
-    if (!edge.from || !edge.to) {
-      issue("missing_edge_endpoint", "missing edge endpoint", ["edges", index]);
-      continue;
-    }
-    if (rules.has("no-self-loops") && edge.from === edge.to) {
-      issue("self_loop", "self loop", ["edges", index]);
-      continue;
-    }
-    const ok = ids.has(edge.from) && ids.has(edge.to);
-    if (rules.has("no-unknown-edge-endpoints")) {
-      if (!ids.has(edge.from)) issue("unknown_edge_source", "unknown edge source", ["edges", index, "from"]);
-      if (!ids.has(edge.to)) issue("unknown_edge_target", "unknown edge target", ["edges", index, "to"]);
-    }
-    if (ok) {
-      adjacency.get(edge.from).push(edge.to);
-      incoming.set(edge.to, (incoming.get(edge.to) || 0) + 1);
-    }
+  if (resolvedStandard.requireSpecVersion && g.circuitry !== resolvedStandard.version) issue("invalid_version", "invalid version", ["circuitry"]);
+  if (!g.resources || Object.keys(g.resources).length === 0) issue("missing_resources", "missing resources", ["resources"]);
+  if (g.nodes) issue("forbidden_nodes", "forbidden nodes", ["nodes"]);
+  if (g.edges) issue("forbidden_edges", "forbidden edges", ["edges"]);
+  if (g.agents) issue("forbidden_agents", "forbidden agents", ["agents"]);
+  const resolved = resolveCircuitrySource(g);
+  const ids = new Set(Object.keys(resolved.resources || {}));
+  if (resolved.entry && !ids.has(resolved.entry)) issue("unknown_entry", "unknown entry", ["entry"]);
+  for (const [name, target] of Object.entries(resolved.entries || {})) {
+    if (!ids.has(target)) issue("unknown_entry", `unknown entry: ${name}`, ["entries", name]);
+  }
+  for (const [id, resource] of Object.entries(resolved.resources || {})) {
+    if (!resource.type) issue("missing_resource_type", "missing resource type", ["resources", id, "type"]);
+    for (const input of resourceInputIds(resource)) {
+      if (!ids.has(input)) issue("unknown_resource_input", `unknown resource input: ${input}`, ["resources", id, "inputs"]);
+      if (input === id) issue("self_input", "self input", ["resources", id, "inputs"]);
+    }
+  }
+  for (const [name, output] of Object.entries(resolved.outputs || {})) {
+    const root = output.from.split(".")[0];
+    if (!ids.has(root)) issue("unknown_output_source", `unknown output source: ${output.from}`, ["outputs", name, "from"]);
   }
-  if (rules.has("require-executable-inputs")) {
-    const executable = new Set(resolved.executableKinds);
-    for (const [index, node] of (normalized.nodes || []).entries()) {
-      if (executable.has(node.kind) && (incoming.get(node.id) || 0) === 0) issue("missing_executable_input", "missing executable input", ["nodes", index]);
-    }
+  try {
+    toposortCircuitryResources(resolved);
+  } catch {
+    issue("cycle", "cycle");
   }
-  if (rules.has("no-cycles")) {
-    const visiting = /* @__PURE__ */ new Set();
-    const visited = /* @__PURE__ */ new Set();
-    const visit = (id) => {
-      if (visiting.has(id)) return true;
-      if (visited.has(id)) return false;
-      visiting.add(id);
-      for (const next of adjacency.get(id) || []) if (visit(next)) return true;
-      visiting.delete(id);
-      visited.add(id);
-      return false;
-    };
-    for (const id of ids) if (visit(id)) {
-      issue("cycle", "cycle");
-      break;
-    }
+  return { ok: errors.length === 0, errors, standard: resolvedStandard };
+};
+var validateCircuitryGraphWithStandard = validateCircuitrySource;
+var validateCircuitryExecutionGraphWithStandard = validateCircuitrySource;
+var validateCircuitryGraph = (graph, standard = {}) => validateCircuitrySource(graph, standard).errors.map((error) => error.message);
+var normalizeCircuitryGraph = (graph) => {
+  const resolved = resolveCircuitrySource(graph);
+  const nodes = [];
+  for (const [id, resource] of Object.entries(resolved.resources || {})) {
+    if (resource.type === "agent") nodes.push({ id, kind: "agent", label: resource.label || resource.identity || id, agent: { identity: resource.identity, model: resource.model, tools: resource.tools, instructions: resource.instructions, personality: resource.personality, context: resource.context }, skills: resource.skills, expect: resource.expect });
+    else nodes.push({ id, kind: resource.type === "tool" ? "tool" : "input", label: resource.label || id, input: { type: resource.type, value: typeof resource.value === "string" ? resource.value : void 0, uri: resource.uri || resource.path, mimeType: resource.mime || resource.mimeType, data: resource.data } });
   }
-  return { ok: errors.length === 0, errors, standard: resolved };
+  const edges = getCircuitryDependencies(resolved).map(({ from, to }) => ({ from, to, kind: "dependency" }));
+  return { ...resolved, nodes, edges };
 };
-var validateCircuitryGraphWithStandard = (graph, standard = {}) => validateCircuitryGraphInternal(graph, standard, true);
-var validateCircuitryExecutionGraphWithStandard = (graph, standard = {}) => validateCircuitryGraphInternal(graph, standard, false);
-var validateCircuitryGraph = (graph, standard = {}) => validateCircuitryGraphWithStandard(graph, standard).errors.map((error) => error.message);
 
 // src/yaml.ts
 var parseYamlData = (text) => {
@@ -446,7 +423,7 @@ var runCircuitryGraphExecution = async ({
   const executionGraph = buildCircuitryExecutionGraph(graph);
   const runs = [];
   const parallelism = Math.max(1, Math.floor(maxParallelRuns));
-  const defaultModel = graph.runtime?.model;
+  const defaultModel = typeof graph.runtime?.model === "string" ? graph.runtime.model : void 0;
   const runOne = async (nodeId, outputs2) => {
     const cycle = false;
     const item = executionGraph.nodes.get(nodeId);
@@ -645,10 +622,19 @@ var runNodeWithPiSDK = async ({
   }
 };
 var defaultFilename = "graph.circuitry.yaml";
-var resourceInputs = (resource) => "inputs" in resource && Array.isArray(resource.inputs) ? resource.inputs : [];
-var withResourceInputs = (resource, inputs) => "inputs" in resource ? { ...resource, inputs } : resource;
+var resourceInputs = (resource) => {
+  if (!("inputs" in resource) || !resource.inputs) return [];
+  return Array.isArray(resource.inputs) ? resource.inputs : Object.values(resource.inputs);
+};
+var withResourceInputs = (resource, inputs) => {
+  if (!("inputs" in resource) || !resource.inputs) return resource;
+  if (Array.isArray(resource.inputs)) return { ...resource, inputs };
+  const inputMap = resource.inputs;
+  const names = Object.keys(inputMap);
+  return { ...resource, inputs: Object.fromEntries(names.map((name, index) => [name, inputs[index] || inputMap[name]])) };
+};
 var selectedImportResources = (imp, resources) => {
-  if (imp.resources === "*") return Object.fromEntries(Object.keys(resources).map((id) => [id, id]));
+  if (!imp.resources || imp.resources === "*") return Object.fromEntries(Object.keys(resources).map((id) => [id, id]));
   if (Array.isArray(imp.resources)) return Object.fromEntries(imp.resources.map((id) => [id, id]));
   return imp.resources;
 };
@@ -686,7 +672,7 @@ var resolveCircuitryGraph = async (parsed, graphFile, text, standard, stack = []
     resources[id] = resource;
     origins[id] = graphFile;
   }
-  const graph = normalizeCircuitryGraph({ ...parsed, imports: [], resources });
+  const graph = { ...parsed, circuitry: "0.4", imports: [], inputs: parsed.inputs || parsed.args || {}, resources };
   if (stack.length === 0) {
     const validation = validateCircuitryExecutionGraphWithStandard(graph, standard);
     if (validation.errors.length) {

package/examples/agent.circuitry.yaml

@@ -0,0 +1,24 @@
+circuitry: "0.4"
+title: Agent with prompt input
+inputs:
+  user_turn:
+    type: text
+    required: true
+entry: assistant
+resources:
+  user_turn:
+    type: input
+    from: user_turn
+  guide:
+    type: text
+    value: Be direct, accurate, and natural.
+  assistant:
+    type: agent
+    inputs: [guide, user_turn]
+    tools: [read, write, bash, run_graph]
+    instructions: Use the guide and answer the user.
+    expect:
+      response: str
+outputs:
+  response:
+    from: assistant.response

package/examples/imports.circuitry.yaml

@@ -0,0 +1,13 @@
+circuitry: "0.4"
+title: Imports and entries
+imports:
+  - path: ./agent.circuitry.yaml
+    resources: "*"
+    prefix: imported_
+entry: imported_assistant
+entries:
+  default: imported_assistant
+resources:
+  local_note:
+    type: text
+    value: Local resource.

package/examples/minimal.circuitry.yaml

@@ -0,0 +1,20 @@
+circuitry: "0.4"
+title: Minimal
+inputs:
+  user_turn:
+    type: text
+    required: true
+entry: assistant
+resources:
+  user_turn:
+    type: input
+    from: user_turn
+  assistant:
+    type: agent
+    inputs: [user_turn]
+    instructions: Answer the user.
+    expect:
+      response: str
+outputs:
+  response:
+    from: assistant.response

package/examples/run-resource.circuitry.yaml

@@ -0,0 +1,24 @@
+circuitry: "0.4"
+title: Run resource
+inputs:
+  user_turn:
+    type: text
+    required: true
+entry: assistant
+resources:
+  user_turn:
+    type: input
+    from: user_turn
+  recovered_context:
+    type: run
+    graph: ./context-recovery.circuitry.yaml
+    entry: recovery
+    inputs:
+      user_turn: user_turn
+  assistant:
+    type: agent
+    inputs: [user_turn, recovered_context]
+    instructions: Answer with recovered context when useful.
+outputs:
+  response:
+    from: assistant

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@darkhorseprojects/circuitry",
-  "version": "0.3.9",
+  "version": "0.4.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -17,9 +17,12 @@
   "bin": {
     "circuitry": "./dist/cli.js"
   },
-  "license": "LGPL-3.0-only",
+  "license": "MPL-2.0",
   "files": [
     "dist",
+    "SPEC.md",
+    "schema.json",
+    "examples",
     "LICENSE"
   ],
   "scripts": {

package/schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://darkhorseprojects.github.io/circuitry/schema/0.4/schema.json",
+  "title": "Circuitry 0.4",
+  "type": "object",
+  "required": ["circuitry", "resources"],
+  "properties": {
+    "circuitry": { "const": "0.4" },
+    "title": { "type": "string" },
+    "description": { "type": "string" },
+    "imports": { "type": "array" },
+    "inputs": { "type": "object" },
+    "entry": { "type": "string" },
+    "entries": { "type": "object", "additionalProperties": { "type": "string" } },
+    "resources": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/resource" }
+    },
+    "outputs": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/output" }
+    }
+  },
+  "additionalProperties": true,
+  "$defs": {
+    "resource": {
+      "type": "object",
+      "required": ["type"],
+      "properties": {
+        "type": { "type": "string" },
+        "label": { "type": "string" },
+        "description": { "type": "string" },
+        "inputs": {
+          "oneOf": [
+            { "type": "array", "items": { "type": "string" } },
+            { "type": "object", "additionalProperties": { "type": "string" } }
+          ]
+        },
+        "from": { "type": "string" },
+        "value": true,
+        "path": { "type": "string" },
+        "uri": { "type": "string" },
+        "mime": { "type": "string" },
+        "identity": { "type": "string" },
+        "instructions": { "type": "string" },
+        "tools": { "type": "array", "items": { "type": "string" } },
+        "graph": { "type": "string" },
+        "entry": { "type": "string" },
+        "expect": true
+      },
+      "additionalProperties": true
+    },
+    "output": {
+      "type": "object",
+      "required": ["from"],
+      "properties": {
+        "from": { "type": "string" },
+        "type": { "type": "string" },
+        "mime": { "type": "string" },
+        "schema": true
+      },
+      "additionalProperties": true
+    }
+  }
+}