kompas-kernel 0.0.1__py3-none-any.whl

kompas_kernel/features/document_session/commands.py

@@ -0,0 +1,94 @@
+"""Framework-free public document-state commands for document session, over `KompasSession`.
+
+No Pydantic AI, no `kompas_copilot.bridge` import — raw checkpoint/restore KsAPI calls
+live in `ksapi/snapshot.py`; this module wires them through session callbacks and owns
+the digest-before/after honesty check shared by both operations.
+
+CQS: both commands here mutate DOCUMENT state (`checkpoint` saves the active document
+to disk, `restore` closes/overwrites/reopens it) — unlike `queries.screenshot_window`,
+which only reads the current view. Neither knows about the session workspace or the
+checkpoint registry; that's `service.CheckpointService`'s job (multi-step orchestration).
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from pathlib import Path
+from uuid import uuid4
+
+from kompas_kernel.features.document_session.digest import build_digest, digest_changed
+from kompas_kernel.features.document_session.ksapi import context_reader, snapshot
+from kompas_kernel.features.document_session.models import Checkpoint, GeoDigest, RestoreResult
+from kompas_kernel.kompas.session import KompasContext, KompasSession
+from kompas_kernel.observability.logger import get_logger
+from kompas_kernel.observability.taxonomy import LogDomain, LogEventType, event_name
+
+logger = get_logger(__name__)
+
+
+async def checkpoint(session: KompasSession, *, checkpoint_dir: Path, untitled_document_dir: Path) -> Checkpoint:
+    """Снять снимок активного 3D-документа; безымянный сперва сохранить в рабочую область.
+
+    Оба каталога приходят снаружи (`service.CheckpointService` резолвит их от корня
+    сессии) — этот модуль не знает ни про рабочую область, ни про `session_id`.
+    """
+
+    def _operation(context: KompasContext) -> Checkpoint:
+        checkpoint_id = uuid4().hex
+        digest = build_digest(context_reader.read_active_topology(context.modules, context.app))
+        saved = snapshot.save_snapshot(
+            context.modules,
+            context.app,
+            checkpoint_dir=checkpoint_dir,
+            checkpoint_id=checkpoint_id,
+            untitled_document_dir=untitled_document_dir,
+        )
+        logger.info(
+            event_name(LogDomain.BRIDGE, "ksapi_checkpoint", LogEventType.COMPLETED),
+            checkpoint_id=checkpoint_id,
+            path=str(saved.checkpoint_path),
+            saved_untitled_document=saved.saved_untitled_document,
+        )
+        return Checkpoint(
+            checkpoint_id=checkpoint_id,
+            path=saved.checkpoint_path,
+            document_path=saved.document_path,
+            digest=digest,
+            created_at=datetime.now(UTC),
+            saved_untitled_document=saved.saved_untitled_document,
+        )
+
+    return await session.run(operation_name="document_session.checkpoint", operation=_operation)
+
+
+async def restore(session: KompasSession, target: Checkpoint) -> RestoreResult:
+    """Откатить документ к переданному снимку — дайджест снимка берётся из `target`."""
+
+    def _operation(context: KompasContext) -> RestoreResult:
+        digest_before: GeoDigest | None
+        try:
+            digest_before = build_digest(context_reader.read_active_topology(context.modules, context.app))
+        except Exception as exc:  # KsAPI can refuse reads precisely when rollback is required.
+            digest_before = None
+            logger.warning(
+                event_name(LogDomain.BRIDGE, "ksapi_restore_pre_digest", LogEventType.FAILED),
+                checkpoint_id=target.checkpoint_id,
+                error=str(exc),
+            )
+        snapshot.restore_snapshot(context.modules, context.app, target)
+        digest_after = build_digest(context_reader.read_active_topology(context.modules, context.app))
+        logger.info(
+            event_name(LogDomain.BRIDGE, "ksapi_restore", LogEventType.COMPLETED),
+            checkpoint_id=target.checkpoint_id,
+            document_path=target.document_path,
+        )
+        return RestoreResult(
+            ok=True,
+            restored_from=target.path,
+            document_path=target.document_path,
+            digest_before=digest_before,
+            digest_after=digest_after,
+            matches_checkpoint=not digest_changed(target.digest, digest_after),
+        )
+
+    return await session.run(operation_name="document_session.restore", operation=_operation)

kompas_kernel/features/document_session/digest.py

@@ -0,0 +1,126 @@
+"""Сборка геометрического дайджеста — чистое ядро, отделённое от CAD runtime.
+
+Здесь нет KsAPI runtime-объектов: чтение сырой топологии живёт в `ksapi/context_reader.py`,
+а сюда приходит уже через структурный `TopologyReader` или готовый `RawTopology`. Так
+нормализация единиц, форма дайджеста и логика "изменилось/нет" тестируются фейком.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from kompas_kernel.features.document_session.models import GeoDigest
+from kompas_kernel.kompas.models import BBox
+from kompas_kernel.kompas.objects import Gabarit
+from kompas_kernel.kompas.units import SourceUnit, volume_to_mm3
+
+# Порог совпадения непрерывных величин: ниже - считаем "не изменилось" (шум пересчёта).
+_BBOX_TOL_MM = 1e-6
+_VOLUME_TOL_MM3 = 1e-6
+
+
+@dataclass(frozen=True)
+class RawTopology:
+    """Сырое чтение топологии активной 3D-детали - до нормализации в дайджест.
+
+    `gabarit_mm` уже в мм. `volume` несёт свою единицу `volume_unit` и нормализуется
+    в мм3 при сборке. `None` означает "нет данных".
+    """
+
+    body_count: int
+    face_count: int
+    edge_count: int
+    gabarit_mm: Gabarit | None
+    volume: float | None
+    volume_unit: SourceUnit
+
+
+class TopologyReader(Protocol):
+    """Структурный интерфейс чтения топологии.
+
+    Граница между "как читаем из CAD runtime" и "как собираем дайджест".
+    """
+
+    def body_count(self) -> int: ...
+
+    def face_count(self) -> int: ...
+
+    def edge_count(self) -> int: ...
+
+    def gabarit_mm(self) -> Gabarit | None: ...
+
+    def volume(self) -> tuple[float, SourceUnit] | None: ...
+
+
+def read_raw_topology(reader: TopologyReader) -> RawTopology:
+    """Собрать `RawTopology`, дёрнув читателя. Command-свободно: только запросы (GPC3)."""
+    measured = reader.volume()
+    if measured is None:
+        volume, unit = None, SourceUnit.MM
+    else:
+        volume, unit = measured
+    return RawTopology(
+        body_count=reader.body_count(),
+        face_count=reader.face_count(),
+        edge_count=reader.edge_count(),
+        gabarit_mm=reader.gabarit_mm(),
+        volume=volume,
+        volume_unit=unit,
+    )
+
+
+def build_digest(raw: RawTopology) -> GeoDigest:
+    """`RawTopology` -> `GeoDigest`: нормализует объём в мм3 и разворачивает габарит в bbox."""
+    bbox = None if raw.gabarit_mm is None else _bbox_from_gabarit(raw.gabarit_mm)
+    volume_mm3 = None if raw.volume is None else volume_to_mm3(raw.volume, raw.volume_unit)
+    return GeoDigest(
+        body_count=raw.body_count,
+        face_count=raw.face_count,
+        edge_count=raw.edge_count,
+        volume_mm3=volume_mm3,
+        bbox=bbox,
+    )
+
+
+def _bbox_from_gabarit(gabarit: Gabarit) -> BBox:
+    x1, y1, z1, x2, y2, z2 = gabarit
+    return BBox(
+        min_x=min(x1, x2),
+        min_y=min(y1, y2),
+        min_z=min(z1, z2),
+        max_x=max(x1, x2),
+        max_y=max(y1, y2),
+        max_z=max(z1, z2),
+    )
+
+
+def digest_changed(before: GeoDigest, after: GeoDigest) -> bool:
+    """Изменилась ли геометрия по дайджесту - основа честности `run_python`/`restore`.
+
+    Считаем "изменилось", если различается хоть один структурный признак: число
+    тел/граней/рёбер (точно), габарит или объём (с порогом на шум пересчёта).
+    Появление/исчезновение габарита или объёма - тоже изменение.
+    """
+    if (before.body_count, before.face_count, before.edge_count) != (
+        after.body_count,
+        after.face_count,
+        after.edge_count,
+    ):
+        return True
+    if _bbox_changed(before.bbox, after.bbox):
+        return True
+    return _scalar_changed(before.volume_mm3, after.volume_mm3, _VOLUME_TOL_MM3)
+
+
+def _bbox_changed(before: BBox | None, after: BBox | None) -> bool:
+    if before is None or after is None:
+        return before is not after
+    corners = ("min_x", "min_y", "min_z", "max_x", "max_y", "max_z")
+    return any(abs(getattr(before, c) - getattr(after, c)) > _BBOX_TOL_MM for c in corners)
+
+
+def _scalar_changed(before: float | None, after: float | None, tol: float) -> bool:
+    if before is None or after is None:
+        return before is not after
+    return abs(before - after) > tol

