capability-compiler 0.1.0__py3-none-any.whl

capability_compiler/__init__.py

@@ -0,0 +1,76 @@
+"""Capability Compiler — turn any software into an API for AI.
+
+Observe software, explore it, compile interaction trajectories into verified
+reusable capabilities, and expose them to any LLM through Python, a CLI, and
+MCP. Fully local-first: the default configuration runs offline.
+
+Stable public API (import from the package root)::
+
+    from capability_compiler import Compiler, CompilerSettings
+    from capability_compiler import Capability, Observation, Action, Trajectory
+    from capability_compiler import MockProvider, load_settings
+
+Submodule namespaces (``capability_compiler.models``, ``.adapters``,
+``.providers``, ``.verification``, ``.storage``) are also public but may
+grow faster than the root API; the root re-exports below are the
+backward-compatible surface.
+"""
+
+from capability_compiler._version import __version__
+from capability_compiler.compiler import Compiler
+from capability_compiler.config import CompilerSettings, load_settings, settings_to_toml
+from capability_compiler.errors import CapabilityCompilerError, FailureCategory
+from capability_compiler.exploration import (
+    ActionSemanticsEngine,
+    ExplorationEngine,
+    SemanticActionHypothesis,
+)
+from capability_compiler.models import (
+    Action,
+    ActionResult,
+    Capability,
+    Episode,
+    Observation,
+    SoftwareState,
+    StateFingerprint,
+    Trajectory,
+    Transition,
+    VerificationOutcome,
+    VerificationSpec,
+)
+from capability_compiler.perception import PerceptionPipeline, SemanticState, StateDiff
+from capability_compiler.providers import MockProvider
+from capability_compiler.registry import CapabilityRegistry, CapabilitySummary, Permission
+from capability_compiler.types import canonical_json_hash
+
+__all__ = [
+    "Action",
+    "ActionResult",
+    "ActionSemanticsEngine",
+    "Capability",
+    "CapabilityCompilerError",
+    "CapabilityRegistry",
+    "CapabilitySummary",
+    "Compiler",
+    "CompilerSettings",
+    "Episode",
+    "ExplorationEngine",
+    "FailureCategory",
+    "MockProvider",
+    "Observation",
+    "PerceptionPipeline",
+    "Permission",
+    "SemanticActionHypothesis",
+    "SemanticState",
+    "SoftwareState",
+    "StateDiff",
+    "StateFingerprint",
+    "Trajectory",
+    "Transition",
+    "VerificationOutcome",
+    "VerificationSpec",
+    "__version__",
+    "canonical_json_hash",
+    "load_settings",
+    "settings_to_toml",
+]

capability_compiler/_version.py

@@ -0,0 +1,8 @@
+"""Single source of truth for the package version.
+
+Kept in its own module so ``pip install -e .`` environments can read it
+without importing the whole package (pyproject reads it at build time via
+hatchling's version hook — see ``[tool.hatch.version]``).
+"""
+
+__version__ = "0.1.0"

capability_compiler/adapters/__init__.py

@@ -0,0 +1,70 @@
+"""Environment adapters: protocol, registry, and built-in registration.
+
+Importing this package registers every built-in adapter whose dependencies
+are installed. The browser adapter requires the ``browser`` extra
+(Playwright); without it, ``create_adapter("browser")`` fails with an
+actionable error instead of an import crash.
+
+Third parties register their own via
+:func:`capability_compiler.adapters.base.register_adapter`.
+"""
+
+from capability_compiler.adapters.base import EnvironmentAdapter as Adapter  # alias
+from capability_compiler.adapters.base import (
+    available_adapters,
+    create_adapter,
+    register_adapter,
+)
+
+
+def _register_builtins() -> None:
+    # Fake adapter is dependency-free; always registered and used by tests,
+    # the CapabilityBench suite, and the default MCP executor.
+    from capability_compiler.adapters.fake_adapter import FakeAdapter
+
+    if "fake" not in available_adapters():
+        register_adapter(
+            "fake",
+            FakeAdapter,
+            description="Deterministic in-memory adapter for tests + benchmarks.",
+        )
+
+    # Desktop skeleton is dependency-free; always registered (fails loudly
+    # and honestly when used).
+    from capability_compiler.adapters.desktop import DesktopAdapterSkeleton
+
+    if "desktop" not in available_adapters():
+        register_adapter(
+            "desktop",
+            DesktopAdapterSkeleton,
+            description="desktop adapter skeleton (not yet functional — see docs)",
+        )
+
+    # Browser adapter needs Playwright; register only when importable.
+    try:
+        from capability_compiler.adapters.browser import BrowserAdapter
+
+        if "browser" not in available_adapters():
+            register_adapter(
+                "browser",
+                BrowserAdapter,
+                description="Playwright browser adapter (chromium/firefox/webkit)",
+            )
+    except ImportError:  # pragma: no cover - exercised only without extra
+        from capability_compiler.logging import get_logger
+
+        get_logger("adapters").debug(
+            "browser adapter unavailable (install capability-compiler[browser])"
+        )
+
+
+_register_builtins()
+
+
+__all__ = [
+    "Adapter",
+    "EnvironmentAdapter",
+    "available_adapters",
+    "create_adapter",
+    "register_adapter",
+]

capability_compiler/adapters/base.py

