pyproject.toml

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "osprey-framework"
dynamic = ["version"]
description = "An open-source, domain-agnostic, capability-based architecture for building intelligent agents"
readme = "README.md"
requires-python = ">=3.11"
license = {text = "BSD-3-Clause"}
authors = [
    {name = "Thorsten Hellert", email = "thellert@lbl.gov"},
]
maintainers = [
    {name = "Thorsten Hellert", email = "thellert@lbl.gov"},
]
keywords = [
    "ai", "agents", "framework", "scientific-computing",
    "epics", "accelerator-physics", "als", "berkeley", "agent-framework",
    "capability-based", "human-in-the-loop", "container-orchestration"
]
classifiers = [
    "Development Status :: 3 - Alpha",
    "Intended Audience :: Developers",
    "Intended Audience :: Science/Research",
    "License :: OSI Approved :: BSD License",
    "Operating System :: OS Independent",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Topic :: Scientific/Engineering",
    "Topic :: Scientific/Engineering :: Physics",
    "Topic :: Software Development :: Libraries :: Python Modules",
    "Topic :: System :: Distributed Computing",
]

# Core runtime dependencies from requirements.txt analysis
dependencies = [
    # Core framework dependencies
    "rich>=14.0.0",
    "click>=8.1.0",
    "questionary>=2.0.0",
    "python-dotenv>=1.1.0",
    "PyYAML>=6.0.2",
    "ruamel.yaml>=0.18.0",  # Comment-preserving YAML for config updates
    "Jinja2>=3.1.6",
    "requests>=2.32.3",
    # Container runtime (Docker or Podman) must be installed separately via system package managers
    # Framework uses CLI tools (docker/podman commands), not Python packages
    # Install Docker Desktop 4.0+ OR Podman 4.0+:
    #   - Docker: https://docs.docker.com/get-docker/
    #   - Podman: https://podman.io/getting-started/installation
    # Jupyter notebook support
    "nbformat>=5.0.0",
    "nbclient",
    "nbconvert>=7.0.0",
    # AI/ML provider integrations
    "litellm>=1.56.0",  # Unified LLM provider interface (100+ providers)
    "openai>=2",
    "anthropic",
    "google-generativeai",
    "ollama>=0.5.1",
    # Advanced code generation
    # Claude Code SDK - pinned. Bundles CLI 2.1.167 (verified to work with
    # als-apg routing). >=0.1.46 needed for list_subagents/
    # get_subagent_messages, which the e2e trace collector uses to read sub-agent
    # transcripts (CLI >=2.1.x no longer streams them through query()).
    "claude-agent-sdk==0.2.106",
    # Data processing - required for archiver connectors and data handling
    # Archiver connectors return pandas DataFrames for time-series data
    "pandas>=2.2.3",
    "numpy>=2.2.6",  # Required by pandas
    "matplotlib>=3.10.3",  # Required for Python capability visualization (core use case)
    # Networking and protocols
    "aiohttp>=3.10",  # Required by litellm (ConnectionTimeoutError added in 3.10)
    "websocket-client>=1.7.0",
    "urllib3>=2.4.0",
    "certifi>=2025.4.26",
    "charset-normalizer>=3.4.2",
    "idna>=3.10",
    "MarkupSafe>=3.0.2",
    "markdown>=3.5",  # Markdown-to-HTML rendering for artifact converters
    "aiofiles>=24.1.0",  # Async file I/O for non-blocking Python executor
    # MCP server development (for building MCP servers)
    "fastmcp>=3.0.0",
    # Scientific computing stack - for Python execution capability
    "scipy>=1.15.3",
    "seaborn",
    "scikit-learn",
    "plotly>=5.0.0",
    "bokeh>=3.0",  # Interactive dashboards (data-visualizer agent)
    "playwright>=1.40.0",
    "ipywidgets",  # Interactive widgets for Jupyter notebooks
    # Natural language processing
    "nltk>=3.8.1",
    # ARIEL Web Interface (FastAPI server)
    "fastapi>=0.109.0",
    "uvicorn[standard]>=0.27.0",
    # Utilities
    "unique-namer>=0.1.0",
    # EPICS Channel Access client (used by control_system connector,
    # limits_validator, and python_executor wrapper).
    "pyepics",
    # PostgreSQL (required for native logbook_search capability and checkpointing)
    "psycopg[binary,pool]>=3.1.0,<4.0.0",
    "psycopg-pool>=3.1.0,<4.0.0",
    # ARIEL proxy support for HTTP ingestion through SOCKS tunnels
    "aiohttp-socks>=0.8.0",
    # File system monitoring for web terminal
    "watchdog>=3.0.0",
    # Async HTTP client for tuning panel reverse proxy
    "httpx>=0.27.0",
    # Lattice physics (Accelerator Toolbox for lattice dashboard)
    "accelerator-toolbox[plot]",
    "duckdb>=1.5.1",
    "tenacity>=9.1.4",
    # Cross-version TypedDict/NotRequired — pydantic v2.12 rejects typing.TypedDict on py<3.12.
    "typing_extensions>=4.12.0",
]

