fuli-context 0.5.0 → 0.7.3

package/graph-provider/fuli_graph/knowledge_review_models.py

@@ -0,0 +1,133 @@
+from datetime import datetime
+from typing import Literal
+
+from pydantic import Field, model_validator
+
+from .models import (
+    ConfirmationStatus,
+    EpistemicQuadrant,
+    KnowledgeFeedbackKind,
+    KnowledgeItemKind,
+    PersonalProfileAspect,
+    PreferenceScope,
+    StrictModel,
+)
+
+KnowledgeReviewScope = Literal[
+    'all',
+    'preferences_global',
+    'preferences_project',
+    'projects_all',
+    'project',
+]
+KnowledgeReviewStatus = Literal['active', 'paused', 'completed']
+KnowledgeReviewDisposition = Literal['paused', 'completed']
+KnowledgeReviewOutcome = Literal[
+    'confirmed', 'updated', 'invalidated', 'deferred', 'delegated_to_ai'
+]
+KnowledgeReviewReason = Literal[
+    'changed_since_last',
+    'deferred_from_previous',
+    'conflict_or_attention',
+    'low_weight',
+    'repeated_cross_session',
+]
+
+
+class KnowledgeReviewStart(StrictModel):
+    personal_space_id: str = Field(min_length=1, max_length=128)
+    scope: KnowledgeReviewScope
+    personal_project_id: str | None = Field(default=None, min_length=1, max_length=128)
+
+    @model_validator(mode='after')
+    def validate_scope_project(self):
+        needs_project = self.scope in {'preferences_project', 'project'}
+        if needs_project and not self.personal_project_id:
+            raise ValueError(f'{self.scope} requires personal_project_id')
+        if not needs_project and self.personal_project_id:
+            raise ValueError(f'{self.scope} does not accept personal_project_id')
+        return self
+
+
+class KnowledgeReviewRun(StrictModel):
+    review_id: str
+    personal_space_id: str
+    scope: KnowledgeReviewScope
+    personal_project_id: str | None = None
+    scope_key: str
+    status: KnowledgeReviewStatus
+    previous_completed_at: datetime | None = None
+    review_cutoff_at: datetime
+    started_at: datetime
+    updated_at: datetime
+    completed_at: datetime | None = None
+    resumed: bool = False
+
+
+class KnowledgeReviewCandidate(StrictModel):
+    candidate_key: str
+    item_id: str
+    item_kind: KnowledgeItemKind
+    title: str
+    content: str
+    # Keep the decision-critical ranking context near the front of the wire
+    # payload. Older MCP clients may project a bounded prefix of the Provider
+    # response, and the user must still see why a candidate was selected.
+    priority: int = Field(ge=1, le=4)
+    reasons: list[KnowledgeReviewReason]
+    confirmation_status: ConfirmationStatus
+    current_quadrant: EpistemicQuadrant
+    project_ids: list[str] = Field(default_factory=list)
+    profile_aspect: PersonalProfileAspect | None = None
+    preference_scope: PreferenceScope | None = None
+    preference_project_id: str | None = None
+    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)
+    negative_evidence_count: int = Field(ge=0)
+    requires_attention: bool
+    last_feedback_kind: KnowledgeFeedbackKind | None = None
+    distinct_session_count: int = Field(ge=0)
+    changed_at: datetime | None = None
+
+
+class KnowledgeReviewCandidateRequest(StrictModel):
+    personal_space_id: str = Field(min_length=1, max_length=128)
+    review_id: str = Field(min_length=1, max_length=256)
+    limit: int = Field(default=10, ge=1, le=50)
+
+
+class KnowledgeReviewCandidatePage(StrictModel):
+    review: KnowledgeReviewRun
+    candidates: list[KnowledgeReviewCandidate]
+    total_candidate_count: int = Field(ge=0)
+    remaining_candidate_count: int = Field(ge=0)
+
+
+class KnowledgeReviewProgress(StrictModel):
+    personal_space_id: str = Field(min_length=1, max_length=128)
+    review_id: str = Field(min_length=1, max_length=256)
+    candidate_key: str = Field(
+        min_length=3,
+        max_length=520,
+        pattern=r'^(entity|relationship):.+$',
+    )
+    outcome: KnowledgeReviewOutcome
+    note: str | None = Field(default=None, min_length=1, max_length=2000)
+
+
+class KnowledgeReviewDecision(StrictModel):
+    decision_id: str
+    review_id: str
+    candidate_key: str
+    outcome: KnowledgeReviewOutcome
+    note: str | None = None
+    created_at: datetime
+    updated_at: datetime
+
+
+class KnowledgeReviewFinish(StrictModel):
+    personal_space_id: str = Field(min_length=1, max_length=128)
+    review_id: str = Field(min_length=1, max_length=256)
+    disposition: KnowledgeReviewDisposition

