core-runtime 0.1.1__py3-none-any.whl

body/infrastructure/repositories/decision_trace_repository.py

@@ -0,0 +1,210 @@
+# src/body/infrastructure/repositories/decision_trace_repository.py
+
+"""
+DecisionTrace Repository - Governed database access for decision traces.
+
+CONSTITUTIONAL (proper, non-legacy):
+- Callers do NOT pass sessions around.
+- Repository owns DB session lifecycle via Body service_registry.session().
+- Repository commits its own writes (because it owns the session).
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from datetime import datetime
+from typing import Any
+
+from sqlalchemy import desc, select
+
+from body.services.service_registry import service_registry
+from shared.infrastructure.database.models.decision_traces import DecisionTrace
+from shared.infrastructure.intent.operational_config import load_operational_config
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+_CFG_REPO = load_operational_config().repositories
+
+
+# ID: 8d9e0f1a-2b3c-4d5e-6f7a-8b9c0d1e2f3a
+class DecisionTraceRepository:
+    """
+    Repository for decision trace database operations.
+
+    Proper pattern:
+        async with DecisionTraceRepository.open() as repo:
+            await repo.create(...)
+            traces = await repo.get_recent(...)
+    """
+
+    def __init__(self, _session: Any):
+        self._session = _session
+
+    @classmethod
+    @asynccontextmanager
+    # ID: 64cc1aa7-0aa2-4de0-881a-60aa58dd1d22
+    async def open(cls) -> AsyncIterator[DecisionTraceRepository]:
+        async with service_registry.session() as session:
+            yield cls(session)
+
+    # ID: f1746e04-8e4f-4ea9-9678-948ff69793d1
+    async def create(
+        self,
+        session_id: str,
+        agent_name: str,
+        decisions: list[dict[str, Any]],
+        goal: str | None = None,
+        pattern_stats: dict[str, int] | None = None,
+        has_violations: bool | None = None,
+        violation_count: int | None = None,
+        duration_ms: int | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> DecisionTrace:
+        """
+        Create a new decision trace record.
+
+        Commits internally because this repository owns the session lifecycle.
+        """
+        trace = DecisionTrace(
+            session_id=session_id,
+            agent_name=agent_name,
+            goal=goal,
+            decisions=decisions,
+            decision_count=len(decisions),
+            pattern_stats=pattern_stats,
+            has_violations=(
+                str(has_violations).lower() if has_violations is not None else None
+            ),
+            violation_count=violation_count,
+            duration_ms=duration_ms,
+            extra_metadata=metadata or {},
+        )
+
+        self._session.add(trace)
+        await self._session.flush()  # get ID without committing
+        await self._session.commit()
+
+        logger.debug(
+            "Created decision trace: session=%s agent=%s decisions=%d",
+            session_id,
+            agent_name,
+            len(decisions),
+        )
+        return trace
+
+    # ID: 0f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
+    async def get_by_session_id(self, session_id: str) -> DecisionTrace | None:
+        """
+        Retrieve decision trace by session ID.
+
+        If multiple snapshots exist, returns the most recent one
+        (highest decision count) to prevent MultipleResultsFound.
+        """
+        stmt = (
+            select(DecisionTrace)
+            .where(DecisionTrace.session_id == session_id)
+            .order_by(desc(DecisionTrace.decision_count))
+            .limit(1)
+        )
+        result = await self._session.execute(stmt)
+        return result.scalar_one_or_none()
+
+    # ID: 65b96a8a-de11-428c-9781-3f2455ee0636
+    async def get_recent(
+        self,
+        limit: int = _CFG_REPO.decision_trace_default_limit,
+        agent_name: str | None = None,
+        failures_only: bool = False,
+    ) -> list[DecisionTrace]:
+        stmt = select(DecisionTrace).order_by(desc(DecisionTrace.created_at))
+
+        if agent_name:
+            stmt = stmt.where(DecisionTrace.agent_name == agent_name)
+
+        if failures_only:
+            stmt = stmt.where(DecisionTrace.has_violations == "true")
+
+        stmt = stmt.limit(limit)
+
+        result = await self._session.execute(stmt)
+        return list(result.scalars().all())
+
+    # ID: 3d680f10-ce36-4533-80bc-a589002c8e12
+    async def get_by_date_range(
+        self,
+        start_date: datetime,
+        end_date: datetime,
+        agent_name: str | None = None,
+    ) -> list[DecisionTrace]:
+        stmt = (
+            select(DecisionTrace)
+            .where(
+                DecisionTrace.created_at >= start_date,
+                DecisionTrace.created_at <= end_date,
+            )
+            .order_by(desc(DecisionTrace.created_at))
+        )
+
+        if agent_name:
+            stmt = stmt.where(DecisionTrace.agent_name == agent_name)
+
+        result = await self._session.execute(stmt)
+        return list(result.scalars().all())
+
+    # ID: 06a534cf-e651-4166-9de4-e5ca2063e76f
+    async def get_pattern_stats(
+        self,
+        pattern_name: str,
+        limit: int = _CFG_REPO.decision_trace_max_limit,
+    ) -> list[DecisionTrace]:
+        stmt = (
+            select(DecisionTrace)
+            .where(DecisionTrace.pattern_stats.has_key(pattern_name))
+            .order_by(desc(DecisionTrace.created_at))
+            .limit(limit)
+        )
+        result = await self._session.execute(stmt)
+        return list(result.scalars().all())
+
+    # ID: 1f913131-8382-4711-adf5-ec7d1fb39125
+    async def count_by_agent(self, days: int = 7) -> dict[str, int]:
+        from datetime import timedelta
+
+        from sqlalchemy import func
+
+        cutoff = datetime.now() - timedelta(days=days)
+
+        stmt = (
+            select(
+                DecisionTrace.agent_name, func.count(DecisionTrace.id).label("count")
+            )
+            .where(DecisionTrace.created_at >= cutoff)
+            .group_by(DecisionTrace.agent_name)
+        )
+
+        result = await self._session.execute(stmt)
+        return {row.agent_name: row.count for row in result}
+
+    # ID: 6e5f9fd8-5b7f-4632-8956-e5303c253088
+    async def delete_old_traces(
+        self, days: int = _CFG_REPO.decision_trace_retention_days
+    ) -> int:
+        from datetime import timedelta
+
+        from sqlalchemy import delete
+
+        cutoff = datetime.now() - timedelta(days=days)
+
+        stmt = delete(DecisionTrace).where(DecisionTrace.created_at < cutoff)
+        result = await self._session.execute(stmt)
+        deleted_count = result.rowcount or 0
+
+        await self._session.commit()
+
+        logger.info(
+            "Deleted %d decision traces older than %d days", deleted_count, days
+        )
+        return deleted_count

body/infrastructure/repositories/refusal_repository.py

@@ -0,0 +1,294 @@
+# src/body/infrastructure/repositories/refusal_repository.py
+
+"""
+Refusal Repository - Governed database access for refusal records.
+
+Constitutional Compliance:
+- Repository owns DB session lifecycle via Body service_registry.session()
+- Repository commits its own writes (because it owns the session)
+- Never blocks operations - graceful degradation on storage failures
+
+This repository enables constitutional refusal tracking and the
+`core-admin inspect refusals` command.
+"""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from datetime import datetime
+from typing import Any
+
+from sqlalchemy import desc, select
+
+from body.services.service_registry import service_registry
+from shared.infrastructure.database.models.refusals import RefusalRecord
+from shared.infrastructure.intent.operational_config import load_operational_config
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+_CFG_REPO = load_operational_config().repositories
+
+
+# ID: 1930d0d3-30a5-4902-b6c2-a5125c287ea5
+class RefusalRepository:
+    """
+    Repository for refusal record database operations.
+
+    Constitutional Pattern:
+    - Owns session lifecycle (via service_registry)
+    - Commits its own writes
+    - Gracefully degrades on failures (logs but doesn't raise)
+    """
+
+    @asynccontextmanager
+    async def _session(self):
+        """Get async DB session from service registry."""
+        async with service_registry.session() as session:
+            yield session
+
+    # ID: 1f9de411-5616-4f18-84be-1c6bd99fd632
+    async def record_refusal(
+        self,
+        component_id: str,
+        phase: str,
+        refusal_type: str,
+        reason: str,
+        suggested_action: str,
+        original_request: str = "",
+        confidence: float = 0.0,
+        context_data: dict[str, Any] | None = None,
+        session_id: str | None = None,
+        user_id: str | None = None,
+    ) -> RefusalRecord | None:
+        """
+        Record a constitutional refusal.
+
+        CONSTITUTIONAL: Never raises - gracefully degrades on storage failure.
+
+        Args:
+            component_id: Component that refused
+            phase: Component phase (EXECUTION, PARSE, etc.)
+            refusal_type: Category (boundary, confidence, extraction, etc.)
+            reason: Constitutional reason with policy citation
+            suggested_action: What user should do
+            original_request: The refused request (for audit)
+            confidence: Confidence score at refusal time
+            context_data: Additional context
+            session_id: Decision trace session ID (optional)
+            user_id: User who received refusal (optional)
+
+        Returns:
+            RefusalRecord if stored successfully, None on failure
+        """
+        try:
+            async with self._session() as session:
+                record = RefusalRecord(
+                    component_id=component_id,
+                    phase=phase,
+                    refusal_type=refusal_type,
+                    reason=reason,
+                    suggested_action=suggested_action,
+                    original_request=original_request,
+                    confidence=confidence,
+                    context_data=context_data or {},
+                    session_id=session_id,
+                    user_id=user_id,
+                )
+
+                session.add(record)
+                await session.commit()
+                await session.refresh(record)
+
+                logger.debug(
+                    "Refusal recorded: %s by %s (type: %s)",
+                    record.id,
+                    component_id,
+                    refusal_type,
+                )
+                return record
+
+        except Exception as e:
+            logger.warning(
+                "Failed to record refusal (non-blocking): %s",
+                e,
+                exc_info=True,
+            )
+            return None
+
+    # ID: 22c5bf48-3b45-4817-9dbb-96bcdb3f345d
+    async def get_recent(
+        self,
+        limit: int = _CFG_REPO.refusal_default_limit,
+        refusal_type: str | None = None,
+        component_id: str | None = None,
+    ) -> list[RefusalRecord]:
+        """
+        Get recent refusals with optional filtering.
+
+        Args:
+            limit: Maximum number of records (1-100)
+            refusal_type: Filter by type (boundary, confidence, etc.)
+            component_id: Filter by component
+
+        Returns:
+            List of RefusalRecord objects, newest first
+        """
+        limit = max(1, min(limit, 100))  # Clamp to 1-100
+
+        try:
+            async with self._session() as session:
+                query = select(RefusalRecord).order_by(desc(RefusalRecord.created_at))
+
+                if refusal_type:
+                    query = query.where(RefusalRecord.refusal_type == refusal_type)
+
+                if component_id:
+                    query = query.where(RefusalRecord.component_id == component_id)
+
+                query = query.limit(limit)
+
+                result = await session.execute(query)
+                return list(result.scalars().all())
+
+        except Exception as e:
+            logger.error("Failed to query refusals: %s", e, exc_info=True)
+            return []
+
+    # ID: 8a1044fd-1f8a-4a1b-8e04-7aabc959cffb
+    async def get_by_session(self, session_id: str) -> list[RefusalRecord]:
+        """
+        Get all refusals for a specific decision trace session.
+
+        Args:
+            session_id: Decision trace session ID
+
+        Returns:
+            List of RefusalRecord objects for this session
+        """
+        try:
+            async with self._session() as session:
+                query = (
+                    select(RefusalRecord)
+                    .where(RefusalRecord.session_id == session_id)
+                    .order_by(RefusalRecord.created_at)
+                )
+
+                result = await session.execute(query)
+                return list(result.scalars().all())
+
+        except Exception as e:
+            logger.error(
+                "Failed to query refusals for session %s: %s",
+                session_id,
+                e,
+                exc_info=True,
+            )
+            return []
+
+    # ID: ae6795f1-32b2-4128-9770-bb71881984d2
+    async def get_by_type(
+        self, refusal_type: str, limit: int = _CFG_REPO.refusal_by_type_limit
+    ) -> list[RefusalRecord]:
+        """
+        Get refusals by type for analysis.
+
+        Args:
+            refusal_type: Refusal category
+            limit: Maximum records (1-100)
+
+        Returns:
+            List of RefusalRecord objects of this type
+        """
+        return await self.get_recent(
+            limit=limit, refusal_type=refusal_type, component_id=None
+        )
+
+    # ID: d21057f9-7f64-4783-8bf7-dd1ec8d0ddca
+    async def get_statistics(self, days: int = 7) -> dict[str, Any]:
+        """
+        Get refusal statistics for analysis.
+
+        Args:
+            days: Number of days to analyze
+
+        Returns:
+            Dictionary with refusal statistics
+        """
+        try:
+            async with self._session() as session:
+                # Get refusals from last N days
+                cutoff = datetime.now().replace(
+                    hour=0, minute=0, second=0, microsecond=0
+                )
+                from datetime import timedelta
+
+                cutoff = cutoff - timedelta(days=days - 1)
+
+                query = select(RefusalRecord).where(RefusalRecord.created_at >= cutoff)
+
+                result = await session.execute(query)
+                refusals = list(result.scalars().all())
+
+                # Calculate statistics
+                stats = {
+                    "total_refusals": len(refusals),
+                    "days_analyzed": days,
+                    "by_type": {},
+                    "by_component": {},
+                    "by_phase": {},
+                    "avg_confidence": 0.0,
+                }
+
+                if not refusals:
+                    return stats
+
+                # Count by type
+                for refusal in refusals:
+                    # By type
+                    type_key = refusal.refusal_type
+                    stats["by_type"][type_key] = stats["by_type"].get(type_key, 0) + 1
+
+                    # By component
+                    comp_key = refusal.component_id
+                    stats["by_component"][comp_key] = (
+                        stats["by_component"].get(comp_key, 0) + 1
+                    )
+
+                    # By phase
+                    phase_key = refusal.phase
+                    stats["by_phase"][phase_key] = (
+                        stats["by_phase"].get(phase_key, 0) + 1
+                    )
+
+                # Average confidence
+                confidences = [r.confidence for r in refusals]
+                stats["avg_confidence"] = sum(confidences) / len(confidences)
+
+                return stats
+
+        except Exception as e:
+            logger.error("Failed to calculate refusal statistics: %s", e, exc_info=True)
+            return {
+                "total_refusals": 0,
+                "days_analyzed": days,
+                "by_type": {},
+                "by_component": {},
+                "by_phase": {},
+                "avg_confidence": 0.0,
+            }
+
+    # ID: e7c9af63-f216-414d-8a3f-9c0edf070842
+    async def count_by_type(self, days: int = 7) -> dict[str, int]:
+        """
+        Count refusals by type for the last N days.
+
+        Args:
+            days: Number of days to analyze
+
+        Returns:
+            Dictionary mapping refusal_type -> count
+        """
+        stats = await self.get_statistics(days)
+        return stats.get("by_type", {})

body/introspection/__init__.py

@@ -0,0 +1,4 @@
+# src/body/introspection/__init__.py
+"""Provides functionality for the __init__ module."""
+
+from __future__ import annotations

body/introspection/capability_discovery_service.py

@@ -0,0 +1,107 @@
+# src/body/introspection/capability_discovery_service.py
+"""
+Capability Discovery Service - Refactored for High Fidelity (V2.3).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from shared.config_loader import load_yaml_file
+from shared.logger import getLogger
+from shared.models import CapabilityMeta
+
+from .discovery import loader, sync
+
+# 1. FIXED: Proper import to avoid shadowing/type expression errors
+from .discovery.registry import CapabilityRegistry
+
+
+logger = getLogger(__name__)
+
+
+# ID: d6bd862e-8278-4967-bf95-e83bdd5ad576
+def load_and_validate_capabilities(intent_dir: Path) -> CapabilityRegistry:
+    base = intent_dir / "knowledge" / "capability_tags"
+    if not base.exists():
+        raise FileNotFoundError(f"Capability tags directory not found: {base}")
+
+    canonical: set[str] = set()
+    aliases: dict[str, str] = {}
+
+    for path in loader._iter_capability_files(base):
+        doc = load_yaml_file(path)
+        canonical |= loader._extract_canonical_from_doc(doc)
+        aliases.update(loader._extract_aliases_from_doc(doc))
+
+    if cycles := loader._detect_alias_cycles(aliases):
+        raise ValueError(f"Alias cycle(s) detected: {cycles}")
+
+    unresolved = [(a, t) for a, t in aliases.items() if t not in canonical]
+    if unresolved:
+        raise ValueError(
+            "Alias targets do not map to canonical capabilities:\n"
+            + "\n".join(f"{a} → {t}" for a, t in unresolved)
+        )
+
+    return CapabilityRegistry(canonical, aliases)
+
+
+# ID: ba659030-b38a-4be3-ae9c-fce21f68cd59
+async def sync_capabilities_to_db(
+    db: AsyncSession, intent_dir: Path
+) -> tuple[int, list[str]]:
+    registry = load_and_validate_capabilities(intent_dir)
+    count = await sync.run_capability_upsert(db, registry.canonical)
+    await db.commit()
+    logger.info("Synced %s capabilities", count)
+    return count, []
+
+
+# ID: 2b7449f9-dbac-4f09-9948-2be669b42fec
+def collect_code_capabilities(
+    root: Path, include_globs: list[str], exclude_globs: list[str], require_kgb: bool
+) -> dict[str, CapabilityMeta]:
+    from body.introspection.discovery.from_kgb import _collect_from_kgb
+    from body.introspection.discovery.from_source_scan import (
+        collect_from_source_scan,
+    )
+
+    try:
+        return (
+            _collect_from_kgb(root)
+            if require_kgb
+            else collect_from_source_scan(root, include_globs, exclude_globs)
+        )
+    except Exception as e:
+        logger.warning("Capability discovery failed: %s", e, exc_info=True)
+        return {}
+
+
+# ID: bbfb9527-fa8e-4b68-b5c4-b38c94133d1e
+def validate_agent_roles(agent_roles: dict, registry: CapabilityRegistry) -> None:
+    roles = agent_roles.get("roles", {})
+    if not isinstance(roles, dict):
+        raise ValueError("agent_roles must contain a 'roles' mapping")
+
+    errors = [
+        f"{role}: unknown capability '{tag}'"
+        for role, cfg in roles.items()
+        for tag in cfg.get("allowed_tags", [])
+        if not registry.resolve(tag)
+    ]
+
+    if errors:
+        raise ValueError("Invalid capability references:\n" + "\n".join(errors))
+
+
+# Re-export the class name for backward compatibility without breaking type hints
+__all__ = [
+    "CapabilityRegistry",
+    "collect_code_capabilities",
+    "load_and_validate_capabilities",
+    "sync_capabilities_to_db",
+    "validate_agent_roles",
+]

body/introspection/discovery/from_kgb.py

@@ -0,0 +1,33 @@
+# src/body/introspection/discovery/from_kgb.py
+"""
+Discovers implemented capabilities by leveraging the KnowledgeGraphBuilder.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from body.introspection.knowledge_graph_service import KnowledgeGraphBuilder
+from shared.models import CapabilityMeta
+
+
+def _collect_from_kgb(root: Path) -> dict[str, CapabilityMeta]:
+    """
+    Internal helper: use the KnowledgeGraphBuilder to find all capabilities.
+
+    This is a strategy used by the higher-level capability discovery service.
+    It is not a public capability surface on its own.
+    """
+    builder = KnowledgeGraphBuilder(root_path=root)
+    graph = builder.build()
+
+    capabilities: dict[str, CapabilityMeta] = {}
+    for symbol in graph.get("symbols", {}).values():
+        cap_key = symbol.get("capability")
+        if cap_key and cap_key != "unassigned":
+            capabilities[cap_key] = CapabilityMeta(
+                key=cap_key,
+                domain=symbol.get("domain"),
+                owner=symbol.get("owner"),
+            )
+    return capabilities

body/introspection/discovery/from_source_scan.py

@@ -0,0 +1,40 @@
+# src/body/introspection/discovery/from_source_scan.py
+"""
+Discovers implemented capabilities by performing a direct source code scan.
+This is a fallback for when the knowledge graph is not available.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from shared.models import CapabilityMeta
+
+
+CAPABILITY_PATTERN = re.compile(r"#\s*CAPABILITY:\s*(\S+)")
+
+
+# ID: 3fb50751-54f5-4282-9b52-fcc5eb6c23d2
+def collect_from_source_scan(
+    root: Path, include_globs: list[str], exclude_globs: list[str]
+) -> dict[str, CapabilityMeta]:
+    """
+    Scans Python files for # CAPABILITY tags.
+    """
+    capabilities: dict[str, CapabilityMeta] = {}
+    search_path = root / "src"
+
+    files_to_scan = list(search_path.rglob("*.py"))
+
+    for py_file in files_to_scan:
+        try:
+            content = py_file.read_text("utf-8")
+            matches = CAPABILITY_PATTERN.findall(content)
+            for cap_key in matches:
+                if cap_key not in capabilities:
+                    capabilities[cap_key] = CapabilityMeta(key=cap_key)
+        except (OSError, UnicodeDecodeError):
+            continue
+
+    return capabilities