@darkhorseprojects/circuitry 0.3.10 → 0.4.1

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.