package/graph-provider/fuli_graph/knowledge_search.py

@@ -358,6 +358,7 @@ async def _personal_entities(
                  AS confirmation_status,
                node.fuli_confirmation_basis_json AS confirmation_basis_json,
                node.fuli_reasoning_summary AS reasoning_summary,
+               node.fuli_attributes_json AS attributes_json,
                node.fuli_profile_aspect AS profile_aspect,
                CASE WHEN node.fuli_profile_aspect IS NULL THEN NULL
                     ELSE coalesce(node.fuli_preference_scope, 'global') END
@@ -650,6 +651,7 @@ def _entity_search_result(record, score: float, space_id: str) -> EntitySearchRe
         value.pop('last_feedback_at', None)
     )
     for field in (
+        'attributes_json',
         'assignment_project_id',
         'episode_project_ids',
         'has_global_episode',
@@ -699,6 +701,7 @@ def _relevance(query: str, record) -> float:
     if not needle:
         return 0.0
     score = 8.0 if needle in haystack else 0.0
+    score = max(score, _alias_relevance(needle, _retrieval_aliases(record)))
     terms = _terms(needle)
     if terms:
         coverage = len(terms & _terms(haystack)) / len(terms)
@@ -733,13 +736,57 @@ def _terms(value: str) -> set[str]:
         term for term in re.findall(r'[a-z0-9_]+', value)
         if term not in LATIN_QUERY_FILLERS
     }
-    chinese = ''.join(re.findall(r'[\u4e00-\u9fff]', value))
-    for filler in CHINESE_QUERY_FILLERS:
-        chinese = chinese.replace(filler, '')
-    grams = {chinese[index:index + 2] for index in range(max(0, len(chinese) - 1))}
+    chinese_segments = re.findall(r'[\u4e00-\u9fff]+', value)
+    grams = set()
+    for chinese in chinese_segments:
+        for filler in CHINESE_QUERY_FILLERS:
+            chinese = chinese.replace(filler, '')
+        grams.update(
+            chinese[index:index + 2]
+            for index in range(max(0, len(chinese) - 1))
+        )
     return latin | grams
 
 
+def _retrieval_aliases(record) -> list[str]:
+    attributes = record.get('attributes')
+    if not isinstance(attributes, dict):
+        attributes = json_object(record.get('attributes_json'))
+    values = (
+        attributes.get('searchTerms')
+        or attributes.get('search_terms')
+        or []
+    )
+    if isinstance(values, str):
+        values = [values]
+    if not isinstance(values, list):
+        return []
+    return [
+        value.strip()
+        for value in values[:32]
+        if isinstance(value, str) and 0 < len(value.strip()) <= 256
+    ]
+
+
+def _alias_relevance(query: str, aliases: list[str]) -> float:
+    query_terms = _terms(query)
+    best = 0.0
+    for alias in aliases:
+        normalized_alias = _normalized(alias)
+        if not normalized_alias:
+            continue
+        if normalized_alias in query:
+            best = max(best, 8.0)
+            continue
+        alias_terms = _terms(normalized_alias)
+        if len(alias_terms) < 2:
+            continue
+        coverage = len(alias_terms & query_terms) / len(alias_terms)
+        if coverage >= 0.75:
+            best = max(best, 6.0 + coverage * 2.0)
+    return round(best, 4)
+
+
 def _timestamp(value) -> float:
     native = _native_datetime(value)
     return native.timestamp() if isinstance(native, datetime) else 0.0

