Metadata-Version: 2.5
Name: capability-compiler
Version: 0.1.1
Summary: Turn any software into an API for AI: compile interaction trajectories into verified, reusable capabilities exposed via Python, CLI, and MCP.
Project-URL: Homepage, https://github.com/capability-compiler/capability-compiler
Project-URL: Documentation, https://github.com/capability-compiler/capability-compiler/tree/main/docs
Project-URL: Issues, https://github.com/capability-compiler/capability-compiler/issues
Author: Capability Compiler Contributors
License-Expression: MIT
License-File: LICENSE
Keywords: agents,automation,browser-automation,capability-learning,gui-agents,llm,mcp,model-context-protocol
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: mcp<3,>=2.0
Requires-Dist: platformdirs<5,>=4.2
Requires-Dist: pydantic-settings<3,>=2.3
Requires-Dist: pydantic<3,>=2.7
Requires-Dist: pyyaml<7,>=6.0
Requires-Dist: typer<1,>=0.12
Provides-Extra: anthropic
Requires-Dist: httpx>=0.27; extra == 'anthropic'
Provides-Extra: browser
Requires-Dist: playwright>=1.45; extra == 'browser'
Provides-Extra: dev
Requires-Dist: bandit>=1.7; extra == 'dev'
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.2; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Provides-Extra: models
Requires-Dist: httpx>=0.27; extra == 'models'
Provides-Extra: ollama
Requires-Dist: httpx>=0.27; extra == 'ollama'
Provides-Extra: openai
Requires-Dist: httpx>=0.27; extra == 'openai'
Provides-Extra: sqlite
Description-Content-Type: text/markdown

# Capability Compiler

> **Turn any software into an API for AI.**

Capability Compiler observes black-box software, explores it safely, and
compiles interaction trajectories into **verified, reusable capabilities** —
exposed to any LLM through Python APIs, the `cc` CLI, and the Model Context
Protocol (MCP). Fully local-first: the default configuration runs offline
with no account and no telemetry.

```text
UNKNOWN SOFTWARE ─▶ OBSERVE ─▶ EXPLORE ─▶ COMPILE ─▶ VERIFY ─▶ REUSE
                                                                  │
                                          ┌───────────────────────┼───────────────────────┐
                                          ▼                       ▼                       ▼
                                    `cc execute`           `cc serve` (MCP)         Python API
```

## What does this do?

Capability Compiler records how an application responds to actions, classifies
those responses with deterministic semantic-state diffs, and turns the result
into a typed, versioned, permission-scoped **Capability** artifact — a unit
of reusable software control that any LLM can call via MCP. The output is
*executable without an LLM in the loop*: it carries inputs, preconditions,
postconditions, verifiers, and confidence derived from execution evidence.

## Why does it exist?

Every adjacent project — record/replay tools, GUI-agent libraries, skill
distributors — stops one or two steps short of the full pipeline. Capability
Compiler ships the whole pipeline as a **compiler**, with the properties
compilers have: determinism where possible, typed artifacts, reproducible
outputs, and versioned inputs/outputs. See
[`docs/research/differentiation.md`](docs/research/differentiation.md) for
the detailed thesis, and [`docs/research/landscape.md`](docs/research/landscape.md)
for the ecosystem map that motivated it.

Five differentiators in one line each:

1. **Trajectories → parameterized capabilities** (not replays, not prompts).
2. **Verification manufactured, not hand-written** (synthesized from the
   observed state diffs).
3. **Cross-run element re-anchoring** (semantic refs survive DOM drift).
4. **Trust data attached to executable artifacts** (fingerprint,
   provenance, evidence-based score, deny-by-default permissions).
5. **Local-first, offline-complete** (mock provider runs the whole pipeline
   with zero network).

## Quick start

```bash
# 1. Install (Python 3.11+; MCP transport included by default)
pip install capability-compiler                  # everything except adapters/providers below
pip install capability-compiler[browser]         # add the Playwright adapter
pip install capability-compiler[models]          # add Anthropic / OpenAI / Ollama providers

# 2. Verify the install
cc doctor

# 3. Inspect effective configuration
cc config show

# 4. Learn a capability from a local app (fake adapter, no browser needed)
cc learn "export a pdf" --adapter fake --name export_pdf

# 5. Run it through the gate-ordered executor
cc execute export_pdf --key format=pdf --key file_name=report.pdf

# 6. Browse what you have
cc capabilities
cc inspect export_pdf

# 7. Serve every capability as MCP tools (stdio for editor clients)
cc serve --transport stdio
cc serve --transport http --host 127.0.0.1 --port 8765 --token "$CC_MCP_TOKEN"
```

