fc-data 0.2.0__py3-none-any.whl

datasmith/agents/classifiers.py

@@ -0,0 +1,272 @@
+from __future__ import annotations
+
+import enum
+import os
+from dataclasses import dataclass
+from typing import Any
+
+from datasmith.utils import get_logger
+
+logger = get_logger("agents.classifiers")
+
+
+class OptimizationType(str, enum.Enum):
+    USE_BETTER_ALGORITHM = "use_better_algorithm"
+    USE_BETTER_DATA_STRUCTURE_AND_LAYOUT = "use_better_data_structure_and_layout"
+    USE_LOWER_LEVEL_SYSTEM = "use_lower_level_system"
+    ACCEPT_LESS_PRECISE_SOLUTION = "accept_less_precise_solution"
+    USE_PARALLELIZATION = "use_parallelization"
+    REMOVE_OR_REDUCE_WORK = "remove_or_reduce_work"
+    CACHE_AND_REUSE = "cache_and_reuse"
+    DO_IT_EARLIER_BATCH_THROTTLE = "do_it_earlier_batch_throttle"
+    SCALE_PLATFORM = "scale_platform"
+    DATABASE_AND_STORAGE_TUNING = "database_and_storage_tuning"
+    MICRO_OPTIMIZATIONS = "micro_optimizations"
+    IO_AND_LATENCY_HIDING = "io_and_latency_hiding"
+    USE_HIGHER_LEVEL_SYSTEM = "use_higher_level_system"
+    UNCATEGORIZED = "uncategorized"
+
+    @property
+    def description(self) -> str:
+        return _OPTIMIZATION_DESCRIPTIONS.get(self.value, "")
+
+
+_OPTIMIZATION_DESCRIPTIONS: dict[str, str] = {
+    "use_better_algorithm": (
+        "Complexity reduction or switching to a faster algorithm "
+        "(e.g. O(n^2) -> O(n log n), better sorting, smarter search)."
+    ),
+    "use_better_data_structure_and_layout": (
+        "Switching to a more efficient data structure or improving memory layout "
+        "(e.g. list -> set/dict for lookups, struct-of-arrays, contiguous buffers)."
+    ),
+    "use_lower_level_system": (
+        "Offloading work to C/Cython/Rust/Fortran extensions, NumPy vectorized ops, "
+        "or native SIMD intrinsics instead of pure Python."
+    ),
+    "accept_less_precise_solution": (
+        "Trading accuracy for speed via approximations, heuristics, sampling, "
+        "or reduced precision (e.g. float32 instead of float64)."
+    ),
+    "use_parallelization": (
+        "Using threads, multiprocessing, GPU kernels, or parallel algorithms "
+        "to split work across cores (not just async I/O)."
+    ),
+    "remove_or_reduce_work": (
+        "Eliminating unnecessary computation, short-circuiting, early exits, "
+        "skipping redundant steps, or simplifying requirements."
+    ),
+    "cache_and_reuse": (
+        "Memoization, LRU caches, materialized views, precomputed lookup tables, "
+        "or reusing expensive results across calls."
+    ),
+    "do_it_earlier_batch_throttle": (
+        "Batching small operations, lazy evaluation, deferred computation, "
+        "throttling, or moving work to an earlier/better time."
+    ),
+    "scale_platform": (
+        "Horizontal/vertical scaling, load balancing, sharding, or infrastructure-level capacity changes."
+    ),
+    "database_and_storage_tuning": (
+        "Adding indices, optimizing queries, denormalization, partitioning, "
+        "connection pooling, or storage engine configuration."
+    ),
+    "micro_optimizations": (
+        "Hot-path tweaks: inlining, branch reordering, avoiding temporary objects, "
+        "strength reduction, guard clauses, or tight-loop tuning."
+    ),
+    "io_and_latency_hiding": (
+        "Async/non-blocking I/O, overlapping I/O with compute, prefetching, pipelining, or reducing round-trip latency."
+    ),
+    "use_higher_level_system": (
+        "Replacing hand-rolled logic with an optimized library or framework "
+        "(e.g. pandas, polars, scipy, BLAS) that handles performance internally."
+    ),
+    "uncategorized": ("Performance-related change that does not clearly fit any of the above categories."),
+}
+
+
+class DifficultyLevel(str, enum.Enum):
+    EASY = "easy"
+    MEDIUM = "medium"
+    HARD = "hard"
+
+
+@dataclass
+class ClassificationDecision:
+    reason: str = ""
+    category: str = ""
+    difficulty: str = ""
+    confidence: int = 0
+
+    def __post_init__(self) -> None:
+        self.confidence = max(0, min(100, self.confidence))
+
+    @classmethod
+    def from_prediction(cls, prediction: Any) -> ClassificationDecision:
+        """Create a decision object from a DSPy prediction response."""
+        reasoning = getattr(prediction, "reasoning", "") or ""
+        category = getattr(prediction, "category", "") or ""
+        difficulty = getattr(prediction, "difficulty", "") or ""
+        raw_confidence = getattr(prediction, "confidence", None)
+
+        confidence: int
+        if isinstance(raw_confidence, int):
+            confidence = raw_confidence
+        else:
+            try:
+                confidence = int(str(raw_confidence).strip()) if raw_confidence is not None else 0
+            except (TypeError, ValueError):
+                confidence = 0
+
+        return cls(
+            reason=str(reasoning).strip(),
+            category=str(category).strip(),
+            difficulty=str(difficulty).strip(),
+            confidence=confidence,
+        )
+
+
+class PerfClassifier:
+    """Binary classifier: is this PR a performance improvement?"""
+
+    def __init__(self) -> None:
+        self._predictor: Any | None = None
+
+    def _get_predictor(self) -> Any:
+        if self._predictor is None:
+            from datasmith.agents.config import ensure_configured
+
+            ensure_configured()
+            import dspy
+
+            class JudgeSignature(dspy.Signature):
+                """Decide if this commit's PRIMARY intent is to improve product/runtime performance.
+
+                Label YES only when there is CLEAR, EXPLICIT evidence in the description and/or patch that the
+                runtime gets faster (e.g., algorithm change, fewer allocations, caching, vectorization, reduced I/O,
+                async/non-blocking for throughput, latency reduction, memory footprint reduction, fix a speed regression).
+
+                Strong positive signals (weigh these collectively):
+                - PR title/body contains performance intent (e.g., "PERF:", "speed up", "faster", "performance").
+                - Linked issues/comments include benchmark links or timings demonstrating impact.
+                - Low-level/hot-path tweaks (e.g., reuse global context, avoid per-call init/teardown, vectorize C/NumPy).
+
+                Hard NO (non-performance) examples: tests/ASV/harness-only changes; CI/workflows/build/packaging; coverage;
+                pre-commit/format/lints (clippy/ruff/black); docs; version bumps; terminology/renames; pure refactors without
+                performance claims; changes aimed at making perf tests pass but not improving runtime.
+
+                If ambiguous, weigh the concrete code changes and problem description together. When there are
+                specific performance cues (title keywords, measured timings, fewer allocations, vectorization,
+                caching/reuse) lean YES; otherwise NO.
+                """
+
+                problem_description: str = dspy.InputField(desc="Problem statement and technical context from PR/issue")
+                github_patch: str = dspy.InputField(desc="Git diff showing actual code changes")
+                file_change_summary: str = dspy.InputField(
+                    desc="A markdown table summarizing all the files changed in the commit along with lines added/removed.",
+                    default="",
+                )
+                reasoning: str = dspy.OutputField(desc="Deductive reasoning steps leading to the classification.")
+                label: str = dspy.OutputField(desc='Final label: "YES" for performance-related, "NO" otherwise.')
+
+            self._predictor = dspy.Predict(JudgeSignature)
+        return self._predictor
+
+    def classify(
+        self, problem_description: str, github_patch: str = "", file_change_summary: str = ""
+    ) -> tuple[bool, str]:
+        try:
+            predictor = self._get_predictor()
+            result = predictor(
+                problem_description=problem_description,
+                github_patch=github_patch,
+                file_change_summary=file_change_summary,
+            )
+            label = str(getattr(result, "label", "NO"))
+            is_perf = label.strip().upper().startswith("YES")
+            reasoning = str(getattr(result, "reasoning", ""))
+        except Exception:
+            logger.exception("PerfClassifier failed")
+            return False, "Classification failed"
+        else:
+            return is_perf, reasoning
+
+
+class ClassifyJudge:
+    """Classify optimization type and difficulty."""
+
+    def __init__(self, max_tokens: int | None = None) -> None:
+        self._max_tokens = max_tokens or int(os.getenv("DSPY_MAX_TOKENS", "16000"))
+        self._predictor: Any | None = None
+
+    def _get_predictor(self) -> Any:
+        if self._predictor is None:
+            from datasmith.agents.config import ensure_configured
+
+            ensure_configured()
+            import dspy
+
+            cat_lines = "\n".join(f"- {t.value}: {t.description}" for t in OptimizationType)
+            cat_values = ", ".join(t.value for t in OptimizationType)
+
+            class ClassifySignature(dspy.Signature):
+                """Decide the PRIMARY performance optimization technique and difficulty level."""
+
+                problem_description: str = dspy.InputField(desc="Problem statement and technical context from PR/issue")
+                github_patch: str = dspy.InputField(desc="Git patch showing code changes")
+                category: str = dspy.OutputField(desc=f"One of: {cat_values}")
+                difficulty: str = dspy.OutputField(desc="One of: easy, medium, hard")
+                reasoning: str = dspy.OutputField(desc="Brief explanation of the classification")
+
+            ClassifySignature.__doc__ = (
+                "Decide the PRIMARY performance optimization technique and difficulty level.\n\n"
+                f"Category mapping (pick the single best match):\n{cat_lines}\n\n"
+                "Difficulty levels:\n"
+                "- easy: localized change (<50 lines), minimal risk\n"
+                "- medium: module-level refactor, data structure changes\n"
+                "- hard: algorithm rewrite or architectural change"
+            )
+
+            self._predictor = dspy.Predict(ClassifySignature)
+        return self._predictor
+
+    def truncate_patch(self, patch: str) -> str:
+        try:
+            import tiktoken
+
+            enc = tiktoken.get_encoding("cl100k_base")
+            tokens = enc.encode(patch)
+            if len(tokens) > self._max_tokens:
+                tokens = tokens[: self._max_tokens - 10]
+                truncated = enc.decode(tokens)
+                return truncated + "\n\n// [TRUNCATED DUE TO LENGTH]"
+        except Exception:  # noqa: S110
+            pass  # tiktoken not available, return untruncated
+        return patch
+
+    def classify(self, problem_description: str, github_patch: str = "") -> ClassificationDecision:
+        github_patch = self.truncate_patch(github_patch)
+        try:
+            predictor = self._get_predictor()
+            result = predictor(problem_description=problem_description, github_patch=github_patch)
+
+            cat = str(getattr(result, "category", "")).strip().lower()
+            valid_cats = {t.value for t in OptimizationType}
+            if cat not in valid_cats:
+                cat = "uncategorized"
+
+            diff = str(getattr(result, "difficulty", "")).strip().lower()
+            if diff not in ("easy", "medium", "hard"):
+                diff = "medium"
+
+            return ClassificationDecision(
+                reason=str(getattr(result, "reasoning", "")),
+                category=cat,
+                difficulty=diff,
+            )
+        except Exception:
+            logger.exception("ClassifyJudge failed")
+            return ClassificationDecision(
+                reason="Classification failed", category="uncategorized", difficulty="medium", confidence=0
+            )

