171 lines
4.6 KiB
Markdown
171 lines
4.6 KiB
Markdown
# Structural Refs
|
|
|
|
Qualified names are display strings. They are not authoritative identifiers.
|
|
|
|
The platform still accepts old dotted strings at MCP/API boundaries when it can
|
|
parse them, but saved workflow artifacts and deployments should store structural
|
|
refs from now on. A dotted string may be shown to humans and LLM clients, but
|
|
runtime code should not infer source boundaries from it.
|
|
|
|
## Why
|
|
|
|
These strings look similar but mean different things:
|
|
|
|
```text
|
|
context7.default.query-docs
|
|
workflow.echo_wrapper.v1
|
|
demo.foo.bar
|
|
```
|
|
|
|
`context7.default.query-docs` usually means a concrete external source and a
|
|
capability key. `workflow.echo_wrapper.v1` means a saved workflow artifact and
|
|
artifact version. `demo.foo.bar` is ambiguous: it could be source `demo` with
|
|
capability key `foo.bar`, or source `demo.foo` with capability key `bar`.
|
|
|
|
No first-dot, last-dot, or regex parser can recover a boundary that was not
|
|
stored.
|
|
|
|
## Capability Refs
|
|
|
|
Use a source plus a local capability key:
|
|
|
|
```json
|
|
{
|
|
"source": "demo",
|
|
"capability_key": "foo.bar"
|
|
}
|
|
```
|
|
|
|
The `capability_key` is local to the known source. It may contain dots. Those
|
|
dots do not carry source meaning.
|
|
|
|
Old input like `"demo.foo.bar"` may still parse at compatibility boundaries, but
|
|
that parse is best-effort and should not be used for new saves.
|
|
|
|
## Workflow Artifact Refs
|
|
|
|
Saved workflow and wrapper capabilities are a separate domain:
|
|
|
|
```json
|
|
{
|
|
"artifact_id": "echo_wrapper",
|
|
"version": 1
|
|
}
|
|
```
|
|
|
|
The display string `workflow.echo_wrapper.v1` remains useful for lists,
|
|
inspection, and old callers, but it is not the canonical saved shape.
|
|
|
|
## Deployment Bindings
|
|
|
|
Deployment bindings map an artifact-local logical source to a concrete source:
|
|
|
|
```json
|
|
{
|
|
"logical_source": "demo",
|
|
"concrete_source": "demo.personal"
|
|
}
|
|
```
|
|
|
|
Neither field is a capability name. Runtime code uses this source mapping before
|
|
looking up the capability key.
|
|
|
|
## Graph Paths
|
|
|
|
Capability refs and graph paths are different domains.
|
|
|
|
Path strings such as `input.text`, `state.person.name`, and `output.echoed`
|
|
describe graph data movement. Do not reuse capability-ref parsing rules for
|
|
graph paths.
|
|
|
|
New canonical graph path JSON uses TOML-key strings:
|
|
|
|
```json
|
|
"input.message"
|
|
```
|
|
|
|
Structural root/parts objects are still accepted at model-parse boundaries and
|
|
are advertised by generated schemas as an input form. Serializers and new
|
|
examples should emit strings.
|
|
Quote a segment when the field name itself contains a dot or space, for example
|
|
`state."person.name"` or `state.person."full name"`.
|
|
|
|
## Authoring Path Inputs
|
|
|
|
`wf_authoring` accepts ergonomic path inputs and normalizes them into the core
|
|
path objects before building canonical node bindings.
|
|
|
|
Single string arguments are TOML key expressions:
|
|
|
|
```python
|
|
state("person.name") # state -> person -> name
|
|
state('"person.name"') # state -> "person.name"
|
|
state('person."full name"') # state -> person -> "full name"
|
|
```
|
|
|
|
Varargs and iterables are literal path segments:
|
|
|
|
```python
|
|
state("person.name", "email") # state -> "person.name" -> email
|
|
state(("person.name",)) # state -> "person.name"
|
|
```
|
|
|
|
Builder canonical bindings use the path kind implied by position:
|
|
|
|
```python
|
|
g.use(
|
|
node,
|
|
input=[
|
|
{
|
|
"target": '"payload.email"',
|
|
"path": 'input."email.address"',
|
|
}
|
|
],
|
|
output=[
|
|
{
|
|
"source": '"result.score"',
|
|
"target": "state.score",
|
|
}
|
|
],
|
|
)
|
|
```
|
|
|
|
In an input binding, `path` is a graph source path and `target` is a
|
|
node-local input path. In an output binding, `source` is a node-local output
|
|
path and `target` is a workflow state destination path.
|
|
|
|
`in_map`, `input_values`, and `out_map` remain deprecated Python sugar for
|
|
concise authoring. Use canonical binding lists when working from JSON/MCP or
|
|
when path segments contain display punctuation.
|
|
|
|
```json
|
|
"state.\"person.name\".\"three and four\""
|
|
```
|
|
|
|
```json
|
|
"."
|
|
```
|
|
|
|
Old strings are accepted at parse boundaries for compatibility. Structural
|
|
`parts` are literal field names, so a part may contain dots or spaces without
|
|
being split again.
|
|
|
|
## Reducer Refs
|
|
|
|
Reducer refs are capability refs, not graph paths. `wf.std.add` is shorthand for
|
|
source `wf.std` and capability key `add`.
|
|
|
|
Configured reducer refs now use a structural `CapabilityRef` while keeping
|
|
string reducer names as parse-only shorthand and display keys. Reducer config
|
|
stays part of the reducer reference payload:
|
|
|
|
```json
|
|
{
|
|
"ref": { "source": "wf.std", "capability_key": "modulo_add" },
|
|
"config": { "modulus": 10 }
|
|
}
|
|
```
|
|
|
|
That shape must not reuse graph path parsing rules. Reducer names live in the
|
|
capability/source domain.
|