fuli-context 0.2.0

package/graph-provider/fuli_graph/project_management.py

@@ -0,0 +1,251 @@
+from uuid import uuid4
+
+from fastapi import HTTPException
+
+from .models import (
+    ProjectDeleteResult,
+    ProjectReleaseRecord,
+    SpaceCreate,
+    SpaceRecord,
+)
+from .provider_values import graphiti_group_id, now_utc, stable_uuid
+
+
+async def publish_project(store, actor: dict, request: SpaceCreate) -> SpaceRecord:
+    existing = await _owned_publication(store, actor, request.publication_key)
+    if existing:
+        if request.release is None:
+            return store._space(
+                existing,
+                owner_id=actor['id'],
+                role='maintainer',
+                can_manage=True,
+            )
+        return await _update_project(store, actor, existing, request)
+    return await _create_project(store, actor, request)
+
+
+async def list_project_releases(
+    store,
+    actor: dict,
+    project_id: str,
+) -> list[ProjectReleaseRecord]:
+    await store.authorize(actor, project_id, 'reader')
+    records, _, _ = await store.runtime.driver.execute_query(
+        '''
+        MATCH (:FuliSpace {id: $project_id, kind: 'project'})-
+              [:HAS_RELEASE]->(release:FuliProjectRelease)
+        RETURN release ORDER BY release.published_at DESC
+        ''',
+        project_id=project_id,
+        routing_='r',
+    )
+    return [store._project_release(record['release']) for record in records]
+
+
+async def delete_project(store, actor: dict, project_id: str) -> ProjectDeleteResult:
+    store._require_workspace()
+    records, _, _ = await store.runtime.driver.execute_query(
+        '''
+        MATCH (space:FuliSpace {
+          id: $project_id,
+          kind: 'project',
+          visibility: 'public'
+        })
+        MATCH (owner:FuliPrincipal)-[:OWNS]->(space)
+        WHERE owner.id = $principal_id OR $provider_admin = true
+        RETURN space.name AS name, space.group_id AS group_id
+        ''',
+        project_id=project_id,
+        principal_id=actor['id'],
+        provider_admin=bool(actor.get('provider_admin')),
+        routing_='r',
+    )
+    if not records:
+        raise HTTPException(status_code=403, detail='project owner or provider administrator required')
+
+    project = records[0]
+    await store.runtime.driver.execute_query(
+        '''
+        MATCH (space:FuliSpace {id: $project_id, kind: 'project'})
+        OPTIONAL MATCH (artifact)
+        WHERE artifact <> space AND (
+          artifact.group_id = $group_id OR
+          (artifact.project_id = $project_id AND
+           (artifact:FuliProjectRelease OR artifact:FuliProposal))
+        )
+        WITH space, collect(DISTINCT artifact) AS artifacts
+        FOREACH (artifact IN artifacts | DETACH DELETE artifact)
+        DETACH DELETE space
+        ''',
+        project_id=project_id,
+        group_id=project['group_id'],
+    )
+    return ProjectDeleteResult(
+        project_id=project_id,
+        project_name=project['name'],
+        deleted=True,
+    )
+
+
+async def _owned_publication(store, actor: dict, publication_key: str | None):
+    if not publication_key:
+        return None
+    records, _, _ = await store.runtime.driver.execute_query(
+        '''
+        MATCH (p:FuliPrincipal {id: $principal_id})-[:OWNS]->
+              (s:FuliSpace {
+                kind: 'project',
+                publication_key: $publication_key
+              })
+        RETURN s
+        ''',
+        principal_id=actor['id'],
+        publication_key=publication_key,
+        routing_='r',
+    )
+    return records[0]['s'] if records else None
+
+
+async def _update_project(store, actor: dict, existing, request: SpaceCreate) -> SpaceRecord:
+    project_id = existing['id']
+    release = request.release
+    duplicate, _, _ = await store.runtime.driver.execute_query(
+        '''
+        MATCH (:FuliSpace {id: $project_id})-[:HAS_RELEASE]->
+              (release:FuliProjectRelease {version: $version})
+        RETURN release.id AS id
+        ''',
+        project_id=project_id,
+        version=release.version,
+        routing_='r',
+    )
+    if duplicate:
+        raise HTTPException(status_code=409, detail='project release version already exists')
+
+    published_at = now_utc()
+    release_id = stable_uuid(project_id, 'release', release.version)
+    records, _, _ = await store.runtime.driver.execute_query(
+        '''
+        MATCH (owner:FuliPrincipal {id: $principal_id})-[:OWNS]->
+              (space:FuliSpace {id: $project_id, kind: 'project'})
+        SET space.name = $name,
+            space.description = $description,
+            space.profile_json = $profile_json,
+            space.release_version = $version,
+            space.release_id = $release_id,
+            space.release_summary = $summary,
+            space.release_publisher_id = $principal_id,
+            space.release_publisher_name = $publisher_name,
+            space.released_at = $published_at,
+            space.updated_at = $published_at
+        CREATE (release:FuliProjectRelease {
+          id: $release_id,
+          project_id: $project_id,
+          version: $version,
+          summary: $summary,
+          publisher_id: $principal_id,
+          publisher_name: $publisher_name,
+          published_at: $published_at
+        })
+        CREATE (space)-[:HAS_RELEASE]->(release)
+        RETURN space
+        ''',
+        principal_id=actor['id'],
+        publisher_name=actor.get('name') or actor['id'],
+        project_id=project_id,
+        name=request.name,
+        description=request.description,
+        profile_json=request.profile.model_dump_json() if request.profile else None,
+        release_id=release_id,
+        version=release.version,
+        summary=release.summary,
+        published_at=published_at,
+    )
+    return store._space(
+        records[0]['space'],
+        owner_id=actor['id'],
+        role='maintainer',
+        can_manage=True,
+    )
+
+
+async def _create_project(store, actor: dict, request: SpaceCreate) -> SpaceRecord:
+    space_id = str(uuid4())
+    group_id = graphiti_group_id(store.settings.provider_id, request.kind, space_id)
+    created_at = now_utc()
+    release = request.release
+    if release:
+        query = '''
+        MATCH (principal:FuliPrincipal {id: $principal_id})
+        CREATE (space:FuliSpace {
+          id: $id,
+          name: $name,
+          kind: 'project',
+          group_id: $group_id,
+          description: $description,
+          visibility: 'public',
+          publication_key: $publication_key,
+          profile_json: $profile_json,
+          release_version: $version,
+          release_id: $release_id,
+          release_summary: $summary,
+          release_publisher_id: $principal_id,
+          release_publisher_name: $publisher_name,
+          released_at: $created_at,
+          updated_at: $created_at,
+          created_at: $created_at
+        })
+        CREATE (principal)-[:OWNS {created_at: $created_at}]->(space)
+        CREATE (principal)-[:MEMBER_OF {role: 'maintainer', created_at: $created_at}]->(space)
+        CREATE (releaseNode:FuliProjectRelease {
+          id: $release_id,
+          project_id: $id,
+          version: $version,
+          summary: $summary,
+          publisher_id: $principal_id,
+          publisher_name: $publisher_name,
+          published_at: $created_at
+        })
+        CREATE (space)-[:HAS_RELEASE]->(releaseNode)
+        RETURN space
+        '''
+    else:
+        query = '''
+        MATCH (principal:FuliPrincipal {id: $principal_id})
+        CREATE (space:FuliSpace {
+          id: $id,
+          name: $name,
+          kind: 'project',
+          group_id: $group_id,
+          description: $description,
+          visibility: 'public',
+          publication_key: $publication_key,
+          profile_json: $profile_json,
+          created_at: $created_at
+        })
+        CREATE (principal)-[:OWNS {created_at: $created_at}]->(space)
+        CREATE (principal)-[:MEMBER_OF {role: 'maintainer', created_at: $created_at}]->(space)
+        RETURN space
+        '''
+    parameters = {
+        'principal_id': actor['id'],
+        'publisher_name': actor.get('name') or actor['id'],
+        'id': space_id,
+        'name': request.name,
+        'group_id': group_id,
+        'description': request.description,
+        'publication_key': request.publication_key,
+        'profile_json': request.profile.model_dump_json() if request.profile else None,
+        'created_at': created_at,
+        'release_id': stable_uuid(space_id, 'release', release.version) if release else None,
+        'version': release.version if release else None,
+        'summary': release.summary if release else None,
+    }
+    records, _, _ = await store.runtime.driver.execute_query(query, **parameters)
+    return store._space(
+        records[0]['space'],
+        owner_id=actor['id'],
+        role='maintainer',
+        can_manage=True,
+    )

