first

services/asf-context/app/semantic_store.py

@@ -0,0 +1,71 @@
+"""Semantic / vector retrieval abstraction (stub + in-memory mock).
+
+A real implementation will talk to a vector DB / embedding store and return
+"semantically similar" artifacts. For bootstrap we keep the Protocol open and
+provide a deterministic mock.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Protocol, Optional, Sequence
+from uuid import UUID
+
+
+@dataclass
+class SemanticHit:
+    artifact_id: UUID
+    score: float
+    snippet: str = ""
+    metadata: dict = field(default_factory=dict)
+
+
+class SemanticStore(Protocol):
+    """Future vector / embedding store interface."""
+
+    async def search(
+        self,
+        tenant_id: UUID,
+        query: str,
+        *,
+        project_id: Optional[UUID] = None,
+        top_k: int = 10,
+        filters: Optional[dict] = None,
+    ) -> Sequence[SemanticHit]: ...
+
+    async def index_artifact(
+        self,
+        tenant_id: UUID,
+        artifact_id: UUID,
+        text: str,
+        metadata: Optional[dict] = None,
+    ) -> None: ...
+
+
+class InMemorySemanticStoreMock(SemanticStore):
+    """Deterministic, no-op mock.
+
+    Useful for unit tests and for getting the Context Engine scaffolding up
+    before a real vector DB is deployed. Always returns an empty hit list so
+    callers gracefully degrade to structural context only.
+    """
+
+    async def search(
+        self,
+        tenant_id: UUID,
+        query: str,
+        *,
+        project_id: Optional[UUID] = None,
+        top_k: int = 10,
+        filters: Optional[dict] = None,
+    ) -> Sequence[SemanticHit]:
+        return tuple()
+
+    async def index_artifact(
+        self,
+        tenant_id: UUID,
+        artifact_id: UUID,
+        text: str,
+        metadata: Optional[dict] = None,
+    ) -> None:  # pragma: no cover - mock side effect
+        return None