@darkhorseprojects/circuitry 0.3.9 → 0.4.0

package/SPEC.md

@@ -0,0 +1,96 @@
+# Circuitry 0.4
+
+Circuitry is a resource-native source format for executable graphs.
+
+A Circuitry file describes named resources and the dependencies between them. Running a graph means resolving an entry resource. Runtimes decide how to execute supported resource types.
+
+## Top-level shape
+
+```yaml
+circuitry: "0.4"
+title: string
+description: string
+imports: []
+inputs: {}
+entry: resource_id
+entries: {}
+resources: {}
+outputs: {}
+```
+
+## Resources
+
+Resources are the graph. A resource is identified by its key under `resources`.
+
+```yaml
+resources:
+  id:
+    type: string
+    label: string
+    description: string
+    inputs: []
+    from: string
+    value: any
+    path: string
+    uri: string
+    mime: string
+    identity: string
+    instructions: string
+    tools: []
+    graph: string
+    entry: string
+    expect: {}
+```
+
+`inputs` may be a list of resource ids or a map of local input names to resource ids.
+
+## Inputs
+
+Top-level `inputs` declare runtime inputs. Resolvers may inject matching `type: input` resources when absent.
+
+```yaml
+inputs:
+  user_turn:
+    type: text
+    required: true
+```
+
+## Entry points
+
+`entry` is the default resource to resolve. `entries` optionally names multiple run surfaces.
+
+```yaml
+entry: assistant
+entries:
+  recover: recovered_context
+```
+
+## Run resources
+
+`type: run` represents declarative graph execution as a resource.
+
+```yaml
+resources:
+  recovered_context:
+    type: run
+    graph: ./context.circuitry.yaml
+    entry: recovery
+    inputs:
+      user_turn: user_turn
+```
+
+A runtime tool such as `run_graph` is dynamic capability. A `type: run` resource is declarative topology.
+
+## Outputs
+
+```yaml
+outputs:
+  response:
+    from: assistant.response
+    schema:
+      response: str
+```
+
+## Extensions
+
+Fields beginning with `x-` are preserved for runtimes and ecosystems.

package/dist/cli.js

@@ -12,150 +12,128 @@ 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 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 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 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 dependencies;
+};
+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 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 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"]);
+  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]);
   }
-  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;
+  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"]);
     }
-    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 [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"]);
   }
-  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 (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]);
-    }
-  }
-  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;
-    }
+  try {
+    toposortCircuitryResources(resolved);
+  } catch {
+    issue("cycle", "cycle");
   }
-  return { ok: errors.length === 0, errors, standard: resolved };
+  return { ok: errors.length === 0, errors, standard: resolvedStandard };
+};
+var validateCircuitryExecutionGraphWithStandard = validateCircuitrySource;
+var validateCircuitryGraph = (graph, standard = {}) => validateCircuitrySource(graph, standard).errors.map((error) => error.message);
+var inspectCircuitrySource = (graph) => {
+  const resolved = resolveCircuitrySource(graph);
+  return {
+    version: String(resolved.circuitry),
+    title: resolved.title,
+    entry: resolved.entry,
+    entries: resolved.entries || {},
+    inputs: Object.keys(resolved.inputs || {}),
+    resources: Object.keys(resolved.resources || {}),
+    outputs: Object.keys(resolved.outputs || {}),
+    dependencies: getCircuitryDependencies(resolved)
+  };
 };
-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) => {
@@ -186,10 +164,19 @@ import YAML3 from "yaml";
 
 // src/node.ts
 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;
 };
@@ -227,7 +214,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) {
@@ -247,27 +234,30 @@ var loadCircuitryGraphFile = async (filename2 = defaultFilename, standard, stack
 // src/cli.ts
 var [, , command, filename] = process.argv;
 var usage = () => {
-  console.error("usage: circuitry <check|parse> <file.yaml>");
+  console.error("usage: circuitry <check|resolve|inspect|parse> <file.yaml|--stdin>");
   process.exit(2);
 };
+var readInput = async (name) => name === "--stdin" ? await new Promise((resolve, reject) => {
+  let data = "";
+  process.stdin.on("data", (chunk) => data += chunk);
+  process.stdin.on("end", () => resolve(data));
+  process.stdin.on("error", reject);
+}) : await readFile2(name, "utf8");
 if (!command || !filename) usage();
 try {
-  if (command === "parse") {
+  if (command === "resolve" || command === "parse") {
     if (filename.endsWith(".circuitry.yaml") || filename.endsWith(".circuitry.yml")) {
       const loaded = await loadCircuitryGraphFile(filename);
-      process.stdout.write(JSON.stringify({ graph: loaded.graph, origins: loaded.origins }));
+      process.stdout.write(JSON.stringify(loaded.graph, null, 2));
     } else {
-      const text = filename === "--stdin" ? await new Promise((resolve, reject) => {
-        let data = "";
-        process.stdin.on("data", (chunk) => data += chunk);
-        process.stdin.on("end", () => resolve(data));
-        process.stdin.on("error", reject);
-      }) : await readFile2(filename, "utf8");
-      process.stdout.write(JSON.stringify(parseYamlData(text)));
+      process.stdout.write(JSON.stringify(parseYamlData(await readInput(filename)), null, 2));
     }
+  } else if (command === "inspect") {
+    const loaded = await loadCircuitryGraphFile(filename);
+    process.stdout.write(JSON.stringify(inspectCircuitrySource(loaded.graph), null, 2));
   } else if (command === "check") {
     const loaded = await loadCircuitryGraphFile(filename);
-    const result = validateCircuitryExecutionGraphWithStandard(loaded.graph);
+    const result = validateCircuitrySource(loaded.graph);
     if (!result.ok) {
       console.error(result.errors.map((error) => error.message).join("\n"));
       process.exit(1);