datasmith/agents/codex.py

@@ -0,0 +1,25 @@
+"""Backward-compatibility shim — real logic lives in agents.installed.codex."""
+
+from __future__ import annotations
+
+from datasmith.agents.installed import AgentResult as CodexResult
+from datasmith.agents.installed import CodexAgent
+from datasmith.agents.installed.codex import _parse_codex_stdout
+
+__all__ = ["CodexResult", "_parse_codex_stdout", "codex_exec"]
+
+
+def codex_exec(
+    prompt: str,
+    timeout: int = 900,
+    workdir: str | None = None,
+    dry_run: bool = False,
+    full_auto: bool = False,
+    sandbox: str = "",
+) -> CodexResult:
+    """Execute a prompt via the Codex CLI.
+
+    Thin wrapper around :class:`~datasmith.agents.installed.codex.CodexAgent`.
+    """
+    agent = CodexAgent(full_auto=full_auto, sandbox=sandbox)
+    return agent.exec_or_dry_run(prompt, timeout=timeout, workdir=workdir, dry_run=dry_run)

datasmith/agents/config.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import contextlib
+import os
+import threading
+from dataclasses import dataclass
+from typing import Any
+
+from datasmith.utils import get_logger
+
+logger = get_logger("agents.config")
+
+
+@dataclass
+class AgentConfig:
+    """Configuration for LLM agent backends."""
+
+    primary_model: str = ""
+    fallback_model: str = ""
+    api_key: str = ""
+    api_base: str = ""
+    max_tokens: int = 16000
+    temperature: float = 0.0
+    portkey_api_key: str = ""
+    portkey_model_name: str = ""
+
+    @classmethod
+    def from_env(cls) -> AgentConfig:
+        return cls(
+            primary_model=os.environ.get("DSPY_MODEL", "openai/gpt-oss-120b"),
+            fallback_model=os.environ.get("DSPY_FALLBACK_MODEL", ""),
+            api_key=os.environ.get("DSPY_API_KEY", "local"),
+            api_base=os.environ.get("DSPY_API_BASE", "http://localhost:30001/v1"),
+            max_tokens=int(os.environ.get("DSPY_MAX_TOKENS", "16000")),
+            temperature=float(os.environ.get("DSPY_TEMPERATURE", "0")),
+            portkey_api_key=os.environ.get("PORTKEY_API_KEY", ""),
+            portkey_model_name=os.environ.get("PORTKEY_MODEL_NAME", ""),
+        )
+
+
+# Module-level state for lazy DSPy configuration.
+_configured = False
+_lock = threading.Lock()
+_lm: Any = None  # Stores the dspy.LM instance for async-safe reuse
+
+
+def configure_dspy(config: AgentConfig) -> None:
+    """Configure DSPy backends from AgentConfig."""
+    global _lm
+    import dspy
+
+    kwargs: dict[str, Any] = {
+        "temperature": config.temperature,
+        "max_tokens": config.max_tokens,
+    }
+
+    if config.api_key and config.primary_model:
+        _lm = dspy.LM(
+            model=config.primary_model,
+            api_key=config.api_key,
+            api_base=config.api_base or None,
+            **kwargs,
+        )
+        model_name = config.primary_model
+    elif config.portkey_api_key:
+        from portkey_ai import PORTKEY_GATEWAY_URL
+
+        model_name = config.portkey_model_name or "@anthropic/claude-3-5-sonnet-latest"
+        kwargs["api_base"] = PORTKEY_GATEWAY_URL
+        kwargs["api_key"] = "unused-by-portkey"
+        kwargs["headers"] = {
+            "x-portkey-api-key": config.portkey_api_key,
+            "x-portkey-provider": model_name.split("/")[0].lstrip("@"),
+        }
+        kwargs["custom_llm_provider"] = "openai"
+        _lm = dspy.LM(model=model_name, **kwargs)
+    else:
+        logger.warning("No LM backend configured")
+        return
+
+    with contextlib.suppress(RuntimeError):
+        dspy.configure(lm=_lm)
+    logger.info("Configured DSPy with model: %s", model_name)
+
+
+def ensure_configured() -> None:
+    """Lazy-initialize DSPy on first LLM call.  Thread- and async-safe.
+
+    Uses double-checked locking to avoid repeated configuration.
+    If ``dspy.configure()`` was already called from a different async task,
+    the stored LM is applied via ``dspy.context()`` instead.
+    """
+    global _configured
+    if _configured:
+        # DSPy was configured, but possibly from a different async task.
+        # Re-apply the LM via dspy.context() which is async-safe.
+        if _lm is not None:
+            import dspy
+
+            with contextlib.suppress(RuntimeError):
+                dspy.configure(lm=_lm)
+        return
+    with _lock:
+        if _configured:
+            return
+        config = AgentConfig.from_env()
+        configure_dspy(config)
+        _configured = True

