fuli-context 0.2.0

package/graph-provider/fuli_graph/search_projection.py

@@ -0,0 +1,156 @@
+from graphiti_core.edges import EntityEdge
+
+from .models import (
+    ConfirmationBasis,
+    FactResult,
+    _validate_confirmation_state,
+)
+from .provider_values import json_object, native_datetime as _native_datetime
+
+
+def is_default_retrievable(metadata: dict) -> bool:
+    return effective_confirmation_status(metadata) in {
+        'confirmed',
+        'agent_confirmed',
+    }
+
+
+def effective_confirmation_status(metadata: dict) -> str:
+    status = metadata.get('confirmation_status', 'pending')
+    basis_data = json_object(metadata.get('confirmation_basis_json'))
+    if not basis_data:
+        return 'pending'
+    try:
+        basis = ConfirmationBasis.model_validate(basis_data)
+        _validate_confirmation_state(status, basis)
+    except ValueError:
+        return 'pending'
+    return status
+
+
+async def read_edge_epistemic_metadata(store, edge_ids: list[str]) -> dict[str, dict]:
+    if not edge_ids:
+        return {}
+    records, _, _ = await store.runtime.driver.execute_query(
+        '''
+        MATCH ()-[edge:RELATES_TO]->()
+        WHERE edge.uuid IN $edge_ids
+        RETURN edge.uuid AS id,
+               coalesce(edge.fuli_origin_quadrant, 'known_known') AS origin_quadrant,
+               coalesce(edge.fuli_current_quadrant, 'known_known') AS current_quadrant,
+               coalesce(edge.fuli_epistemic_status, 'confirmed') AS epistemic_status,
+               coalesce(edge.fuli_confirmation_status, 'pending')
+                 AS confirmation_status,
+               edge.fuli_confirmation_basis_json AS confirmation_basis_json,
+               edge.fuli_reasoning_summary AS reasoning_summary,
+               edge.fuli_profile_aspect AS profile_aspect,
+               CASE WHEN edge.fuli_profile_aspect IS NULL THEN NULL
+                    ELSE coalesce(edge.fuli_preference_scope, 'global') END
+                    AS preference_scope,
+               edge.fuli_preference_project_id AS preference_project_id,
+               edge.fuli_key AS key,
+               coalesce(edge.fuli_inheritance_mode, 'local_only')
+                 AS inheritance_mode,
+               coalesce(edge.fuli_inherited_project_ids, [])
+                 AS inherited_project_ids,
+               coalesce(edge.fuli_human_edited, false) AS human_edited,
+               coalesce(edge.fuli_human_change_status, 'none')
+                 AS human_change_status,
+               coalesce(edge.fuli_human_change_version, 0)
+                 AS human_change_version,
+               edge.fuli_last_human_changed_at AS last_human_changed_at,
+               edge.fuli_last_agent_viewed_at AS last_agent_viewed_at,
+               edge.fuli_last_agent_reviewed_at AS last_agent_reviewed_at
+               ,coalesce(edge.fuli_utility_score, 0.0) AS utility_score
+               ,coalesce(edge.fuli_confidence_score, 0.5) AS confidence_score
+               ,coalesce(edge.fuli_qualified_use_count, 0)
+                 AS qualified_use_count
+               ,coalesce(edge.fuli_distinct_task_count, 0)
+                 AS distinct_task_count
+               ,edge.fuli_last_used_at AS last_used_at
+        ''',
+        edge_ids=edge_ids,
+        routing_='r',
+    )
+    result = {}
+    for record in records:
+        value = dict(record)
+        effective_status = effective_confirmation_status(value)
+        if effective_status != value.get('confirmation_status'):
+            value['confidence_score'] = min(
+                float(value.get('confidence_score') or 0.5),
+                0.5,
+            )
+        value['confirmation_status'] = effective_status
+        result[record['id']] = value
+    return result
+
+
+def fact_result(
+    edge: EntityEdge,
+    names: dict[str, str],
+    space_id: str,
+    epistemic: dict | None = None,
+) -> FactResult:
+    metadata = epistemic or {}
+    return FactResult(
+        id=edge.uuid,
+        space_id=space_id,
+        group_id=edge.group_id,
+        source_entity=names.get(edge.source_node_uuid, edge.source_node_uuid),
+        target_entity=names.get(edge.target_node_uuid, edge.target_node_uuid),
+        relationship=edge.name,
+        fact=edge.fact,
+        valid_at=edge.valid_at,
+        invalid_at=edge.invalid_at,
+        created_at=_native_datetime(edge.created_at),
+        episodes=edge.episodes,
+        origin_quadrant=metadata.get('origin_quadrant', 'known_known'),
+        current_quadrant=metadata.get('current_quadrant', 'known_known'),
+        epistemic_status=metadata.get('epistemic_status', 'confirmed'),
+        confirmation_status=metadata.get('confirmation_status', 'pending'),
+        confirmation_basis=_confirmation_basis(
+            metadata.get('confirmation_basis_json')
+        ),
+        reasoning_summary=metadata.get('reasoning_summary'),
+        profile_aspect=metadata.get('profile_aspect'),
+        preference_scope=metadata.get('preference_scope'),
+        preference_project_id=metadata.get('preference_project_id'),
+        key=metadata.get('key'),
+        defined_project_id=metadata.get('defined_project_id'),
+        inheritance_mode=metadata.get('inheritance_mode') or 'local_only',
+        inherited_project_ids=metadata.get('inherited_project_ids') or [],
+        human_edited=metadata.get('human_edited') is True,
+        human_change_status=metadata.get('human_change_status') or 'none',
+        human_change_version=int(metadata.get('human_change_version') or 0),
+        last_human_changed_at=_native_datetime(
+            metadata.get('last_human_changed_at')
+        ),
+        last_agent_viewed_at=_native_datetime(
+            metadata.get('last_agent_viewed_at')
+        ),
+        last_agent_reviewed_at=_native_datetime(
+            metadata.get('last_agent_reviewed_at')
+        ),
+        utility_score=float(metadata.get('utility_score') or 0),
+        confidence_score=float(
+            metadata['confidence_score']
+            if metadata.get('confidence_score') is not None else 0.5
+        ),
+        qualified_use_count=int(metadata.get('qualified_use_count') or 0),
+        distinct_task_count=int(metadata.get('distinct_task_count') or 0),
+        last_used_at=_native_datetime(metadata.get('last_used_at')),
+        scope_distance=int(metadata.get('scope_distance') or 0),
+        inherited_from_project_id=metadata.get('inherited_from_project_id'),
+        scope_path=metadata.get('scope_path') or [],
+    )
+
+
+def _confirmation_basis(value) -> ConfirmationBasis | None:
+    data = json_object(value)
+    if not data:
+        return None
+    try:
+        return ConfirmationBasis.model_validate(data)
+    except ValueError:
+        return None