Every command supports `--json` for machine-readable output. Pass `--verbose`
(`-v`) at the top level to bump logging to DEBUG; set `CC_DEBUG=1` to print
full tracebacks instead of structured error messages.

### Python quick start

```python
import asyncio
from capability_compiler import Compiler, CompilerSettings, CapabilityRegistry

async def main() -> None:
    compiler = Compiler()                    # offline-safe defaults (mock provider)
    async with compiler:                     # connect/disconnect bracket
        observation = await compiler.observe()
        report = await compiler.explore(max_steps=20)
        if compiler.exploration and compiler.exploration.trajectories:
            capability = await compiler.synthesize(
                compiler.exploration.trajectories[-1],
                goal_hint="export a pdf",
            )
            registry = CapabilityRegistry.from_settings(CompilerSettings())
            await registry.save(capability)
            result = await compiler.execute(capability, {"format": "pdf"})
            print(result.status.value, result.duration_ms)

asyncio.run(main())
```

## Architecture summary

The framework is layered so each phase delivers a coherent unit and each
later phase builds on a stable contract from the previous one.

| Layer | Module | Contract | Notes |
|---|---|---|---|
| Domain models | `capability_compiler.models` | Pydantic v2 data contracts | Single source of truth for capabilities, trajectories, actions, observations |
| Errors | `capability_compiler.errors` | `CapabilityCompilerError` + 9-way `FailureCategory` taxonomy | Every failure classifies exactly once |
| Logging | `capability_compiler.logging` | Structured JSON or human formatter; secret redaction filter | Never logs API keys, even under odd key names |
| Config | `capability_compiler.config` | Layered settings (defaults → TOML → `CC_*__*` env) | API keys only ever resolved from env vars |
| Adapters | `capability_compiler.adapters` | `EnvironmentAdapter` protocol | `fake` (offline), `browser` (Playwright), `desktop` (skeleton) |
| Providers | `capability_compiler.providers` | `ModelProvider` protocol | `mock`, `ollama`, `anthropic`, `openai`, `openai_compatible` |
| Recording | `capability_compiler.recording` | `TrajectoryRecorder` + `Replayer` | Every action carries before/after state ids |
| Perception | `capability_compiler.perception` | `SemanticState` + `StateDiff` (deterministic, no model) | `semantic-v1` fingerprint algorithm |
| Exploration | `capability_compiler.exploration` | `ExplorationEngine` + `ActionSemanticsEngine` | Effect-first naming; UNKNOWN beats hallucination |
| Synthesis | `capability_compiler.synthesis` | `CapabilitySynthesizer` | Trajectory → typed, templatized capability |
| Runtime | `capability_compiler.runtime` | `CapabilityExecutor` (8-gate ordered) | Validate → permissions → confirm → preconditions → procedure → postconditions → record |
| Verification | `capability_compiler.verification` | 8 verifier kinds (`state`, `dom`, `accessibility`, `file`, `visual`, `schema`, `custom`, `composite`) | Never accepts "exit code 0" as success |
| Refinement | `capability_compiler.refinement` | `SelfImprovementEngine` + `CapabilityRepairer` | Deterministic repairs promoted only on test-pass |
| Storage | `capability_compiler.storage` | `CapabilityStore` protocol | `FileCapabilityStore` (atomic writes + integrity check) and `SqliteCapabilityStore` |
| Registry | `capability_compiler.registry` | `CapabilityRegistry` + `Permission` bitfield | Search, summaries, risk tagging, version-aware rollback |
| Compiler | `capability_compiler.compiler` | The `Compiler` facade | Wires + supervises — algorithms live in engines |
| CLI | `capability_compiler.cli` | The `cc` command | `version`, `doctor`, `config`, `capabilities`, `inspect`, `learn`, `execute`, `serve`, `benchmark` |
| Server | `capability_compiler.server` | MCP transports (`stdio` and streamable `http`) | Bearer-token auth on the HTTP transport |

