This release is a pre-release and may not be stable for production use.
Osprey
An agentic interface to scientific control systems.
Osprey addresses control-specific challenges: semantic addressing across large channel namespaces, protocol-agnostic integration with control stacks, logbook search across facility electronic logbooks, and mandatory human oversight for every hardware write.
Built for large scientific facilities, such as particle accelerators.
Quick start
# Install the framework as a standalone CLI tool (using uv, recommended).
# A pre-release needs the flag: uv tool install --prerelease allow osprey-framework
uv tool install osprey-framework
# Create a minimal deployment repo to verify your setup
osprey init quickstart --preset hello-world
cd quickstart
# init seeds .env from the provider keys your shell exports, and says so.
# When it reports none, copy the example and fill it in:
# cp .env.example .env
# Render the deployment, then open the web terminal
osprey build
osprey web
For a deployment tailored to your detector, beamline, or accelerator subsystem, install the
osprey plugin and run its guided install skill from your agent session:
claude plugin marketplace add als-apg/osprey --sparse .claude-plugin plugins
claude plugin install osprey@osprey
Then start the agent in an empty directory and type /osprey:install. The skill
walks you through a guided conversation and produces the deployment repository — a git
repository whose profile.yml is the source of truth. From inside it, osprey build
renders the ready-to-run deployment into build/.
Key features
- Agent-driven orchestration — Skills, MCP tools, and explicit dependency declarations let the Osprey agent decompose operator requests into auditable steps with mandatory approval gates.
- Control-system safety — Pattern detection, channel boundary checking, and mandatory human approval for every hardware write.
- Protocol-agnostic integration — EPICS, DOOCS, TANGO, and Mock connectors ship in-tree; LabVIEW and other stacks connect through the connector interface.
- Replaceable backends — The agent harness, the underlying model, and the compute backend are each swappable by configuration, without changing what the operator sees.
- Scalable capability management — Dynamic classification prevents prompt explosion as toolsets grow.
Documentation
Osprey follows CalVer (vYYYY.M.P). Public APIs may change between releases — pin a version
and check the changelog before upgrading.
Contributing
Contributions are welcome. See the Contributing Guide for development setup, coding standards, and the pull-request workflow. To report a security issue, please follow the security policy rather than opening a public issue.
Citation
If you use Osprey in your research, please cite the paper. GitHub's Cite this repository button, in the sidebar, exports BibTeX and APA directly.
License
BSD 3-Clause — see LICENSE.txt. Additional notices, including the U.S. Department of Energy's retained rights and Berkeley Lab's Enhancements grant, are in NOTICE.
Copyright (c) 2025, The Regents of the University of California, through Lawrence Berkeley National Laboratory (subject to receipt of any required approvals from the U.S. Dept. of Energy). All rights reserved.
Questions about your rights to use or distribute this software: contact Berkeley Lab's Intellectual Property Office at IPO@lbl.gov.
Release files for osprey-framework 2026.9.0b3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| osprey_framework-2026.9.0b3.tar.gz | 22.9 MB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| osprey_framework-2026.9.0b3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 30.8 MB
Release files / osprey_framework-2026.9.0b3.tar.gz
| Download URL | osprey_framework-2026.9.0b3.tar.gz |
|---|---|
| Size | 22.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
dd314e1e4489e1382aa5f515336346c211ba73fcb70d3bf1ae5293612a2c3529
|
|
BLAKE2b-256 checksum How to use checksums |
7f1c83dc2a3bdb73893c61098a8319c917d896cd38175f8e839207c599a369dc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.
Transparency logRelease files / osprey_framework-2026.9.0b3-py3-none-any.whl
| Download URL | osprey_framework-2026.9.0b3-py3-none-any.whl |
|---|---|
| Size | 7.9 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0f7efae4e93445ad5eec9457f4c262f20f36ac1aeeba7370a3fd8562ece03fe0
|
|
BLAKE2b-256 checksum How to use checksums |
2a662c4073bf0a1a160705dddf47458b69039dc34c878d172607d4463a2c6873
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.
Transparency logSecurity for osprey-framework 2026.9.0b3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for osprey_framework-2026.9.0b3.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
