@darkhorseprojects/circuitry 0.4.2 → 0.4.4

package/SPEC.md

@@ -1,15 +1,14 @@
-# Circuitry 0.4
+# Circuitry 0.4 Specification
 
-Circuitry is a resource-native source format for executable graphs.
+Circuitry is a source format for executable resource 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
+## Shape
 
 ```yaml
 circuitry: "0.4"
 title: string
 description: string
+
 imports: []
 inputs: {}
 entry: resource_id
@@ -18,9 +17,20 @@ resources: {}
 outputs: {}
 ```
 
-## Resources
+Only `circuitry` and `resources` are required.
+
+## Concepts
 
-Resources are the graph. A resource is identified by its key under `resources`.
+- A **resource** is a named part of the graph.
+- A top-level **input** is a graph invocation input/argument.
+- `resources.*.inputs` are resource dependencies.
+- An **entry** is the default resource a runtime resolves when the graph is run.
+- `resources.*.output` is the resource's output schema/contract.
+- Top-level **outputs** are named graph-level exported outputs.
+- A **tool** is a graph-declared runtime function name. Circuitry does not implement tools.
+- A **prompt** is ordinary text/input. Circuitry has no special prompt primitive.
+
+## Resource fields
 
 ```yaml
 resources:
@@ -28,69 +38,211 @@ resources:
     type: string
     label: string
     description: string
-    inputs: []
+
+    inputs: [] | {}
+
     from: string
     value: any
     path: string
     uri: string
     mime: string
+
     identity: string
     instructions: string
     tools: []
+
     graph: string
     entry: string
-    expect: {}
+
+    output: {}
+
+    x-runtime-name: any
 ```
 
-`inputs` may be a list of resource ids or a map of local input names to resource ids.
+Unknown resource `type` values are allowed so runtimes can extend behavior.
+
+Unknown fields are preserved. Runtime-specific fields should generally use `x-*`. Portable tooling preserves `x-*` fields and does not interpret them.
+
+Circuitry stays small by defining stable graph primitives instead of encoding every workflow feature a runtime might provide.
 
 ## Inputs
 
-Top-level `inputs` declare runtime inputs. Resolvers may inject matching `type: input` resources when absent.
+Top-level `inputs` declare caller-provided values.
 
 ```yaml
 inputs:
-  user_turn:
+  question:
     type: text
     required: true
 ```
 
-## Entry points
+An input resource binds a top-level input into the graph.
+
+```yaml
+resources:
+  question:
+    type: input
+    from: question
+```
+
+## Text and data
+
+A value resource may use exactly one of `value`, `path`, or `uri`.
+
+- `value`: inline value
+- `path`: file path relative to the graph file
+- `uri`: runtime-resolved URI
+
+Circuitry preserves `uri` strings. Runtimes resolve URI schemes.
+
+## Agents
+
+`type: agent` is a portable resource type for model-backed execution.
+
+```yaml
+assistant:
+  type: agent
+  identity: Researcher
+  inputs: [system, question]
+  tools: [read, search]
+  instructions: |
+    Answer carefully.
+  output:
+    answer: str
+```
+
+Circuitry does not call a model. A runtime resolves the agent resource.
+
+`output` describes the expected schema of the agent resource's materialized result. It does not define graph exports.
+
+## Runs
+
+`type: run` composes graphs.
+
+```yaml
+recovered_context:
+  type: run
+  graph: ./context.circuitry.yaml
+  entry: recover
+  inputs:
+    question: question
+```
+
+A run resource asks the runtime to resolve another Circuitry graph. `inputs` maps child input names to resources in the current graph.
+
+For `type: run`, `output` describes the expected schema of the child graph run result.
+
+## Entries
 
-`entry` is the default resource to resolve. `entries` optionally names multiple run surfaces.
+`entry` is the default resource to run.
 
 ```yaml
 entry: assistant
+```
+
+`entries` optionally gives named entry aliases.
+
+```yaml
 entries:
+  chat: assistant
   recover: recovered_context
 ```
 
