core-runtime 0.1.1__py3-none-any.whl

cli/resources/context/build.py

@@ -0,0 +1,374 @@
+# src/cli/resources/context/build.py
+
+"""
+Context build command - Agent simulation mode.
+
+Builds doctrine-aligned context packets and renders them for human / LAG use.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+from body.infrastructure.bootstrap import create_core_context
+from body.services.service_registry import service_registry
+from cli.utils import core_command
+from shared.cli.command_meta import CommandBehavior, CommandLayer, command_meta
+from shared.infrastructure.context.models import ContextBuildRequest
+from shared.infrastructure.intent.task_type_phases import (
+    allowed_task_types,
+    resolve_phase,
+)
+from shared.infrastructure.storage.file_handler import FileHandler
+
+from .hub import app
+
+
+logger = logging.getLogger(__name__)
+console = Console()
+
+# ADR-004: Typer --task autocompletion and help binding. The choice list
+# is derived from the governed vocabulary in
+# .intent/enforcement/config/task_type_phases.yaml and materialised once
+# at module load. No hardcoded copy of the vocabulary is permitted.
+_TASK_CHOICES: list[str] = sorted(allowed_task_types())
+
+
+def _format_item_source(item: dict[str, Any]) -> str:
+    source = item.get("source", "unknown")
+    score = item.get("score")
+    score_str = f": {score:.2f}" if isinstance(score, int | float) else ""
+
+    source_map = {
+        "vector_search": f"🔍 vector search{score_str}",
+        "database": "🗄️ database",
+        "workspace": "✍️ workspace",
+        "filesystem": "📄 filesystem",
+        "unknown": "❓ unknown source",
+    }
+    return source_map.get(source, f"📎 {source}")
+
+
+def _assemble_enriched_prompt(
+    evidence: list[dict[str, Any]],
+    file: str,
+    symbol: str | None,
+    task_type: str,
+) -> str:
+    deps: list[str] = []
+    examples: list[str] = []
+    existing_code = ""
+    seen: set[str] = set()
+
+    for item in evidence:
+        name = item.get("name", "")
+        path = item.get("path", "")
+        content = item.get("content", "") or ""
+        sig = item.get("signature", "") or ""
+
+        if path == file and content:
+            if symbol and name == symbol:
+                existing_code = content
+            elif not existing_code:
+                existing_code = content
+
+        if (
+            name
+            and name not in seen
+            and item.get("item_type") in {"code", "symbol", "semantic_match"}
+        ):
+            seen.add(name)
+            dep_line = f"- `{name}` from `{path}`"
+            if sig:
+                dep_line += f"\n  Signature: `{sig}`"
+            deps.append(dep_line)
+
+        if content and len(content) > 50 and item.get("item_type") == "code":
+            block = [f"### {name}"]
+            if item.get("summary"):
+                block.append(str(item["summary"]))
+            block.append("```python")
+            block.append(content[:500])
+            if len(content) > 500:
+                block.append("# ... (truncated for display)")
+            block.append("```")
+            examples.append("\n".join(block))
+
+    parts = [
+        "# Code Task",
+        "",
+        (
+            f"**Goal:** Implement or modify `{symbol}` in `{file}`"
+            if symbol
+            else f"**Goal:** Work in `{file}`"
+        ),
+        f"**Task type:** {task_type}",
+        "",
+    ]
+
+    if deps:
+        parts += ["## Available Dependencies", "\n".join(deps), ""]
+
+    if examples:
+        parts += ["## Relevant Code", "\n".join(examples), ""]
+
+    if existing_code:
+        parts += ["## Existing Code Context", "```python", existing_code, "```", ""]
+
+    parts += [
+        "## Requirements",
+        "1. Return only valid Python code",
+        "2. Include needed imports",
+        "3. Include type hints and docstrings",
+        "4. Respect CORE constitutional patterns",
+        "",
+        "## Target",
+        f"Symbol: `{symbol}`" if symbol else "Symbol: `(file-level)`",
+        f"Target file: `{file}`",
+    ]
+    return "\n".join(parts)
+
+
+def _render_layer_constraints(section: Any) -> list[str]:
+    if not isinstance(section, dict):
+        return []
+
+    layer = section.get("layer")
+    rules = section.get("rules") or []
+    if not layer or not rules:
+        return []
+
+    lines: list[str] = [
+        f"## CONSTITUTIONAL CONSTRAINTS — {str(layer).upper()} layer",
+        "",
+        f"⛔ The following blocking rules apply to ALL files in the {layer} layer.",
+        "These constraints are derived from file path alone and are authoritative",
+        "regardless of role inference confidence.",
+        "",
+    ]
+
+    for rule in rules:
+        rid = rule.get("id") or "?"
+        statement = rule.get("statement") or ""
+        lines.append(f"{rid}: {statement}")
+
+    warning = section.get("warning") or ""
+    if warning:
+        lines.append("")
+        lines.append(f"⚠️  {warning}")
+
+    lines.append("")
+    return lines
+
+
+def _format_packet_for_display(
+    packet: dict[str, Any],
+    file: str,
+    symbol: str | None,
+    task_type: str,
+    show_prompt: bool,
+) -> str:
+    lines: list[str] = []
+
+    header = packet.get("header", {})
+    provenance = packet.get("provenance", {})
+    stats = provenance.get("build_stats", {})
+    evidence = packet.get("evidence", [])
+
+    lines.append("=" * 80)
+    lines.append("CORE CONTEXT PACKET  [Agent Simulation Mode]")
+    lines.append("=" * 80)
+    lines.append(f"Target file  : {file}")
+    lines.append(f"Target symbol: {symbol or '(file-level)'}")
+    lines.append(f"Task type    : {task_type}")
+    lines.append(f"Phase        : {packet.get('phase', 'unknown')}")
+    lines.append(f"Packet ID    : {header.get('packet_id', 'unknown')}")
+    lines.append(f"Evidence     : {len(evidence)}")
+    lines.append(f"Tokens (est) : ~{stats.get('tokens_total', 0)}")
+    lines.append(f"Build time   : {stats.get('duration_ms', 0)}ms")
+    lines.append("")
+
+    for section_name in (
+        "layer_constraints",
+        "constitution",
+        "policy",
+        "constraints",
+        "runtime",
+    ):
+        section = packet.get(section_name)
+        if section_name == "layer_constraints":
+            rendered = _render_layer_constraints(section)
+            if rendered:
+                lines.extend(rendered)
+            continue
+        if section:
+            lines.append(f"## {section_name.upper()}")
+            lines.append("```json")
+            lines.append(json.dumps(section, indent=2, sort_keys=True, default=str))
+            lines.append("```")
+            lines.append("")
+
+    if not evidence:
+        lines.append("[!] No evidence collected.")
+        lines.append("")
+    else:
+        lines.append("## EVIDENCE")
+        lines.append("")
+        for idx, item in enumerate(evidence, 1):
+            name = item.get("name", "unknown")
+            path = item.get("path", "unknown")
+            item_type = item.get("item_type", "unknown")
+            summary = item.get("summary", "")
+            content = item.get("content", "")
+            source_label = _format_item_source(item)
+
+            lines.append(f"### {idx}. {path}::{name}")
+            lines.append(f"Type   : {item_type}")
+            lines.append(f"Source : {source_label}")
+            if summary:
+                lines.append(f"Summary: {str(summary)[:160]}")
+            lines.append("")
+            if content:
+                lines.append("```python")
+                lines.append(content)
+                lines.append("```")
+            else:
+                lines.append("(No code content available)")
+            lines.append("")
+
+    if show_prompt:
+        lines.append("=" * 80)
+        lines.append("ASSEMBLED PROMPT")
+        lines.append("=" * 80)
+        lines.append("")
+        lines.append(_assemble_enriched_prompt(evidence, file, symbol, task_type))
+        lines.append("")
+
+    lines.append("=" * 80)
+    lines.append("STATS")
+    source_counts: dict[str, int] = {}
+    for item in evidence:
+        src = item.get("source", "unknown")
+        source_counts[src] = source_counts.get(src, 0) + 1
+    for src, count in sorted(source_counts.items()):
+        lines.append(f"  {src}: {count}")
+
+    return "\n".join(lines)
+
+
+@app.command("build")
+@command_meta(
+    canonical_name="context.build",
+    behavior=CommandBehavior.READ,
+    layer=CommandLayer.BODY,
+    summary="Simulate exact context CoderAgent sees.",
+)
+@core_command(dangerous=False, requires_context=False)
+# ID: 945e6c12-26e2-423d-ad3e-0cb10faaccb1
+async def build_cmd(
+    ctx: typer.Context,
+    file: str = typer.Option(..., "--file", "-f", help="Target file path"),
+    symbol: str | None = typer.Option(
+        None, "--symbol", "-s", help="Target symbol name"
+    ),
+    task: str = typer.Option(
+        "code_modification",
+        "--task",
+        "-t",
+        help=f"Task type: {', '.join(_TASK_CHOICES)}",
+    ),
+    goal: str = typer.Option("", "--goal", "-g", help="Optional goal override"),
+    show_prompt: bool = typer.Option(
+        False, "--show-prompt", help="Also show assembled LLM prompt"
+    ),
+    output: str | None = typer.Option(
+        None, "--output", "-o", help="Write output to file instead of stdout"
+    ),
+    no_cache: bool = typer.Option(False, "--no-cache", help="Bypass context cache"),
+    max_tokens: int = typer.Option(
+        30000, "--max-tokens", help="Token budget (display only)"
+    ),
+    max_items: int = typer.Option(20, "--max-items", help="Max evidence items hint"),
+) -> None:
+    if task not in allowed_task_types():
+        logger.info("Unknown task type: %s", task)
+        raise typer.Exit(code=1)
+
+    from shared.infrastructure.database.session_manager import get_session
+
+    service_registry.prime(get_session)
+    core_context = create_core_context(service_registry)
+
+    async with service_registry.session() as session:
+        cognitive = await service_registry.get_cognitive_service()
+        await cognitive.initialize(session)
+
+    console.print(
+        Panel(
+            f"[bold]File:[/bold]   {file}\n[bold]Symbol:[/bold] {symbol or '(file-level)'}\n[bold]Task:[/bold]   {task}",
+            title="[bold blue]🔬 Building Agent Context[/bold blue]",
+            expand=False,
+        )
+    )
+
+    request = ContextBuildRequest(
+        goal=goal
+        or (f"{task} for {symbol} in {file}" if symbol else f"{task} for {file}"),
+        trigger="cli",
+        phase=resolve_phase(task),
+        target_files=[file],
+        target_symbols=[symbol] if symbol else [],
+        include_constitution=True,
+        include_policy=True,
+        include_symbols=True,
+        include_vectors=True,
+        include_runtime=True,
+    )
+
+    packet_obj = await core_context.context_service.build(
+        request,
+        use_cache=not no_cache,
+    )
+
+    packet = {
+        "header": packet_obj.header,
+        "phase": packet_obj.request.phase,
+        "layer_constraints": packet_obj.layer_constraints,
+        "constitution": packet_obj.constitution,
+        "policy": packet_obj.policy,
+        "constraints": packet_obj.constraints,
+        "evidence": packet_obj.evidence[:max_items],
+        "runtime": packet_obj.runtime,
+        "provenance": packet_obj.provenance,
+    }
+
+    formatted = _format_packet_for_display(packet, file, symbol, task, show_prompt)
+
+    if output:
+        output_path = Path(output)
+        repo_root = Path(core_context.git_service.repo_path).resolve()
+        resolved = (
+            (repo_root / output_path).resolve()
+            if not output_path.is_absolute()
+            else output_path.resolve()
+        )
+
+        if not resolved.is_relative_to(repo_root):
+            raise ValueError(f"Output path is outside repository boundary: {output}")
+
+        rel_output = resolved.relative_to(repo_root).as_posix()
+        FileHandler(str(core_context.git_service.repo_path)).write_runtime_text(
+            rel_output,
+            formatted,
+        )
+        logger.info("✅ Context written to %s", output)
+    else:
+        logger.info("")
+        logger.info(formatted)

cli/resources/context/cache.py

@@ -0,0 +1,156 @@
+# src/cli/resources/context/cache.py
+"""
+Context cache command - Manage context cache.
+
+Usage:
+    core-admin context cache list
+    core-admin context cache clear
+    core-admin context cache stats
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from shared.infrastructure.intent.operational_config import load_operational_config
+
+
+logger = logging.getLogger(__name__)
+console = Console()
+_CACHE_DIR = "work/context_cache"
+_CFG = load_operational_config().context
+
+
+# ID: f58e6b83-332e-4b8a-bcf0-e51069ecfe1e
+def cache(action: str = typer.Argument(..., help="Action: list, clear, stats")) -> None:
+    """
+    Manage context cache.
+
+    Actions:
+        list   - Show cached context queries
+        clear  - Clear all cached contexts
+        stats  - Show cache statistics (size, hit rate, etc.)
+
+    Examples:
+        core-admin context cache list
+        core-admin context cache clear
+        core-admin context cache stats
+
+    The context cache stores built context packages to speed up
+    repeated queries. Caching is automatically disabled when
+    working with Shadow Truth (LimbWorkspace).
+    """
+    try:
+        if action == "list":
+            _list_cache()
+        elif action == "clear":
+            _clear_cache()
+        elif action == "stats":
+            _show_stats()
+        else:
+            console.print(f"[red]❌ Unknown action: {action}[/red]")
+            console.print("[dim]Valid actions: list, clear, stats[/dim]")
+            raise typer.Exit(code=1)
+    except Exception as e:
+        console.print(f"[red]❌ Error: {e}[/red]")
+        logger.exception("Cache operation failed")
+        raise typer.Exit(code=1)
+
+
+def _get_cache_dir() -> Path:
+    """Resolve the cache directory relative to cwd (repo root)."""
+    return Path(_CACHE_DIR)
+
+
+def _list_cache() -> None:
+    """List all cached context queries."""
+    cache_dir = _get_cache_dir()
+    if not cache_dir.exists():
+        console.print("[dim]Cache directory does not exist. No entries.[/dim]")
+        return
+    files = sorted(
+        cache_dir.glob("*.yaml"), key=lambda f: f.stat().st_mtime, reverse=True
+    )
+    if not files:
+        console.print("[dim]Cache is empty.[/dim]")
+        return
+    table = Table(
+        title=f"Context Cache ({len(files)} entries)", header_style="bold cyan"
+    )
+    table.add_column("Key (short)", style="cyan", no_wrap=True)
+    table.add_column("Modified", style="green")
+    table.add_column("Size", style="yellow", justify="right")
+    table.add_column("Age (h)", style="magenta", justify="right")
+    now = datetime.now(UTC)
+    for f in files:
+        stat = f.stat()
+        mtime = datetime.fromtimestamp(stat.st_mtime, tz=UTC)
+        age_h = (now - mtime).total_seconds() / 3600
+        size_kb = stat.st_size / 1024
+        table.add_row(
+            f.stem[:16],
+            mtime.strftime("%Y-%m-%d %H:%M"),
+            f"{size_kb:.1f} KB",
+            f"{age_h:.1f}",
+        )
+    console.print(table)
+
+
+def _clear_cache() -> None:
+    """Clear all cached contexts."""
+    cache_dir = _get_cache_dir()
+    if not cache_dir.exists() or not list(cache_dir.glob("*.yaml")):
+        console.print("[dim]Cache is already empty.[/dim]")
+        return
+    count = len(list(cache_dir.glob("*.yaml")))
+    console.print(
+        f"[yellow]⚠️  This will delete {count} cached context package(s).[/yellow]"
+    )
+    if not typer.confirm("Continue?"):
+        console.print("[dim]Aborted.[/dim]")
+        return
+    from shared.infrastructure.context.cache import ContextCache
+
+    removed = ContextCache(str(cache_dir)).clear_all()
+    console.print(f"[green]✅ Cleared {removed} cache entries.[/green]")
+
+
+def _show_stats() -> None:
+    """Show cache statistics."""
+    cache_dir = _get_cache_dir()
+    if not cache_dir.exists():
+        console.print("[dim]Cache directory does not exist.[/dim]")
+        return
+    files = list(cache_dir.glob("*.yaml"))
+    ttl_hours = _CFG.cache_ttl_hours
+    now = datetime.now(UTC)
+    total_size = 0
+    expired = 0
+    oldest_dt = None
+    for f in files:
+        stat = f.stat()
+        total_size += stat.st_size
+        mtime = datetime.fromtimestamp(stat.st_mtime, tz=UTC)
+        age_h = (now - mtime).total_seconds() / 3600
+        if age_h > ttl_hours:
+            expired += 1
+        if oldest_dt is None or mtime < oldest_dt:
+            oldest_dt = mtime
+    table = Table(title="Context Cache Statistics", header_style="bold cyan")
+    table.add_column("Metric", style="cyan")
+    table.add_column("Value", style="green")
+    table.add_row("Total entries", str(len(files)))
+    table.add_row("Total size", f"{total_size / 1024:.1f} KB")
+    table.add_row("Expired entries", f"{expired} (TTL={ttl_hours}h)")
+    table.add_row("Active entries", str(len(files) - expired))
+    table.add_row(
+        "Oldest entry", oldest_dt.strftime("%Y-%m-%d %H:%M") if oldest_dt else "—"
+    )
+    table.add_row("Cache dir", str(cache_dir))
+    console.print(table)