kompas_kernel/features/document_session/ksapi/__init__.py

@@ -0,0 +1,5 @@
+"""Raw KsAPI reads for document session: context, topology, screenshot, snapshot.
+
+Everything that touches raw `IKompasDocument`/`IPart`/`ksapi.py` objects lives here,
+inside a `KompasSession.run(...)` callback — no raw handle leaves this package.
+"""

kompas_kernel/features/document_session/ksapi/context_reader.py

@@ -0,0 +1,174 @@
+"""Raw KsAPI reads that back `document_session.queries` — context + topology.
+
+Free functions taking explicit `modules`/`app` (no adapter `self` state), same facade
+split as the other KsAPI capability modules (`kompas_kernel.kompas.objects`).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from kompas_kernel.features.document_session.digest import RawTopology, build_digest
+from kompas_kernel.features.document_session.models import (
+    NO_ACTIVE_DOCUMENT,
+    ActiveDocument,
+    AssemblyContext,
+    CadContext,
+    DocumentContext,
+    DocumentKind,
+    PartContext,
+    simple_document_context,
+)
+from kompas_kernel.kompas.models import EntityKind, EntityRef
+from kompas_kernel.kompas.objects import (
+    as_document_3d,
+    constants3d_class,
+    constants_class,
+    doc_name,
+    doc_path,
+    part_gabarit,
+)
+from kompas_kernel.kompas.runtime import KsApiModules
+from kompas_kernel.kompas.units import SourceUnit
+
+EMPTY_TOPOLOGY = RawTopology(
+    body_count=0,
+    face_count=0,
+    edge_count=0,
+    gabarit_mm=None,
+    volume=None,
+    volume_unit=SourceUnit.MM,
+)
+
+
+def _active_part(modules: KsApiModules, app: Any) -> Any | None:
+    doc3d = as_document_3d(modules, app.GetActiveDocument())
+    return None if doc3d is None else doc3d.GetTopPart()
+
+
+def _document_kind_from_code(constants: Any, type_code: int) -> DocumentKind:
+    """`ksDocumentTypeEnum` code → `DocumentKind`, через ИМЕНОВАННЫЕ константы (не магические int).
+
+    Незнакомый код → `UNKNOWN` (не падаем): его несёт `UnknownDocumentContext.raw_type_code`.
+    """
+    mapping = {
+        int(constants.ksDocumentPart): DocumentKind.PART,
+        int(constants.ksDocumentAssembly): DocumentKind.ASSEMBLY,
+        int(constants.ksDocumentDrawing): DocumentKind.DRAWING,
+        int(constants.ksDocumentFragment): DocumentKind.FRAGMENT,
+        int(constants.ksDocumentSpecification): DocumentKind.SPECIFICATION,
+        int(constants.ksDocumentTextual): DocumentKind.TEXTUAL,
+    }
+    return mapping.get(type_code, DocumentKind.UNKNOWN)
+
+
+def _model_objects_count(container: Any, obj_type: int) -> int:
+    objects = container.GetObjects(obj_type)
+    return len(objects) if objects is not None else 0
+
+
+def _count_bodies_via_faces(modules: KsApiModules, faces: list[Any]) -> int:
+    """Число тел активной детали — через грани, НЕ через `GetObjects(o3d_body)`.
+
+    `GetObjects(o3d_body)` в КОМПАС не перечисляет тела (даёт 0 даже на детали с
+    телом). Берём тело каждой грани (`IFace.GetBody`) и дедуплицируем по
+    `IBody.GetBodyId`.
+    """
+    body_ids: set[int] = set()
+    for face_obj in faces:
+        face = modules.ksapi.IFace(face_obj)
+        body = face.GetBody()
+        if body is None:
+            continue
+        body_ids.add(int(body.GetBodyId()))
+    return len(body_ids)
+
+
+def read_active_topology(modules: KsApiModules, app: Any) -> RawTopology:
+    """Сырая топология активной 3D-детали; нет активной детали → пустая топология."""
+    part = _active_part(modules, app)
+    if part is None:
+        return EMPTY_TOPOLOGY
+    return _read_part_topology(modules, part)
+
+
+def _read_part_topology(modules: KsApiModules, part: Any) -> RawTopology:
+    constants3d = constants3d_class(modules)
+    container = part.GetModelContainer()
+    if container is None:
+        return EMPTY_TOPOLOGY
+    raw_faces = container.GetObjects(int(constants3d.o3d_face))
+    faces: list[Any] = list(raw_faces) if raw_faces is not None else []
+    # Тела — через грани (o3d_body не перечисляется GetObjects, см. _count_bodies_via_faces).
+    body_count = _count_bodies_via_faces(modules, faces)
+    edge_count = _model_objects_count(container, int(constants3d.o3d_edge))
+    return RawTopology(
+        body_count=body_count,
+        face_count=len(faces),
+        edge_count=edge_count,
+        gabarit_mm=part_gabarit(part, body_count),
+        volume=None,
+        volume_unit=SourceUnit.MM,
+    )
+
+
+def read_active_document(modules: KsApiModules, app: Any) -> ActiveDocument:
+    """Кто открыт — четырьмя вызовами, без обращения к топологии (см. `ActiveDocument`).
+
+    Тип берётся из `GetDocumentType` тем же `_document_kind_from_code`, что и у полного
+    контекста: дискриминатор один, разъехаться они не могут. Ни `GetTopPart`, ни
+    `GetModelContainer`, ни `GetObjects` здесь не вызываются — в этом вся суть.
+    """
+    doc = app.GetActiveDocument()
+    if doc is None:
+        return NO_ACTIVE_DOCUMENT
+    kind = _document_kind_from_code(constants_class(modules), int(doc.GetDocumentType()))
+    return ActiveDocument(document_open=True, doc_kind=kind, name=doc_name(doc), path=doc_path(doc))
+
+
+def read_context(modules: KsApiModules, app: Any) -> CadContext:
+    """Снимок текущего состояния сессии CAD для оркестратора (`get_context`)."""
+    version = str(app.GetApplicationName(True))
+    doc = app.GetActiveDocument()
+    if doc is None:
+        return CadContext(connected=True, app_version=version, document_open=False)
+    return CadContext(
+        connected=True,
+        app_version=version,
+        document_open=True,
+        document=EntityRef(kind=EntityKind.DOCUMENT, index=0, document_path=doc_path(doc)),
+        document_name=doc_name(doc),
+        document_context=_read_document_context(modules, app, doc),
+    )
+
+
+def _read_document_context(modules: KsApiModules, app: Any, doc: Any) -> DocumentContext:
+    """Полиморфный контекст по типу документа сессии (`GetDocumentType`).
+
+    Деталь → digest (честный: свои тела). Сборка → лёгкая сводка. Прочее → payload-less
+    вариант. Дискриминируем по типу документа, а не по расширению исходника.
+    """
+    constants = constants_class(modules)
+    type_code = int(doc.GetDocumentType())
+    kind = _document_kind_from_code(constants, type_code)
+    if kind is DocumentKind.PART:
+        part = _active_part(modules, app)
+        raw = EMPTY_TOPOLOGY if part is None else _read_part_topology(modules, part)
+        return PartContext(digest=build_digest(raw))
+    if kind is DocumentKind.ASSEMBLY:
+        return _read_assembly_context(modules, doc)
+    return simple_document_context(kind, type_code)
+
+
+def _read_assembly_context(modules: KsApiModules, doc: Any) -> AssemblyContext:
+    """Лёгкая сводка сборки: число компонентов + обозначение корня, без чтения их геометрии."""
+    doc3d = as_document_3d(modules, doc)
+    if doc3d is None:
+        return AssemblyContext(component_count=0, top_marking=None)
+    constants3d = constants3d_class(modules)
+    top = doc3d.GetTopPart()
+    parts = top.GetPartsArray(int(constants3d.ksAllParts))
+    component_count = len(parts) if parts is not None else 0
+    raw_marking = top.GetMarking()
+    marking = str(raw_marking).strip() if raw_marking is not None else ""
+    return AssemblyContext(component_count=component_count, top_marking=marking or None)