Metadata-Version: 2.5
Name: osprey-framework
Version: 2026.9.0b3
Summary: An agentic interface to scientific control systems
Project-URL: Homepage, https://als-apg.github.io/osprey
Project-URL: Documentation, https://als-apg.github.io/osprey
Project-URL: Repository, https://github.com/als-apg/osprey
Project-URL: Paper, https://doi.org/10.1063/5.0306302
Project-URL: Issues, https://github.com/als-apg/osprey/issues
Project-URL: Changelog, https://github.com/als-apg/osprey/blob/main/CHANGELOG.md
Author-email: Thorsten Hellert <thellert@lbl.gov>
Maintainer-email: Thorsten Hellert <thellert@lbl.gov>
License: BSD-3-Clause
License-File: LICENSE.txt
License-File: NOTICE
Keywords: accelerator-physics,agent-framework,agents,ai,als,berkeley,container-orchestration,control-systems,epics,framework,human-in-the-loop,mcp,scientific-computing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.11
Requires-Dist: accelerator-toolbox[plot]>=0.8.0
Requires-Dist: aiofiles>=25.1.0
Requires-Dist: aiohttp-socks>=0.8.0
Requires-Dist: aiohttp>=3.14.3
Requires-Dist: anthropic
Requires-Dist: authlib>=1.7.2
Requires-Dist: bluesky-queueserver-api==0.0.13
Requires-Dist: bluesky-tiled-plugins==2.0.9
Requires-Dist: bluesky>=1.15.1
Requires-Dist: bokeh>=3.9.1
Requires-Dist: build
Requires-Dist: certifi>=2026.7.22
Requires-Dist: charset-normalizer>=3.4.9
Requires-Dist: claude-agent-sdk==0.2.136
Requires-Dist: click>=8.4.2
Requires-Dist: duckdb>=1.5.4
Requires-Dist: fastapi>=0.141.1
Requires-Dist: fastmcp>=3.4.4
Requires-Dist: google-generativeai
Requires-Dist: httpx>=0.28.1
Requires-Dist: idna>=3.18
Requires-Dist: ipykernel
Requires-Dist: ipywidgets
Requires-Dist: itsdangerous>=2.2.0
Requires-Dist: jinja2>=3.1.6
Requires-Dist: jupyter-server<3,>=2.21
Requires-Dist: jupyterlab<5,>=4.6
Requires-Dist: litellm>=1.56.0
Requires-Dist: lume-base==0.5.0
Requires-Dist: lume-pyat==0.1.0
Requires-Dist: markdown>=3.5
Requires-Dist: markupsafe>=3.0.2
Requires-Dist: matplotlib>=3.11.1
Requires-Dist: nbclient
Requires-Dist: nbconvert>=7.0.0
Requires-Dist: nbformat>=5.0.0
Requires-Dist: neo4j>=5.20
Requires-Dist: nltk>=3.10.0
Requires-Dist: numpy>=2.2.6
Requires-Dist: ollama>=0.6.2
Requires-Dist: openai<3,>=2.53.0
Requires-Dist: ophyd-async[ca]<1.0,>=0.16
Requires-Dist: osprey-connectors!=2026.6.2a0,>=2026.6.2
Requires-Dist: pandas>=2.2.3
Requires-Dist: playwright>=1.61.0
Requires-Dist: plotly>=6.9.0
Requires-Dist: psycopg-pool<4.0.0,>=3.3.1
Requires-Dist: psycopg[binary,pool]<4.0.0,>=3.3.4
Requires-Dist: pyepics
Requires-Dist: pymongo>=4.17.0
Requires-Dist: python-dateutil>=2.9.0
Requires-Dist: python-dotenv>=1.1.0
Requires-Dist: python-multipart>=0.0.18
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: questionary>=2.1.1
Requires-Dist: rdflib>=7.0
Requires-Dist: requests>=2.34.2
Requires-Dist: rich>=15.0.0
Requires-Dist: ruamel-yaml>=0.18.0
Requires-Dist: scikit-learn
Requires-Dist: scipy>=1.17.1
Requires-Dist: seaborn
Requires-Dist: tenacity>=9.1.4
Requires-Dist: tiled[client]>=0.2.14
Requires-Dist: typing-extensions>=4.16.0
Requires-Dist: unique-namer>=1.6.2
Requires-Dist: urllib3>=2.7.0
Requires-Dist: uvicorn[standard]>=0.52.1
Requires-Dist: watchdog>=6.0.0
Requires-Dist: websocket-client>=1.7.0
Requires-Dist: websockets>=14
Provides-Extra: all
Requires-Dist: azure-servicebus>=7.11; extra == 'all'
Requires-Dist: docker>=7.2.0; extra == 'all'
Requires-Dist: google-api-python-client>=2.100; extra == 'all'
Requires-Dist: google-auth>=2.56.3; extra == 'all'
Requires-Dist: google-cloud-pubsub>=2.18; extra == 'all'
Requires-Dist: google-cloud-storage>=2.10; extra == 'all'
Requires-Dist: graphviz; extra == 'all'
Requires-Dist: gspread>=6.2.1; extra == 'all'
Requires-Dist: linkml-runtime<2,>=1.11.1; extra == 'all'
Requires-Dist: mss>=10.2.0; extra == 'all'
Requires-Dist: mypy; extra == 'all'
Requires-Dist: myst-parser; extra == 'all'
Requires-Dist: pillow>=10; extra == 'all'
Requires-Dist: pillow>=12.3.0; extra == 'all'
Requires-Dist: pre-commit; extra == 'all'
Requires-Dist: psycopg-pool<4.0.0,>=3.3.1; extra == 'all'
Requires-Dist: psycopg[binary,pool]<4.0.0,>=3.3.4; extra == 'all'
Requires-Dist: psycopg[pool]<4.0.0,>=3.1.0; extra == 'all'
Requires-Dist: pydata-sphinx-theme; extra == 'all'
Requires-Dist: pyjwt[crypto]>=2.8; extra == 'all'
Requires-Dist: pysocks>=1.7; extra == 'all'
Requires-Dist: pytest; extra == 'all'
Requires-Dist: pytest-asyncio; extra == 'all'
Requires-Dist: pytest-cov; extra == 'all'
Requires-Dist: pytest-order; extra == 'all'
Requires-Dist: pytest-rerunfailures; extra == 'all'
Requires-Dist: pytest-timeout; extra == 'all'
Requires-Dist: pytest-xdist; extra == 'all'
Requires-Dist: python-xlib>=0.33; extra == 'all'
Requires-Dist: ruff<0.17,>=0.16.2; extra == 'all'
Requires-Dist: setuptools-scm; extra == 'all'
Requires-Dist: sphinx-autobuild; extra == 'all'
Requires-Dist: sphinx-copybutton; extra == 'all'
Requires-Dist: sphinx-design; extra == 'all'
Requires-Dist: sphinx-reredirects==1.1.0; extra == 'all'
Requires-Dist: sphinx>=9.0.4; extra == 'all'
Requires-Dist: sphinxcontrib-jsmath>=1.0.1; extra == 'all'
Requires-Dist: testcontainers[mongodb]>=4.15.0; extra == 'all'
Requires-Dist: testcontainers[postgres]>=4.15.0; extra == 'all'
Requires-Dist: types-aiofiles; extra == 'all'
Requires-Dist: types-markdown; extra == 'all'
Requires-Dist: types-pyyaml; extra == 'all'
Provides-Extra: ariel
Requires-Dist: psycopg-pool<4.0.0,>=3.3.1; extra == 'ariel'
Requires-Dist: psycopg[pool]<4.0.0,>=3.1.0; extra == 'ariel'
Provides-Extra: ariel-proxy
Requires-Dist: aiohttp-socks>=0.8.0; extra == 'ariel-proxy'
Provides-Extra: dev
Requires-Dist: docker>=7.2.0; extra == 'dev'
Requires-Dist: linkml-runtime<2,>=1.11.1; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pillow>=12.3.0; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: psycopg-pool<4.0.0,>=3.3.1; extra == 'dev'
Requires-Dist: psycopg[binary,pool]<4.0.0,>=3.3.4; extra == 'dev'
Requires-Dist: pyjwt[crypto]>=2.8; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest-order; extra == 'dev'
Requires-Dist: pytest-rerunfailures; extra == 'dev'
Requires-Dist: pytest-timeout; extra == 'dev'
Requires-Dist: pytest-xdist; extra == 'dev'
Requires-Dist: ruff<0.17,>=0.16.2; extra == 'dev'
Requires-Dist: setuptools-scm; extra == 'dev'
Requires-Dist: testcontainers[mongodb]>=4.15.0; extra == 'dev'
Requires-Dist: testcontainers[postgres]>=4.15.0; extra == 'dev'
Requires-Dist: types-aiofiles; extra == 'dev'
Requires-Dist: types-markdown; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Provides-Extra: docs
Requires-Dist: graphviz; extra == 'docs'
Requires-Dist: myst-parser; extra == 'docs'
Requires-Dist: pydata-sphinx-theme; extra == 'docs'
Requires-Dist: sphinx-autobuild; extra == 'docs'
Requires-Dist: sphinx-copybutton; extra == 'docs'
Requires-Dist: sphinx-design; extra == 'docs'
Requires-Dist: sphinx-reredirects==1.1.0; extra == 'docs'
Requires-Dist: sphinx>=9.0.4; extra == 'docs'
Requires-Dist: sphinxcontrib-jsmath>=1.0.1; extra == 'docs'
Provides-Extra: gchat
Requires-Dist: google-api-python-client>=2.100; extra == 'gchat'
Requires-Dist: google-auth>=2.56.3; extra == 'gchat'
Requires-Dist: google-cloud-pubsub>=2.18; extra == 'gchat'
Requires-Dist: google-cloud-storage>=2.10; extra == 'gchat'
Requires-Dist: pysocks>=1.7; extra == 'gchat'
Provides-Extra: knowledge
Requires-Dist: linkml-runtime<2,>=1.11.1; extra == 'knowledge'
Provides-Extra: screen-capture-linux
Requires-Dist: mss>=10.2.0; extra == 'screen-capture-linux'
Requires-Dist: python-xlib>=0.33; extra == 'screen-capture-linux'
Provides-Extra: sheets
Requires-Dist: gspread>=6.2.1; extra == 'sheets'
Provides-Extra: teams
Requires-Dist: azure-servicebus>=7.11; extra == 'teams'
Requires-Dist: pillow>=10; extra == 'teams'
Provides-Extra: virtual-accelerator
Requires-Dist: aioca>=1.7; extra == 'virtual-accelerator'
Requires-Dist: lume-pva-apg[ca,pva]==0.1.4; (sys_platform == 'linux' and platform_machine == 'x86_64') and extra == 'virtual-accelerator'
Requires-Dist: pcaspy>=0.8.1; (sys_platform == 'linux' and platform_machine == 'x86_64') and extra == 'virtual-accelerator'
Description-Content-Type: text/markdown

