opencode-arch 1.0.0__py3-none-any.whl

opencode_arch/mcp/tools/slice.py

@@ -0,0 +1,235 @@
+"""architect_slice MCP tool — compress repository context for LLM consumption."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def compute_adaptive_budget(module_count: int, base: int = 4000) -> int:
+    """Scale token budget with repository size.
+    
+    Small repos (<=20 modules): base budget (4000 tokens)
+    Medium repos: +200 tokens per 10 modules over 20
+    Large repos: capped at 16000 tokens
+    
+    Examples:
+        20 modules → 4000 tokens
+        50 modules → 4600 tokens  
+        100 modules → 5600 tokens
+        161 modules → 6800 tokens
+        500 modules → 16000 tokens (capped)
+    """
+    if module_count <= 20:
+        return base
+    extra = ((module_count - 20) // 10) * 200
+    return min(base + extra, 16000)
+
+
+# Compression ratio thresholds (from telemetry analysis of 389 regen outcomes)
+# <2x: 78% pass | 2-10x: 69% | 10-50x: 55% | 50-200x: 44% | >200x: 19%
+COMPRESSION_WARN_THRESHOLD = 50  # warn above this
+COMPRESSION_CRITICAL_THRESHOLD = 200  # strongly recommend per-block above this
+
+
+def _estimate_source_size(path: Path) -> int:
+    """Estimate total source code size in chars (quick heuristic)."""
+    total = 0
+    for ext in ("*.py", "*.ts", "*.js", "*.go", "*.rs", "*.java"):
+        for f in path.rglob(ext):
+            # Skip vendor, node_modules, .git
+            parts = f.parts
+            if any(p in parts for p in ("vendor", "_vendor", "node_modules", ".git", "__pycache__")):
+                continue
+            try:
+                total += f.stat().st_size
+            except OSError:
+                pass
+    return total
+
+
+async def slice_context(
+    repo_path: str,
+    focus: str = "all",
+    budget: int = 0,
+    detail: str = "standard",
+) -> str:
+    """Generate an optimized context slice from a repository.
+
+    This is the core token-arbitrage function. It compresses a full repository
+    into a dense, structured context string within the token budget.
+
+    If an .architecture-model.yaml exists, uses the model + slicer + formatter.
+    Otherwise, falls back to manifest-based context.
+
+    Args:
+        repo_path: Absolute path to the repository root.
+        focus: Focus scope - "all", an F-block ID (e.g. "F1"), a layer name,
+               or an artifact name (e.g. "icd", "requirements-analysis").
+        budget: Maximum token budget (1 token ~ 4 chars).
+        detail: Detail level - "minimal", "standard", or "full".
+
+    Returns:
+        Formatted context string within budget, or error message.
+    """
+    path = Path(repo_path)
+    if not path.exists():
+        return f"Error: Repository path does not exist: {repo_path}"
+
+    try:
+        model_file = path / ".architecture-model.yaml"
+
+        # Adaptive budget: compute from repo size if not specified
+        if budget <= 0:
+            if model_file.exists():
+                from architecture_model.core.parser import load_model
+                model = load_model(model_file)
+                file_count = sum(len(getattr(c, 'files', [])) for c in model.entities.components)
+                budget = compute_adaptive_budget(file_count)
+            else:
+                from architecture_model.manifest.generator import generate_manifest
+                manifest = generate_manifest(path)
+                budget = compute_adaptive_budget(len(manifest.modules))
+
+            # Secondary check: ensure compression ratio stays below 50x
+            source_size = _estimate_source_size(path)
+            min_budget_for_50x = source_size // (50 * 4)  # 50x compression, 4 chars/token
+            if min_budget_for_50x > budget:
+                budget = min(min_budget_for_50x, 16000)  # cap at 16K tokens
+
+        if model_file.exists():
+            result = _slice_from_model(path, focus, budget, detail)
+        else:
+            result = _slice_from_manifest(path, focus, budget)
+
+        # Compression ratio guard: warn if context is dangerously compressed
+        source_size = _estimate_source_size(path)
+        char_budget = budget * 4
+        if source_size > 0 and char_budget > 0:
+            ratio = source_size / char_budget
+            if ratio > COMPRESSION_CRITICAL_THRESHOLD:
+                warning = (
+                    f"# COMPRESSION WARNING: {ratio:.0f}x compression detected!\n"
+                    f"# Source: {source_size // 1024}KB compressed into {char_budget // 1024}KB context.\n"
+                    f"# At >200x compression, regeneration pass rate drops to ~19%.\n"
+                    f"# RECOMMENDATION: Use focused slicing (architect_slice with focus='F1', 'F2', etc.)\n"
+                    f"# to slice per-block. Available F-blocks can be found via architect_scan.\n\n"
+                )
+                result = warning + result
+            elif ratio > COMPRESSION_WARN_THRESHOLD:
+                warning = (
+                    f"# NOTE: {ratio:.0f}x compression ratio (>50x reduces pass rate).\n"
+                    f"# Consider per-block slicing for better regeneration outcomes.\n\n"
+                )
+                result = warning + result
+
+        try:
+            from opencode_arch.telemetry.collector import drain_and_store
+            drain_and_store(tool="architect_slice", repo=path.name)
+        except Exception:
+            pass
+        return result
+
+    except Exception as e:
+        return f"Error during context slicing: {e}"
+
+
+def _slice_from_model(project_root: Path, focus: str, budget: int, detail: str) -> str:
+    """Slice context using the architecture model (rich path)."""
+    from architecture_model.core.parser import load_model
+    from opencode_arch.context import (
+        format_model_context,
+        format_fblock_context,
+        format_artifact_context,
+    )
+    from architecture_model.core.slicer import slice_by_layer
+
+    model_path = project_root / ".architecture-model.yaml"
+    model = load_model(model_path)
+
+    if focus == "all":
+        return format_model_context(model, max_tokens=budget, detail_level=detail)
+    elif focus.startswith("F") and focus[1:].isdigit():
+        # Complexity-proportional budget: complex blocks get more tokens
+        block_budget = _compute_block_budget(model, focus, budget)
+        return format_fblock_context(model, f_block=focus, max_tokens=block_budget, project_root=project_root)
+    elif focus in (
+        "functional-architecture", "logical-architecture", "use-cases",
+        "icd", "requirements-analysis", "operations-manual", "conops",
+        "testing", "deployment-guide", "data-dictionary", "readme",
+    ):
+        return format_artifact_context(model, artifact_name=focus, max_tokens=budget)
+    else:
+        try:
+            sliced = slice_by_layer(model, layer_id=focus)
+            return format_model_context(sliced, max_tokens=budget, detail_level=detail)
+        except (KeyError, ValueError):
+            return format_model_context(model, max_tokens=budget, detail_level=detail)
+
+
+def _compute_block_budget(model: Any, f_block: str, total_budget: int) -> int:
+    """Allocate budget proportionally to block complexity.
+
+    Complex blocks (many signatures/files) get more tokens.
+    Simple blocks get the minimum needed.
+    Telemetry: <10 signatures reliably converge; complex blocks need 2-3x more context.
+    """
+    components = [c for c in model.entities.components if getattr(c, 'f_block', '') == f_block]
+    if not components:
+        # No f_block match — give full budget
+        return total_budget
+
+    # Complexity = total signatures + total files
+    sig_count = sum(len(getattr(c, 'signatures', [])) for c in components)
+    file_count = sum(len(getattr(c, 'files', [])) for c in components)
+    complexity = sig_count + file_count
+
+    # Simple (< 10): base budget, Complex (10-30): 1.5x, Very complex (>30): 2x
+    if complexity < 10:
+        return min(total_budget, 4000)
+    elif complexity < 30:
+        return min(int(total_budget * 1.5), 8000)
+    else:
+        return min(total_budget * 2, 16000)
+
+
+def _slice_from_manifest(project_root: Path, focus: str, budget: int) -> str:
+    """Slice context using manifest only (no architecture model yet)."""
+    from architecture_model.manifest.generator import generate_manifest
+
+    manifest = generate_manifest(project_root)
+
+    # Try to include grouped component suggestions for richer context
+    groups_info = []
+    try:
+        from architecture_model.manifest.grouping import group_modules
+        groups = group_modules(manifest.modules, manifest.interfaces)
+        groups_info = [
+            {"name": g.name, "files": g.modules, "primary": g.primary_file}
+            for g in groups
+        ]
+    except Exception:
+        pass
+
+    manifest_yaml = yaml.dump(manifest, default_flow_style=False, sort_keys=False)
+
+    char_budget = budget * 4
+    if len(manifest_yaml) > char_budget:
+        summary: dict[str, Any] = {
+            "project_root": manifest.get("project_root"),
+            "metrics": manifest.get("metrics", {}),
+            "module_count": len(manifest.get("modules", [])),
+        }
+        if groups_info:
+            summary["suggested_components"] = groups_info
+        else:
+            summary["functional_blocks"] = {
+                k: {"file_count": len(v.get("sub_functions", []))}
+                for k, v in manifest.get("functional_blocks", {}).items()
+            }
+        if focus != "all":
+            summary["focus"] = focus
+        manifest_yaml = yaml.dump(summary, default_flow_style=False, sort_keys=False)
+
+    return manifest_yaml[:char_budget]

opencode_arch/mcp/tools/validate.py

@@ -0,0 +1,59 @@
+# src/opencode_arch/mcp/tools/validate.py
+"""architect_validate MCP tool — validate architecture model quality."""
+from __future__ import annotations
+
+from typing import Any
+
+import yaml
+
+
+async def validate_architecture(
+    model_yaml: str,
+) -> dict[str, Any]:
+    """Validate an architecture model for structural correctness.
+
+    Args:
+        model_yaml: The YAML architecture model string to validate.
+
+    Returns:
+        Dict with: score (0-100), issues (list), entity_count, relationship_count, is_valid.
+    """
+    try:
+        raw = yaml.safe_load(model_yaml)
+        if raw is None:
+            return {
+                "score": 0,
+                "issues": ["Empty YAML document"],
+                "entity_count": 0,
+                "relationship_count": 0,
+                "is_valid": False,
+            }
+
+        from architecture_model.core.parser import _parse_raw
+        from architecture_model.core.validator import validate_model
+
+        model = _parse_raw(raw)
+        validation_result = validate_model(model)
+
+        try:
+            from opencode_arch.telemetry.collector import drain_and_store
+            drain_and_store(tool="architect_validate", repo="")
+        except Exception:
+            pass
+
+        return {
+            "score": validation_result.score,
+            "issues": [str(issue) for issue in validation_result.issues],
+            "entity_count": model.entity_count,
+            "relationship_count": model.relationship_count,
+            "is_valid": validation_result.is_valid,
+        }
+
+    except Exception as e:
+        return {
+            "score": 0,
+            "issues": [f"Parse/validation error: {e}"],
+            "entity_count": 0,
+            "relationship_count": 0,
+            "is_valid": False,
+        }

opencode_arch/prompts/__init__.py

@@ -0,0 +1 @@
+"""Prompt templates for regen-loop and related workflows."""

opencode_arch/prompts/regen.py

@@ -0,0 +1,36 @@
+"""Prompt templates for the decomposed regen-loop."""
+
+REGEN_PROMPT = """\
+## Regenerate {subsystem_name} (iteration {iteration}/{max_iterations})
+
+You are regenerating a subsystem of a Python project. Your goal is to produce
+source files that pass the associated test suite.
+
+### Source files to produce:
+{source_files}
+
+### Architecture Model (structural)
+{model_context}
+
+### Constants (must be exact)
+{constants}
+
+### Function Signatures
+{signatures}
+
+### Test Contracts (assertions that MUST pass)
+{test_contracts}
+
+### Dependency Context
+{dependency_apis}
+
+{previous_feedback}\
+"""
+
+FEEDBACK_HEADER = """\
+### Feedback from previous iteration ({prev_iteration})
+
+The following tests failed. Fix these issues:
+
+{failure_analysis}
+"""

opencode_arch/runner/__init__.py

@@ -0,0 +1,5 @@
+"""Runner backends for agent invocation."""
+from opencode_arch.runner.base import RunResult, RunnerBackend
+from opencode_arch.runner.opencode import OpencodeRunner
+
+__all__ = ["RunResult", "RunnerBackend", "OpencodeRunner"]

opencode_arch/runner/base.py

@@ -0,0 +1,21 @@
+"""Runner protocol and result types."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+
+@dataclass
+class RunResult:
+    """Result of an agent run."""
+    output: str
+    exit_code: int
+    success: bool
+
+
+class RunnerBackend(Protocol):
+    """Protocol for agent invocation backends."""
+
+    async def run(self, prompt: str, repo_path: str) -> RunResult:
+        """Run the agent with a prompt in a repo context."""
+        ...

