Extending Osprey#
A facility can add its own control system, its own logbook, its own health checks and its own panels without forking Osprey. Each of those is a seam: a base class or a registry entry the framework already knows how to load, plus a config key that names your implementation. Deployers configure; developers extend.
This page is the map, not the tutorial. For each seam it names the class or registry to work against, one test that pins that seam’s behaviour, and the how-to a deployer uses to switch your implementation on. The base classes and the tests beside them are written to be read. So the fastest route to working code is to hand both to a coding agent and let it draft against them.
Everything on this page assumes a development checkout — see Development Setup.
Each seam’s registration lives in your deployment’s own registry module. The
framework finds that file through the registry_path key in its
config.yml. Set it in your profile’s config: block, as
registry_path: project/registry.py. application.registry_path is
accepted as an alias, and the REGISTRY_PATH environment variable outranks
both, as Environment Variables records. Without
one of them the framework loads only its own components, and nothing you
register is reachable.
Connector#
A connector is Osprey’s single interface to one control system. Subclass
ControlSystemConnector from osprey_connectors.control_system
— the source lives in
packages/osprey-connectors/src/osprey_connectors/control_system/ — and
return the ChannelValue, ChannelMetadata and ChannelWriteResult
models it defines. A write’s result carries the outcome your connector
determined. Use the shared values_match helper from the same module to
compare what you read back against what was sent. That way your connector
confirms a write exactly as every other one does. Register it with
ConnectorFactory.register_control_system, or ship it as an
osprey.registry.base.ConnectorRegistration passed to
osprey.registry.helpers.extend_framework_registry. Pinning test:
tests/connectors/test_connector_factory.py. What every connector owes its
callers is Connector Contracts; deployers point a project
at yours in Use Connectors.
Archiver#
An archiver connector answers questions about the past instead of the present.
Subclass ArchiverConnector from osprey_connectors.archiver
(alongside the control-system connectors in
packages/osprey-connectors/src/osprey_connectors/archiver/) and register it
the same two ways, with ConnectorFactory.register_archiver or a
ConnectorRegistration whose connector_type is archiver. A deployment
can also select one without registering it, by setting archiver.type to its
dotted module path. Either way it is configured from archiver.settings, which
the factory hands to connect(). The return
shape is a contract of its own: one row per sample, historical enum values
as strings rather than indices. It is written down under “Archiver
Connectors” in Connector Contracts. Pinning test:
tests/connectors/test_archiver_mock_default.py, which holds the
archiver.type key to a fail-closed default so a missing archiver never
looks like a working one.
MCP server#
An MCP server is how new tools reach the agent. Adding an external server
needs no Python at all — it is an entry in the mcp_servers: block of
profile.yml, covered in
Add an MCP Server. A framework server is the
developer seam: a package under src/osprey/mcp_server/ holding a
module-level FastMCP instance and a create_server() factory in
server.py, and one tool per module under tools/. The server also needs
an osprey.registry.mcp.ServerDefinition added to FRAMEWORK_SERVERS in
src/osprey/registry/mcp.py. The controls server
(osprey.mcp_server.control_system) is the canonical example to copy.
Pinning test: tests/registry/test_mcp.py, which resolves those definitions
into the generated agent configuration — permissions, hooks and environment
included.
Chat bridge#
Nextcloud Talk, Google Chat, Microsoft Teams and Slack ship with Osprey;
Mattermost or plain email would each be a new bridge. Almost none of a bridge is per-service —
deduplication, history, retries, honest give-up and crash recovery live in the
engine under src/osprey/bridges/core/. What you write is an arrival loop
and one class, osprey.bridges.core.ports.ChannelOps. Read that module’s
docstring first: it carries the failure contract member by member, and getting
it wrong is the one mistake that leaves a bridge looking healthy while losing
answers. A bridge that can list who is in a conversation also implements the
optional osprey.bridges.core.ports.RoomRoster. The engine then tells the
agent who is in the room. The bridge renders the agent’s <@ID> mentions
in its own chat system’s syntax. Copy src/osprey/bridges/google_chat/,
src/osprey/bridges/nextcloud_talk/, src/osprey/bridges/teams/ or
src/osprey/bridges/slack/, and
expect to touch the build-profile
and injector modules in src/osprey/cli/ so a profile can switch the new
service on. Pinning test: tests/bridges/test_ports.py. Deployers start
from Chat Bridges.
Trigger source#
A trigger source is what wakes the event dispatcher, as a webhook call, a fixed interval or an EPICS channel crossing does. A message queue or a file drop would each be a new one. To write a trigger source:
Write a class matching
osprey.dispatch.sources.base.TriggerSource.Give it a
source_typeclass attribute.Implement
register_routes. It runs before the dispatcher’s app is built, and does something only for a source that serves HTTP routes.Implement
startandstop, which run with the event loop going.startreceives the triggers that name this source and a fire callback.Read each trigger’s own
source_config. For every event the source detects, await the callback with the trigger and a payload mapping.Stamp the event’s instant as a timezone-aware
datetime. The dispatcher stores it as given and shows it to the agent in the facility zone. A time carried as text reaches the agent unchanged.Handle the callback’s result. It returns the queued run’s id, or
Nonewhen the trigger is disabled. It raisesosprey.dispatch.pool.QueueFullErrorwhen the queue is full. What happens then is the source’s decision; every shipped source logs the event and drops it.Declare the class as an entry point (below) and install the package where the dispatcher runs.
A fire from a source is attributed to nobody.
This seam is the exception to the registry-module paragraph that opens this
page: sources are not registered in a registry module. They are found through
a Python package entry point in
[project.entry-points."osprey.trigger_sources"], the group under which
OSPREY’s own pyproject.toml declares its three sources. The entry point’s name is
the source: value a trigger writes.
osprey.dispatch.source_registry.SourceRegistry loads the group when the
dispatcher starts. The dispatcher does not start when an entry point’s
class lacks the three methods, or when one name is claimed by two different
classes.
The package has to be installed wherever the dispatcher runs. A
dispatcher started with python -m osprey.dispatch finds it in that
environment. The image OSPREY builds for the containerized dispatcher
installs OSPREY alone. So a container deployment names an image that carries
the package, through services.event_dispatcher.image
(Overriding Service Images). Copy
src/osprey/dispatch/sources/cron.py for a source with no routes, or
src/osprey/dispatch/sources/webhook.py for one that serves them. Pinning
test: tests/dispatch/test_source_registry.py; deployer view:
Trigger sources.
ARIEL#
ARIEL is the interface to logbook data, and it has three seams:
a facility adapter (
osprey.services.ariel_search.ingestion.base.FacilityAdapter) that reads your logbook and normalises itan enhancement module (
osprey.services.ariel_search.enhancement.base.BaseEnhancementModule) that enriches stored entriesa search module that exposes a new way to query them
All three are registered through
osprey.registry.helpers.extend_framework_registry with the matching
osprey.registry.base.ArielIngestionAdapterRegistration,
ArielEnhancementModuleRegistration or ArielSearchModuleRegistration,
then named from config.yml. Reasoning over ARIEL’s results is a skill in
your build profile, not an ARIEL extension. Pinning test:
tests/registry/test_ariel_module_registrations.py; deployer view:
Data Ingestion.
A facility adapter may also declare the fields an author fills in when writing
an entry. It does so through two optional hooks on the same class:
get_entry_field_descriptors returns ParameterDescriptor declarations
and get_entry_field_options lists a dynamic_select field’s choices.
Both default to declaring nothing, which keeps the built-in entry form. The
declaration checks, the value coercion and the reserved names
(osprey.services.ariel_search.entry_fields.RESERVED_FIELD_NAMES) live in
osprey.services.ariel_search.entry_fields. Pinning tests:
tests/services/ariel_search/test_entry_fields.py and
tests/integration/test_ariel_entry_fields_roundtrip.py; author view: the
Entry Fields section of Data Ingestion.
Health plugin#
Most health checks are declarative YAML. A plugin is for the ones that need real Python — querying a facility service, computing a derived state. To write a health plugin:
Write a module that exposes
get_health_categories(). It returns a mapping of category name to a callable (sync or async) that produces a list ofosprey.health.models.CheckResult.Name the module under
health.plugins, either as a dotted path to an importable module (my_package.health_checks) or as a path to a.pyfile (./health/facility_checks.py).
A relative file path is resolved against the project root, the same anchor
data/ and plans/ use. So a deployment can keep its checks beside its
profile without packaging them or setting PYTHONPATH. A file loaded that
way is given a synthetic module name derived from its path. It is
re-executed every time the health config is reloaded, so it must not keep
state at module level.
osprey.health.plugins.load_plugin_categories loads the plugin, and does so
fail-safe. A plugin that will not import, returns the wrong type, or collides
with an existing category name becomes one error row rather than a crashed
suite.
A category callable normally takes no arguments. An async def one
may instead declare a runtime parameter and receive the suite’s shared
osprey.health.runtime.HealthRuntime. Then await runtime.get_connector()
hands back the one control-system connector the whole run shares, instead of
opening a second Channel Access context. The runtime is valid only for that
call. A sync callable cannot take it: it runs on a worker thread with no event
loop. A sync callable that declares runtime is refused with an error
row saying to make it async def. Pinning test:
tests/health/test_plugins.py. Config side:
Configure Health Checks.
Panel#
A panel is a tab in the Web Terminal. The supported route is the guided skill,
/osprey:panel, whose source is plugins/osprey/skills/panel/. The skill
walks a coding agent through a bundle that already meets every rule: a
directory under the project’s panels/ holding a manifest.json and an
entry HTML file. Discovery is off until a deployer sets
web.allow_runtime_panels, and it is fail-closed, so a malformed bundle is
skipped rather than served. Pinning test:
tests/interfaces/web_terminal/test_panel_discovery.py. What a panel may
and may not do at runtime — notably the proxy’s header stripping, which
rules out backends that authenticate their own callers — is on
Panels.
Login service#
The login service is a closed seam, not a plugin point. It serves exactly the
methods in osprey.services.auth_sidecar.methods.SUPPORTED_METHODS, and a
facility registers no other. A site meets it at two places. One is an OIDC
issuer: a sign-in that is not OIDC is brokered to one. The other is the answer
nginx asks of it, GET /verify with the four headers named in
osprey.services.auth_sidecar.identity_headers, which every terminal decodes
through osprey.interfaces.common_middleware.forwarded_identity. A new login
method is a framework change: it joins SUPPORTED_METHODS and the render
postures in osprey.deployment.web_terminals.render.SUPPORTED_AUTH_METHODS
together, with an audit category of its own. Pinning tests:
tests/services/auth_sidecar/test_methods_parity.py for the method set,
tests/services/auth_sidecar/test_verify.py for the answer, and
tests/deployment/web_terminals/test_nginx_auth_surface.py for nginx’s
side. Deployer view: Require a Login.
LUME model#
The virtual accelerator serves one composite, and each physics model under it
is a lume.model.LUMEModel built by an engine plug-in. The container
always runs the shipped osprey.services.virtual_accelerator.entrypoint; a
different physics backend is a different plug-in, never a different
entrypoint. A different pyAT deck needs no code at all (see “Bringing your own
model” on Virtual Accelerator). The shipped pyat plug-in,
osprey.simulation.engines.pyat, is the reference implementation; the
shipped injection plug-in, osprey.simulation.engines.injection, is the
reference for one that reads no deck and is time-driven.
What a plug-in is given and asked for:
Registration. A plug-in is a module registered under the
osprey.simulation.enginesentry-point group in its package’s ownpyproject.toml, under the name a model record’senginegives. The composite looks it up withmetadata.entry_points(group="osprey.simulation.engines", name=...); an engine no package registers fails that model.Build-time contract.
osprey buildcalls four pure functions of the module, none of which builds a model:locategives an element’s place along the deck.preparechecks the deck against the model’s settings.start_valuesderives each wired channel’s operating point from the deck. A plug-in settingdeckless_start_values = Trueis called withdeckNonefor a model that names no deck.describe(record)says what one wiring record is.
describereturns{engine_role, plane, refresh}:engine_roleissetpoint,readback,monitororoutput.planeisxoryfor a record that steers or reads one transverse plane, elseNone.refreshispassfor a value each write’s solve updates,periodicfor one only the periodic solve publishes,fastfor one read at the fast period, oreventfor one that changes with each event the engine raises.
It may add
marks, a list:commandmarks a write record whose write is a command. The words are the facility schema’s, and a word it does not state stops the build. The build writes the description onto each wiring record, so no reader re-derives it from engine attributes.Build. The composite calls the module’s
build(model, wiring, deck, settings, active=...)once per served model. It returns theLUMEModel. The arguments:wiringis the model’s wiring records from the simulator view’svariables.json.deckis the path of the model’s deck,decks/<model>.<its suffix>, orNonefor a model that names none.settingsis the model record’s settings.activeholds the active scenarios’ setpoint values and fault seeds.
Set and get. The composite reaches the model only through its
set()andget(). Each variable is named for the channel address its wiring record claims, so a plug-in parses no channel names.Report a failed build. A
buildthat raises leaves the model failed. Its<code>:SIM:<model>:STATUSchannel carries the text the module’s optionalerror_text(exc)gives, else the exception’s own text. The rest of the namespace is still served.The contract in code.
osprey.simulation.engines.EnginePluginnames those five functions, andisinstance(module, EnginePlugin)checks a module states them.osprey.simulation.engines.OPTIONAL_NAMESlists every optional name, and the protocol’s docstring says what each gives and what a model whose engine lacks it gets.fault_variablesis called asfault_variables(wiring, settings), with the model’ssettingssecond.The time contract. A model that changes between solves, as an injection chain does during a shot, is time-driven: its engine states the four optional functions
osprey.simulation.engines.TIME_CONTRACTnames.advance(model, t_s)applies every step due by epoch secondt_s;next_deadline(model)gives the next due step’s epoch second, orNone;emitted(model)gives theeventaddresses fired since the last call, cleared;client_write(model, values, t_s)tells the engine a client wrote these setpoints. The model has no thread or clock of its own, and the same calls with the same clock readings always yield the same values. Itssetonly stores values, because restores and scenario writes reach it too; what a client write triggers lives behindclient_writealone.buildreceives no clock, so the composite callsadvanceright after a build, a rebuild or a reset. Only the served venue drives the contract; in process the model serves its start values.Model inputs. An engine whose models read other models’ records states two optional functions.
describe_input(input_record)is called at facility build with one input’s{address, engine}record; raisingValueErrorrefuses it, and the build stopsengine-invalidwith its text, naming the input.take_inputs(model, inputs, t_s, *, baseline)gets one(input_record, value)pair per declared input whose producer has not failed, the value the producer’s current plain value. It only stores, likeset; what a new value starts happens in theadvancethat follows.baseline=Truemarks a starting point: compare nothing against what was held. Theengineblock travelling with each pair is how a model tells its inputs apart;buildis unchanged. A model that declares inputs over an engine withouttake_inputsis refused at build.osprey.simulation.engines.pyatstates both, and the time contract, for a turn-by-turn ring (Turn-by-turn data from an injection chain).The response kind. An optional
response_matrixis called with the keywordkind,"orbit"or"trajectory", and names each corrector without a column inunsolvedwith its text. One whose signature takes nokindis called without it for"orbit"; any other kind is refused as a request, naming the engine, without calling it. Its answer may staterow_positionsandcolumn_positions, one lattice element index per row and per column, counted for"trajectory"from the injection element. An answer without them is served with everypositionnull; positions that do not line up with the rows or columns fail the solve.
What the container keeps the same for every engine:
The environment.
VA_INSTANCEis required;VA_DATA_DIR(default/data) is the data root the simulator view sits under;VA_STATE_DIR,VA_POLL_INTERVAL_S,VA_FAST_INTERVAL_SandVA_MODEL_WRITE_TOKENare read as the entrypoint describes them. Channel Access is served onEPICS_CAS_SERVER_PORT, which the image’s command exports fromEPICS_CA_SERVER_PORT.Clamping. The runner clamps every written setpoint into the
value_rangethe view’s limits records give it before anything else happens to the value. The connector’s ownlimits_checkingis separate and unchanged.The ready line. Once the first publishing pass has published, the entrypoint prints one line starting with
osprey.services.virtual_accelerator.entrypoint.READY_MARKER(virtual accelerator IOC serving PVs), followed by: <N> channels. The image boot check and the container test fixtures wait on that line and read the count out of it. A first pass that fails exits non-zero without it.SIGTERM. The image’s command
execs Python, so the entrypoint is the container’s first process. It receivesdocker stop’s SIGTERM itself. It handles SIGTERM as it handles SIGINT and leaves through the runner’s own exit.One image for every instance. With a live stand-in, both containers run the same image and the same entrypoint;
VA_INSTANCEtells them apart.
tests/va/test_entrypoint.py pins what the shipped entrypoint reads and
refuses. How to deploy a plug-in is in Serving your facility’s own model.
Measurement kind#
A measurement kind is an osprey.facility.kinds.KindDeclaration registered
under the osprey.facility.kinds entry-point group in its package’s
pyproject.toml; OSPREY’s shipped kinds are entry points of the same group.
The package is installed where osprey build runs and in the project image,
through the profile’s dependencies. Pinning test:
tests/facility/test_fixture_kind_deployment.py, whose package under
tests/facility/fixtures/fixture_kind/ registers a kind and an engine. The
contract: Facility Kinds Contract; step by step:
Register a measurement kind.
Agent harness#
The agent harness is not a seam. Osprey ships one harness, Claude Code, and
there is no configuration key or base class for choosing another. What the
codebase keeps instead is a boundary: the code specific to Claude Code lives in
one package, src/osprey/agent_runner/, and the rest of the framework reaches
the agent through it. That package owns:
the Agent SDK calls.
osprey.agent_runner.run_queryandosprey.agent_runner.stream_queryrun one prompt,osprey.agent_runner.agent_sessionholds a conversation of many turns, and each hands its caller the plain event records ofosprey.agent_runner.eventsrather than SDK types;the command line that starts the CLI: its program name, its flags and the resolution of its bare name (
src/osprey/agent_runner/launcher.py);the provider and model environment the agent is launched with (
src/osprey/agent_runner/provider_env.py);the first-run state the CLI expects in
.claude.json, and the suffix that names each user’s state volume (src/osprey/agent_runner/claude_state.py);the catalog of files a build writes for the CLI (
src/osprey/agent_runner/build_artifacts/);the built-in tool names every deny list is made of (
src/osprey/agent_runner/tool_names.py), and the permission hook and callback of a dispatched run (src/osprey/agent_runner/tool_policy.py).
The templates a build renders for the CLI — settings, hooks, rules, agents and
skills — are Claude Code’s own file formats and stay with the other templates,
in src/osprey/templates/claude_code/. The deny list in the rendered settings
comes from src/osprey/agent_runner/tool_names.py.
A lint holds the boundary. Ruff’s banned-api rule (TID251, configured in
pyproject.toml) refuses an import of claude_agent_sdk anywhere in
src/ or packages/ outside the adapter. The unit suite refuses the
same import, including the dynamic imports ruff cannot see. No module is exempt
by name. Tests and developer scripts sit outside the shipped trees and drive the
SDK directly. New code that needs the agent calls the adapter; a Claude-specific
need the adapter does not meet yet is added to the adapter, not written inline
where it is needed. Pinning test: tests/test_harness_fence.py.