The full overview lives at [`docs/architecture.md`](docs/architecture.md).
Subsystem deep-dives live in [`docs/architecture/`](docs/architecture/).

## Security posture

Capability Compiler is **deny-by-default** at every layer:

- `security.allow_network` and `security.allow_shell` both default to `false`.
- `allowed_read_roots` and `allowed_write_roots` default to empty lists
  (filesystem scope is opt-in per capability).
- The browser adapter blocks navigation to non-loopback URLs unless
  `security.allow_network=true`; failed navigation becomes a structured
  `PERMISSION_DENIED`, never a crash.
- API keys are referenced by env-var *name* in config; values are resolved at
  call time and never persisted. The logging layer redacts by key name
  (`api_key`, `token`, `secret`, `password`, `authorization`, `cookie`,
  `credential`, `session_id`) and by value pattern (`Bearer …`, `sk-…`,
  `gh[pousr]_…`) as a second line of defense.
- Destructive capabilities (`permissions.destructive=true` or
  `risk ≥ HIGH`) require explicit user confirmation by default; the CLI
  prompts on a TTY and the executor accepts `confirmed=True` to skip.
- Capabilities are **pure data** (JSON-serializable Pydantic models).
  Nothing in a stored capability is ever evaluated as code.

The complete threat model, scope of promises, and explicit non-goals are in
[`SECURITY.md`](SECURITY.md). Local-first design choices are explained in
[`docs/concepts/local-first.md`](docs/concepts/local-first.md).

## How to contribute / how to extend

Capability Compiler ships pluggable protocols at every cross-cutting
boundary; subclasses are not required (Protocols are structural).

| To add … | Use … |
|---|---|
| A new environment (browser, desktop, mobile, CLI) | `register_adapter(kind, factory)` in `capability_compiler.adapters.base` |
| A new model backend (new vendor, new on-prem) | `register_provider(name, factory)` in `capability_compiler.providers.base` |
| A new persistence backend (Redis, Postgres, S3) | Implement the `CapabilityStore` protocol in `capability_compiler.storage.base` |
| A new check on capability outcomes | `register_verifier(kind, factory)` in `capability_compiler.verification.base` |
| A new CLI command | Append a Typer command module under `src/capability_compiler/cli/` and register it in `main.py` |

The differentiation thesis ([`docs/research/differentiation.md`](docs/research/differentiation.md))
is the source of intent — please read it before opening a feature PR.
The master plan ([`docs/master-plan.md`](docs/master-plan.md)) defines
what is in scope and what is not. Development setup, test layout, and CI
gates are in [`docs/ci.md`](docs/ci.md).

## Benchmarks

Capability Compiler ships an internal **CapabilityBench** suite used for
sanity checks and gate reporting. It runs against the in-memory `fake`
adapter so it never touches the network, a real OS, or a browser. See
[`docs/benchmarks.md`](docs/benchmarks.md) for what is and isn't measured.

## Documentation index

- Concepts — [`docs/concepts/exploration.md`](docs/concepts/exploration.md),
  [`docs/concepts/local-first.md`](docs/concepts/local-first.md)
- Architecture — [`docs/architecture.md`](docs/architecture.md),
  [`docs/architecture/registry.md`](docs/architecture/registry.md),
  [`docs/architecture/mcp.md`](docs/architecture/mcp.md)
- Adapters — [`docs/adapters/browser.md`](docs/adapters/browser.md)
- Model providers — [`docs/models.md`](docs/models.md)
- CLI reference — [`docs/cli/commands.md`](docs/cli/commands.md)
- Benchmarks — [`docs/benchmarks.md`](docs/benchmarks.md)
- CI / `cc doctor` — [`docs/ci.md`](docs/ci.md)
- Research — [`docs/research/landscape.md`](docs/research/landscape.md),
  [`docs/research/differentiation.md`](docs/research/differentiation.md)

## License

MIT — see [`LICENSE`](LICENSE).

## Acknowledgments

Capability Compiler stands on the shoulders of projects whose work the
[`docs/research/landscape.md`](docs/research/landscape.md) map credits in
detail. The full production-readiness release was authored by the
Capability Compiler contributors; see
[`CHANGELOG.md`](CHANGELOG.md) for what shipped in each phase.