fuli-context 0.2.0

package/graph-provider/fuli_graph/knowledge_usage_models.py

@@ -0,0 +1,52 @@
+from pydantic import Field, model_validator
+
+from .models import (
+    ConfirmationStatus,
+    KnowledgeItemKind,
+    KnowledgeUseKind,
+    StrictModel,
+)
+
+
+class KnowledgeUsageItem(StrictModel):
+    item_id: str = Field(min_length=1, max_length=256)
+    item_kind: KnowledgeItemKind
+    use_kind: KnowledgeUseKind
+
+
+class KnowledgeUsageCreate(StrictModel):
+    personal_space_id: str = Field(min_length=1, max_length=128)
+    task_id: str = Field(min_length=1, max_length=256)
+    session_id: str | None = Field(default=None, min_length=1, max_length=256)
+    tool_name: str | None = Field(default=None, min_length=1, max_length=128)
+    items: list[KnowledgeUsageItem] = Field(min_length=1, max_length=200)
+
+    @model_validator(mode='after')
+    def validate_usage_items(self):
+        identities = {
+            (item.item_kind, item.item_id, item.use_kind)
+            for item in self.items
+        }
+        if len(identities) != len(self.items):
+            raise ValueError('knowledge usage items must be unique')
+        return self
+
+
+class KnowledgeUsageItemResult(StrictModel):
+    item_id: str
+    item_kind: KnowledgeItemKind
+    recorded: bool
+    promoted: bool = False
+    confirmation_status: ConfirmationStatus
+    utility_score: float = Field(ge=0, le=1)
+    confidence_score: float = Field(ge=0, le=1)
+    qualified_use_count: int = Field(ge=0)
+    distinct_task_count: int = Field(ge=0)
+    usage_generation: int = Field(ge=1)
+
+
+class KnowledgeUsageResult(StrictModel):
+    recorded_count: int = Field(ge=0, le=200)
+    duplicate_count: int = Field(ge=0, le=200)
+    promoted_count: int = Field(ge=0, le=200)
+    items: list[KnowledgeUsageItemResult] = Field(max_length=200)

package/graph-provider/fuli_graph/model_validation.py

@@ -0,0 +1,58 @@
+import json
+import re
+from typing import Any
+
+
+_CREDENTIAL_PATTERNS = (
+    re.compile(r'-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----', re.I),
+    re.compile(
+        r'\b(?:sk-[A-Za-z0-9_-]{12,}|gh[pousr]_[A-Za-z0-9]{20,}|'
+        r'github_pat_[A-Za-z0-9_]{20,}|glpat-[A-Za-z0-9_-]{16,}|'
+        r'AKIA[A-Z0-9]{16}|ASIA[A-Z0-9]{16}|xox[baprs]-[A-Za-z0-9-]{20,})\b'
+    ),
+    re.compile(r'\bBearer\s+[A-Za-z0-9._~+/=-]{16,}', re.I),
+    re.compile(r'\beyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\b'),
+    re.compile(
+        r'\b(?:password|passwd|passphrase|secret|api[-_ ]?key|access[-_ ]?token|'
+        r'auth[-_ ]?token)\b\s*[:=]\s*(?:"[^"]+"|\'[^\']+\'|[^\s,]+)',
+        re.I,
+    ),
+)
+
+
+def reject_credentials(model: Any, label: str) -> None:
+    searchable = json.dumps(model.model_dump(mode='json'), ensure_ascii=False)
+    if any(pattern.search(searchable) for pattern in _CREDENTIAL_PATTERNS):
+        raise ValueError(f'{label} contains credentials')
+
+
+def normalize_provider_url(value: str) -> str:
+    if not value.startswith(('https://', 'http://127.0.0.1:', 'http://localhost:')):
+        raise ValueError('provider_url must use HTTPS or a loopback HTTP address')
+    return value.rstrip('/')
+
+
+def complete_epistemic_state(
+    *,
+    origin_quadrant: str,
+    current_quadrant: str | None,
+    epistemic_status: str,
+    reasoning_summary: str | None,
+    profile_aspect: str | None,
+) -> str:
+    current = current_quadrant or origin_quadrant
+    if origin_quadrant != 'known_known' and not reasoning_summary:
+        raise ValueError('non-known-known knowledge requires a reasoning summary')
+    if profile_aspect and epistemic_status == 'exploratory':
+        raise ValueError('personal profile knowledge cannot be exploratory')
+    return current
+
+
+def require_public_eligible_episode(episode: Any) -> None:
+    items = [*episode.entities, *episode.relationships]
+    if any(item.profile_aspect for item in items):
+        raise ValueError('Personal profile knowledge cannot enter public review')
+    if any(item.confirmation_status != 'confirmed' for item in items):
+        raise ValueError(
+            'Only knowledge with an auditable confirmation can enter public review'
+        )