opencode_arch/runner/opencode.py

@@ -0,0 +1,66 @@
+"""OpenCode subprocess runner backend."""
+from __future__ import annotations
+
+import subprocess
+
+from opencode_arch.runner.base import RunResult
+
+
+class OpencodeRunner:
+    """Invokes `opencode run` as a subprocess."""
+
+    def __init__(self, timeout: int = 600, model: str | None = None):
+        self.timeout = timeout
+        self.model = model
+
+    async def run(self, prompt: str, repo_path: str) -> RunResult:
+        """Run OpenCode with a prompt in the given repo directory.
+
+        Uses stdin to pass the prompt (avoids ARG_MAX limits for long prompts).
+        Uses cwd to set the working directory (no --dir flag needed).
+        """
+        cmd = ["opencode", "run"]
+        if self.model:
+            cmd.extend(["--model", self.model])
+
+        try:
+            result = subprocess.run(
+                cmd,
+                input=prompt,
+                capture_output=True,
+                text=True,
+                timeout=self.timeout,
+                cwd=repo_path,
+            )
+            # Strip ANSI escape codes from output
+            output = _strip_ansi(result.stdout)
+            return RunResult(
+                output=output,
+                exit_code=result.returncode,
+                success=result.returncode == 0,
+            )
+        except subprocess.TimeoutExpired:
+            return RunResult(
+                output=f"Timeout: opencode run exceeded {self.timeout}s",
+                exit_code=-1,
+                success=False,
+            )
+        except FileNotFoundError:
+            return RunResult(
+                output="Error: opencode not found. Install with: npm i -g opencode",
+                exit_code=-1,
+                success=False,
+            )
+        except Exception as e:
+            return RunResult(
+                output=f"Error: {e}",
+                exit_code=-1,
+                success=False,
+            )
+
+
+def _strip_ansi(text: str) -> str:
+    """Remove ANSI escape sequences from text."""
+    import re
+    ansi_pattern = re.compile(r'\x1b\[[0-9;]*m|\x1b\[\?[0-9;]*[a-zA-Z]|\x1b\[[0-9;]*[a-zA-Z]')
+    return ansi_pattern.sub('', text)