package/graph-provider/fuli_graph/models.py

@@ -471,6 +471,25 @@ class EntityInput(StrictModel):
     def bound_attributes(cls, value: dict[str, Any]) -> dict[str, Any]:
         if len(value) > 32:
             raise ValueError('an entity may contain at most 32 attributes')
+        for key in ('searchTerms', 'search_terms'):
+            if key not in value:
+                continue
+            terms = value[key]
+            if (
+                not isinstance(terms, list)
+                or not terms
+                or len(terms) > 32
+                or any(
+                    not isinstance(term, str)
+                    or not term.strip()
+                    or len(term) > 256
+                    for term in terms
+                )
+            ):
+                raise ValueError(
+                    'entity search terms must be 1 to 32 non-empty strings '
+                    'of at most 256 characters'
+                )
         return value
 
     @model_validator(mode='after')

package/graph-provider/fuli_graph/runtime.py

@@ -169,6 +169,18 @@ class GraphitiRuntime:
             'CREATE CONSTRAINT fuli_knowledge_audit_id IF NOT EXISTS '
             'FOR (n:FuliKnowledgeAudit) REQUIRE n.id IS UNIQUE'
         )
+        await self.driver.execute_query(
+            'CREATE CONSTRAINT fuli_knowledge_review_id IF NOT EXISTS '
+            'FOR (n:FuliKnowledgeReviewRun) REQUIRE n.id IS UNIQUE'
+        )
+        await self.driver.execute_query(
+            'CREATE CONSTRAINT fuli_knowledge_review_active IF NOT EXISTS '
+            'FOR (n:FuliKnowledgeReviewRun) REQUIRE n.active_key IS UNIQUE'
+        )
+        await self.driver.execute_query(
+            'CREATE CONSTRAINT fuli_knowledge_review_decision_id IF NOT EXISTS '
+            'FOR (n:FuliKnowledgeReviewDecision) REQUIRE n.id IS UNIQUE'
+        )
         for query in (
             'CREATE INDEX fuli_entity_confirmation IF NOT EXISTS '
             'FOR (n:Entity) ON (n.group_id, n.fuli_confirmation_status)',
@@ -188,6 +200,9 @@ class GraphitiRuntime:
             'CREATE INDEX fuli_knowledge_audit_lookup IF NOT EXISTS '
             'FOR (n:FuliKnowledgeAudit) '
             'ON (n.space_id, n.item_id, n.usage_generation)',
+            'CREATE INDEX fuli_knowledge_review_scope IF NOT EXISTS '
+            'FOR (n:FuliKnowledgeReviewRun) '
+            'ON (n.personal_space_id, n.scope_key, n.status)',
             'CREATE INDEX fuli_personal_project_relation_type IF NOT EXISTS '
             'FOR ()-[r:PERSONAL_PROJECT_RELATION]-() ON (r.relation_type)',
         ):

package/graph-provider/fuli_graph/store_knowledge.py

@@ -44,9 +44,10 @@ class StoreKnowledge:
         space_id: str,
         limit: int | None = None,
         personal_project_id: str | None = None,
+        offset: int | None = None,
     ) -> GraphResult:
         return await read_graph(
-            self, actor, space_id, limit, personal_project_id
+            self, actor, space_id, limit, personal_project_id, offset
         )
 
     async def collaboration_context(

package/graph-provider/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fuli-graph-provider"
-version = "0.5.0"
+version = "0.7.3"
 description = "Graphiti-backed personal and shared project provider for Fuli."
 requires-python = ">=3.12"
 dependencies = [