Python Execution#

The Python Execution Service is Osprey’s managed approach to Python code generation, security analysis, and execution. It provides a service layer that capabilities can invoke to safely generate and run Python code with human oversight.

Architecture Overview#

How It Works:

The Python execution flow follows this pattern:

Capability (e.g., PythonCapability)
     ↓
Python Executor Service
     ↓
┌─────────────────────────────┐
│ 1. Code Generation          │ → Pluggable generators (Legacy/Claude/Mock)
│ 2. Security Analysis        │ → Pattern detection (EPICS writes, etc.)
│ 3. Approval (if needed)     │ → LangGraph interrupts for human review
│ 4. Execution                │ → Container or local execution
│ 5. Result Processing        │ → Structured results, notebooks, retry
└─────────────────────────────┘
     ↓
Results back to Capability

Key Components:

Service Layer: Orchestrates the entire pipeline through a LangGraph-based workflow
Code Generators: Pluggable implementations for code generation (the heart of the system)
Security Analysis: Static analysis and pattern detection for risky operations
Approval System: Human oversight for high-stakes operations (EPICS writes, etc.)
Execution Environment: Container or local execution with consistent result handling

Core Concept: Pluggable Code Generators#

The code generator is the core of the Python execution system. Osprey provides three built-in generators, each optimized for different use cases:

Generator Comparison#
Generator	Speed	Quality	Best Use Case
Basic LLM	Fast	Good	Self-hosted, simple setups, minimal dependencies
Claude Code	Slower	Excellent	Complex tasks, learning from examples
Mock	Instant	N/A (Fixed)	Testing, CI/CD, development

Protocol-Based Architecture:

All generators implement a simple protocol - no inheritance required:

class CodeGenerator(Protocol):
    async def generate_code(
        self,
        request: PythonExecutionRequest,
        error_chain: list[str]
    ) -> str:
        """Generate Python code based on request and error feedback."""
        ...

This enables:

Easy creation of custom generators
Clean separation from the executor service
Runtime type checking
Error-aware iterative improvement

Learn More:

📚 Python Service Overview

Complete service guide: architecture, integration, generators, and configuration

Python Service Overview

🤖 Basic LLM Generator

Simple single-pass LLM generation

Basic LLM Generator

🧠 Claude Code Generator

Multi-phase agentic reasoning with codebase learning

Claude Code Generator

🧪 Mock Generator

Fast, deterministic testing without API calls

Mock Generator

Quick Start#

Minimal configuration to get started:

# config.yml
osprey:
  execution:
    code_generator: "basic"  # or "claude_code", "mock"
    execution_method: "container"  # or "local"

    generators:
      basic:
        model_config_name: "python_code_generator"
      claude_code:
        profile: "fast"  # fast (DEFAULT, single-phase) | robust (multi-phase)
      mock:
        behavior: "success"

    container:
      jupyter_host: "localhost"
      jupyter_port: 8888

Choose Your Generator:

Basic LLM: Simple single-pass generation - for self-hosted models and minimal setups
Claude Code: Advanced multi-phase generation - learns from your codebase
Mock: Testing only - instant, deterministic, no API calls

Note

For complete service documentation including integration patterns, configuration reference, and creating custom generators, see Python Service Overview.

Python Execution#

Architecture Overview#

Core Concept: Pluggable Code Generators#

Quick Start#

See Also#