opencode_arch/telemetry/__init__.py

@@ -0,0 +1,6 @@
+"""Telemetry: records tool usage and outcomes for optimization."""
+
+from opencode_arch.telemetry.store import TelemetryStore
+from opencode_arch.telemetry.recorder import record_invocation
+
+__all__ = ["TelemetryStore", "record_invocation"]

opencode_arch/telemetry/collector.py

@@ -0,0 +1,40 @@
+"""Drain metrics from architecture-model-standard and store in telemetry.
+
+Call drain_and_store() at the end of each MCP tool invocation to persist
+all function-level metrics that were collected during the operation.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+def drain_and_store(tool: str, repo: str = "", db_path: str | None = None) -> int:
+    """Drain the thread-local metrics collector and write to telemetry DB.
+
+    Returns the number of metrics stored. Never raises — swallows all exceptions.
+    """
+    try:
+        from architecture_model.monitoring import get_collector
+        from opencode_arch.telemetry.store import TelemetryStore
+
+        collector = get_collector()
+        metrics = collector.drain()
+        if not metrics:
+            return 0
+
+        store = TelemetryStore(Path(db_path)) if db_path else TelemetryStore()
+        for m in metrics:
+            store.record_function_metric(
+                tool=tool,
+                function=m.function,
+                module=m.module,
+                repo=repo,
+                time_ms=m.time_ms,
+                quality_scores=json.dumps(m.quality_scores),
+                input_metrics=json.dumps(m.input_metrics),
+                output_metrics=json.dumps(m.output_metrics),
+            )
+        return len(metrics)
+    except Exception:
+        return 0

opencode_arch/telemetry/recorder.py

@@ -0,0 +1,12 @@
+"""Async recorder for tool invocations."""
+from __future__ import annotations
+
+from opencode_arch.telemetry.store import TelemetryStore
+
+
+async def record_invocation(store: TelemetryStore, tool: str, repo: str = "",
+                            context_tokens: int = 0, output_quality: int = 0,
+                            iterations: int = 1, metadata: str = ""):
+    """Record a tool invocation asynchronously."""
+    store.record(tool=tool, repo=repo, context_tokens=context_tokens,
+                 output_quality=output_quality, iterations=iterations, metadata=metadata)