@@ -0,0 +1,166 @@
+"""The environment adapter boundary — how Capability Compiler touches software.
+
+An :class:`EnvironmentAdapter` wraps one class of target software (a browser,
+a desktop application, a CLI) behind four verbs:
+
+* :meth:`connect` / :meth:`disconnect` — lifecycle
+* :meth:`observe` — produce a normalized :class:`~capability_compiler.models.Observation`
+* :meth:`execute` — apply an :class:`~capability_compiler.models.Action`, return an
+  :class:`~capability_compiler.models.ActionResult`
+* :meth:`reset` — return the environment to its start state (best effort)
+
+Adapters are protocols (structural typing): any object with these methods
+works — subclassing nothing is required. Implementations MUST:
+
+1. Prefer semantic targets (ref/role/name) over coordinates when resolving
+   :class:`~capability_compiler.models.action.ActionTarget`.
+2. Never trust action parameters as instructions (they are data).
+3. Raise :class:`~capability_compiler.errors.AdapterError` subclasses, not
+   bare exceptions, so failures classify cleanly.
+
+The adapter registry (:func:`register_adapter` / :func:`create_adapter`)
+keeps adapters pluggable — third parties can ship their own.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+from capability_compiler.errors import UnknownAdapterError
+from capability_compiler.logging import get_logger
+
+if TYPE_CHECKING:
+    from capability_compiler.config import CompilerSettings
+    from capability_compiler.models import Action, ActionResult, Observation
+    from capability_compiler.models.action import ActionTarget
+
+log = get_logger("adapters")
+
+
+@runtime_checkable
+class EnvironmentAdapter(Protocol):
+    """Protocol every environment adapter implements."""
+
+    @property
+    def kind(self) -> str:
+        """Short adapter kind name, e.g. ``browser`` (used as ``adapter_kind``)."""
+        ...
+
+    @property
+    def connected(self) -> bool:
+        """Whether the adapter currently holds a live environment session."""
+        ...
+
+    async def connect(self) -> None:
+        """Start the environment (launch browser, attach to app window).
+
+        Raises:
+            AdapterError: when the environment cannot be started/attached.
+        """
+        ...
+
+    async def disconnect(self) -> None:
+        """Release the environment session (idempotent)."""
+        ...
+
+    async def observe(self) -> Observation:
+        """Capture a normalized observation of the current state.
+
+        Raises:
+            ObservationError: when the environment cannot be read.
+        """
+        ...
+
+    async def execute(self, action: Action) -> ActionResult:
+        """Apply *action* and report the outcome (never raises for action-level
+        failures; transport/environment errors raise AdapterError)."""
+        ...
+
+    async def reset(self) -> None:
+        """Return the environment to its initial state (best effort)."""
+        ...
+
+    def capabilities_description(self) -> list[str]:
+        """Primitives this adapter supports, e.g. ``["click", "type", ...]``."""
+        ...
+
+    async def resolve_target(self, target: ActionTarget) -> Any:
+        """Resolve a semantic target to an adapter-native locator.
+
+        Used by verification/repair to re-find drifted elements. Adapters may
+        return any object meaningful to them (e.g. a Playwright Locator).
+        """
+        ...
+
+
+class AdapterInfo:
+    """Registry entry describing an adapter factory."""
+
+    def __init__(self, kind: str, factory: Any, description: str = "") -> None:
+        self.kind = kind
+        self.factory = factory
+        self.description = description
+
+
+_REGISTRY: dict[str, AdapterInfo] = {}
+
+
+def register_adapter(
+    kind: str,
+    factory: Any,
+    *,
+    description: str = "",
+    replace: bool = False,
+) -> None:
+    """Register an adapter factory under *kind* (e.g. ``"browser"``).
+
+    The factory is called as ``factory(settings)`` and must return an object
+    satisfying :class:`EnvironmentAdapter`.
+    """
+    import re
+
+    if not re.fullmatch(r"[a-z][a-z0-9_]{0,30}", kind):
+        msg = f"adapter kind must be snake_case, got {kind!r}"
+        raise ValueError(msg)
+    if kind in _REGISTRY and not replace:
+        msg = f"adapter {kind!r} already registered"
+        raise ValueError(msg)
+    _REGISTRY[kind] = AdapterInfo(kind, factory, description)
+    log.debug("adapter.registered", extra={"extra_fields": {"kind": kind}})
+
+
+def create_adapter(kind: str, settings: CompilerSettings | None = None) -> Any:
+    """Instantiate a registered adapter by kind.
+
+    Raises:
+        UnknownAdapterError: when *kind* was never registered.
+    """
+    info = _REGISTRY.get(kind)
+    if info is None:
+        raise UnknownAdapterError(
+            f"no adapter registered for {kind!r}",
+            context={"available": sorted(_REGISTRY)},
+            suggestions=[
+                "install the adapter's extra (e.g. pip install capability-compiler[browser])",
+                "check spelling of the adapter kind",
+            ],
+        )
+    if settings is None:
+        from capability_compiler.config import CompilerSettings
+
+        settings = CompilerSettings()
+    return info.factory(settings)
+
+
+def available_adapters() -> list[str]:
+    """Sorted kind names of all registered adapters."""
+    return sorted(_REGISTRY)
+
+
+__all__ = [
+    "AdapterInfo",
+    "EnvironmentAdapter",
+    "available_adapters",
+    "create_adapter",
+    "register_adapter",
+]

capability_compiler/adapters/browser/__init__.py

@@ -0,0 +1,7 @@
+"""Browser adapter package (Playwright-based)."""
+
+from capability_compiler.adapters.browser.adapter import BrowserAdapter, register, url_allowed
+from capability_compiler.adapters.browser.aria import parse_aria_snapshot
+from capability_compiler.adapters.browser.elements import parse_scan
+
+__all__ = ["BrowserAdapter", "parse_aria_snapshot", "parse_scan", "register", "url_allowed"]