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.

Inline execution

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

Use text when the graph source is supplied directly.

Authored graph format

circuitry: "0.2"
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 graph files define resources under resources:. Execution nodes and edges are derived at runtime from resource inputs: references.

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.