core-runtime 0.1.1__py3-none-any.whl

api/v1/sync_routes.py

@@ -0,0 +1,261 @@
+# src/api/v1/sync_routes.py
+
+"""
+Sync API endpoints (ADR-058 Phase 4, D2).
+
+Five endpoints, all async-dispatch + poll:
+
+* `POST /sync/knowledge-graph`  → sync_type='knowledge_graph'
+* `POST /sync/vectors`      → sync_type='vectors'
+* `POST /sync/code-vectors` → sync_type='code_vectors'
+* `POST /sync/dev-sync`     → sync_type='dev_sync' (composite)
+* `GET  /sync/runs/{run_id}` → poll persisted sync_runs row
+
+All four POST paths share one `_dispatch_sync` body that INSERTs a
+pending row in `core.sync_runs` and schedules the dispatch on a
+background task via `will.governance.sync_runner`.
+
+CONSTITUTIONAL:
+- Session access via `api.dependencies.get_api_session` /
+  `open_background_session` only.
+- `CoreContext` read from `request.app.state.core_context`.
+- `body.atomic.*` and `will.workflows.*` reached through the
+  `will.governance.sync_runner` facade — no direct imports here.
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from fastapi import (
+    APIRouter,
+    BackgroundTasks,
+    Body,
+    Depends,
+    HTTPException,
+    Request,
+    Response,
+)
+from pydantic import BaseModel
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from api.dependencies import get_api_session, open_background_session
+from shared.context import CoreContext
+from shared.logger import getLogger
+from will.governance.sync_runner import (
+    ALLOWED_SYNC_TYPES,
+    run_and_persist_sync,
+)
+
+
+logger = getLogger(__name__)
+
+
+router = APIRouter(prefix="/sync")
+
+
+# ID: 6e3a0f8b-2d7c-4f5a-0431-f6789a0bcdef
+class SyncRequest(BaseModel):
+    """Body for the four POST /sync/* endpoints.
+
+    `target` is an optional scope filter forwarded to the backend.
+    Backends that don't honour it ignore it.
+
+    `force` is a backend-specific re-run hint. Today only
+    `sync.vectors_code` honours it (resets chunk_count on already-embedded
+    artifacts so the embed loop re-processes them). Default False — no
+    behaviour change for callers that don't pass it.
+    """
+
+    write: bool = False
+    target: str | None = None
+    requested_by: str = "api"
+    force: bool = False
+
+
+# ID: 7f4b1a9c-3e8d-4a6b-1542-07890ab12345
+async def _dispatch_sync(
+    *,
+    sync_type: str,
+    request: Request,
+    response: Response,
+    background_tasks: BackgroundTasks,
+    payload: SyncRequest,
+    session: AsyncSession,
+) -> dict:
+    """Shared body for the four POST /sync/* endpoints."""
+    if sync_type not in ALLOWED_SYNC_TYPES:
+        raise HTTPException(
+            status_code=422,
+            detail={
+                "error": f"Unknown sync_type: {sync_type}",
+                "allowed": sorted(ALLOWED_SYNC_TYPES),
+            },
+        )
+
+    core_context: CoreContext = request.app.state.core_context
+
+    result = await session.execute(
+        text(
+            """
+            INSERT INTO core.sync_runs
+                (sync_type, write, target, status, requested_by)
+            VALUES (:sync_type, :write, :target, 'pending', :requested_by)
+            RETURNING id
+            """
+        ),
+        {
+            "sync_type": sync_type,
+            "write": payload.write,
+            "target": payload.target,
+            "requested_by": payload.requested_by,
+        },
+    )
+    run_id: UUID = result.scalar_one()
+    await session.commit()
+
+    # ID: 8a5c2b0d-4f9e-4b7c-2653-189012345abc
+    async def drive_sync() -> None:
+        async for bg_session in open_background_session():
+            await run_and_persist_sync(
+                core_context,
+                bg_session,
+                run_id=run_id,
+                sync_type=sync_type,
+                write=payload.write,
+                target=payload.target,
+                force=payload.force,
+            )
+
+    background_tasks.add_task(drive_sync)
+
+    response.status_code = 202
+    return {
+        "run_id": str(run_id),
+        "status": "pending",
+        "href": f"/sync/runs/{run_id}",
+    }
+
+
+@router.post("/knowledge-graph")
+# ID: 9b6d3c1e-5a0f-4c8d-3764-29a01234abcd
+async def sync_knowledge_graph(
+    request: Request,
+    response: Response,
+    background_tasks: BackgroundTasks,
+    payload: SyncRequest = Body(default_factory=SyncRequest),
+    session: AsyncSession = Depends(get_api_session),
+) -> dict:
+    """Dispatch code-symbols → PostgreSQL knowledge graph sync."""
+    return await _dispatch_sync(
+        sync_type="knowledge_graph",
+        request=request,
+        response=response,
+        background_tasks=background_tasks,
+        payload=payload,
+        session=session,
+    )
+
+
+@router.post("/vectors")
+# ID: 0c7e4d2f-6b1a-4d9e-4875-3ab12345bcde
+async def sync_vectors(
+    request: Request,
+    response: Response,
+    background_tasks: BackgroundTasks,
+    payload: SyncRequest = Body(default_factory=SyncRequest),
+    session: AsyncSession = Depends(get_api_session),
+) -> dict:
+    """Dispatch constitutional vector sync (PG ↔ Qdrant)."""
+    return await _dispatch_sync(
+        sync_type="vectors",
+        request=request,
+        response=response,
+        background_tasks=background_tasks,
+        payload=payload,
+        session=session,
+    )
+
+
+@router.post("/code-vectors")
+# ID: 1d8f5e3a-7c2b-4e0f-5986-4bc23456cdef
+async def sync_code_vectors(
+    request: Request,
+    response: Response,
+    background_tasks: BackgroundTasks,
+    payload: SyncRequest = Body(default_factory=SyncRequest),
+    session: AsyncSession = Depends(get_api_session),
+) -> dict:
+    """Dispatch codebase symbol embedding via the worker pipeline."""
+    return await _dispatch_sync(
+        sync_type="code_vectors",
+        request=request,
+        response=response,
+        background_tasks=background_tasks,
+        payload=payload,
+        session=session,
+    )
+
+
+@router.post("/dev-sync")
+# ID: 2e9a6f4b-8d3c-4f1a-6a97-5cd34567def0
+async def sync_dev_sync(
+    request: Request,
+    response: Response,
+    background_tasks: BackgroundTasks,
+    payload: SyncRequest = Body(default_factory=SyncRequest),
+    session: AsyncSession = Depends(get_api_session),
+) -> dict:
+    """Dispatch the composite fix + knowledge-graph + vectors workflow."""
+    return await _dispatch_sync(
+        sync_type="dev_sync",
+        request=request,
+        response=response,
+        background_tasks=background_tasks,
+        payload=payload,
+        session=session,
+    )
+
+
+@router.get("/runs/{run_id}")
+# ID: 3f0b7a5c-9e4d-4a2b-7ba8-6de45678ef01
+async def get_sync_run(
+    run_id: UUID,
+    session: AsyncSession = Depends(get_api_session),
+) -> dict:
+    """Return a persisted sync run by id, or 404 if unknown."""
+    result = await session.execute(
+        text(
+            """
+            SELECT id, sync_type, write, target, status,
+                   requested_by, requested_at, started_at, finished_at,
+                   result, error
+              FROM core.sync_runs
+             WHERE id = :rid
+            """
+        ),
+        {"rid": run_id},
+    )
+    row = result.mappings().first()
+    if row is None:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Sync run not found: {run_id}",
+        )
+
+    return {
+        "run_id": str(row["id"]),
+        "sync_type": row["sync_type"],
+        "write": row["write"],
+        "target": row["target"],
+        "status": row["status"],
+        "requested_by": row["requested_by"],
+        "requested_at": (
+            row["requested_at"].isoformat() if row["requested_at"] else None
+        ),
+        "started_at": row["started_at"].isoformat() if row["started_at"] else None,
+        "finished_at": (row["finished_at"].isoformat() if row["finished_at"] else None),
+        "result": row["result"],
+        "error": row["error"],
+    }

body/__init__.py

@@ -0,0 +1,4 @@
+# src/body/__init__.py
+"""Body-layer acting workers — execution of blackboard proposals."""
+
+from __future__ import annotations

body/analyzers/__init__.py

@@ -0,0 +1,25 @@
+# src/body/analyzers/__init__.py
+
+"""
+Analyzers - Parse/Load phase components.
+
+Analyzers extract information from code without making decisions.
+They are pure functions: same input → same output.
+"""
+
+from __future__ import annotations
+
+from .file_analyzer import FileAnalyzer
+from .knowledge_graph_analyzer import KnowledgeGraphAnalyzer
+from .prompt_analyzer import PromptAnalyzer
+from .symbol_extractor import SymbolExtractor, SymbolInfo, SymbolMetadata
+
+
+__all__ = [
+    "FileAnalyzer",
+    "KnowledgeGraphAnalyzer",
+    "PromptAnalyzer",
+    "SymbolExtractor",
+    "SymbolInfo",
+    "SymbolMetadata",
+]

body/analyzers/base_analyzer.py

@@ -0,0 +1,28 @@
+# src/body/analyzers/base_analyzer.py
+"""Base Analyzer - PARSE phase base class.
+
+All Body analyzers extract structural facts from code without making decisions.
+They are pure functions: same input → same output.
+
+Owning `phase` here eliminates AST duplication across:
+    FileAnalyzer, KnowledgeGraphAnalyzer, PromptAnalyzer, SymbolExtractor.
+"""
+
+from __future__ import annotations
+
+from shared.component_primitive import Component, ComponentPhase
+
+
+# ID: b4e2f3a5-c6d7-8901-bcde-f01234567891
+class BaseAnalyzer(Component):
+    """Base class for all PARSE phase analyzers.
+
+    Subclasses must implement execute(). They inherit phase automatically.
+    No side effects permitted — analyzers are read-only fact extractors.
+    """
+
+    @property
+    # ID: c5f3a4b6-d7e8-9012-cdef-012345678912
+    def phase(self) -> ComponentPhase:
+        """All analyzers operate in the PARSE phase."""
+        return ComponentPhase.PARSE

body/analyzers/constitutional_path_analyzer.py

@@ -0,0 +1,63 @@
+# src/body/analyzers/constitutional_path_analyzer.py
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from body.analyzers.base_analyzer import BaseAnalyzer
+from shared.component_primitive import ComponentResult
+from shared.infrastructure.intent.intent_repository import get_intent_repository
+
+
+# ID: 9666577f-5e1f-4dea-a104-59c72bfffe82
+class ConstitutionalPathAnalyzer(BaseAnalyzer):
+    """
+    PARSE Phase Component.
+    Authoritatively discovers all artifacts indexed in the Mind (.intent/).
+
+    CONSTITUTIONAL ALIGNMENT:
+    - Authority: IntentRepository (The sole gateway to the Mind).
+    - Boundary: Read-only access to indexed policies and META contracts.
+    """
+
+    # ID: ba8e4735-0988-479a-92ad-5aeeba2ba4c6
+    async def execute(self, **kwargs: Any) -> ComponentResult:
+        """Executes the Constitutional Path Analyzer to retrieve and validate indexed policy paths and core system contracts from the IntentRepository, returning a ComponentResult with the unique artifacts and metadata."""
+        start_time = time.time()
+
+        # 1. Access the Mind through the sanctioned gateway
+        # This automatically triggers validate_intent_tree (Bootstrap Contract v0)
+        repo = get_intent_repository()
+        repo.initialize()  # Builds the in-memory index
+
+        # 2. Sensation: Retrieve only what the Repository has indexed as "Law"
+        # This prevents the Body from 'hallucinating' or crawling unindexed files.
+        policy_paths = [str(ref.path) for ref in repo.list_policies()]
+
+        # 3. Add the "Contractual Primitives" (META files required for system operation)
+        # These are derived from the repo.root provided by the PathResolver.
+        core_structure = [
+            repo.root / "META" / "intent_tree.schema.json",
+            repo.root / "META" / "rule_document.schema.json",
+            repo.root / "META" / "enums.json",
+            repo.root / "constitution" / "precedence_rules.yaml",
+        ]
+
+        artifacts = policy_paths + [str(p) for p in core_structure if p.exists()]
+        unique_artifacts = sorted(list(set(artifacts)))
+
+        duration = time.time() - start_time
+
+        return ComponentResult(
+            component_id=self.component_id,
+            ok=True,
+            data={"paths": unique_artifacts, "count": len(unique_artifacts)},
+            phase=self.phase,
+            confidence=1.0,
+            duration_sec=duration,
+            metadata={
+                "intent_root": str(repo.root),
+                "rationale": "Collected indexed policy refs and META contracts from IntentRepository.",
+            },
+        )

body/analyzers/file_analyzer.py

@@ -0,0 +1,211 @@
+# src/body/analyzers/file_analyzer.py
+"""File Analyzer - Analyzes Python file structure and classifies type."""
+
+from __future__ import annotations
+
+import ast
+import time
+from typing import Any
+
+from body.analyzers.base_analyzer import BaseAnalyzer
+from shared.component_primitive import ComponentResult  # Component, ComponentPhase,
+from shared.context import CoreContext
+from shared.infrastructure.intent.operational_config import load_operational_config
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+_CFG_AZ = load_operational_config().analyzers
+
+
+# ID: c9251530-0236-41a9-9630-b305f283277a
+class FileAnalyzer(BaseAnalyzer):
+    """Analyzes Python files to detect type and complexity.
+
+    Determines if a file is a:
+    - sqlalchemy_model: Requires integration fixtures.
+    - async_module: Requires pytest-asyncio.
+    - function_module / class_module: Requires standard unit testing.
+
+    Constitutional requirements:
+    - MUST be initialized with CoreContext containing valid git_service.
+    - Body layer components do not access settings directly.
+    """
+
+    def __init__(self, context: CoreContext | None = None):
+        """Initialize with context for governed path resolution."""
+        self.context = context
+
+    # ID: ddb4df7c-87db-40dd-91b1-1691cb0b8203
+    async def execute(self, file_path: str, **kwargs) -> ComponentResult:
+        """Analyze file structure and classify for downstream strategy selection."""
+        start_time = time.time()
+
+        # Constitutional boundary enforcement: Body requires proper context
+        if not self.context or not getattr(self.context, "git_service", None):
+            return ComponentResult(
+                component_id=self.component_id,
+                ok=False,
+                data={
+                    "error": (
+                        "FileAnalyzer requires CoreContext with git_service. "
+                        "Body layer components must not access settings directly."
+                    )
+                },
+                phase=self.phase,
+                confidence=0.0,
+            )
+
+        repo_root = self.context.git_service.repo_path
+        abs_path = (repo_root / file_path).resolve()
+
+        if not abs_path.exists():
+            return ComponentResult(
+                component_id=self.component_id,
+                ok=False,
+                data={"error": f"File not found: {file_path}"},
+                phase=self.phase,
+                confidence=0.0,
+            )
+
+        try:
+            code = abs_path.read_text(encoding="utf-8")
+            tree = ast.parse(code)
+
+            analysis = self._analyze_ast(tree)
+            file_type, confidence = self._classify_file(analysis)
+
+            duration = time.time() - start_time
+
+            return ComponentResult(
+                component_id=self.component_id,
+                ok=True,
+                data={
+                    "file_type": file_type,
+                    "has_sqlalchemy": analysis["has_sqlalchemy"],
+                    "has_async": analysis["has_async"],
+                    "class_count": analysis["class_count"],
+                    "function_count": analysis["function_count"],
+                    "complexity": analysis["complexity"],
+                },
+                phase=self.phase,
+                confidence=confidence,
+                next_suggested="symbol_extractor",
+                duration_sec=duration,
+                metadata={
+                    "file_path": file_path,
+                    "line_count": len(code.splitlines()),
+                    "total_definitions": analysis["total_definitions"],
+                    "rationale": (
+                        f"Classified {file_path} as {file_type} based on structural markers"
+                    ),
+                    "decision_context": {
+                        "agent": "FileAnalyzer",
+                        "decision_type": "file_classification",
+                        "has_sqlalchemy": analysis["has_sqlalchemy"],
+                        "has_async": analysis["has_async"],
+                        "definitions": analysis["total_definitions"],
+                    },
+                },
+            )
+
+        except SyntaxError as e:
+            return ComponentResult(
+                component_id=self.component_id,
+                ok=False,
+                data={"error": f"Syntax error in {file_path}: {e}"},
+                phase=self.phase,
+                confidence=0.0,
+            )
+        except Exception as e:
+            logger.error("FileAnalyzer failed for %s: %s", file_path, e, exc_info=True)
+            return ComponentResult(
+                component_id=self.component_id,
+                ok=False,
+                data={"error": str(e)},
+                phase=self.phase,
+                confidence=0.0,
+            )
+
+    def _analyze_ast(self, tree: ast.AST) -> dict[str, Any]:
+        """Extract structural facts from AST."""
+        facts: dict[str, Any] = {
+            "has_sqlalchemy": False,
+            "has_base_class": False,
+            "has_mapped": False,
+            "has_async": False,
+            "class_count": 0,
+            "function_count": 0,
+            "async_function_count": 0,
+        }
+
+        for node in ast.walk(tree):
+            # Check imports for framework usage
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    if "sqlalchemy" in alias.name:
+                        facts["has_sqlalchemy"] = True
+
+            elif isinstance(node, ast.ImportFrom):
+                if node.module and "sqlalchemy" in node.module:
+                    facts["has_sqlalchemy"] = True
+                    if any("Mapped" in a.name for a in node.names):
+                        facts["has_mapped"] = True
+
+            # Count definitions
+            elif isinstance(node, ast.ClassDef):
+                facts["class_count"] += 1
+                for base in node.bases:
+                    if isinstance(base, ast.Name) and base.id == "Base":
+                        facts["has_base_class"] = True
+
+            elif isinstance(node, ast.FunctionDef):
+                facts["function_count"] += 1
+
+            elif isinstance(node, ast.AsyncFunctionDef):
+                facts["async_function_count"] += 1
+                facts["has_async"] = True
+
+        total = (
+            facts["class_count"]
+            + facts["function_count"]
+            + facts["async_function_count"]
+        )
+        facts["total_definitions"] = total
+
+        # Categorize complexity
+        if total > _CFG_AZ.file_complexity_high_threshold:
+            facts["complexity"] = "high"
+        elif total > 5:
+            facts["complexity"] = "medium"
+        else:
+            facts["complexity"] = "low"
+
+        return facts
+
+    def _classify_file(self, analysis: dict[str, Any]) -> tuple[str, float]:
+        """Classify file type based on collected facts.
+
+        Returns:
+            (file_type, confidence)
+        """
+        # SQLAlchemy model detection
+        if analysis["has_sqlalchemy"] and (
+            analysis["has_base_class"] or analysis["has_mapped"]
+        ):
+            return ("sqlalchemy_model", 0.95)
+
+        # Async module detection
+        if analysis["has_async"] and analysis["async_function_count"] > 1:
+            return ("async_module", 0.90)
+
+        # Class-heavy logic
+        if analysis["class_count"] > 0 and analysis["function_count"] == 0:
+            return ("class_module", 0.85)
+
+        # Function-heavy logic
+        if analysis["function_count"] > 0 and analysis["class_count"] == 0:
+            return ("function_module", 0.85)
+
+        return ("mixed_module", 0.60)

body/analyzers/knowledge_graph_analyzer.py

@@ -0,0 +1,86 @@
+# src/body/analyzers/knowledge_graph_analyzer.py
+
+"""
+Knowledge Graph Analyzer - PARSE Phase Component.
+Standardized interface for system introspection.
+
+Constitutional Alignment:
+- Phase: PARSE (Structural analysis)
+- Authority: CODE (Implementation)
+- Boundary: Requires repo_root via dependency injection (no settings fallback)
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Any
+
+from body.analyzers.base_analyzer import BaseAnalyzer
+from body.introspection.knowledge_graph_service import KnowledgeGraphBuilder
+from shared.component_primitive import ComponentResult  # Component, ComponentPhase,
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+
+# ID: e9b2c3d4-f5a6-7b8c-9d0e-1f2a3b4c5d6e
+class KnowledgeGraphAnalyzer(BaseAnalyzer):
+    """
+    Standardized component for building the Knowledge Graph.
+
+    Constitutional Requirement:
+    - MUST receive repo_root parameter (no settings fallback)
+    - Body layer components do not access settings directly
+    """
+
+    # ID: 46b5ce81-b2fc-4822-88ba-53682cf1f431
+    async def execute(
+        self, repo_root: Path | None = None, **kwargs: Any
+    ) -> ComponentResult:
+        """
+        Execute the codebase scan.
+
+        Args:
+            repo_root: Repository root path (required for constitutional compliance)
+
+        Constitutional Compliance:
+        - Requires repo_root parameter (no settings fallback)
+        - Returns error if repo_root not provided (fail fast, dependency injection enforced)
+        """
+        start_time = time.time()
+
+        # Constitutional boundary enforcement: Body requires proper parameters
+        if repo_root is None:
+            return ComponentResult(
+                component_id=self.component_id,
+                ok=False,
+                data={
+                    "error": "KnowledgeGraphAnalyzer requires repo_root parameter. "
+                    "Body layer components must not access settings directly."
+                },
+                phase=self.phase,
+                confidence=0.0,
+            )
+
+        # Instantiate the pure logic builder
+        builder = KnowledgeGraphBuilder(repo_root)
+
+        # Build the graph (pure in-memory operation)
+        graph_data = builder.build()
+
+        duration = time.time() - start_time
+
+        return ComponentResult(
+            component_id=self.component_id,
+            ok=True,
+            data=graph_data,
+            phase=self.phase,
+            confidence=1.0,
+            metadata={
+                "symbol_count": graph_data["metadata"].get("symbol_count", 0),
+                "repo_root": str(repo_root),
+            },
+            duration_sec=duration,
+        )