package/graph-provider/fuli_graph/store.py

@@ -0,0 +1,24 @@
+from .config import Settings
+from .provider_values import graphiti_group_id, native_datetime
+from .runtime import GraphitiRuntime
+from .store_identity import StoreIdentity
+from .store_knowledge import StoreKnowledge
+from .store_projects import StoreProjects
+from .store_publication import StorePublication
+from .store_records import StoreRecords
+
+
+class GraphStore(
+    StoreIdentity,
+    StoreProjects,
+    StorePublication,
+    StoreKnowledge,
+    StoreRecords,
+):
+    def __init__(self, runtime: GraphitiRuntime, settings: Settings):
+        self.runtime = runtime
+        self.settings = settings
+        self._group_locks = {}
+
+
+__all__ = ['GraphStore', 'graphiti_group_id', 'native_datetime']

package/graph-provider/fuli_graph/store_identity.py

@@ -0,0 +1,237 @@
+from uuid import uuid4
+
+from fastapi import HTTPException, status
+
+from .auth import issue_access_token, token_hash
+from .models import PrincipalResult, SpaceCreate, SpaceRecord
+from .project_management import publish_project
+from .provider_values import graphiti_group_id, now_utc
+
+
+ROLE_RANK = {'reader': 1, 'contributor': 2, 'maintainer': 3}
+
+
+class StoreIdentity:
+    async def health(self) -> dict:
+        records, _, _ = await self.runtime.driver.execute_query(
+            'RETURN 1 AS ready', routing_='r'
+        )
+        return {
+            'status': 'ready' if records and records[0]['ready'] == 1 else 'degraded',
+            'providerId': self.settings.provider_id,
+            'mode': self.settings.provider_mode,
+            'storage': 'graphiti-neo4j',
+            'llmExtraction': 'agent-structured',
+            'embedding': 'local-hash-v1',
+            'telemetry': False,
+        }
+
+    async def bootstrap(self, principal_name: str) -> tuple[str, str]:
+        existing, _, _ = await self.runtime.driver.execute_query(
+            '''
+            MATCH (p:FuliPrincipal {provider_admin: true})
+            RETURN p.id AS id ORDER BY p.created_at LIMIT 1
+            ''',
+            routing_='r',
+        )
+        access_token = issue_access_token()
+        if existing:
+            principal_id = existing[0]['id']
+            await self.runtime.driver.execute_query(
+                '''
+                MATCH (p:FuliPrincipal {id: $id, provider_admin: true})
+                SET p.token_hash = $token_hash, p.active = true
+                ''',
+                id=principal_id,
+                token_hash=token_hash(access_token),
+            )
+            return principal_id, access_token
+        principal_id = str(uuid4())
+        await self.runtime.driver.execute_query(
+            '''
+            CREATE (p:FuliPrincipal {
+              id: $id,
+              name: $name,
+              token_hash: $token_hash,
+              active: true,
+              provider_admin: true,
+              created_at: $created_at
+            })
+            ''',
+            id=principal_id,
+            name=principal_name,
+            token_hash=token_hash(access_token),
+            created_at=now_utc(),
+        )
+        return principal_id, access_token
+
+    async def authenticate(self, access_token: str) -> dict:
+        records, _, _ = await self.runtime.driver.execute_query(
+            '''
+            MATCH (p:FuliPrincipal {token_hash: $token_hash, active: true})
+            RETURN p.id AS id, p.name AS name, p.provider_admin AS provider_admin
+            ''',
+            token_hash=token_hash(access_token),
+            routing_='r',
+        )
+        if not records:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail='invalid access token',
+            )
+        return dict(records[0])
+
+    async def create_principal(self, actor: dict, name: str) -> PrincipalResult:
+        if not actor.get('provider_admin'):
+            raise HTTPException(status_code=403, detail='provider administrator required')
+        principal_id = str(uuid4())
+        access_token = issue_access_token()
+        await self.runtime.driver.execute_query(
+            '''
+            CREATE (p:FuliPrincipal {
+              id: $id,
+              name: $name,
+              token_hash: $token_hash,
+              active: true,
+              provider_admin: false,
+              created_at: $created_at
+            })
+            ''',
+            id=principal_id,
+            name=name,
+            token_hash=token_hash(access_token),
+            created_at=now_utc(),
+        )
+        return PrincipalResult(principal_id=principal_id, access_token=access_token)
+
+    async def create_space(self, actor: dict, request: SpaceCreate) -> SpaceRecord:
+        expected_kind = 'personal' if self.settings.provider_mode == 'personal' else 'project'
+        if request.kind != expected_kind:
+            raise HTTPException(
+                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+                detail=f'{self.settings.provider_mode} provider only accepts {expected_kind} spaces',
+            )
+        if request.kind == 'project' and request.profile:
+            if any(source.sensitivity != 'normal' for source in request.profile.sources):
+                raise HTTPException(
+                    status_code=422,
+                    detail='private or restricted project sources cannot be published',
+                )
+        if request.kind == 'project':
+            return await publish_project(self, actor, request)
+        space_id = str(uuid4())
+        group_id = graphiti_group_id(self.settings.provider_id, request.kind, space_id)
+        created_at = now_utc()
+        visibility = 'private' if request.kind == 'personal' else 'public'
+        query = '''
+        MATCH (p:FuliPrincipal {id: $principal_id})
+        CREATE (s:FuliSpace {
+          id: $id,
+          name: $name,
+          kind: $kind,
+          group_id: $group_id,
+          description: $description,
+          visibility: $visibility,
+          publication_key: $publication_key,
+          profile_json: $profile_json,
+          created_at: $created_at
+        })
+        CREATE (p)-[:OWNS {created_at: $created_at}]->(s)
+        RETURN s
+        '''
+        records, _, _ = await self.runtime.driver.execute_query(
+            query,
+            principal_id=actor['id'],
+            id=space_id,
+            name=request.name,
+            kind=request.kind,
+            group_id=group_id,
+            description=request.description,
+            visibility=visibility,
+            publication_key=request.publication_key,
+            profile_json=request.profile.model_dump_json() if request.profile else None,
+            created_at=created_at,
+        )
+        return self._space(
+            records[0]['s'],
+            owner_id=actor['id'],
+            role='maintainer',
+        )
+
+    async def list_spaces(self, actor: dict) -> list[SpaceRecord]:
+        if self.settings.provider_mode == 'personal':
+            query = '''
+            MATCH (p:FuliPrincipal {id: $principal_id})-[:OWNS]->
+                  (s:FuliSpace {kind: 'personal'})
+            RETURN s, p.id AS owner_id, 'maintainer' AS role
+            ORDER BY s.created_at
+            '''
+        else:
+            query = '''
+            MATCH (s:FuliSpace {kind: 'project', visibility: 'public'})
+            MATCH (owner:FuliPrincipal)-[:OWNS]->(s)
+            OPTIONAL MATCH (actor:FuliPrincipal {id: $principal_id})-
+                           [membership:MEMBER_OF]->(s)
+            RETURN s, owner.id AS owner_id,
+                   coalesce(membership.role, 'reader') AS role
+            ORDER BY s.created_at
+            '''
+        records, _, _ = await self.runtime.driver.execute_query(
+            query,
+            principal_id=actor['id'],
+            routing_='r',
+        )
+        return [
+            self._space(
+                record['s'],
+                owner_id=record['owner_id'],
+                role=record['role'],
+                can_manage=(
+                    bool(actor.get('provider_admin')) or record['owner_id'] == actor['id']
+                ),
+            )
+            for record in records
+        ]
+
+    async def authorize(self, actor: dict, space_id: str, required_role: str) -> dict:
+        if self.settings.provider_mode == 'personal':
+            records, _, _ = await self.runtime.driver.execute_query(
+                '''
+                MATCH (principal:FuliPrincipal {id: $principal_id})-[:OWNS]->
+                      (space:FuliSpace {id: $space_id, kind: 'personal'})
+                RETURN space, 'maintainer' AS role
+                ''',
+                principal_id=actor['id'],
+                space_id=space_id,
+                routing_='r',
+            )
+        else:
+            records, _, _ = await self.runtime.driver.execute_query(
+                '''
+                MATCH (space:FuliSpace {
+                  id: $space_id,
+                  kind: 'project',
+                  visibility: 'public'
+                })
+                OPTIONAL MATCH (principal:FuliPrincipal {id: $principal_id})-
+                               [membership:MEMBER_OF]->(space)
+                RETURN space, coalesce(membership.role, 'reader') AS role
+                ''',
+                principal_id=actor['id'],
+                space_id=space_id,
+                routing_='r',
+            )
+        if not records:
+            raise HTTPException(status_code=403, detail='space access denied')
+        role = records[0]['role']
+        if ROLE_RANK.get(role, 0) < ROLE_RANK[required_role]:
+            raise HTTPException(status_code=403, detail=f'{required_role} role required')
+        return dict(records[0]['space'])
+
+    def _require_personal(self) -> None:
+        if self.settings.provider_mode != 'personal':
+            raise HTTPException(status_code=404, detail='personal provider endpoint')
+
+    def _require_workspace(self) -> None:
+        if self.settings.provider_mode != 'workspace':
+            raise HTTPException(status_code=404, detail='workspace provider endpoint')