datasmith/agents/extractors.py

@@ -0,0 +1,197 @@
+"""
+ProblemExtractor: Extractive-first approach for problem statement generation.
+
+Key principles:
+- 90% extractive, 10% abstractive
+- Preserve code snippets verbatim (character-exact)
+- Keep technical terms exactly as written
+- Natural structure over imposed templates
+- Preserve disagreements and different viewpoints
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from datasmith.utils import get_logger
+
+logger = get_logger("agents.extractors")
+
+
+@dataclass
+class ProblemExtraction:
+    """Structured extraction from a PR description.
+
+    Captures four phases of a performance optimization or bug fix:
+    1. initial_observations: Objective symptoms of the problematic behavior
+    2. triage_attempts: Investigative steps and reasoning used to narrow down the issue
+    3. solution_overview: Description of the change(s) made
+    4. solution_observations: Observations after applying the change
+    """
+
+    initial_observations: str = ""
+    triage_attempts: str = ""
+    solution_overview: str = ""
+    solution_observations: str = ""
+
+    def to_problem_markdown(self) -> str:
+        """Render only the problem portion (initial observations)."""
+        text = (self.initial_observations or "").strip()
+        text = re.sub(r"^```json\s*$", "", text, flags=re.MULTILINE)
+        return text
+
+    def _normalise_section(self, content: str | None, header_variants: list[str]) -> str | None:
+        """Remove redundant headers from section content."""
+        if not content:
+            return None
+        content = content.strip()
+        low = content.lstrip().lower()
+        for variant in header_variants:
+            if low.startswith(variant.lower()):
+                lines = content.splitlines()
+                if lines:
+                    lines = lines[1:]
+                content = "\n".join(lines).lstrip()
+                break
+        return content
+
+    def to_full_markdown(self) -> str:
+        """Render all sections with headers."""
+        sections: list[str] = []
+
+        initial_obs = (self.initial_observations or "").strip()
+        if initial_obs:
+            sections.append(initial_obs)
+
+        triage = self._normalise_section(
+            self.triage_attempts,
+            ["## triage attempts", "**triage attempts**"],
+        )
+        if triage:
+            sections.append(f"## Triage Attempts\n\n{triage}")
+
+        solution = self._normalise_section(
+            self.solution_overview,
+            ["## solution overview", "**solution overview**"],
+        )
+        if solution:
+            sections.append(f"## Solution Overview\n\n{solution}")
+
+        solution_obs = self._normalise_section(
+            self.solution_observations,
+            ["## solution observations", "**solution observations**"],
+        )
+        if solution_obs:
+            sections.append(f"## Solution Observations\n\n{solution_obs}")
+
+        text = "\n\n".join(sections).strip()
+        text = re.sub(r"^```json\s*$", "", text, flags=re.MULTILINE)
+        return text
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "initial_observations": self.initial_observations,
+            "triage_attempts": self.triage_attempts,
+            "solution_overview": self.solution_overview,
+            "solution_observations": self.solution_observations,
+        }
+
+
+class ProblemExtractor:
+    """Extractive problem/solution bucketizer using DSPy."""
+
+    def __init__(self) -> None:
+        self._predictor: Any | None = None
+
+    def _get_predictor(self) -> Any:
+        if self._predictor is None:
+            from datasmith.agents.config import ensure_configured
+
+            ensure_configured()
+            import dspy
+
+            class ProblemExtractorSignature(dspy.Signature):
+                """What problem is this Github PR trying to solve? Extract near-verbatim relevant text following the given JSON output. If no relevant context exists for a field, return an empty string for it."""
+
+                pr_title: str = dspy.InputField(desc="The GitHub PR title")
+                pr_body: str = dspy.InputField(desc="The GitHub PR description")
+                pr_comments: str = dspy.InputField(desc="Comments on the PR thread.")
+                initial_observations: str = dspy.OutputField(
+                    desc="Objective symptoms of the problematic behavior, described in the present tense. Focus strictly on what is happening (metrics, user impact, frequency). Do not include causes, hypotheses, or explanations."
+                )
+                triage_attempts: str = dspy.OutputField(
+                    desc="The investigative steps and reasoning used to narrow down contributing factors—what you checked, what you ruled out, and what evidence you gathered to understand where the issue originates."
+                )
+                solution_overview: str = dspy.OutputField(
+                    desc="A concise description of the change(s) made and how they address the identified bottleneck or constraint."
+                )
+                solution_observations: str = dspy.OutputField(
+                    desc="What you observe after applying the change—new measurements, behavior differences, and any regressions or trade-offs that appeared."
+                )
+
+            self._predictor = dspy.Predict(ProblemExtractorSignature)
+        return self._predictor
+
+    def extract_problem(self, pr_title: str, pr_body: str, pr_comments: str = "") -> ProblemExtraction:
+        try:
+            predictor = self._get_predictor()
+            result = predictor(pr_title=pr_title, pr_body=pr_body, pr_comments=pr_comments)
+            return self._build_extraction(result)
+        except Exception:
+            logger.exception("Problem extraction failed, returning empty")
+            return ProblemExtraction(initial_observations=pr_body[:500] if pr_body else "")
+
+    def _clean_text(self, value: Any | None) -> str | None:
+        """Clean and normalize text values from predictions."""
+        if value is None:
+            return None
+        if isinstance(value, list):
+            try:
+                flat: list[str] = []
+                for v in value:
+                    if isinstance(v, list):
+                        flat.extend(str(x) for x in v)
+                    else:
+                        flat.append(str(v))
+                value = "\n".join(flat)
+            except Exception:
+                value = "\n".join(str(v) for v in value)
+        if not isinstance(value, str):
+            value = str(value)
+        stripped = value.strip()
+        if stripped.lower() in {"null", "none", "undefined", "n/a", ""}:
+            return None
+        return stripped or None
+
+    def _build_extraction(self, prediction: Any) -> ProblemExtraction:
+        """Normalize the raw DSPy prediction into a ProblemExtraction."""
+        initial_obs = self._clean_text(getattr(prediction, "initial_observations", None))
+        triage = self._clean_text(getattr(prediction, "triage_attempts", None))
+        solution = self._clean_text(getattr(prediction, "solution_overview", None))
+        solution_obs = self._clean_text(getattr(prediction, "solution_observations", None))
+
+        def plausible(s: str | None, *, min_len: int = 20) -> bool:
+            if s is None:
+                return False
+            stripped = s.strip()
+            if len(stripped) < min_len:
+                return False
+            return bool(re.search(r"[A-Za-z]", stripped))
+
+        if not plausible(initial_obs, min_len=20):
+            initial_obs = None
+        if not plausible(triage, min_len=10):
+            triage = None
+        if not plausible(solution, min_len=10):
+            solution = None
+        if not plausible(solution_obs, min_len=10):
+            solution_obs = None
+
+        return ProblemExtraction(
+            initial_observations=initial_obs or "",
+            triage_attempts=triage or "",
+            solution_overview=solution or "",
+            solution_observations=solution_obs or "",
+        )

datasmith/agents/installed/README.md

@@ -0,0 +1,52 @@
+# Installed Agent Abstraction
+
+An **installed agent** is a CLI coding agent installed on the host machine that
+can execute prompts non-interactively, auto-approve tool calls, and return
+structured output.
+
+## Supported agents
+
+| Agent | CLI binary | Install |
+|-------|-----------|---------|
+| Claude Code | `claude` | `npm install -g @anthropic-ai/claude-code` |
+| Codex | `codex` | `npm install -g @openai/codex` |
+| Gemini CLI | `gemini` | `npm install -g @anthropic-ai/gemini-cli` |
+
+## Interface contract
+
+Every `InstalledAgent` implementation must satisfy these requirements:
+
+1. **Non-interactive execution** — run a prompt, return when done
+2. **Auto-approve all tool calls** — no human-in-the-loop
+3. **JSON/structured output** — parseable stdout with agent messages and file changes
+4. **Working directory** — operate in a specified directory (via subprocess `cwd=`)
+5. **Ephemeral sessions** — don't persist state across runs
+6. **Shell + file editing** — can run bash and edit files in the workspace
+7. **External timeout** — can be killed via subprocess timeout
+
+## Auto-detection
+
+`get_agent()` tries agents in preference order (default: `claude → codex → gemini`)
+and returns the first one whose CLI binary is on `PATH`:
+
+```python
+from datasmith.agents.installed import get_agent
+
+agent = get_agent()                          # auto-detect
+agent = get_agent(preference=["codex"])      # force codex
+result = agent.exec("Fix the build", timeout=600, workdir="/tmp/workspace")
+```
+
+## Adding a new agent
+
+1. Create `src/datasmith/agents/installed/<name>.py`
+2. Subclass `InstalledAgent` and implement `name()`, `is_available()`, `exec()`
+3. Add a `_parse_<name>_stdout()` function to normalise CLI output
+4. Register the class in `base.py`'s `get_agent()` registry dict
+5. Re-export from `__init__.py`
+
+## Output parsing
+
+Each agent's CLI emits a different JSON schema. The `_parse_*_stdout()` function
+for each agent normalises the output into `(output_lines, files_changed)` which
+is then wrapped in an `AgentResult`.

datasmith/agents/installed/__init__.py

@@ -0,0 +1,22 @@
+"""Installed CLI agent abstraction.
+
+Provides a unified interface for CLI-based coding agents (Codex, Claude Code,
+Gemini CLI) with auto-detection of whichever is available on the host.
+"""
+
+from datasmith.agents.installed.base import AgentResult, CodexResult, InstalledAgent, get_agent
+from datasmith.agents.installed.claude import ClaudeAgent
+from datasmith.agents.installed.codex import CodexAgent
+from datasmith.agents.installed.gemini import GeminiAgent
+from datasmith.agents.installed.none import NoneAgent
+
+__all__ = [
+    "AgentResult",
+    "ClaudeAgent",
+    "CodexAgent",
+    "CodexResult",
+    "GeminiAgent",
+    "InstalledAgent",
+    "NoneAgent",
+    "get_agent",
+]