Channel Finder Contracts#
The Channel Finder runs one of four pipelines — in-context, hierarchical,
middle-layer, or graph — and each paradigm has its own database contract:
the shape of what the pipeline reads is part of choosing it. This page gives
the four contracts, the config.yml keys that select a pipeline and point it
at its database, and how the active pipeline reaches the agent. For the task
of choosing and running one, see How to Use the Channel Finder.
Database Contracts, per Paradigm#
In-context#
A flat JSON structure, the index osprey build writes from every channel, or
from the subset the facility tags in_context: one row per channel, sorted by
address, loaded by the flat ChannelDatabase. A row’s channel is the
channel’s label, else its address:
{
"schema": "osprey.facility.channel_finder/1",
"count": 1,
"channels": [
{"channel": "TerminalVoltageReadBack",
"address": "TerminalVoltageReadBack",
"description": "Actual value of the terminal potential"}
]
}
count is the number of rows.
Hierarchical#
Declares the levels the pipeline navigates and the naming pattern the addresses follow, with the tree itself underneath:
{
"hierarchy": {
"levels": [
{"name": "system", "type": "tree"},
{"name": "family", "type": "tree"},
{"name": "device", "type": "instances"},
{"name": "field", "type": "tree"},
{"name": "subfield", "type": "tree"}
],
"naming_pattern": "{system}:{family}[{device}]:{field}:{subfield}"
},
"tree": {
"SR": {
"_description": "Storage ring",
"BPM": {
"_description": "Beam position monitors",
"DEVICE": {
"_expansion": {"_type": "range", "_pattern": "{:02d}", "_range": [1, 2]},
"X": {
"_description": "Horizontal position",
"RB": {"_description": "Readback"}
}
}
}
}
}
}
An instances level is a node named after the level in capitals (DEVICE
here), whose _expansion lists the instances. This tree holds two channels,
SR:BPM[01]:X:RB and SR:BPM[02]:X:RB.
Middle-layer#
MATLAB Middle Layer (MML) style organization: channels grouped by functional
hierarchy — system, family, field, optional subfield — rather than by naming
pattern, with the addresses listed under a channel key and the family’s device
roster in its setup block:
{
"_provenance": "exporter=1.2.0 ao_sha256=1f4b… mapping_sha256=9c07…",
"SR": {
"BPM": {
"Monitor": {
"ChannelNames": ["SR01C:BPM1:X", "SR01C:BPM1:Y"],
"TangoNames": ["sr/bpm/1/X", "sr/bpm/1/Y"]
},
"Setpoint": {
"X": {"ChannelNames": ["SR01C:BPM1:XSet"]},
"Y": {"ChannelNames": ["SR01C:BPM1:YSet"]}
},
"setup": {
"CommonNames": ["BPM 1", "BPM 2"],
"DeviceList": [[1, 1], [1, 2]]
}
}
}
}
DeviceList holds [place index, ordinal] pairs: the device’s place
numbered among its sibling places at the same level, by beam position, and the
device’s ordinal inside that place. A device whose place has no sibling places
— one at the machine itself, or with no place — has place index 0, and those
devices are numbered together, so no two rows of a family are equal.
Only a device with a channel is listed: a rack, a supply or a host with none
is in no family, and a system or family left without a device is absent.
PlaceList, when present, holds each device’s place beside its row.
It is parallel to CommonNames, which is each device’s label, else its id.
An existing MML export keeps its metadata keys (Units, DataType,
Description, …) — the pipeline skips them during navigation rather than
requiring their removal.
Two channel keys, one per protocol. A field lists its addresses under
ChannelNames (Channel Access) or TangoNames (Tango device attributes),
or under both when the same signal is reachable either way. Each channel the
pipeline loads carries a protocol of ca or tango accordingly, so a
database can describe a facility that runs both. The list_channels tool
takes a protocol argument to pick between them; without one it returns the
ChannelNames list, and asking for a protocol the field does not carry is an
error naming the keys it does.
The row count. Every index osprey build writes states count beside
schema: the rows of an in-context index, the leaves of a hierarchical
tree, the distinct addresses listed under the fields of a middle-layer index
(a channel of no family is not counted). osprey channel-finder benchmark
records it as the run’s channel_count and refuses an index that does not
state it; in graph mode the number is the store’s channel count. A
middle-layer System cannot be named schema or count.
Graph#
The graph pipeline has no channel database of its own: the facility graph
describes the machine. Its contract is the graph schema documented in
Search the Facility Graph, carried by the Turtle
corpus osprey build writes from the facility file into
data/graph/facility.ttl. The build writes that path into every rendered
services.graphdb block as ttl_path unless the profile names a corpus of
its own. osprey up loads that corpus into the services.graphdb store.
The corpus is the source of truth, and two things are built from it. The store
answers questions about structure — which device an address belongs to, what a
class is a kind of — and the device card and the agent’s Cypher tools read it.
osprey build also derives a flat search index from the same file, and every
render with a services.graphdb block ships that index as
data/channel_databases/graph.duckdb under the render, a fixed path no key
moves. Nothing parses the corpus while the deployment runs; osprey build &&
osprey up rebuilds the index and reseeds the store from the same file, so the
two agree.
The deployment’s channel roster — the one answer to which channels the
facility has, and which of them are written — is the facility file
(facility.json) the build writes at the root of the render, not the corpus
or the index. The web interface enumerates and validates against it, and
osprey build derives the queue server’s plan devices from it
(Write Your Own Plans).
Configuration Reference#
Key config.yml settings:
channel_finder:
pipeline_mode: in_context # "in_context", "hierarchical", "middle_layer", or "graph"
pipelines:
in_context:
database: {path: data/channel_finder/in_context.json}
hierarchical:
database: {path: data/channel_finder/hierarchical.json}
middle_layer:
database:
path: data/channel_finder/middle_layer.json
duckdb_path: data/channel_finder/middle_layer.duckdb
# graph has no entry: it is configured by the `services.graphdb` block.
benchmark:
# Stated by the build when the facility ships benchmark query sources;
# the benchmarks view writes the mode's query file here.
dataset_path: data/benchmarks/queries.json
# Concurrency and output dir are set per run via CLI flags
# (osprey channel-finder benchmark --concurrency / --output-dir);
# they are not read from config.yml.
Three of the four pipelines name the database they read, so a build renders the
one block its mode needs. Graph mode renders none: pipeline_mode: graph plus
the services.graphdb block is its whole configuration.
Framework Integration#
Each pipeline ships as its own MCP server package
(channel_finder_in_context, channel_finder_hierarchical,
channel_finder_middle_layer, channel_finder_graph), and whichever one
channel_finder.pipeline_mode names in config.yml is served to the agent
under the single name channel-finder — so the tools change with the mode
but the server the agent reaches does not. It is wired into the agent’s
artifacts when you run osprey build, and rebuilt by the next
osprey build after you edit the config. There is no public Python
find_channels(...) entry point — drive the resolver from natural
language via the agent, or invoke the CLI directly:
osprey channel-finder validate # check the configured database
osprey channel-finder benchmark # evaluate on a query dataset