@matt82198/aesop 0.1.0 → 0.2.0

package/driver/openai_compatible_driver.py

@@ -0,0 +1,249 @@
+#!/usr/bin/env python3
+"""OpenAI-compatible backend driver for aesop.
+
+Implements AgentDriver for any OpenAI Chat Completions-COMPATIBLE endpoint
+(e.g., OpenRouter, Together, local Ollama). Parameterized by base_url and
+model, supporting optional custom API key environment variable.
+
+REUSES Phase 2 CodexDriver execution contract (file injection, JSON schema,
+full-file replacement, ownership enforcement, verification tier 2/3) but
+overrides only the transport wiring and model resolution.
+
+stdlib-only, ASCII-only, Windows + Linux safe.
+"""
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Dict, Optional
+
+# Add driver to path for imports if needed.
+DRIVER_DIR = Path(__file__).resolve().parent
+if str(DRIVER_DIR) not in sys.path:
+    sys.path.insert(0, str(DRIVER_DIR))
+
+from agent_driver import (  # noqa: E402
+    DriverCapabilities,
+    ROLE_SETUP,
+    ROLE_VERIFY,
+    ROLE_WORKER,
+)
+from codex_driver import CodexDriver  # noqa: E402
+from openai_transport import _AuthStripRedirectHandler  # noqa: E402
+
+
+def make_openai_compatible_transport(
+    base_url: str, api_key_env: str = "OPENAI_API_KEY", timeout_s: float = 120.0
+):
+    """Factory function: return a transport callable for an OpenAI-compatible endpoint.
+
+    Args:
+        base_url: e.g. "https://openrouter.ai/api/v1", "http://localhost:11434/v1"
+        api_key_env: environment variable name for the API key (default "OPENAI_API_KEY")
+        timeout_s: HTTP timeout in seconds
+
+    Returns:
+        A transport callable (payload dict) -> dict matching the CodexDriver contract.
+
+    Raises:
+        RuntimeError: if the API key env var is not set (unless base_url suggests local Ollama).
+    """
+    import urllib.error
+    import urllib.request
+
+    def transport(payload: dict) -> dict:
+        """POST to the OpenAI-compatible endpoint via urllib."""
+        # For local Ollama, the API key may be unused/dummy; for hosted services, get it.
+        # The pattern os.environ.get("OPENAI_API_KEY") does not trigger secret_scan
+        # because the RHS contains dots/parens; we use a variable for flexibility.
+        retrieved_key = os.environ.get(api_key_env)
+        if not retrieved_key and "localhost" not in base_url.lower():
+            raise RuntimeError(
+                f"{api_key_env} environment variable is not set, and "
+                f"base_url '{base_url}' does not look like localhost. "
+                f"Set {api_key_env} before running, or use a FakeTransport in tests."
+            )
+
+        # Use dummy key for local Ollama if not set.
+        if not retrieved_key:
+            retrieved_key = "local-only"
+
+        endpoint = f"{base_url}/chat/completions"
+
+        # Build the HTTP request.
+        payload_json = json.dumps(payload)
+        request = urllib.request.Request(
+            endpoint,
+            data=payload_json.encode("utf-8"),
+            headers={
+                "Authorization": f"Bearer {retrieved_key}",
+                "Content-Type": "application/json",
+            },
+        )
+
+        try:
+            # POST with hard timeout.
+            # Create a custom opener with auth-stripping redirect handler.
+            # This prevents Authorization header leakage on cross-origin redirects.
+            opener = urllib.request.build_opener(_AuthStripRedirectHandler())
+            with opener.open(request, timeout=timeout_s) as response:
+                status = response.status
+                body = response.read().decode("utf-8")
+
+            # Classify non-2xx as an error.
+            if not (200 <= status < 300):
+                raise RuntimeError(
+                    f"OpenAI-compatible API returned HTTP {status}: {body[:200]}"
+                )
+
+            return json.loads(body)
+
+        except urllib.error.URLError as exc:
+            raise RuntimeError(f"OpenAI-compatible API request failed: {exc}") from exc
+        except json.JSONDecodeError as exc:
+            raise RuntimeError(f"OpenAI-compatible API returned invalid JSON: {exc}") from exc
+
+    return transport
+
+
+class OpenAICompatibleDriver(CodexDriver):
+    """AgentDriver for OpenAI-Chat-Completions-COMPATIBLE endpoints.
+
+    Supports OpenRouter, Together, local Ollama, and any service offering
+    OpenAI-compatible endpoints. Configurable base_url, model, and API key env var.
+
+    REUSES CodexDriver's Phase 2 execution contract entirely (file injection,
+    JSON schema validation with retry, full-file replacement, ownership enforcement).
+    Overrides only:
+      - resolve_model: returns the configured model (not a role map)
+      - transport construction: points urllib at the configured base_url
+      - probe_capabilities: honest reporting of verification tier (2 for hosted, 3 for local small)
+    """
+
+    name = "openai-compatible"
+
+    def __init__(
+        self,
+        base_url: str,
+        model: str,
+        api_key_env: str = "OPENAI_API_KEY",
+        is_local: bool = False,
+        model_map: Optional[dict] = None,
+        transport: Optional[callable] = None,
+        now: Optional[callable] = None,
+        max_owned_bytes: int = 200_000,
+        max_retries: int = 2,
+        timeout_s: float = 120.0,
+    ):
+        """Initialize the OpenAI-compatible driver.
+
+        Args:
+            base_url: OpenAI-compatible endpoint URL (e.g., https://openrouter.ai/api/v1)
+            model: Model ID to use (e.g., "gpt-4-turbo" on OpenRouter, "neural-chat" on Ollama)
+            api_key_env: Environment variable name for API key (default "OPENAI_API_KEY").
+                For local Ollama, can be unused/dummy.
+            is_local: If True, marks this as a local/small model and sets verification tier to 3.
+                Default False (hosted models -> tier 2).
+            model_map: Optional role-to-model mapping for setup/verify roles (default=None, uses role-based fallback).
+            transport: Optional injectable transport callable for testing (default=None, builds from base_url).
+            now: callable returning time.time() for testing (default=time.time).
+            max_owned_bytes: max total bytes of owned files (default 200KB).
+            max_retries: max in-turn retries on malformed JSON (default 2).
+            timeout_s: HTTP timeout in seconds (default 120).
+        """
+        self._base_url = base_url
+        self._model = model
+        self._api_key_env = api_key_env
+        self._is_local = is_local
+
+        # Build the transport if not provided (for testing).
+        if transport is None:
+            transport = make_openai_compatible_transport(
+                base_url=base_url,
+                api_key_env=api_key_env,
+                timeout_s=timeout_s,
+            )
+
+        # If no model_map provided, use a simple single-model fallback.
+        # All roles use the same model.
+        if model_map is None:
+            model_map = {}
+
+        # Initialize CodexDriver with the transport.
+        # CodexDriver's __init__ will merge model_map with defaults.
+        super().__init__(
+            model_map=model_map,
+            transport=transport,
+            now=now,
+            max_owned_bytes=max_owned_bytes,
+            max_retries=max_retries,
+            timeout_s=timeout_s,
+        )
+
+    def probe_capabilities(self) -> DriverCapabilities:
+        """Honest capability matrix for OpenAI-compatible backend.
+
+        Reuses CodexDriver tier 2 (hosted strong models like OpenRouter GPT-4)
+        or tier 3 (local small models like Ollama neural-chat) based on is_local.
+
+        Same contract as CodexDriver:
+          - No native parallelism (orchestrator provides external loop).
+          - No worker filesystem/shell (orchestrator injects + runs).
+          - Structured output via JSON schema.
+          - No worktree isolation (temp-dir).
+          - Honest tool-use accuracy (lower for local small models).
+        """
+        if self._is_local:
+            # Local/small model: Tier 3 (higher verification burden).
+            # Tool-use accuracy lower than hosted models.
+            accuracy = 0.80
+            tier = 3
+            notes = (
+                "Local/small open model (e.g., Ollama neural-chat). Tier 3: "
+                "validate all output, heavy spot-check, adversarial review required. "
+                "Orchestrator-managed backend: no parallelism, no worker filesystem/shell."
+            )
+        else:
+            # Hosted strong model (e.g., OpenRouter GPT-4): Tier 2.
+            # Better accuracy than local models but lower than Claude.
+            accuracy = 0.92
+            tier = 2
+            notes = (
+                "Hosted OpenAI-compatible backend (e.g., OpenRouter, Together). "
+                "Tier 2: validate all JSON, ~50% spot-check, adversarial review. "
+                "Orchestrator-managed backend: no parallelism, no worker filesystem/shell."
+            )
+
+        return DriverCapabilities(
+            name=f"{self.name} ({self._model})",
+            parallel_dispatch=False,  # no native async; orchestrator loops
+            worker_filesystem_access=False,  # orchestrator injects files
+            worker_shell_access=False,  # orchestrator runs tests
+            structured_output=True,  # JSON schema + response_format
+            worktree_isolation=False,  # temp-dir fallback; no git
+            native_cost_tracking=True,  # most endpoints report usage
+            native_stall_detection=False,  # orchestrator times out
+            tool_use_accuracy=accuracy,
+            recommended_verification_tier=tier,
+            available_models=(self._model,),
+            notes=notes,
+        )
+
+    def resolve_model(self, role: str) -> str:
+        """Resolve an abstract role to the configured model.
+
+        For an OpenAI-compatible endpoint, always use the configured model.
+        This overrides CodexDriver's role-based model mapping since we're a
+        single-model adapter (all roles use the same model).
+
+        Args:
+            role: abstract role (worker/setup/verify)
+
+        Returns:
+            The configured model string (same for all roles).
+        """
+        # Always use self._model for OpenAI-compatible drivers.
+        # They target a single endpoint/model, unlike CodexDriver which can
+        # vary models by role (worker=gpt-3.5, setup/verify=gpt-4).
+        return self._model

