codeframe-ai 0.9.0__py3-none-any.whl

codeframe/core/engine_registry.py

@@ -0,0 +1,256 @@
+"""Engine registry for adapter lookup and resolution."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from codeframe.core.adapters.agent_adapter import AgentAdapter
+
+
+# All valid engine names
+VALID_ENGINES = frozenset({
+    "react",
+    "plan",
+    "claude-code",
+    "codex",
+    "opencode",
+    "kilocode",
+    "cloud",
+    "built-in",  # Alias for "react"
+})
+
+# External engines that use subprocess adapters (no LLM provider needed)
+EXTERNAL_ENGINES = frozenset({
+    "claude-code",
+    "codex",
+    "opencode",
+    "kilocode",
+    "cloud",
+})
+
+# Builtin engines that need workspace + LLM provider
+BUILTIN_ENGINES = frozenset({
+    "react",
+    "plan",
+    "built-in",
+})
+
+
+def resolve_engine(cli_engine: str | None = None) -> str:
+    """Resolve which engine to use.
+
+    Priority:
+    1. CLI --engine flag (explicit wins)
+    2. CODEFRAME_ENGINE environment variable
+    3. Default: "react"
+
+    Args:
+        cli_engine: Engine name from CLI flag, or None.
+
+    Returns:
+        Resolved engine name.
+
+    Raises:
+        ValueError: If resolved engine is not valid.
+    """
+    engine = cli_engine or os.environ.get("CODEFRAME_ENGINE") or "react"
+
+    # Normalize alias
+    if engine == "built-in":
+        engine = "react"
+
+    if engine not in VALID_ENGINES:
+        raise ValueError(
+            f"Invalid engine '{engine}'. "
+            f"Must be one of: {', '.join(sorted(VALID_ENGINES))}"
+        )
+
+    return engine
+
+
+def is_external_engine(engine: str) -> bool:
+    """Check if an engine uses an external subprocess adapter."""
+    return engine in EXTERNAL_ENGINES
+
+
+def get_external_adapter(engine: str, **kwargs: Any) -> AgentAdapter:
+    """Get an adapter instance for an external engine.
+
+    Args:
+        engine: Engine name (must be in EXTERNAL_ENGINES).
+        **kwargs: Adapter-specific keyword arguments.
+
+    Returns:
+        AgentAdapter instance.
+
+    Raises:
+        ValueError: If engine is not an external engine.
+        EnvironmentError: If the required binary is not installed.
+    """
+    if engine == "claude-code":
+        from codeframe.core.adapters.claude_code import ClaudeCodeAdapter
+
+        return ClaudeCodeAdapter(**kwargs)
+    elif engine == "codex":
+        from codeframe.core.adapters.codex import CodexAdapter
+
+        return CodexAdapter(**kwargs)
+    elif engine == "opencode":
+        from codeframe.core.adapters.opencode import OpenCodeAdapter
+
+        return OpenCodeAdapter()
+    elif engine == "kilocode":
+        from codeframe.core.adapters.kilocode import KilocodeAdapter
+
+        return KilocodeAdapter(**kwargs)
+    elif engine == "cloud":
+        from codeframe.adapters.e2b.adapter import E2BAgentAdapter
+
+        timeout_minutes = kwargs.get("timeout_minutes", 30)
+        return E2BAgentAdapter(timeout_minutes=timeout_minutes)
+    else:
+        raise ValueError(
+            f"Unknown external engine '{engine}'. "
+            f"Valid external engines: {', '.join(sorted(EXTERNAL_ENGINES))}"
+        )
+
+
+def get_builtin_adapter(
+    engine: str,
+    workspace: Any,
+    llm_provider: Any,
+    **kwargs: Any,
+) -> AgentAdapter:
+    """Get an adapter instance for a builtin engine.
+
+    Args:
+        engine: Engine name (must be in BUILTIN_ENGINES).
+        workspace: Workspace instance.
+        llm_provider: LLM provider instance.
+        **kwargs: Additional keyword arguments passed to the adapter.
+
+    Returns:
+        AgentAdapter instance.
+
+    Raises:
+        ValueError: If engine is not a builtin engine.
+    """
+    resolved = "react" if engine == "built-in" else engine
+
+    if resolved == "react":
+        from codeframe.core.adapters.builtin import BuiltinReactAdapter
+
+        return BuiltinReactAdapter(workspace, llm_provider, **kwargs)
+    elif resolved == "plan":
+        from codeframe.core.adapters.builtin import BuiltinPlanAdapter
+
+        return BuiltinPlanAdapter(workspace, llm_provider, **kwargs)
+    else:
+        raise ValueError(
+            f"Unknown builtin engine '{engine}'. "
+            f"Valid builtin engines: {', '.join(sorted(BUILTIN_ENGINES))}"
+        )
+
+
+def check_requirements(engine: str) -> dict[str, bool]:
+    """Check if an engine's requirements are met.
+
+    Args:
+        engine: Engine name to check.
+
+    Returns:
+        Dict of requirement-name → bool (True if satisfied).
+
+    Raises:
+        ValueError: If engine is not valid.
+    """
+    if engine not in VALID_ENGINES:
+        raise ValueError(
+            f"Invalid engine '{engine}'. "
+            f"Must be one of: {', '.join(sorted(VALID_ENGINES))}"
+        )
+
+    # Resolve alias
+    resolved = "react" if engine == "built-in" else engine
+
+    # Get the adapter class and check for a requirements() classmethod
+    adapter_cls = _get_adapter_class(resolved)
+    if adapter_cls is None:
+        return {}
+
+    req_method = getattr(adapter_cls, "requirements", None)
+    if req_method is None or not callable(req_method):
+        return {}
+
+    reqs = req_method()
+    result: dict[str, bool] = {}
+    for key in reqs:
+        # Check environment variables for builtin engines
+        result[key] = bool(os.getenv(key))
+
+    # External adapters may also have a check_ready() classmethod
+    check_ready = getattr(adapter_cls, "check_ready", None)
+    if check_ready and callable(check_ready):
+        result.update(check_ready())
+
+    return result
+
+
+def _get_adapter_class(engine: str) -> type | None:
+    """Get the adapter class for an engine (without instantiating)."""
+    if engine == "react":
+        from codeframe.core.adapters.builtin import BuiltinReactAdapter
+        return BuiltinReactAdapter
+    elif engine == "plan":
+        from codeframe.core.adapters.builtin import BuiltinPlanAdapter
+        return BuiltinPlanAdapter
+    elif engine == "claude-code":
+        from codeframe.core.adapters.claude_code import ClaudeCodeAdapter
+        return ClaudeCodeAdapter
+    elif engine == "codex":
+        from codeframe.core.adapters.codex import CodexAdapter
+        return CodexAdapter
+    elif engine == "opencode":
+        from codeframe.core.adapters.opencode import OpenCodeAdapter
+        return OpenCodeAdapter
+    elif engine == "kilocode":
+        from codeframe.core.adapters.kilocode import KilocodeAdapter
+        return KilocodeAdapter
+    elif engine == "cloud":
+        from codeframe.adapters.e2b.adapter import E2BAgentAdapter
+        return E2BAgentAdapter
+    return None
+
+
+def get_adapter(
+    engine: str,
+    workspace: Any = None,
+    llm_provider: Any = None,
+    **kwargs: Any,
+) -> AgentAdapter:
+    """Get an adapter for any engine type.
+
+    Unified factory that handles both external and builtin engines.
+
+    Args:
+        engine: Engine name.
+        workspace: Workspace (required for builtin engines).
+        llm_provider: LLM provider (required for builtin engines).
+        **kwargs: Additional adapter-specific arguments.
+
+    Returns:
+        AgentAdapter instance.
+
+    Raises:
+        ValueError: If engine is invalid or builtin engine missing required args.
+        EnvironmentError: If external engine binary is not installed.
+    """
+    if is_external_engine(engine):
+        return get_external_adapter(engine, **kwargs)
+    else:
+        if workspace is None or llm_provider is None:
+            raise ValueError(
+                f"Builtin engine '{engine}' requires workspace and llm_provider"
+            )
+        return get_builtin_adapter(engine, workspace, llm_provider, **kwargs)

codeframe/core/engine_stats.py

@@ -0,0 +1,231 @@
+"""Engine performance tracking for CodeFRAME.
+
+Records per-run engine metrics and computes aggregate statistics
+for comparing engine performance (react vs plan vs external adapters).
+
+This module is headless - no FastAPI or HTTP dependencies.
+"""
+
+from typing import Optional
+
+from codeframe.core.workspace import Workspace, get_db_connection, _utc_now
+
+
+def record_run(
+    workspace: Workspace,
+    run_id: str,
+    engine: str,
+    task_id: str,
+    status: str,
+    duration_ms: Optional[int] = None,
+    tokens_used: int = 0,
+    gates_passed: Optional[int] = None,
+    self_corrections: int = 0,
+) -> None:
+    """Record an engine run in the run_engine_log table.
+
+    After inserting, recomputes aggregate stats for the engine.
+
+    Args:
+        workspace: Active workspace.
+        run_id: Unique run identifier.
+        engine: Engine name (e.g. "react", "plan").
+        task_id: Task that was executed.
+        status: Final run status (COMPLETED, FAILED, BLOCKED).
+        duration_ms: Execution duration in milliseconds.
+        tokens_used: Total LLM tokens consumed.
+        gates_passed: 1 if all gates passed, 0 if not, None if no gate data.
+        self_corrections: Number of self-correction attempts.
+    """
+    now = _utc_now().isoformat()
+
+    conn = get_db_connection(workspace)
+    try:
+        conn.execute(
+            "INSERT INTO run_engine_log "
+            "(run_id, engine, task_id, workspace_id, status, duration_ms, "
+            "tokens_used, gates_passed, self_corrections, created_at) "
+            "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+            (
+                run_id,
+                engine,
+                task_id,
+                workspace.id,
+                status,
+                duration_ms,
+                tokens_used,
+                gates_passed,
+                self_corrections,
+                now,
+            ),
+        )
+        # Recompute aggregates in the same connection to avoid TOCTOU issues
+        _update_aggregate_stats_conn(conn, workspace.id, engine)
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def _update_aggregate_stats(workspace: Workspace, engine: str) -> None:
+    """Recompute aggregate metrics for an engine (opens its own connection).
+
+    Convenience wrapper for external callers (e.g., data seeding).
+    """
+    conn = get_db_connection(workspace)
+    try:
+        _update_aggregate_stats_conn(conn, workspace.id, engine)
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def _update_aggregate_stats_conn(conn, ws_id: str, engine: str) -> None:
+    """Recompute aggregate metrics using an existing connection.
+
+    Does NOT commit — caller is responsible for committing.
+    """
+    now = _utc_now().isoformat()
+
+    cur = conn.cursor()
+
+    # Compute all metrics in one pass where possible
+    row = cur.execute(
+        "SELECT "
+        "  COUNT(*), "
+        "  COUNT(CASE WHEN status = 'COMPLETED' THEN 1 END), "
+        "  COUNT(CASE WHEN status = 'FAILED' THEN 1 END), "
+        "  COUNT(CASE WHEN gates_passed = 1 THEN 1 END), "
+        "  COUNT(CASE WHEN gates_passed IS NOT NULL THEN 1 END), "
+        "  COUNT(CASE WHEN self_corrections > 0 THEN 1 END), "
+        "  AVG(CASE WHEN duration_ms IS NOT NULL THEN duration_ms END), "
+        "  SUM(tokens_used), "
+        "  SUM(CASE WHEN status = 'COMPLETED' THEN tokens_used ELSE 0 END), "
+        "  COUNT(CASE WHEN status = 'COMPLETED' THEN 1 END) "
+        "FROM run_engine_log "
+        "WHERE engine = ? AND workspace_id = ?",
+        (engine, ws_id),
+    ).fetchone()
+
+    total = row[0]
+    completed = row[1]
+    failed = row[2]
+    gates_pass_count = row[3]
+    gates_total = row[4]
+    self_corr_count = row[5]
+    avg_duration = row[6]
+    total_tokens = row[7] or 0
+    completed_tokens = row[8] or 0
+    completed_count = row[9]
+
+    gate_pass_rate = (
+        100.0 * gates_pass_count / gates_total if gates_total > 0 else 0.0
+    )
+    self_correction_rate = (
+        100.0 * self_corr_count / total if total > 0 else 0.0
+    )
+    avg_tokens_per_task = (
+        completed_tokens / completed_count if completed_count > 0 else 0.0
+    )
+
+    metrics = {
+        "tasks_attempted": float(total),
+        "tasks_completed": float(completed),
+        "tasks_failed": float(failed),
+        "gate_pass_rate": round(gate_pass_rate, 2),
+        "self_correction_rate": round(self_correction_rate, 2),
+        "avg_duration_ms": round(avg_duration, 2) if avg_duration is not None else 0.0,
+        "total_tokens": float(total_tokens),
+        "avg_tokens_per_task": round(avg_tokens_per_task, 2),
+    }
+
+    for metric, value in metrics.items():
+        cur.execute(
+            "INSERT OR REPLACE INTO engine_stats "
+            "(workspace_id, engine, metric, value, updated_at) "
+            "VALUES (?, ?, ?, ?, ?)",
+            (ws_id, engine, metric, value, now),
+        )
+
+
+def get_engine_stats(
+    workspace: Workspace, engine: Optional[str] = None
+) -> dict[str, dict[str, float]]:
+    """Get aggregate engine statistics.
+
+    Args:
+        workspace: Active workspace.
+        engine: Optional engine filter. If None, returns all engines.
+
+    Returns:
+        Dict keyed by engine name, each value is a dict of metric -> value.
+        Empty dict if no stats exist.
+    """
+    conn = get_db_connection(workspace)
+    try:
+        if engine is not None:
+            rows = conn.execute(
+                "SELECT engine, metric, value FROM engine_stats "
+                "WHERE workspace_id = ? AND engine = ?",
+                (workspace.id, engine),
+            ).fetchall()
+        else:
+            rows = conn.execute(
+                "SELECT engine, metric, value FROM engine_stats "
+                "WHERE workspace_id = ?",
+                (workspace.id,),
+            ).fetchall()
+    finally:
+        conn.close()
+
+    result: dict[str, dict[str, float]] = {}
+    for eng, metric, value in rows:
+        if eng not in result:
+            result[eng] = {}
+        result[eng][metric] = value
+
+    return result
+
+
+def get_run_log(
+    workspace: Workspace, engine: Optional[str] = None, limit: int = 100
+) -> list[dict]:
+    """Get raw per-run records from the run_engine_log table.
+
+    Args:
+        workspace: Active workspace.
+        engine: Optional engine filter.
+        limit: Maximum records to return (default 100).
+
+    Returns:
+        List of dicts, each representing a run record.
+        Ordered by created_at DESC.
+    """
+    conn = get_db_connection(workspace)
+    try:
+        if engine is not None:
+            rows = conn.execute(
+                "SELECT run_id, engine, task_id, workspace_id, status, "
+                "duration_ms, tokens_used, gates_passed, self_corrections, "
+                "created_at FROM run_engine_log "
+                "WHERE workspace_id = ? AND engine = ? "
+                "ORDER BY created_at DESC LIMIT ?",
+                (workspace.id, engine, limit),
+            ).fetchall()
+        else:
+            rows = conn.execute(
+                "SELECT run_id, engine, task_id, workspace_id, status, "
+                "duration_ms, tokens_used, gates_passed, self_corrections, "
+                "created_at FROM run_engine_log "
+                "WHERE workspace_id = ? "
+                "ORDER BY created_at DESC LIMIT ?",
+                (workspace.id, limit),
+            ).fetchall()
+    finally:
+        conn.close()
+
+    columns = [
+        "run_id", "engine", "task_id", "workspace_id", "status",
+        "duration_ms", "tokens_used", "gates_passed", "self_corrections",
+        "created_at",
+    ]
+    return [dict(zip(columns, row)) for row in rows]