cli/resources/context/explain.py

@@ -0,0 +1,140 @@
+# src/cli/resources/context/explain.py
+"""
+Context explain command - Natural language exploration.
+
+Answers "what code relates to this concept?" via semantic search.
+Uses build_from_query() — vector search over the knowledge graph.
+
+This is an EXPLORATION tool, not an agent simulation.
+For agent simulation (what CoderAgent sees), use: core-admin context build
+
+USAGE:
+    core-admin context explain "how does policy enforcement work"
+    core-admin context explain "constitutional violation detection" --max-items 10
+    core-admin context explain "how are assumptions extracted" --output var/exploration.md
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import typer
+from rich.console import Console
+
+from body.infrastructure.bootstrap import create_core_context
+from body.services.service_registry import service_registry
+from cli.utils import core_command
+from shared.cli.command_meta import CommandBehavior, CommandLayer, command_meta
+from shared.infrastructure.storage.file_handler import FileHandler
+
+from .hub import app
+
+
+console = Console()
+
+
+def _format_exploration_for_display(packet: dict[str, Any]) -> str:
+    """Format exploration packet for human readability."""
+    lines: list[str] = []
+    header = packet.get("header", {})
+    stats = packet.get("provenance", {}).get("build_stats", {})
+    items = packet.get("context", [])
+    lines.append("=" * 80)
+    lines.append("CONTEXT EXPLORATION")
+    lines.append("=" * 80)
+    lines.append(f"Query  : {packet.get('problem', {}).get('summary', 'No summary')}")
+    lines.append(f"Items  : {len(items)}")
+    lines.append(f"Tokens : ~{stats.get('tokens_total', 0)}")
+    lines.append(f"Mode   : {header.get('mode', 'HISTORICAL')}")
+    lines.append("")
+    if not items:
+        lines.append("[!] No results found. Try different search terms.")
+        lines.append(
+            "    Ensure vectors are up to date: core-admin vectors vectorize --write"
+        )
+        return "\n".join(lines)
+    lines.append("## RELEVANT CODE")
+    lines.append("")
+    for idx, item in enumerate(items, 1):
+        name = item.get("name", "unknown")
+        path = item.get("path", "unknown")
+        item_type = item.get("item_type", "unknown")
+        content = item.get("content", "")
+        summary = item.get("summary", "")
+        lines.append(f"### {idx}. {path}::{name}")
+        lines.append(f"Type: {item_type}")
+        if summary:
+            lines.append(f"Summary: {summary[:120]}")
+        lines.append("")
+        if content:
+            lines.append("```python")
+            lines.append(content)
+            lines.append("```")
+        else:
+            lines.append("(No code content available)")
+        lines.append("")
+    lines.append("=" * 80)
+    lines.append(f"Build time: {stats.get('duration_ms', 0)}ms")
+    return "\n".join(lines)
+
+
+@app.command("explain")
+@command_meta(
+    canonical_name="context.explain",
+    behavior=CommandBehavior.READ,
+    layer=CommandLayer.BODY,
+    summary="Explore codebase by concept using semantic search.",
+)
+@core_command(dangerous=False, requires_context=False)
+# ID: f36a0b23-f6e7-4813-a75c-4482f78b41f4
+async def explain_cmd(
+    ctx: typer.Context,
+    query: str = typer.Argument(..., help="Natural language query"),
+    output: str = typer.Option(None, "--output", "-o", help="Write to file"),
+    max_tokens: int = typer.Option(30000, "--max-tokens", help="Token budget"),
+    max_items: int = typer.Option(30, "--max-items", help="Max items"),
+    no_cache: bool = typer.Option(False, "--no-cache", help="Disable cache"),
+) -> None:
+    """
+    Explore codebase by concept using semantic search.
+
+    Answers "what code relates to this concept?" — useful for understanding
+    unfamiliar parts of the codebase before making changes.
+
+    For simulating what the agent sees during code generation,
+    use: core-admin context build --file ... --symbol ...
+    """
+    from shared.infrastructure.database.session_manager import get_session
+
+    service_registry.prime(get_session)
+    core_context = create_core_context(service_registry)
+    async with service_registry.session() as session:
+        cognitive = await service_registry.get_cognitive_service()
+        await cognitive.initialize(session)
+    console.print(f"[bold blue]🔍 Exploring:[/bold blue] {query}")
+    packet = await core_context.context_service.build_from_query(
+        natural_query=query,
+        max_tokens=max_tokens,
+        max_items=max_items,
+        use_cache=not no_cache,
+    )
+    formatted = _format_exploration_for_display(packet)
+    if output:
+        output_path = Path(output)
+        repo_root = Path(core_context.git_service.repo_path).resolve()
+        resolved = (
+            (repo_root / output_path).resolve()
+            if not output_path.is_absolute()
+            else output_path.resolve()
+        )
+        if not resolved.is_relative_to(repo_root):
+            raise ValueError(f"Output path is outside repository boundary: {output}")
+        rel_output = resolved.relative_to(repo_root).as_posix()
+        FileHandler(str(core_context.git_service.repo_path)).write_runtime_text(
+            rel_output, formatted
+        )
+        console.print(f"[green]✅ Exploration written to {output}[/green]")
+    else:
+        console.print("")
+        console.print(formatted)

cli/resources/context/hub.py

@@ -0,0 +1,11 @@
+# src/cli/resources/context/hub.py
+import typer
+
+
+# Stable hub for context resource commands.
+# All context commands import from here to avoid circular imports.
+app = typer.Typer(
+    name="context",
+    help="Build and explore context packages for LLM assistance.",
+    no_args_is_help=True,
+)