feat: add governed public knowledge retrieval

app/core/knowledge_contracts.py

@@ -0,0 +1,43 @@
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+ALLOWED_KNOWLEDGE_COLLECTIONS = frozenset({
+    "fin_faq_collection",
+    "fin_product_collection",
+    "fin_policy_collection",
+})
+
+
+class KnowledgeQuery(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    query: str = Field(min_length=1, max_length=2000)
+    intents: tuple[str, ...] = Field(min_length=1, max_length=4)
+    top_k: int = Field(default=5, ge=1, le=20)
+
+    @field_validator("query")
+    @classmethod
+    def query_must_not_be_blank(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("query must not be blank")
+        return value
+
+
+class KnowledgeHit(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    knowledge_id: str
+    collection: str
+    snippet: str
+    title: str | None = None
+    answer: str | None = None
+    score: float | None = Field(default=None, ge=0, le=1)
+    version: str | None = None
+
+
+class KnowledgeSearchResult(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    hits: tuple[KnowledgeHit, ...] = ()
+    degraded: bool = False
+    degradation_reason: str | None = None
+    searched_collections: tuple[str, ...] = ()