-## Run resources
+Runtimes may run a graph from any explicit entry, alias, or resource they support. This lets one graph expose multiple useful executable entrypoints without changing the resource graph.
 
-`type: run` represents declarative graph execution as a resource.
+## Outputs
+
+Top-level `outputs` define named exports from the graph. Each output points to a resource or to a field/path inside a resource's materialized value.
 
 ```yaml
 resources:
-  recovered_context:
-    type: run
-    graph: ./context.circuitry.yaml
-    entry: recovery
-    inputs:
-      user_turn: user_turn
+  assistant:
+    type: agent
+    output:
+      answer: str
+
+outputs:
+  final:
+    from: assistant.answer
 ```
 
-A runtime tool such as `run_graph` is dynamic capability. A `type: run` resource is declarative topology.
+`assistant.output` declares the schema of the assistant resource's materialized value. `outputs.final` exports `assistant.answer` as a named graph output.
 
-## Outputs
+`outputs` is separate from `output`. `output` is schema-only and never defines graph exports.
+
+Output paths are intentionally simple: in `from: assistant.answer`, `assistant` is the resource id before the first dot. The remaining `answer` path selects a field/path within that resource's materialized value. If no dot is present, the whole materialized resource value is referenced.
+
+## Imports
+
+Imports copy selected resources from another graph into the current graph.
 
 ```yaml
-outputs:
-  response:
-    from: assistant.response
-    schema:
-      response: str
+imports:
+  - path: ./shared.circuitry.yaml
+    resources: "*"
 ```
 
-## Extensions
+```yaml
+imports:
+  - path: ./shared.circuitry.yaml
+    resources:
+      system: base_system
+```
+
+Import renaming is assignment-style:
+
+```txt
+local_name = imported.imported_name
+system = imported.base_system
+```
+
+This imports `base_system` from the imported graph and binds it locally as `system`. The current graph should reference `system`.
+
+Imports do not merge top-level inputs, entries, outputs, or extension fields.
+
+## Resolution
+
+Running a graph means resolving its entry resource.
+
+Resource resolution semantics:
+
+- `input`: returns caller input named by `from`.
+- `text`/`data`: returns `value`, file contents from `path`, or runtime-resolved `uri` contents.
+- `agent`: resolves listed inputs, then asks the runtime to execute an agent resource.
+- `run`: resolves mapped inputs, then asks the runtime to run another Circuitry graph.
+- unknown `type`: runtime-defined.
+
+For static resources, `output` describes the resolved/materialized value. For executable resources, `output` describes the produced result.
+
+## Tools
+
+Tools are an explicit graph-declared tool surface.
+
+```yaml
+resources:
+  assistant:
+    type: agent
+    tools: [read, write, bash]
+```
+
+A runtime must not expose undeclared tools to that resource. Circuitry only declares tool names. The runtime defines what each tool means and how it executes. Zinc implements tools such as `read`, `write`, `edit`, `bash`, and `run_graph`.
+
+Circuitry tooling validates graph shape and resolves imports. It does not execute runtime behavior.
+
+## Validation
+
+A valid 0.4 graph:
 
-Fields beginning with `x-` are preserved for runtimes and ecosystems.
+- is an object
+- has `circuitry: "0.4"`
+- has `resources`
+- does not contain `nodes` or `edges`
+- has an existing `entry`, if set
+- has `entries` targets that exist
+- has `type` on every resource
+- has resource inputs pointing to existing resources
+- has no cycles in resource dependencies
+- has `type: input` resources with valid `from`
+- has `type: run` resources with `graph`
+- has outputs with valid `from` roots
+- only uses supported resource fields

package/dist/cli.d.ts

@@ -1 +1,2 @@
+#!/usr/bin/env node
 export {};