package/graph-provider/fuli_graph/provider_values.py

@@ -0,0 +1,40 @@
+import json
+import re
+from datetime import datetime, timezone
+from uuid import NAMESPACE_URL, uuid5
+
+
+def now_utc() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def stable_uuid(*parts: str) -> str:
+    return str(uuid5(NAMESPACE_URL, ':'.join(parts)))
+
+
+def graphiti_group_id(provider_id: str, kind: str, space_id: str) -> str:
+    value = f'{provider_id}-{kind}-{space_id}'
+    return re.sub(r'[^A-Za-z0-9_-]', '_', value)
+
+
+def native_datetime(value):
+    if value is None or isinstance(value, datetime):
+        return value
+    to_native = getattr(value, 'to_native', None)
+    return to_native() if callable(to_native) else value
+
+
+def json_object(value) -> dict:
+    if not value:
+        return {}
+    if isinstance(value, dict):
+        return value
+    try:
+        parsed = json.loads(value)
+    except (TypeError, ValueError):
+        return {}
+    return parsed if isinstance(parsed, dict) else {}
+
+
+def normalized_text(value) -> str:
+    return ' '.join(str(value or '').strip().casefold().split())

package/graph-provider/fuli_graph/runtime.py

@@ -0,0 +1,350 @@
+import hashlib
+import math
+import os
+import re
+import unicodedata
+from collections.abc import Iterable
+from typing import Any
+
+os.environ.setdefault('GRAPHITI_TELEMETRY_ENABLED', 'false')
+
+from graphiti_core import Graphiti
+from graphiti_core.cross_encoder.client import CrossEncoderClient
+from graphiti_core.driver.neo4j_driver import Neo4jDriver
+from graphiti_core.embedder.client import EmbedderClient
+from graphiti_core.llm_client.client import LLMClient
+from graphiti_core.llm_client.config import LLMConfig, ModelSize
+from graphiti_core.prompts.models import Message
+from pydantic import BaseModel
+
+from .config import Settings
+
+
+class AgentStructuredLLM(LLMClient):
+    """Guardrail that prevents the provider from sending knowledge to another LLM."""
+
+    def __init__(self):
+        super().__init__(
+            LLMConfig(
+                api_key='disabled',
+                model='agent-structured-input',
+                small_model='agent-structured-input',
+                max_tokens=1,
+            )
+        )
+
+    async def _generate_response(
+        self,
+        messages: list[Message],
+        response_model: type[BaseModel] | None = None,
+        max_tokens: int = 1,
+        model_size: ModelSize = ModelSize.medium,
+    ) -> dict[str, Any]:
+        del messages, response_model, max_tokens, model_size
+        raise RuntimeError(
+            'This Fuli provider accepts agent-structured graph input and never invokes a second LLM'
+        )
+
+
+class LocalHashEmbedder(EmbedderClient):
+    """Small deterministic multilingual embedder with no model or network dependency."""
+
+    def __init__(self, dimensions: int):
+        if dimensions < 64:
+            raise ValueError('Local hash embeddings require at least 64 dimensions')
+        self.dimensions = dimensions
+
+    async def create(
+        self,
+        input_data: str | list[str] | Iterable[int] | Iterable[Iterable[int]],
+    ) -> list[float]:
+        text = input_data if isinstance(input_data, str) else ' '.join(map(str, input_data))
+        return self._embed(text)
+
+    async def create_batch(self, input_data_list: list[str]) -> list[list[float]]:
+        return [self._embed(value) for value in input_data_list]
+
+    def _embed(self, value: str) -> list[float]:
+        normalized = unicodedata.normalize('NFKC', value).casefold()
+        compact = ''.join(character for character in normalized if not character.isspace())
+        features = re.findall(r'[\w.-]+', normalized, flags=re.UNICODE)
+        features.extend(compact[index : index + 2] for index in range(max(len(compact) - 1, 0)))
+        features.extend(compact[index : index + 3] for index in range(max(len(compact) - 2, 0)))
+        vector = [0.0] * self.dimensions
+        for feature in features:
+            if not feature:
+                continue
+            digest = hashlib.blake2b(
+                feature.encode('utf-8'),
+                digest_size=8,
+                person=b'fuli-embed-v1',
+            ).digest()
+            bucket = int.from_bytes(digest[:4], 'big') % self.dimensions
+            vector[bucket] += 1.0 if digest[4] & 1 else -1.0
+        magnitude = math.sqrt(sum(value * value for value in vector))
+        return vector if magnitude == 0 else [value / magnitude for value in vector]
+
+
+class LocalLexicalReranker(CrossEncoderClient):
+    async def rank(self, query: str, passages: list[str]) -> list[tuple[str, float]]:
+        query_terms = set(query.casefold().split())
+
+        def score(passage: str) -> float:
+            normalized = passage.casefold()
+            if query.casefold() in normalized:
+                return 1.0
+            if not query_terms:
+                return 0.0
+            matches = sum(term in normalized for term in query_terms)
+            return matches / len(query_terms)
+
+        return sorted(
+            [(passage, score(passage)) for passage in passages],
+            key=lambda item: item[1],
+            reverse=True,
+        )
+
+
+class GraphitiRuntime:
+    def __init__(self, settings: Settings):
+        self.settings = settings
+        self.embedder = LocalHashEmbedder(settings.embedding_dim)
+        driver = Neo4jDriver(
+            uri=settings.neo4j_uri,
+            user=settings.neo4j_user,
+            password=settings.neo4j_password,
+            database=settings.neo4j_database,
+        )
+        self.graphiti = Graphiti(
+            graph_driver=driver,
+            llm_client=AgentStructuredLLM(),
+            embedder=self.embedder,
+            cross_encoder=LocalLexicalReranker(),
+            store_raw_episode_content=False,
+        )
+
+    @property
+    def driver(self):
+        return self.graphiti.driver
+
+    async def initialize(self) -> None:
+        await self.graphiti.build_indices_and_constraints()
+        await self.driver.execute_query(
+            'CREATE CONSTRAINT fuli_principal_id IF NOT EXISTS '
+            'FOR (n:FuliPrincipal) REQUIRE n.id IS UNIQUE'
+        )
+        await self.driver.execute_query(
+            'CREATE CONSTRAINT fuli_space_id IF NOT EXISTS '
+            'FOR (n:FuliSpace) REQUIRE n.id IS UNIQUE'
+        )
+        await self.driver.execute_query(
+            'CREATE CONSTRAINT fuli_subscription_id IF NOT EXISTS '
+            'FOR (n:FuliSubscription) REQUIRE n.id IS UNIQUE'
+        )
+        await self.driver.execute_query(
+            'CREATE CONSTRAINT fuli_proposal_id IF NOT EXISTS '
+            'FOR (n:FuliProposal) REQUIRE n.id IS UNIQUE'
+        )
+        await self.driver.execute_query(
+            'CREATE CONSTRAINT fuli_personal_project_id IF NOT EXISTS '
+            'FOR (n:FuliPersonalProject) REQUIRE n.id IS UNIQUE'
+        )
+        await self.driver.execute_query(
+            'CREATE CONSTRAINT fuli_publication_draft_id IF NOT EXISTS '
+            'FOR (n:FuliPublicationDraft) REQUIRE n.id IS UNIQUE'
+        )
+        await self.driver.execute_query(
+            'CREATE CONSTRAINT fuli_project_release_id IF NOT EXISTS '
+            'FOR (n:FuliProjectRelease) REQUIRE n.id IS UNIQUE'
+        )
+        await self.driver.execute_query(
+            'CREATE CONSTRAINT fuli_knowledge_reference_id IF NOT EXISTS '
+            'FOR (n:FuliKnowledgeProjectReference) REQUIRE n.id IS UNIQUE'
+        )
+        await self.driver.execute_query(
+            'CREATE CONSTRAINT fuli_knowledge_conflict_id IF NOT EXISTS '
+            'FOR (n:FuliKnowledgeConflict) REQUIRE n.id IS UNIQUE'
+        )
+        await self.driver.execute_query(
+            'CREATE CONSTRAINT fuli_knowledge_audit_id IF NOT EXISTS '
+            'FOR (n:FuliKnowledgeAudit) 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)',
+            'CREATE INDEX fuli_entity_usage_score IF NOT EXISTS '
+            'FOR (n:Entity) ON (n.group_id, n.fuli_utility_score)',
+            'CREATE INDEX fuli_relationship_confirmation IF NOT EXISTS '
+            'FOR ()-[r:RELATES_TO]-() '
+            'ON (r.group_id, r.fuli_confirmation_status)',
+            'CREATE INDEX fuli_relationship_usage_score IF NOT EXISTS '
+            'FOR ()-[r:RELATES_TO]-() ON (r.group_id, r.fuli_utility_score)',
+            'CREATE INDEX fuli_knowledge_assignment_lookup IF NOT EXISTS '
+            'FOR (n:FuliKnowledgeAssignment) '
+            'ON (n.space_id, n.item_kind, n.item_id)',
+            'CREATE INDEX fuli_knowledge_reference_lookup IF NOT EXISTS '
+            'FOR (n:FuliKnowledgeProjectReference) '
+            'ON (n.space_id, n.item_kind, n.item_id)',
+            '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_personal_project_relation_type IF NOT EXISTS '
+            'FOR ()-[r:PERSONAL_PROJECT_RELATION]-() ON (r.relation_type)',
+        ):
+            await self.driver.execute_query(query)
+        await self._migrate_knowledge_lifecycle_defaults()
+        await self._migrate_space_visibility_and_owners()
+        await self._migrate_project_releases()
+        await self._migrate_legacy_group_ids()
+
+    async def _migrate_space_visibility_and_owners(self) -> None:
+        await self.driver.execute_query(
+            "MATCH (s:FuliSpace) WHERE s.visibility IS NULL "
+            "SET s.visibility = CASE s.kind WHEN 'project' THEN 'public' ELSE 'private' END"
+        )
+        records, _, _ = await self.driver.execute_query(
+            '''
+            MATCH (space:FuliSpace {kind: 'project'})
+            WHERE NOT EXISTS {
+              MATCH (:FuliPrincipal)-[:OWNS]->(space)
+            }
+            OPTIONAL MATCH (principal:FuliPrincipal)-[membership:MEMBER_OF]->(space)
+            WHERE membership.role = 'maintainer'
+            WITH space, principal, membership
+            ORDER BY coalesce(membership.created_at, space.created_at)
+            RETURN space.id AS space_id, head(collect(principal.id)) AS owner_id
+            ''',
+            routing_='r',
+        )
+        for record in records:
+            if not record['owner_id']:
+                continue
+            await self.driver.execute_query(
+                '''
+                MATCH (principal:FuliPrincipal {id: $owner_id})
+                MATCH (space:FuliSpace {id: $space_id})
+                MERGE (principal)-[:OWNS]->(space)
+                ''',
+                owner_id=record['owner_id'],
+                space_id=record['space_id'],
+            )
+
+    async def _migrate_project_releases(self) -> None:
+        await self.driver.execute_query(
+            '''
+            MATCH (owner:FuliPrincipal)-[:OWNS]->
+                  (space:FuliSpace {kind: 'project', visibility: 'public'})
+            WHERE space.release_version IS NULL
+            WITH owner, space, 'legacy-release-' + space.id AS release_id
+            SET space.release_version = 'legacy',
+                space.release_id = release_id,
+                space.release_summary = '历史项目迁移，原始版本与更新内容未记录',
+                space.release_publisher_id = owner.id,
+                space.release_publisher_name = owner.name,
+                space.released_at = space.created_at,
+                space.updated_at = coalesce(space.updated_at, space.created_at)
+            MERGE (release:FuliProjectRelease {id: release_id})
+            ON CREATE SET release.project_id = space.id,
+                          release.version = 'legacy',
+                          release.summary = '历史项目迁移，原始版本与更新内容未记录',
+                          release.publisher_id = owner.id,
+                          release.publisher_name = owner.name,
+                          release.published_at = space.created_at
+            MERGE (space)-[:HAS_RELEASE]->(release)
+            '''
+        )
+
+    async def _migrate_legacy_group_ids(self) -> None:
+        records, _, _ = await self.driver.execute_query(
+            "MATCH (s:FuliSpace) WHERE s.group_id CONTAINS ':' "
+            'RETURN s.id AS id, s.group_id AS group_id',
+            routing_='r',
+        )
+        for record in records:
+            previous = record['group_id']
+            current = previous.replace(':', '-')
+            async with self.driver.transaction() as transaction:
+                await transaction.run(
+                    'MATCH (s:FuliSpace {id: $space_id}) SET s.group_id = $current',
+                    space_id=record['id'],
+                    current=current,
+                )
+                await transaction.run(
+                    'MATCH (n) WHERE n.group_id = $previous SET n.group_id = $current',
+                    previous=previous,
+                    current=current,
+                )
+                await transaction.run(
+                    'MATCH ()-[r]->() WHERE r.group_id = $previous SET r.group_id = $current',
+                    previous=previous,
+                    current=current,
+                )
+
+    async def _migrate_knowledge_lifecycle_defaults(self) -> None:
+        await self.driver.execute_query(
+            '''
+            MATCH (item:Entity)
+            WHERE item.fuli_utility_score IS NULL
+               OR item.fuli_confidence_score IS NULL
+               OR item.fuli_qualified_use_count IS NULL
+               OR item.fuli_distinct_task_count IS NULL
+               OR item.fuli_usage_generation IS NULL
+               OR item.fuli_inheritance_mode IS NULL
+               OR item.fuli_inherited_project_ids IS NULL
+            SET item.fuli_utility_score =
+                  coalesce(item.fuli_utility_score, 0.0),
+                item.fuli_confidence_score = coalesce(
+                  item.fuli_confidence_score,
+                  CASE coalesce(item.fuli_confirmation_status, 'pending')
+                    WHEN 'confirmed' THEN 1.0
+                    WHEN 'agent_confirmed' THEN 0.75
+                    ELSE 0.5
+                  END
+                ),
+                item.fuli_qualified_use_count =
+                  coalesce(item.fuli_qualified_use_count, 0),
+                item.fuli_distinct_task_count =
+                  coalesce(item.fuli_distinct_task_count, 0),
+                item.fuli_usage_generation =
+                  coalesce(item.fuli_usage_generation, 1),
+                item.fuli_inheritance_mode =
+                  coalesce(item.fuli_inheritance_mode, 'local_only'),
+                item.fuli_inherited_project_ids =
+                  coalesce(item.fuli_inherited_project_ids, [])
+            '''
+        )
+        await self.driver.execute_query(
+            '''
+            MATCH ()-[item:RELATES_TO]->()
+            WHERE item.fuli_utility_score IS NULL
+               OR item.fuli_confidence_score IS NULL
+               OR item.fuli_qualified_use_count IS NULL
+               OR item.fuli_distinct_task_count IS NULL
+               OR item.fuli_usage_generation IS NULL
+               OR item.fuli_inheritance_mode IS NULL
+               OR item.fuli_inherited_project_ids IS NULL
+            SET item.fuli_utility_score =
+                  coalesce(item.fuli_utility_score, 0.0),
+                item.fuli_confidence_score = coalesce(
+                  item.fuli_confidence_score,
+                  CASE coalesce(item.fuli_confirmation_status, 'pending')
+                    WHEN 'confirmed' THEN 1.0
+                    WHEN 'agent_confirmed' THEN 0.75
+                    ELSE 0.5
+                  END
+                ),
+                item.fuli_qualified_use_count =
+                  coalesce(item.fuli_qualified_use_count, 0),
+                item.fuli_distinct_task_count =
+                  coalesce(item.fuli_distinct_task_count, 0),
+                item.fuli_usage_generation =
+                  coalesce(item.fuli_usage_generation, 1),
+                item.fuli_inheritance_mode =
+                  coalesce(item.fuli_inheritance_mode, 'local_only'),
+                item.fuli_inherited_project_ids =
+                  coalesce(item.fuli_inherited_project_ids, [])
+            '''
+        )
+
+    async def close(self) -> None:
+        await self.graphiti.close()