# Osprey

[![CI](https://github.com/als-apg/osprey/actions/workflows/ci.yml/badge.svg)](https://github.com/als-apg/osprey/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/osprey-framework)](https://pypi.org/project/osprey-framework/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: BSD 3-Clause](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](LICENSE.txt)
[![DOI](https://img.shields.io/badge/DOI-10.1063%2F5.0306302-blue)](https://doi.org/10.1063/5.0306302)
[![Documentation](https://img.shields.io/badge/docs-als--apg.github.io%2Fosprey-blue)](https://als-apg.github.io/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.

<p align="center">
  <img src="docs/source/_static/resources/architecture.png" width="100%"
       alt="Osprey system architecture, from operator to facility, with the safety gate and approval workflow in-line." />
</p>

## Quick start

```bash
# 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:

```bash
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](https://als-apg.github.io/osprey/contributing/extending-osprey.html).
- **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

**[Read the full documentation →](https://als-apg.github.io/osprey)**

Osprey follows CalVer (`vYYYY.M.P`). Public APIs may change between releases — pin a version
and check the [changelog](CHANGELOG.md) before upgrading.

## Contributing

Contributions are welcome. See the [Contributing Guide](CONTRIBUTING.md) for development
setup, coding standards, and the pull-request workflow. To report a security issue, please
follow the [security policy](SECURITY.md) rather than opening a public issue.

## Citation

If you use Osprey in your research, please cite the
[paper](https://doi.org/10.1063/5.0306302). GitHub's **Cite this repository** button, in the
sidebar, exports BibTeX and APA directly.

## License

BSD 3-Clause — see [LICENSE.txt](LICENSE.txt). Additional notices, including the
U.S. Department of Energy's retained rights and Berkeley Lab's Enhancements grant, are in
[NOTICE](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.
