DataOps-platform/app/core/knowledge/contracts.py

from __future__ import annotations

from collections.abc import Mapping
from dataclasses import dataclass, field
from typing import Any


@dataclass(frozen=True)
class KnowledgePointDraft:
    point_key: str
    semantic_path: str
    content: str
    content_hash: str
    metadata: Mapping[str, Any]
    metadata_hash: str
    permission_scope: Mapping[str, Any]
    permission_hash: str


@dataclass(frozen=True)
class KnowledgeDependencyDraft:
    from_point_key: str
    to_point_key: str
    relation_type: str
    source: str


@dataclass(frozen=True)
class KnowledgeSnapshot:
    source_type: str
    source_uid: str
    source_revision: int
    source_snapshot_hash: str
    point_set_hash: str
    permission_scope: Mapping[str, Any]
    points: tuple[KnowledgePointDraft, ...]
    dependencies: tuple[KnowledgeDependencyDraft, ...] = ()
    source_updated_at: str | None = None


@dataclass(frozen=True)
class PointChange:
    point_key: str
    change_kind: str
    old: KnowledgePointDraft | None = None
    new: KnowledgePointDraft | None = None
    permission_changed: bool = False


@dataclass(frozen=True)
class SnapshotDiff:
    added: tuple[PointChange, ...] = ()
    modified: tuple[PointChange, ...] = ()
    deleted: tuple[PointChange, ...] = ()
    unchanged: tuple[PointChange, ...] = ()

    @property
    def changed_point_keys(self) -> frozenset[str]:
        return frozenset(
            change.point_key
            for group in (self.added, self.modified, self.deleted)
            for change in group
        )


@dataclass(frozen=True)
class ImpactResult:
    impacted_point_keys: frozenset[str]
    paths: Mapping[str, tuple[str, ...]] = field(default_factory=dict)
    truncated: bool = False


@dataclass(frozen=True)
class KnowledgeChunkDraft:
    chunk_key: str
    chunk_kind: str
    section_path: str
    content: str
    content_hash: str
    lexical_text: str
    primary_point_key: str
    point_keys: tuple[str, ...]
    point_set_hash: str
    metadata: Mapping[str, Any]


@dataclass(frozen=True)
class PreparedPublication:
    snapshot: KnowledgeSnapshot
    diff: SnapshotDiff
    chunks: tuple[KnowledgeChunkDraft, ...]
    embeddings: Mapping[str, tuple[float, ...]]
    status: str


@dataclass(frozen=True)
class SyncResult:
    status: str
    source_type: str
    source_uid: str
    source_revision: int
    diff_counts: Mapping[str, int]
    embedded_chunk_count: int
    reused_embedding_count: int