@darkhorseprojects/circuitry 0.4.2 → 0.4.3

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,18 @@ resources: {}
 outputs: {}
 ```
 
-## Resources
+Only `circuitry` and `resources` are required.
+
+## Concepts
+
+- A **resource** is a named part of the graph.
+- An **input** is a caller-supplied value.
+- An **entry** is the resource a runtime resolves when the graph is run.
+- An **output** maps a public graph result to a resource path.
+- A **tool** is a runtime function name. Circuitry does not implement tools.
+- A **prompt** is ordinary text/input. Circuitry has no special prompt primitive.
 
-Resources are the graph. A resource is identified by its key under `resources`.
+## Resource fields
 
 ```yaml
 resources:
@@ -28,69 +36,168 @@ 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: {}
+
+    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. Runtimes decide what they support.
+
+`x-*` fields are extensions. Portable tooling preserves them and does not interpret them.
 
 ## 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.
+  expect:
+    answer: str
+```
+
+Circuitry does not call a model. A runtime resolves the agent resource.
+
+## 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.
+
+## Entries
 
-`entry` is the default resource to resolve. `entries` optionally names multiple run surfaces.
+`entry` is the default resource to resolve.
 
 ```yaml
 entry: assistant
+```
+
+`entries` optionally gives named entry aliases.
+
+```yaml
 entries:
+  chat: assistant
   recover: recovered_context
 ```
 
-## Run resources
+## Outputs
 
-`type: run` represents declarative graph execution as a resource.
+Top-level outputs describe graph return values.
 
 ```yaml
-resources:
-  recovered_context:
-    type: run
-    graph: ./context.circuitry.yaml
-    entry: recovery
-    inputs:
-      user_turn: user_turn
+outputs:
+  answer:
+    from: assistant.answer
 ```
 
-A runtime tool such as `run_graph` is dynamic capability. A `type: run` resource is declarative topology.
+`expect` describes a resource result. `outputs` describes graph boundary values.
 
-## Outputs
+## 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:
+      shared_system: 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.
+
+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

package/dist/cli.d.ts

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