pi-circuitry

Pi extension for Circuitry graph programs. It registers direct Pi tools for reading, writing, validating, and running Circuitry graphs.

Registered tools

| Tool | Contract | | --- | --- | | circuitry_read_graph | Read the current graph or a graph file, including latest run data when available. | | circuitry_write_graph | Replace the current canvas/file graph with supplied graph source. | | circuitry_run_graph | Execute the current graph, inline graph text, or a saved graph file with runtime inputs. | | circuitry_validate_graph | Validate graph YAML/JSON and return structured issues. |

Saved file execution

{
  "filename": "graphs/research.circuitry.yaml",
  "inputs": {
    "research_request": {
      "topic": "knowledge tracing",
      "depth": "focused"
    }
  }
}

Use filename for saved graph programs. Runtime inputs are one-run overlays keyed by existing type: text resource ids. They do not mutate the graph file or canvas.

Saved files may use Circuitry v0.2.99 links:. Links are resolved relative to the file that declares them before validation and execution, so a main graph can swap fragments like context recovery without changing the rest of the loop.

circuitry: "0.2.99"
links:
  - ./context-recovery.circuitry.yaml
resources:
  user_turn:
    type: text
    value: ""
  assistant:
    type: agent
    inputs: [user_turn, recovered_context]

Inline execution

{
  "text": "circuitry: \"0.2.99\"\nresources:\n  request:\n    type: text\n    value: \"\"\n"
}

Use text when the graph source is supplied directly.

Authored graph format

circuitry: "0.2.99"
title: Example workflow
runtime:
  provider: pi
  model: inherit
resources:
  brief:
    type: text
    value: ""

  analyst:
    type: agent
    identity: Analyst
    inputs: [brief]
    instructions: |
      Read the brief and produce a concise decision memo.

Authored v0.2.99 graph files define resources under resources: and may use links: for multi-file graph organization. Execution nodes and edges are derived at runtime from resource inputs: references after linked resources are merged.

Invalid authored top-level sections: nodes:, edges:, agents:, inputs:.

Error reporting

Tool results expose validation errors, host/model errors, tool errors, scheduler stalls, node outputs, and node errors. After a run, read the same graph and inspect lastRun before summarizing.

Installation

Add to Pi settings:

{
  "packages": ["npm:@darkhorseprojects/pi-circuitry"]
}

Or install globally:

npm install -g @darkhorseprojects/pi-circuitry

App and file modes

• app mode: talks to a running Circuitry app on 127.0.0.1:37843
• file mode: reads/writes/runs saved graph files directly when no app surface is involved

License

Apache-2.0. See LICENSE.