User ──> Streamlit UI (8501) ──> Agent Sampling Loop ──> Claude API
              │                        │
              │                        ├── ComputerTool (screenshot/mouse/keyboard via xdotool)
              │                        ├── BashTool (persistent shell session)
              │                        └── EditTool (file view/create/replace/insert/undo)
              │
         HTTP Proxy (8080) ──> Combined app + desktop view
              │
         noVNC (6080) ──> X11/Xvfb + mutter + tint2
              │
         VNC (5900) ──> Direct VNC client access

export ANTHROPIC_API_KEY=sk-ant-...

docker run \
    -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
    -v $HOME/.anthropic:/home/operative/.anthropic \
    -p 5900:5900 \
    -p 8501:8501 \
    -p 6080:6080 \
    -p 8080:8080 \
    -it ghcr.io/hanzoai/operative:latest

export AWS_PROFILE=your-profile

docker run \
    -e API_PROVIDER=bedrock \
    -e AWS_PROFILE=$AWS_PROFILE \
    -e AWS_REGION=us-west-2 \
    -v $HOME/.aws:/home/operative/.aws \
    -v $HOME/.anthropic:/home/operative/.anthropic \
    -p 5900:5900 -p 8501:8501 -p 6080:6080 -p 8080:8080 \
    -it ghcr.io/hanzoai/operative:latest

gcloud auth application-default login
export VERTEX_REGION=us-central1
export VERTEX_PROJECT_ID=your-project-id

docker run \
    -e API_PROVIDER=vertex \
    -e CLOUD_ML_REGION=$VERTEX_REGION \
    -e ANTHROPIC_VERTEX_PROJECT_ID=$VERTEX_PROJECT_ID \
    -v $HOME/.config/gcloud/application_default_credentials.json:/home/operative/.config/gcloud/application_default_credentials.json \
    -p 5900:5900 -p 8501:8501 -p 6080:6080 -p 8080:8080 \
    -it ghcr.io/hanzoai/operative:latest

curl -X POST https://api.hanzo.ai/v1/operative/sessions \
  -H "Authorization: Bearer hk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Open Firefox, navigate to hanzo.ai, and take a screenshot",
    "model": "claude-3-7-sonnet-20250219",
    "thinking_budget": 64000
  }'

import anthropic
from operative.loop import sampling_loop, APIProvider
from operative.tools import ToolVersion

messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": (
                    "Open Firefox and navigate to example.com/signup. "
                    "Fill in the form with: name='Test User', "
                    "email='[email protected]'. Click Submit."
                )
            }
        ]
    }
]

result = await sampling_loop(
    model="claude-3-7-sonnet-20250219",
    provider=APIProvider.ANTHROPIC,
    system_prompt_suffix="Complete the form carefully.",
    messages=messages,
    output_callback=lambda block: print(block),
    tool_output_callback=lambda result, tid: None,
    api_response_callback=lambda req, resp, err: None,
    api_key="sk-ant-...",
    only_n_most_recent_images=3,
    max_tokens=128000,
    tool_version="computer_use_20250124",
    thinking_budget=64000,
)

messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": (
                    "Navigate to news.ycombinator.com. "
                    "Read the top 5 stories and save their titles "
                    "and URLs to /tmp/hn_top5.json as a JSON array."
                )
            }
        ]
    }
]

async def sampling_loop(
    *,
    model: str,                          # e.g. "claude-3-7-sonnet-20250219"
    provider: APIProvider,               # "anthropic", "bedrock", or "vertex"
    system_prompt_suffix: str,           # Appended to the system prompt
    messages: list[dict],                # Conversation history
    output_callback: Callable,           # Receives streaming content blocks
    tool_output_callback: Callable,      # Receives tool results
    api_response_callback: Callable,     # Receives HTTP request/response pairs
    api_key: str,                        # Anthropic API key
    only_n_most_recent_images: int | None = None,
    max_tokens: int = 4096,              # Max output tokens (up to 128000)
    tool_version: ToolVersion,           # "computer_use_20250124" or "computer_use_20241022"
    thinking_budget: int | None = None,  # Thinking token budget (Claude 3.7+)
    token_efficient_tools_beta: bool = False,
) -> list[dict]:

await bash_tool(command="ls -la /tmp")     # Run a command
await bash_tool(restart=True)               # Restart the bash session

cd ~/work/hanzo/operative

# Setup Python environment
make setup

# Run tests
make test

# Run with coverage
make test-cov

# Lint and format
make lint
make format

export ANTHROPIC_API_KEY=sk-ant-...

make dev
# Mounts local ./operative/ into the container for live editing

make build-xvfb    # Build base Xvfb image
make build          # Build operative image (depends on xvfb)
make build-desktop  # Build full desktop variant

make push           # Push operative to GHCR
make push-desktop   # Push desktop variant to GHCR