package/driver/openai_transport.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""OpenAI HTTP transport for the AgentDriver codex_driver.
+
+Provides a callable transport that POSTs to the OpenAI Chat Completions API
+via stdlib urllib.request. This is the injectable seam that lets tests pass
+canned responses without network/secrets, and lets the driver stay dependency-light.
+
+Transport contract:
+  Transport = callable(payload: dict) -> dict
+  where payload is the OpenAI Chat Completions request body (with schema + messages)
+  and returns the parsed response JSON (with choices/usage).
+
+The real transport reads OPENAI_API_KEY from os.environ at call time (NEVER
+hardcoded). Use the pattern:
+  key = os.environ.get("OPENAI_API_KEY")
+so the source code string does NOT trigger secret_scan rules.
+"""
+
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+
+
+# Type alias documenting the transport callable contract.
+Transport = callable  # (payload: dict) -> dict
+
+
+class _AuthStripRedirectHandler(urllib.request.HTTPRedirectHandler):
+    """Custom redirect handler that strips Authorization on cross-origin redirects.
+
+    This prevents credentials from leaking to a different host if the base_url
+    or a network MITM redirects the request (e.g., 301/302 to evil.com).
+    Same-origin redirects preserve the Authorization header.
+    """
+
+    # Sensitive headers that must not leak on cross-origin redirects.
+    _SENSITIVE_HEADERS = {"authorization", "api-key", "x-api-key"}
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        """Handle redirect: strip sensitive headers if the origin changed.
+
+        Args:
+            req: original Request object
+            fp: file pointer (unused here)
+            code: HTTP redirect status code (301, 302, 307, etc.)
+            msg: HTTP reason message (unused here)
+            headers: response headers (unused here)
+            newurl: the redirect target URL
+
+        Returns:
+            A new urllib.request.Request with Authorization stripped if
+            newurl is a different origin; otherwise a Request preserving headers.
+        """
+        # Parse both URLs to extract origin (scheme + host + port).
+        orig_parsed = urllib.parse.urlparse(req.full_url)
+        new_parsed = urllib.parse.urlparse(newurl)
+
+        # Build comparable origins (normalize port if not specified).
+        orig_origin = (
+            orig_parsed.scheme,
+            orig_parsed.hostname or "",
+            orig_parsed.port or (443 if orig_parsed.scheme == "https" else 80),
+        )
+        new_origin = (
+            new_parsed.scheme,
+            new_parsed.hostname or "",
+            new_parsed.port or (443 if new_parsed.scheme == "https" else 80),
+        )
+
+        # Let the parent class build the redirected request normally.
+        redirected = super().redirect_request(
+            req, fp, code, msg, headers, newurl
+        )
+
+        # If origins differ, strip sensitive headers from the new request.
+        if orig_origin != new_origin and redirected:
+            for header_name in list(redirected.headers.keys()):
+                if header_name.lower() in self._SENSITIVE_HEADERS:
+                    del redirected.headers[header_name]
+
+        return redirected
+
+
+def default_openai_transport(
+    payload: dict, timeout_s: float = 120.0, base_url: str = "https://api.openai.com/v1"
+) -> dict:
+    """Default transport: POST to OpenAI Chat Completions via urllib.
+
+    Args:
+        payload: OpenAI Chat Completions request body (messages, model, etc.).
+        timeout_s: HTTP timeout in seconds (default 120).
+        base_url: OpenAI API base URL (default production).
+
+    Returns:
+        Parsed JSON response (choices, usage, etc.).
+
+    Raises:
+        RuntimeError: if OPENAI_API_KEY env var is not set, or if the HTTP
+            status is not 200-299.
+        urllib.error.URLError: if the HTTP request fails.
+    """
+    # Read API key at call time from environment; NEVER hardcoded.
+    # The pattern os.environ.get("OPENAI_API_KEY") does not trigger secret_scan
+    # because the RHS contains dots/parens.
+    api_key = os.environ.get("OPENAI_API_KEY")
+    if not api_key:
+        raise RuntimeError(
+            "OPENAI_API_KEY environment variable is not set. "
+            "Set it before running the codex driver, or pass a FakeTransport in tests."
+        )
+
+    endpoint = f"{base_url}/chat/completions"
+
+    # Build the HTTP request.
+    payload_json = json.dumps(payload)
+    request = urllib.request.Request(
+        endpoint,
+        data=payload_json.encode("utf-8"),
+        headers={
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+        },
+    )
+
+    try:
+        # Create a custom opener with auth-stripping redirect handler.
+        # This prevents Authorization header leakage on cross-origin redirects.
+        opener = urllib.request.build_opener(_AuthStripRedirectHandler())
+        with opener.open(request, timeout=timeout_s) as response:
+            status = response.status
+            body = response.read().decode("utf-8")
+
+        # Classify non-2xx as an error.
+        if not (200 <= status < 300):
+            raise RuntimeError(
+                f"OpenAI API returned HTTP {status}: {body[:200]}"
+            )
+
+        return json.loads(body)
+
+    except urllib.error.URLError as exc:
+        raise RuntimeError(f"OpenAI API request failed: {exc}") from exc
+    except json.JSONDecodeError as exc:
+        raise RuntimeError(f"OpenAI API returned invalid JSON: {exc}") from exc

package/driver/verification_policy.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""Verification policy mapping for AgentDriver backends.
+
+Pure function: given a DriverCapabilities (with recommended_verification_tier),
+return a dict of verification tuning parameters that the wave's integration
+verifier can use to decide how aggressively to spot-check and repair.
+
+This encodes spike-multitool-portability.md Section 4.3: the tier->policy
+mapping that tells the template what verification bars each backend owes.
+
+No I/O, no imports beyond agent_driver.
+"""
+
+from agent_driver import DriverCapabilities
+
+
+def verification_policy(caps: DriverCapabilities) -> dict:
+    """Map a backend's verification tier to orchestrator verification tuning.
+
+    Returns a dict with the following keys (all required):
+      validate_all_json: bool -- if True, validate every worker's JSON output
+          (Tier 2+); if False, trust it (Tier 1).
+      spot_check_frac: float in [0.0, 1.0] -- fraction of results to spot-check.
+      repair_cap: int -- maximum repair attempts per worker.
+      require_adversarial_review: bool -- if True, require refutation-style
+          review (reason about code vs contract, not just re-run tests).
+
+    The tier is a proxy for tool_use_accuracy and determines the orchestrator's
+    burden. Weaker backends (lower accuracy) require higher tiers + heavier
+    verification.
+
+    Args:
+        caps: DriverCapabilities from probe_capabilities().
+
+    Returns:
+        dict with verification tuning.
+
+    Raises:
+        ValueError: if tier is not in [1, 2, 3, 4].
+    """
+    tier = caps.recommended_verification_tier
+
+    # Map tier -> policy per spike Section 4.3.
+    if tier == 1:
+        return {
+            "validate_all_json": False,
+            "spot_check_frac": 0.10,
+            "repair_cap": 1,
+            "require_adversarial_review": False,
+        }
+    elif tier == 2:
+        return {
+            "validate_all_json": True,
+            "spot_check_frac": 0.50,
+            "repair_cap": 2,
+            "require_adversarial_review": True,
+        }
+    elif tier == 3:
+        return {
+            "validate_all_json": True,
+            "spot_check_frac": 1.00,
+            "repair_cap": 2,
+            "require_adversarial_review": True,
+        }
+    elif tier == 4:
+        return {
+            "validate_all_json": True,
+            "spot_check_frac": 1.00,
+            "repair_cap": 3,
+            "require_adversarial_review": True,
+        }
+    else:
+        raise ValueError(
+            f"Unknown verification tier {tier}; must be in [1, 2, 3, 4]"
+        )