[project.optional-dependencies]
# Documentation dependencies (for building docs only)
docs = [
    "sphinx>=8.0.0",
    "pydata-sphinx-theme",
    "myst-parser",
    "sphinx-copybutton",
    "sphinx-autobuild",
    "sphinx-design",
    "sphinxcontrib-mermaid",
    "sphinxcontrib-jsmath>=1.0.1",
    "graphviz",
]

# Development and testing
dev = [
    "pytest",
    "pytest-asyncio",
    "pytest-cov",  # Code coverage reporting
    "pytest-order",  # Run flaky/in-debug e2e tests first via @pytest.mark.order
    "pytest-rerunfailures",  # Absorb rare LLM nondeterminism in agentic e2e via @pytest.mark.flaky
    "pytest-timeout",  # Deadlock-breaker for the model-matrix benchmark runner (--timeout)
    "mypy",
    "pre-commit",
    "ruff",
    "build",  # Required for 'osprey deploy up --dev' to build local wheel
    "testcontainers[postgres]>=4.0.0",  # Real PostgreSQL for integration tests
    "testcontainers[mongodb]>=4.0.0",  # MongoDB for archiver-mongodb integration tests
    "docker>=7.0.0",  # Docker SDK for testcontainers availability check
    "psycopg[binary,pool]>=3.1.0,<4.0.0",  # ARIEL search integration tests
    "psycopg-pool>=3.1.0,<4.0.0",  # ARIEL search integration tests
]

# ARIEL (Agentic Retrieval Interface for Electronic Logbooks)
# See _ISSUES/MAJOR/ARIEL/ for specification
ariel = [
    # PostgreSQL with pgvector for vector similarity search
    "psycopg[pool]>=3.1.0,<4.0.0",
    "psycopg-pool>=3.1.0,<4.0.0",
]

# ARIEL proxy support for HTTP ingestion through SOCKS tunnels
ariel-proxy = [
    "aiohttp-socks>=0.8.0",
]

# Google Sheets database backend for channel finder
sheets = [
    "gspread>=6.0.0",
]

# MongoDB archiver connector backend
archiver-mongodb = [
    "pymongo>=4.0",
]

# Facility knowledge / ontology support (OKF markdown bundles, RDF reasoning)
knowledge = [
    "rdflib>=7.0",
]

# Screen capture on Linux (X11) — not needed on macOS
screen-capture-linux = [
    "mss>=9.0.0",
    "python-xlib>=0.33",
]

# All optional dependencies for complete installation
all = [
    "osprey-framework[docs,dev,ariel,sheets,screen-capture-linux,archiver-mongodb,knowledge]"
]

[project.urls]
Homepage = "https://als-apg.github.io/osprey"
Documentation = "https://als-apg.github.io/osprey"
Repository = "https://github.com/als-apg/osprey"
Paper = "https://doi.org/10.1063/5.0306302"
Issues = "https://github.com/als-apg/osprey/issues"
Changelog = "https://github.com/als-apg/osprey/blob/main/CHANGELOG.md"

# Define console scripts for CLI entry points
[project.scripts]
# Main CLI entry point (Click group with subcommands)
osprey = "osprey.cli.main:cli"

# Built-in trigger sources for the event dispatcher, discovered by
# osprey.dispatch.source_registry.SourceRegistry at startup.
[project.entry-points."osprey.trigger_sources"]
webhook = "osprey.dispatch.sources.webhook:WebhookSource"
cron = "osprey.dispatch.sources.cron:CronSource"
epics_ca = "osprey.dispatch.sources.epics_ca:EpicsCaSource"

# Hatchling build configuration
[tool.hatch.version]
path = "src/osprey/__init__.py"

[tool.hatch.build.targets.wheel]
packages = ["src/osprey"]

# Development tool configurations
[tool.mypy]
python_version = "3.11"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = false  # Gradual typing
ignore_missing_imports = true
exclude = [
    "build/",
    "dist/",
    "venv/",
    "_agent_data/",
    "__pycache__/",
]

