fuli-context 0.7.2 → 0.7.4-beta.1

package/graph-provider/fuli_graph/knowledge_review.py

@@ -159,6 +159,12 @@ async def list_knowledge_review_candidates(
         review_id=run.review_id,
         routing_='r',
     )
+    deferred_rows, _, _ = await store.runtime.driver.execute_query(
+        _DEFERRED_ITEM_QUERY,
+        space_id=space['id'],
+        review_id=run.review_id,
+        routing_='r',
+    )
     candidates = build_review_candidates(
         [dict(row) for row in [*entity_rows, *relationship_rows]],
         scope=run.scope,
@@ -174,6 +180,12 @@ async def list_knowledge_review_candidates(
         decided_candidate_keys={
             row['candidate_key'] for row in decision_rows
         },
+        deferred_candidate_keys={
+            key
+            for row in deferred_rows
+            for key in row.get('candidate_keys', [])
+            if key
+        },
     )
     selected = candidates[:request.limit]
     return KnowledgeReviewCandidatePage(
@@ -272,7 +284,9 @@ def build_review_candidates(
     review_cutoff_at: datetime | None = None,
     conflict_item_keys: set[str],
     decided_candidate_keys: set[str],
+    deferred_candidate_keys: set[str] | None = None,
 ) -> list[KnowledgeReviewCandidate]:
+    deferred_candidate_keys = deferred_candidate_keys or set()
     prepared = []
     for row in rows:
         candidate_key = f"{row['item_kind']}:{row['item_id']}"
@@ -328,6 +342,7 @@ def build_review_candidates(
             normalized,
             previous_completed_at,
             candidate_key in conflict_item_keys,
+            candidate_key in deferred_candidate_keys,
         )
         if not reasons:
             continue
@@ -426,6 +441,7 @@ def _normalize_item_row(row: dict[str, Any]) -> dict[str, Any]:
         'preference_project_id': row.get('preference_project_id'),
         'project_ids': project_ids,
         'confirmation_status': row.get('confirmation_status') or 'pending',
+        'current_quadrant': row.get('current_quadrant') or 'known_known',
         'utility_score': _float_or_default(row.get('utility_score'), 0),
         'confidence_score': _float_or_default(row.get('confidence_score'), 0.5),
         'qualified_use_count': int(row.get('qualified_use_count') or 0),
@@ -471,12 +487,15 @@ def _candidate_reasons(
     item: dict,
     previous_completed_at: datetime | None,
     has_conflict: bool,
+    was_deferred: bool,
 ) -> list[str]:
     reasons = []
     if previous_completed_at is None or (
         item['changed_at'] is not None and item['changed_at'] > previous_completed_at
     ):
         reasons.append('changed_since_last')
+    if was_deferred:
+        reasons.append('deferred_from_previous')
     if (
         has_conflict
         or item['requires_attention']
@@ -496,6 +515,7 @@ def _candidate_reasons(
 def _reason_priority(reason: str) -> int:
     return {
         'changed_since_last': 1,
+        'deferred_from_previous': 1,
         'conflict_or_attention': 2,
         'low_weight': 3,
         'repeated_cross_session': 4,
@@ -539,6 +559,11 @@ RETURN item.uuid AS item_id,
        item.fuli_profile_aspect AS profile_aspect,
        item.fuli_preference_scope AS preference_scope,
        item.fuli_preference_project_id AS preference_project_id,
+       coalesce(
+         item.fuli_current_quadrant,
+         item.fuli_origin_quadrant,
+         'known_known'
+       ) AS current_quadrant,
        collect(DISTINCT assignment.project_id) AS assigned_project_ids,
        collect(DISTINCT episode.fuli_personal_project_id) AS evidence_project_ids,
        collect(DISTINCT episode.fuli_session_id) AS session_ids,
@@ -576,6 +601,11 @@ RETURN item.uuid AS item_id,
        item.fuli_profile_aspect AS profile_aspect,
        item.fuli_preference_scope AS preference_scope,
        item.fuli_preference_project_id AS preference_project_id,
+       coalesce(
+         item.fuli_current_quadrant,
+         item.fuli_origin_quadrant,
+         'known_known'
+       ) AS current_quadrant,
        collect(DISTINCT assignment.project_id) AS assigned_project_ids,
        collect(DISTINCT episode.fuli_personal_project_id) AS evidence_project_ids,
        collect(DISTINCT episode.fuli_session_id) AS session_ids,
@@ -605,8 +635,23 @@ WITH space, collect(DISTINCT 'entity:' + knowledge.item_id) +
      AS knowledge_keys
 OPTIONAL MATCH (space)-[:HAS_PREFERENCE_CONFLICT]->
               (preference:FuliPreferenceConflict {status: 'ai_pending'})
-RETURN knowledge_keys +
-       collect(DISTINCT preference.left_item_kind + ':' + preference.left_item_id) +
-       collect(DISTINCT preference.right_item_kind + ':' + preference.right_item_id)
-       AS candidate_keys
+WITH knowledge_keys,
+     collect(DISTINCT preference.left_item_kind + ':' + preference.left_item_id) +
+     collect(DISTINCT preference.right_item_kind + ':' + preference.right_item_id)
+     AS preference_keys
+RETURN knowledge_keys + preference_keys AS candidate_keys
+'''
+
+
+_DEFERRED_ITEM_QUERY = '''
+MATCH (:FuliSpace {id: $space_id, kind: 'personal'})-
+      [:HAS_KNOWLEDGE_REVIEW]->(past_run:FuliKnowledgeReviewRun)
+WHERE past_run.id <> $review_id
+MATCH (past_run)-[:HAS_REVIEW_DECISION]->
+      (decision:FuliKnowledgeReviewDecision)
+WITH decision.candidate_key AS candidate_key, decision
+ORDER BY decision.updated_at DESC, decision.id DESC
+WITH candidate_key, collect(decision)[0] AS latest_decision
+WHERE latest_decision.outcome = 'deferred'
+RETURN collect(candidate_key) AS candidate_keys
 '''

package/graph-provider/fuli_graph/knowledge_review_models.py

@@ -5,6 +5,7 @@ from pydantic import Field, model_validator
 
 from .models import (
     ConfirmationStatus,
+    EpistemicQuadrant,
     KnowledgeFeedbackKind,
     KnowledgeItemKind,
     PersonalProfileAspect,
@@ -22,10 +23,11 @@ KnowledgeReviewScope = Literal[
 KnowledgeReviewStatus = Literal['active', 'paused', 'completed']
 KnowledgeReviewDisposition = Literal['paused', 'completed']
 KnowledgeReviewOutcome = Literal[
-    'confirmed', 'updated', 'invalidated', 'skipped', 'deferred'
+    'confirmed', 'updated', 'invalidated', 'deferred', 'delegated_to_ai'
 ]
 KnowledgeReviewReason = Literal[
     'changed_since_last',
+    'deferred_from_previous',
     'conflict_or_attention',
     'low_weight',
     'repeated_cross_session',
@@ -68,11 +70,17 @@ class KnowledgeReviewCandidate(StrictModel):
     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
-    project_ids: list[str] = Field(default_factory=list)
-    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)
@@ -82,8 +90,6 @@ class KnowledgeReviewCandidate(StrictModel):
     last_feedback_kind: KnowledgeFeedbackKind | None = None
     distinct_session_count: int = Field(ge=0)
     changed_at: datetime | None = None
-    priority: int = Field(ge=1, le=4)
-    reasons: list[KnowledgeReviewReason]
 
 
 class KnowledgeReviewCandidateRequest(StrictModel):

package/graph-provider/fuli_graph/knowledge_search.py

@@ -10,6 +10,7 @@ from .provider_values import (
     json_object,
     native_datetime as _native_datetime,
     normalized_text as _normalized,
+    preference_qualifiers,
 )
 from .search_projection import (
     effective_confirmation_status,
@@ -255,6 +256,8 @@ async def personal_project_scopes(
         WHERE all(
           relation IN relationships(path)
           WHERE relation.relation_type IN ['PART_OF', 'USES_KNOWLEDGE_FROM']
+            AND relation.status = 'active'
+            AND relation.confirmation_authority = 'human_review'
         )
           AND EXISTS {
             MATCH (space)-[:CONTAINS_PROJECT]->(source)
@@ -634,6 +637,14 @@ def _dedupe_ranked_entities(ranked, active_project_id):
 
 def _entity_search_result(record, score: float, space_id: str) -> EntitySearchResult:
     value = dict(record)
+    attributes = json_object(value.get('attributes_json'))
+    value['preference_key'] = (
+        attributes.get('preferenceKey')
+        or attributes.get('preference_key')
+        or value.get('key')
+        or value.get('id')
+    )
+    value['preference_qualifiers'] = preference_qualifiers(attributes)
     basis = json_object(value.pop('confirmation_basis_json', None))
     source_references = value.pop('source_references', [])
     created_at = _native_datetime(value.pop('created_at', None))

package/graph-provider/fuli_graph/models.py

@@ -163,8 +163,6 @@ def _validate_inheritance(
         raise ValueError(
             'inherited project ids are only valid for selected_projects inheritance'
         )
-    if profile_aspect and mode != 'local_only':
-        raise ValueError('personal preferences cannot inherit across projects')
 
 
 class ConfirmationActor(StrictModel):
@@ -772,6 +770,8 @@ class EntitySearchResult(StrictModel):
     preference_scope: PreferenceScope | None = None
     preference_project_id: str | None = None
     key: str | None = None
+    preference_key: str | None = None
+    preference_qualifiers: dict[str, Any] = Field(default_factory=dict)
     defined_project_id: str | None = None
     inheritance_mode: KnowledgeInheritanceMode = 'local_only'
     inherited_project_ids: list[str] = Field(default_factory=list, max_length=32)
@@ -819,6 +819,8 @@ class FactResult(StrictModel):
     preference_scope: PreferenceScope | None = None
     preference_project_id: str | None = None
     key: str | None = None
+    preference_key: str | None = None
+    preference_qualifiers: dict[str, Any] = Field(default_factory=dict)
     defined_project_id: str | None = None
     inheritance_mode: KnowledgeInheritanceMode = 'local_only'
     inherited_project_ids: list[str] = Field(default_factory=list, max_length=32)
@@ -860,9 +862,18 @@ class CollaborationPreferenceItem(StrictModel):
     preference_scope: PreferenceScope
     preference_project_id: str | None = None
     attributes: dict[str, Any] = Field(default_factory=dict)
+    weight: float | None = Field(default=None, ge=0, le=1, allow_inf_nan=False)
+    reason: str | None = None
+    confirmation_basis: ConfirmationBasis
+    reasoning_summary: str | None = None
+    inheritance_mode: KnowledgeInheritanceMode = 'local_only'
+    inherited_project_ids: list[str] = Field(default_factory=list, max_length=32)
     confirmation_status: Literal['confirmed', 'agent_confirmed']
     confirmed_at: datetime
     created_at: datetime | None = None
+    scope_distance: int = Field(default=0, ge=0, le=2)
+    inherited_from_project_id: str | None = None
+    scope_path: list[str] = Field(default_factory=list, max_length=3)
 
 
 class CollaborationPreferenceConflict(StrictModel):
@@ -880,6 +891,8 @@ class CollaborationContextResult(StrictModel):
     effective_preferences: list[CollaborationPreferenceItem] = Field(default_factory=list)
     conflicts: list[CollaborationPreferenceConflict] = Field(default_factory=list)
     overridden_global_ids: list[str] = Field(default_factory=list)
+    overridden_inherited_ids: list[str] = Field(default_factory=list)
+    overridden_lower_authority_ids: list[str] = Field(default_factory=list)
     truncated: bool = False
 
 

package/graph-provider/fuli_graph/personal_global_preference_models.py

@@ -0,0 +1,234 @@
+from datetime import datetime
+from typing import Any, Literal
+
+from pydantic import Field, model_validator
+
+from .models import (
+    ConfirmationBasis,
+    ConfirmationStatus,
+    KnowledgeItemKind,
+    PersonalProfileAspect,
+    StrictModel,
+)
+
+PersonalGlobalPreferenceTargetScope = Literal[
+    'parent_project',
+    'personal_global',
+]
+
+
+class PersonalGlobalPreferenceSourceRef(StrictModel):
+    item_id: str = Field(min_length=1, max_length=256)
+    item_kind: KnowledgeItemKind
+    project_id: str = Field(min_length=1, max_length=128)
+
+
+class PersonalGlobalPreferenceSourceSnapshot(
+    PersonalGlobalPreferenceSourceRef
+):
+    key: str = Field(min_length=1, max_length=256)
+    preference_key: str = Field(min_length=1, max_length=512)
+    preference_qualifiers: dict[str, Any] = Field(default_factory=dict)
+    title: str = Field(min_length=1, max_length=512)
+    instruction: str = Field(max_length=8192)
+    profile_aspect: PersonalProfileAspect
+    confirmation_status: Literal['confirmed', 'agent_confirmed']
+    confirmation_basis: ConfirmationBasis
+    human_change_version: int = Field(default=0, ge=0)
+    usage_generation: int = Field(default=1, ge=1)
+    last_human_changed_at: datetime | None = None
+    negative_evidence_count: int = Field(default=0, ge=0)
+    requires_attention: bool = False
+    last_feedback_at: datetime | None = None
+    source_uris: list[str] = Field(default_factory=list, max_length=20)
+    stored_confirmation_basis_json: str = Field(
+        default='{}',
+        exclude=True,
+        repr=False,
+    )
+    stored_attributes_json: str = Field(default='{}', exclude=True, repr=False)
+
+
+class PersonalGlobalPreferenceEligibleTargetScope(StrictModel):
+    target_scope: PersonalGlobalPreferenceTargetScope
+    target_project_id: str | None = Field(
+        default=None,
+        min_length=1,
+        max_length=128,
+    )
+    max_distance: int | None = Field(default=None, ge=1, le=2)
+
+    @model_validator(mode='after')
+    def validate_target(self):
+        if self.target_scope == 'parent_project' and not self.target_project_id:
+            raise ValueError('parent_project target requires target_project_id')
+        if self.target_scope == 'personal_global' and self.target_project_id:
+            raise ValueError('personal_global target cannot set target_project_id')
+        return self
+
+
+class PersonalGlobalPreferenceScopeOptionsRequest(StrictModel):
+    personal_space_id: str = Field(min_length=1, max_length=128)
+    source_items: list[PersonalGlobalPreferenceSourceRef] = Field(
+        min_length=2,
+        max_length=32,
+    )
+    preference_key: str = Field(min_length=1, max_length=512)
+
+
+class PersonalGlobalPreferenceScopeOptions(StrictModel):
+    personal_space_id: str
+    candidate_id: str
+    candidate_version: str
+    preference_key: str
+    source_snapshots: list[PersonalGlobalPreferenceSourceSnapshot]
+    eligible_target_scopes: list[PersonalGlobalPreferenceEligibleTargetScope]
+
+
+class PersonalGlobalPreferenceDecisionIntent(StrictModel):
+    personal_space_id: str = Field(min_length=1, max_length=128)
+    candidate_version: str = Field(pattern=r'^v1:[a-f0-9]{24}$')
+    decision_revision: int = Field(ge=0)
+    source_items: list[PersonalGlobalPreferenceSourceRef] = Field(
+        min_length=2,
+        max_length=32,
+    )
+    preference_key: str = Field(min_length=1, max_length=512)
+    target_scope: PersonalGlobalPreferenceTargetScope
+    target_project_id: str | None = Field(
+        min_length=1,
+        max_length=128,
+    )
+    decision: Literal['approve', 'reject']
+    global_title: str | None = Field(default=None, min_length=1, max_length=512)
+    global_instruction: str | None = Field(
+        default=None,
+        min_length=1,
+        max_length=8192,
+    )
+    profile_aspect: PersonalProfileAspect | None = None
+    human_confirmation_reason: str = Field(min_length=1, max_length=4096)
+    confirmed_at: datetime
+    session_id: str = Field(min_length=1, max_length=256)
+    idempotency_key: str = Field(min_length=8, max_length=256)
+
+    @model_validator(mode='after')
+    def validate_decision(self):
+        item_keys = {
+            (item.item_kind, item.item_id)
+            for item in self.source_items
+        }
+        project_ids = {item.project_id for item in self.source_items}
+        if len(item_keys) != len(self.source_items):
+            raise ValueError('source preference items must be unique')
+        if len(project_ids) != len(self.source_items):
+            raise ValueError(
+                'source preferences must come from distinct projects'
+            )
+        if self.target_scope == 'parent_project' and not self.target_project_id:
+            raise ValueError('parent_project target requires target_project_id')
+        if self.target_scope == 'personal_global' and self.target_project_id:
+            raise ValueError('personal_global target cannot set target_project_id')
+        if self.decision == 'approve':
+            if not (
+                self.global_title
+                and self.global_instruction
+                and self.profile_aspect
+            ):
+                raise ValueError(
+                    'approve requires a complete global preference assertion'
+                )
+        elif any((
+            self.global_title,
+            self.global_instruction,
+            self.profile_aspect,
+        )):
+            raise ValueError(
+                'reject cannot include a global preference assertion'
+            )
+        return self
+
+
+class PersonalGlobalPreferenceDecisionApply(
+    PersonalGlobalPreferenceDecisionIntent
+):
+    approval_token: str = Field(min_length=32, max_length=512)
+
+
+class PersonalGlobalPreferenceDecisionInspection(StrictModel):
+    status: Literal['human_review_required']
+    personal_space_id: str
+    candidate_id: str
+    candidate_version: str
+    decision_revision: int = Field(ge=0)
+    decision: Literal['approve', 'reject']
+    preference_key: str
+    target_scope: PersonalGlobalPreferenceTargetScope
+    target_project_id: str | None = None
+    eligible_target_scopes: list[PersonalGlobalPreferenceEligibleTargetScope]
+    payload_fingerprint: str
+    source_snapshots: list[PersonalGlobalPreferenceSourceSnapshot]
+    candidate_binding_verified: bool = True
+    original_sources_will_remain_unchanged: bool = True
+    scope_apply_performed: bool = False
+    approval_token_issued: bool = False
+    required_action: str
+
+
+class PersonalGlobalPreferenceDecisionPreview(StrictModel):
+    preview_id: str
+    candidate_id: str
+    candidate_version: str
+    decision_revision: int = Field(ge=0)
+    target_scope: PersonalGlobalPreferenceTargetScope
+    target_project_id: str | None = None
+    eligible_target_scopes: list[PersonalGlobalPreferenceEligibleTargetScope]
+    payload_fingerprint: str
+    approval_token: str
+    expires_at: datetime
+    source_snapshots: list[PersonalGlobalPreferenceSourceSnapshot]
+    candidate_binding_verified: bool = True
+    original_sources_will_remain_unchanged: bool = True
+    scope_apply_performed: bool = False
+
+
+class PersonalGlobalPreferenceCandidateVersionRef(StrictModel):
+    candidate_id: str = Field(
+        pattern=r'^personal-global-[a-f0-9]{20}$',
+    )
+    candidate_version: str = Field(pattern=r'^v1:[a-f0-9]{24}$')
+
+
+class PersonalGlobalPreferenceDecisionStatusRequest(StrictModel):
+    personal_space_id: str = Field(min_length=1, max_length=128)
+    candidates: list[PersonalGlobalPreferenceCandidateVersionRef] = Field(
+        min_length=1,
+        max_length=100,
+    )
+
+
+class PersonalGlobalPreferenceDecisionRecord(StrictModel):
+    decision_event_id: str
+    candidate_id: str
+    candidate_version: str
+    decision_revision: int = Field(ge=1)
+    decision: Literal['approved', 'rejected']
+    target_scope: PersonalGlobalPreferenceTargetScope
+    target_project_id: str | None = None
+    global_assertion_id: str | None = None
+    global_assertion_active: bool
+    decision_sequence: int = Field(ge=1)
+    decided_at: datetime
+    human_confirmation_reason: str
+
+
+class PersonalGlobalPreferenceDecisionRevision(StrictModel):
+    candidate_id: str
+    decision_revision: int = Field(ge=0)
+    current_candidate_version: str | None = None
+
+
+class PersonalGlobalPreferenceDecisionStatusResult(StrictModel):
+    personal_space_id: str
+    decisions: list[PersonalGlobalPreferenceDecisionRecord]
+    revisions: list[PersonalGlobalPreferenceDecisionRevision]