<!-- code2docs:start --># proxy

![version](https://img.shields.io/badge/version-0.1.0-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.11-blue) ![coverage](https://img.shields.io/badge/coverage-unknown-lightgrey) ![functions](https://img.shields.io/badge/functions-317-green)
> **317** functions | **51** classes | **52** files | CC̄ = 3.1

> Auto-generated project documentation from source code analysis.

**Author:** Tom Sapletta  
**License:** Apache-2.0  
**Repository:** [https://github.com/wronai/proxy](https://github.com/wronai/proxy)

## Installation

### From PyPI

```bash
pip install proxy
```

### From Source

```bash
git clone https://github.com/wronai/proxy
cd proxy
pip install -e .
```

### Optional Extras

```bash
pip install proxy[gpu]    # gpu features
pip install proxy[jetson]    # jetson features
pip install proxy[vm]    # vm features
pip install proxy[test]    # testing tools
pip install proxy[dev]    # development tools
```

## Quick Start

### CLI Usage

```bash
# Generate full documentation for your project
proxy ./my-project

# Only regenerate README
proxy ./my-project --readme-only

# Preview what would be generated (no file writes)
proxy ./my-project --dry-run

# Check documentation health
proxy check ./my-project

# Sync — regenerate only changed modules
proxy sync ./my-project
```

### Python API

```python
from proxy import generate_readme, generate_docs, Code2DocsConfig

# Quick: generate README
generate_readme("./my-project")

# Full: generate all documentation
config = Code2DocsConfig(project_name="mylib", verbose=True)
docs = generate_docs("./my-project", config=config)
```

## Generated Output

When you run `proxy`, the following files are produced:

```
<project>/
├── README.md                 # Main project README (auto-generated sections)
├── docs/
│   ├── api.md               # Consolidated API reference
│   ├── modules.md           # Module documentation with metrics
│   ├── architecture.md      # Architecture overview with diagrams
│   ├── dependency-graph.md  # Module dependency graphs
│   ├── coverage.md          # Docstring coverage report
│   ├── getting-started.md   # Getting started guide
│   ├── configuration.md    # Configuration reference
│   └── api-changelog.md    # API change tracking
├── examples/
│   ├── quickstart.py       # Basic usage examples
│   └── advanced_usage.py   # Advanced usage examples
├── CONTRIBUTING.md         # Contribution guidelines
└── mkdocs.yml             # MkDocs site configuration
```

## Configuration

Create `proxy.yaml` in your project root (or run `proxy init`):

```yaml
project:
  name: my-project
  source: ./
  output: ./docs/

readme:
  sections:
    - overview
    - install
    - quickstart
    - api
    - structure
  badges:
    - version
    - python
    - coverage
  sync_markers: true

docs:
  api_reference: true
  module_docs: true
  architecture: true
  changelog: true

examples:
  auto_generate: true
  from_entry_points: true

sync:
  strategy: markers    # markers | full | git-diff
  watch: false
  ignore:
    - "tests/"
    - "__pycache__"
```

## Sync Markers

proxy can update only specific sections of an existing README using HTML comment markers:

```markdown
<!-- proxy:start -->
# Project Title
... auto-generated content ...
<!-- proxy:end -->
```

Content outside the markers is preserved when regenerating. Enable this with `sync_markers: true` in your configuration.

## Architecture

```
proxy/
        ├── advanced_usage    ├── proxym/        ├── quickstart        ├── ctl        ├── cache/        ├── middleware/            ├── browser_profiles            ├── _enums        ├── virt/            ├── _check            ├── clonebox_adapter            ├── _config            ├── _orchestrator            ├── system            ├── browser            ├── vms        ├── cli/            ├── _client            ├── accounts        ├── providers/        ├── accounts/            ├── registry        ├── mcp/            ├── client            ├── router            ├── detector        ├── context/            ├── session            ├── _context            ├── tool_selector        ├── router/            ├── strategy            ├── completions            ├── system        ├── api/            ├── _pipeline            ├── frontend            ├── context_api            ├── _state        ├── watch/            ├── client            ├── profiles/            ├── api                ├── useDashboardData    ├── proxym-dashboard            ├── panel├── project    ├── jetson-entrypoint    ├── setup        ├── config        ├── dashboard/        ├── main```

## API Overview

### Classes

- **`FileSnapshot`** — Immutable snapshot of a single file.
- **`DeltaPayload`** — Computed delta between two context snapshots.
- **`DeltaBuffer`** — Maintains file snapshots and computes minimal diffs.
- **`AuthMiddleware`** — Simple bearer token auth (matches LiteLLM master_key pattern).
- **`CostTrackingMiddleware`** — Log request timing and attach cost headers to responses.
- **`BrowserProfile`** — Detected browser profile on the host.
- **`AppDataSync`** — Configuration for syncing browser data into a VM.
- **`VMBackend`** — —
- **`VMState`** — —
- **`CloneBoxResult`** — Result of a clonebox CLI invocation.
- **`CloneBoxAdapter`** — Adapter wrapping the clonebox CLI for VM operations.
- **`ProjectsConfig`** — Configuration for shared project mounts from the host.
- **`VMConfig`** — Configuration for a development VM.
- **`VMStatus`** — Runtime status of a VM.
- **`VMOrchestrator`** — Manages VMs for isolated dev environments.
- **`TaskTier`** — Complexity tier that determines which model class is needed.
- **`Capability`** — —
- **`ModelSpec`** — Immutable specification for a single model deployment.
- **`ProviderType`** — —
- **`ToolType`** — —
- **`AccountCredentials`** — Credentials for a single provider account.
- **`UsageMetrics`** — Tracked usage for a single account.
- **`AccountLimits`** — Provider-imposed and user-defined limits.
- **`ToolBinding`** — Binds an account to a specific tool/IDE instance.
- **`Account`** — Single provider account with all associated data.
- **`AccountManager`** — Central account registry.
- **`MCPTransport`** — Transport protocol for MCP communication.
- **`MCPServerSpec`** — Specification of a registered MCP server.
- **`MCPRegistry`** — Registry of available MCP servers.
- **`MCPToolResult`** — Result of an MCP tool invocation.
- **`MCPClient`** — HTTP client for MCP server communication.
- **`MCPRouter`** — Routes tool requests to appropriate MCP servers.
- **`AgentSession`** — Stateful session for an agent working on a project.
- **`SessionStore`** — In-memory session store with TTL-based expiry.
- **`ProjectContext`** — Detected project context for a request.
- **`AnalysisResult`** — Result of content analysis.
- **`RoutingDecision`** — Complete routing decision with audit trail.
- **`CostLedger`** — In-memory cost ledger with Redis persistence.
- **`Router`** — Stateful router that selects the optimal model per request.
- **`CompletionPipeline`** — Structured pipeline for processing a chat completion request.
- **`DeltaWatchClient`** — Watches a directory and pushes context deltas to the proxy server.
- **`Settings`** — All settings with sensible defaults. Override via env vars or .env file.
- **`CreateAccountReq`** — —
- **`BindToolReq`** — —
- **`CreateVMReq`** — —
- **`SwitchProjectReq`** — —

### Functions

- `main()` — —
- `detect_firefox_profiles()` — Detect Firefox profiles by parsing profiles.ini.
- `detect_chrome_profiles()` — Detect Google Chrome profiles by parsing Local State.
- `detect_chromium_profiles()` — Detect Chromium profiles by parsing Local State.
- `detect_all_profiles()` — Detect all browser profiles on the host.
- `generate_app_data_sync(profile, with_passwords)` — Generate an AppDataSync config for copying a profile into a VM.
- `cmd_serve(args)` — Start the proxy server (delegates to proxym.main:cli).
- `cmd_status(args)` — —
- `cmd_models(args)` — —
- `cmd_browser_list(args)` — List detected browser profiles on the host.
- `cmd_browser_assign(args)` — Assign a browser profile to an account.
- `cmd_browser_sync(args)` — Sync browser profile host ↔ VM.
- `cmd_browser_snapshot(args)` — Save browser state from VM as snapshot.
- `cmd_vm_list(args)` — —
- `cmd_vm_create(args)` — —
- `cmd_vm_action(args)` — —
- `cmd_vm_switch(args)` — —
- `cmd_vm_open(args)` — Open SPICE viewer for a VM (virt-viewer).
- `cmd_vm_ssh(args)` — SSH into a VM (auto-detect IP via dashboard).
- `cmd_vm_logs(args)` — Show cloud-init logs and tool logs from a VM.
- `make_client(base, key)` — Create HTTP client with configuration from settings.
- `print_json(data)` — —
- `print_table(rows, columns, widths)` — —
- `cmd_accounts_list(args)` — —
- `cmd_accounts_add(args)` — —
- `cmd_accounts_costs(args)` — —
- `models_for_tier(tier, required_caps, available_providers)` — Return models suitable for a tier, sorted by effective cost ascending.
- `cheapest_model(tier, available_providers, required_caps)` — Return the single cheapest model that satisfies constraints.
- `get_model(model_id)` — —
- `detect_project(messages, headers)` — Detect project context from request data.
- `select_tools(context, analysis, available_servers)` — Select MCP servers for a given project and task analysis.
- `analyze_request(messages)` — Analyze a chat completion request and return routing metadata.
- `chat_completions(request, x_task_tier)` — OpenAI-compatible chat completions with intelligent routing.
- `favicon()` — Return empty favicon to prevent 401 errors.
- `health()` — —
- `list_models()` — List available models (OpenAI-compatible).
- `budget_status()` — Return current budget usage.
- `context_stats()` — Return delta buffer statistics.
- `dashboard_ui()` — Serve the React dashboard UI.
- `dashboard_hook_js()` — Serve the useDashboardData hook (plain JS, no Babel needed).
- `dashboard_api_js()` — Serve the dashboard API client (plain JS, no Babel needed).
- `dashboard_jsx()` — Serve the React dashboard JSX file.
- `get_frontend_config(request)` — Return configuration for frontend.
- `receive_delta(request)` — Receive context delta from the file watcher client.
- `detect_context(request)` — Detect project context from request body (messages + headers).
- `list_sessions()` — List active agent sessions.
- `list_mcp_servers()` — List registered MCP servers.
- `get_router()` — —
- `get_delta_buffer()` — —
- `get_mcp_router()` — —
- `get_session_store()` — —
- `get_context_payload()` — —
- `set_context_payload(payload)` — —
- `cli()` — CLI entry point for proxym-client.
- `get_builtin_profile(tool)` — Get the path to a built-in profile YAML for a tool.
- `list_builtin_profiles()` — List all available built-in profile names.
- `merge_profiles(base, override)` — Deep-merge two profile dicts. Override values take precedence.
- `load_profile_yaml(path)` — Load a YAML profile, with graceful fallback if PyYAML is not installed.
- `get()` — —
- `post()` — —
- `useHealth()` — —
- `refresh()` — —
- `h()` — —
- `useBudget()` — —
- `useModels()` — —
- `m()` — —
- `useProviders()` — —
- `p()` — —
- `useResources()` — —
- `useDashboardData()` — —
- `getInitialTab()` — —
- `hash()` — —
- `setTab()` — —
- `handleHashChange()` — —
- `newTab()` — —
- `healthHook()` — —
- `budgetHook()` — —
- `modelsHook()` — —
- `providersHook()` — —
- `resourcesHook()` — —
- `isUp()` — —
- `i()` — —
- `useState()` — —
- `useEffect()` — —
- `useCallback()` — —
- `StatusBadge()` — —
- `CostBar()` — —
- `pct()` — —
- `color()` — —
- `Card()` — —
- `ModelsTable()` — —
- `AccountRow()` — —
- `a()` — —
- `NewAccountForm()` — —
- `handleSubmit()` — —
- `AccountsPanel()` — —
- `handleCreate()` — —
- `VMCard()` — —
- `actions()` — —
- `VMsPanel()` — —
- `handleAction()` — —
- `DashboardHeader()` — —
- `TabNav()` — —
- `CostSummary()` — —
- `BudgetCards()` — —
- `dailyUsed()` — —
- `monthlyUsed()` — —
- `SystemCard()` — —
- `ProvidersCard()` — —
- `OverviewTab()` — —
- `Dashboard()` — —
- `data()` — —
- `root()` — —
- `get_settings()` — —
- `list_accounts(provider, tag)` — —
- `create_account(req)` — —
- `get_account(account_id)` — —
- `delete_account(account_id)` — —
- `bind_tool(account_id, req)` — —
- `cost_summary()` — Aggregate cost dashboard across all accounts.
- `cost_detailed()` — Per-account cost breakdown.
- `list_vms()` — —
- `create_vm(req)` — —
- `start_vm(vm_id)` — —
- `stop_vm(vm_id, force)` — —
- `pause_vm(vm_id)` — —
- `resume_vm(vm_id)` — —
- `snapshot_vm(vm_id, name)` — —
- `switch_project(vm_id, req)` — —
- `delete_vm(vm_id)` — —
- `dashboard_root()` — Dashboard root - redirects to system status.
- `system_status()` — Full system overview: accounts + VMs + costs + libvirt + providers.
- `list_providers()` — Show configured providers from .env and their model counts.
- `lifespan(app)` — —
- `cli()` — —


## Project Structure

📄 `frontend.proxym-dashboard`
📄 `project`
📄 `project.examples.advanced_usage`
📄 `project.examples.quickstart`
📄 `scripts.jetson-entrypoint`
📄 `scripts.setup`
📦 `src.proxym`
📦 `src.proxym.accounts` (20 functions, 8 classes)
📦 `src.proxym.api`
📄 `src.proxym.api._pipeline` (16 functions, 1 classes)
📄 `src.proxym.api._state` (6 functions)
📄 `src.proxym.api.completions` (1 functions)
📄 `src.proxym.api.context_api` (4 functions)
📄 `src.proxym.api.frontend` (6 functions)
📄 `src.proxym.api.system` (5 functions)
📦 `src.proxym.cache` (10 functions, 3 classes)
📦 `src.proxym.cli`
📄 `src.proxym.cli._client` (3 functions)
📄 `src.proxym.cli.accounts` (3 functions)
📄 `src.proxym.cli.browser` (4 functions)
📄 `src.proxym.cli.system` (3 functions)
📄 `src.proxym.cli.vms` (8 functions)
📄 `src.proxym.config` (2 functions, 1 classes)
📦 `src.proxym.context`
📄 `src.proxym.context._context` (1 functions, 1 classes)
📄 `src.proxym.context.detector` (9 functions)
📄 `src.proxym.context.session` (8 functions, 2 classes)
📄 `src.proxym.context.tool_selector` (2 functions)
📄 `src.proxym.ctl` (6 functions)
📦 `src.proxym.dashboard` (21 functions, 4 classes)
📄 `src.proxym.dashboard.api` (6 functions)
📄 `src.proxym.dashboard.hooks.useDashboardData` (27 functions)
📄 `src.proxym.dashboard.panel` (31 functions)
📄 `src.proxym.main` (2 functions)
📦 `src.proxym.mcp`
📄 `src.proxym.mcp.client` (4 functions, 2 classes)
📄 `src.proxym.mcp.registry` (8 functions, 3 classes)
📄 `src.proxym.mcp.router` (4 functions, 1 classes)
📦 `src.proxym.middleware` (3 functions, 2 classes)
📦 `src.proxym.providers` (4 functions, 3 classes)
📦 `src.proxym.router` (14 functions, 1 classes)
📄 `src.proxym.router.strategy` (14 functions, 3 classes)
📦 `src.proxym.virt`
📄 `src.proxym.virt._check` (1 functions)
📄 `src.proxym.virt._config` (1 functions, 3 classes)
📄 `src.proxym.virt._enums` (2 classes)
📄 `src.proxym.virt._orchestrator` (28 functions, 6 classes)
📄 `src.proxym.virt.browser_profiles` (11 functions, 2 classes)
📄 `src.proxym.virt.clonebox_adapter` (17 functions, 2 classes)
📦 `src.proxym.virt.profiles` (4 functions)
📦 `src.proxym.watch` (5 functions, 1 classes)
📄 `src.proxym.watch.client`

## Requirements

- Python >= >=3.11
- fastapi >=0.115.0- uvicorn [standard]>=0.30.0- httpx >=0.27.0- litellm >=1.55.0- redis >=5.0.0- pydantic >=2.9.0- pydantic-settings >=2.5.0- python-dotenv >=1.0.0- tiktoken >=0.8.0- watchfiles >=0.24.0- xxhash >=3.5.0- rich >=13.9.0- structlog >=24.4.0

## Contributing

**Contributors:**
- Tom Softreck <tom@sapletta.com>
- Tom Sapletta <tom-sapletta-com@users.noreply.github.com>

We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

### Development Setup

```bash
# Clone the repository
git clone https://github.com/wronai/proxy
cd proxy

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest
```

## Documentation

- 📖 [Full Documentation](https://github.com/wronai/proxy/tree/main/docs) — API reference, module docs, architecture
- 🚀 [Getting Started](https://github.com/wronai/proxy/blob/main/docs/getting-started.md) — Quick start guide
- 📚 [API Reference](https://github.com/wronai/proxy/blob/main/docs/api.md) — Complete API documentation
- 🔧 [Configuration](https://github.com/wronai/proxy/blob/main/docs/configuration.md) — Configuration options
- 💡 [Examples](./examples) — Usage examples and code samples

### Generated Files

| Output | Description | Link |
|--------|-------------|------|
| `README.md` | Project overview (this file) | — |
| `docs/api.md` | Consolidated API reference | [View](./docs/api.md) |
| `docs/modules.md` | Module reference with metrics | [View](./docs/modules.md) |
| `docs/architecture.md` | Architecture with diagrams | [View](./docs/architecture.md) |
| `docs/dependency-graph.md` | Dependency graphs | [View](./docs/dependency-graph.md) |
| `docs/coverage.md` | Docstring coverage report | [View](./docs/coverage.md) |
| `docs/getting-started.md` | Getting started guide | [View](./docs/getting-started.md) |
| `docs/configuration.md` | Configuration reference | [View](./docs/configuration.md) |
| `docs/api-changelog.md` | API change tracking | [View](./docs/api-changelog.md) |
| `CONTRIBUTING.md` | Contribution guidelines | [View](./CONTRIBUTING.md) |
| `examples/` | Usage examples | [Browse](./examples) |
| `mkdocs.yml` | MkDocs configuration | — |

<!-- code2docs:end -->