# Specific modules to ignore due to optional dependencies
[[tool.mypy.overrides]]
module = [
    "openai.*",
    "anthropic.*",
    "google.*",
    "ollama.*",
    "litellm.*",
    "pandas.*",
    "numpy.*",
    "matplotlib.*",
    "pyepics.*",
    "podman.*",
    "pymongo.*",
]
ignore_missing_imports = true

[tool.pytest.ini_options]
minversion = "6.0"
addopts = "-ra -v --tb=short --strict-markers --color=yes"
testpaths = [
    "tests",
    "src/applications/*/tests"
]
python_files = [
    "test_*.py",
    "*_test.py"
]
python_classes = ["Test*"]
python_functions = ["test_*"]
asyncio_mode = "auto"
# WARNING: E2E tests MUST be run with 'pytest tests/e2e/' NOT 'pytest -m e2e'
# See tests/e2e/README.md for details
markers = [
    "unit: Unit tests (mocked, no external dependencies)",
    "integration: Integration tests (real external services)",
    "e2e: End-to-end workflow tests - WARNING: Use 'pytest tests/e2e/' not '-m e2e' (see tests/e2e/README.md)",
    "e2e_smoke: Quick smoke tests for critical workflows",
    "e2e_benchmark: Channel finder benchmark validation tests",
    "e2e_tutorial: Tutorial workflow validation tests",
    "slow: Tests that take significant time",
    "requires_api: Tests that require API credentials",
    "requires_openai: Tests that require OpenAI API key",
    "requires_anthropic: Tests that require Anthropic API key",
    "requires_google: Tests that require Google API key",
    "requires_cborg: Tests that require CBORG API key (local dev only — IP allowlist blocks GitHub Actions runners)",
    "requires_als_apg: Tests that require ALS-APG API key (AWS Bedrock proxy; reachable from GitHub Actions runners)",
    "requires_ollama: Tests that require local Ollama service",
    "asyncio: Async test marker",
    "flaky: Rerun on failure to absorb rare LLM nondeterminism (pytest-rerunfailures)",
    "e2e_services: E2E tests requiring local MCP service infrastructure (PostgreSQL, AccelPapers, etc.)",
    "dockerbuild: E2E tests that run a real docker build (skipped when docker is unavailable)",
]

# Ruff configuration for modern Python linting
[tool.ruff]
line-length = 100
target-version = "py311"
src = ["src", "interfaces", "deployment"]

[tool.ruff.lint]
select = [
    "E",  # pycodestyle errors
    "W",  # pycodestyle warnings
    "F",  # pyflakes
    "I",  # isort
    "B",  # flake8-bugbear
    "C4", # flake8-comprehensions
    "UP", # pyupgrade
]
ignore = [
    "E501",  # line too long, handled by formatter
    "B008",  # do not perform function calls in argument defaults
    "C901",  # too complex
]

[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["F401"]  # Allow unused imports in __init__.py
"tests/*" = ["B011", "B017", "B018"]  # Allow assert False, useless attribute access, assert blind exception
"tests/e2e/conftest.py" = ["F811"]  # Allow pytest hook redefinition
"tests/registry/test_registry_isolation.py" = ["F401"]  # Intentional unused import for testing
"tests/documentation/test_workflow_autodoc.py" = ["E402"]  # Late imports after path manipulation
"tests/services/channel_finder/test_registration.py" = ["E402"]  # Late imports after path manipulation
"src/osprey/templates/apps/control_assistant/_agent_data/example_scripts/**/*.py" = ["E402"]  # Example scripts with late imports
"src/osprey/services/channel_finder/__init__.py" = ["E402"]  # Grouped imports with section comments

[tool.ruff.lint.isort]
known-first-party = ["osprey", "configs", "applications", "interfaces", "deployment"]

# Coverage configuration (if using pytest-cov)
[tool.coverage.run]
source = ["src", "interfaces", "deployment"]
omit = [
    "*/tests/*",
    "*/__pycache__/*",
    "*/.*",
    "build/*",
    "dist/*",
    "venv/*",
    "_agent_data/*",
]

[tool.coverage.report]
exclude_lines = [
    "pragma: no cover",
    "def __repr__",
    "if self.debug:",
    "if settings.DEBUG",
    "raise AssertionError",
    "raise NotImplementedError",
    "if 0:",
    "if __name__ == .__main__.:",
    "class .*\\bProtocol\\):",
    "@(abc\\.)?abstractmethod",
]