kompas-kernel 0.0.1__py3-none-any.whl

kompas_kernel/features/assembly_navigator/ksapi/resolver.py

@@ -0,0 +1,35 @@
+"""Single component resolver: identifier <-> `IPart`, indexed by `GetPartsArray(ksAllParts)`.
+
+Both `reader.py` (numbering components while reading) and `presentation.py` (resolving a
+requested identifier back to an `IPart`) need the exact same `GetPartsArray(ksAllParts)`
+listing and the exact same `str(index)` identifier convention — this module is the one
+place that convention lives, replacing the previous split (`enumerate` in the old
+`api/assembly_reader.py` reader vs `_parse_index` in the old adapter's
+`_select_components_and_zoom`). Numbering and semantics are unchanged by this move.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from kompas_kernel.kompas.objects import constants3d_class, parse_index
+from kompas_kernel.kompas.runtime import KsApiModules
+
+
+def list_components(modules: KsApiModules, top: Any) -> list[Any]:
+    """Top-level components of `top`, in stable `GetPartsArray(ksAllParts)` order."""
+    constants3d = constants3d_class(modules)
+    return list(top.GetPartsArray(int(constants3d.ksAllParts)))
+
+
+def component_identifier(index: int) -> str:
+    """The `str(index)` identifier convention `read_assembly`/`show_component` share."""
+    return str(index)
+
+
+def resolve_index(components: list[Any], identifier: str) -> int | None:
+    """identifier -> index into `components`, or `None` if non-numeric/out-of-range."""
+    index = parse_index(identifier)
+    if index is None or not (0 <= index < len(components)):
+        return None
+    return index

kompas_kernel/features/assembly_navigator/models.py

@@ -0,0 +1,218 @@
+"""DTO инспекции сборки — публичный контракт `queries.read_assembly`/`commands.show_components`.
+
+Компоненты верхнего уровня активной КОМПАС-Сборки: вид/состояние/вставка/габарит
+(`AssemblyView`/`AssemblyComponent`/...), плюс результат показа (`ShowComponentsResult`/
+`ComponentShowResult`/`ComponentIdentifiers`). Перенесено из `bridge/models/assembly.py` +
+assembly-часть `bridge/models/presentation.py` (E16.04) — `ShowDistanceResult` (геометрия)
+остаётся в `bridge/models/presentation.py`, уедет в 04a. Framework-free: pydantic-схемы
+на `utils.validation.CustomModel`, без Pydantic AI.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Annotated, Self
+
+from pydantic import Field, model_validator
+
+from kompas_kernel.kompas.models import BBox, Point3D
+from kompas_kernel.utils.validation import CustomModel
+
+
+class ComponentKind(StrEnum):
+    """Вид компонента в сборке КОМПАС: деталь или подсборка.
+
+    Проецируется из `IPart.IsDetail()` reader'ом: True → PART, False → SUBASSEMBLY.
+    """
+
+    PART = "part"
+    SUBASSEMBLY = "subassembly"
+
+
+class ComponentLoadState(StrEnum):
+    """Нейтральная проекция `ksLoadStateEnum` для DTO.
+
+    Маппинг сырого целочисленного enum → это поле — забота `ksapi/mapping.py`.
+    Значения подтверждены спайком-00 на живой сборке `Heat gun.a3d`.
+    """
+
+    FULL = "full"
+    UNLOADED = "unloaded"
+    TRIANGLES = "triangles"
+    PARTIAL = "partial"
+    GABARIT = "gabarit"
+    UNKNOWN = "unknown"
+
+
+class StandardReferenceSource(StrEnum):
+    """Как найден опорный объект стандартного компонента."""
+
+    NAMED = "named"
+    DEFAULT = "default"
+
+
+class ComponentPlacement(CustomModel):
+    """Сериализуемая система координат вставки компонента из `GetPlacement()`.
+
+    `origin_x/y/z` — начало СК в мм (из `IPlacement3D.GetOrigin()`).
+
+    Матрицы ориентации здесь нет намеренно: `GetMatrix3D()` отдаёт 16 float (4×4), их
+    никто в коде не читал, а модели они бесполезны — перемножать матрицу она не станет,
+    а ~450 байт на компонент платила (67.6 КиБ на сборку из 58 компонентов, прогон
+    2026-08-05). Ориентация стандартного компонента доступна точнее и дешевле —
+    `StandardComponentInfo.axis` (`GetVector(o3d_axisOZ)`), она и используется.
+    """
+
+    origin_x: float
+    origin_y: float
+    origin_z: float
+
+
+class StandardReferenceObject(CustomModel):
+    """Сериализуемая ссылка на опорный объект внутри стандартного компонента.
+
+    Raw `IModelObject` наружу не отдаём: только проверяемые факты, которые можно
+    логировать и передать модели.
+    """
+
+    name: str = Field(min_length=1)
+    model_object_type: int = Field(ge=0)
+    source: StandardReferenceSource
+
+
+class StandardComponentAxis(CustomModel):
+    """Ось стандартного компонента в глобальной СК документа, мм."""
+
+    origin: Point3D
+    direction: Point3D
+    reference: StandardReferenceObject | None
+
+
+class StandardComponentPlane(CustomModel):
+    """Опорная плоскость стандартного компонента в глобальной СК документа, мм."""
+
+    origin: Point3D
+    normal: Point3D
+    reference: StandardReferenceObject | None
+
+
+class StandardComponentInfo(CustomModel):
+    """Дополнительные факты `IPart.IsStandard()==True`.
+
+    `axis` — локальная OZ-ось вставки (`GetPlacement().GetVector(o3d_axisOZ)`).
+    `plane` — локальная XOY-плоскость вставки; её нормаль совпадает с OZ.
+    `reference` внутри axis/plane указывает, нашёлся ли именованный объект
+    ("Axis"/"Plane") или взят системный default.
+    """
+
+    file_name: str | None
+    axis: StandardComponentAxis | None
+    plane: StandardComponentPlane | None
+
+
+class AssemblyComponent(CustomModel):
+    """Один компонент верхнего уровня КОМПАС-Сборки (вставка, не уникальный).
+
+    `identifier` — индекс компонента в `GetPartsArray(ksAllParts)` строкой;
+    стабилен в рамках сессии; используется как ключ для `show_component`.
+    `marking` — обозначение (`GetMarking()`); может быть пустой строкой.
+    `name` — наименование (`GetName()`); `None` если пустое.
+    """
+
+    identifier: str
+    marking: str
+    name: str | None
+    kind: ComponentKind
+    is_standard: bool
+    placement: ComponentPlacement
+    bbox: BBox | None
+    standard: StandardComponentInfo | None = None
+    load_state: ComponentLoadState
+    visible: bool
+    valid: bool
+    excluded: bool
+
+
+class AssemblyView(CustomModel):
+    """Снимок компонентов верхнего уровня активной КОМПАС-Сборки.
+
+    `component_count` дублирует `len(components)` явным полем для удобства LLM:
+    модель видит число прямо в JSON, не считая элементы списка.
+    """
+
+    is_assembly: bool
+    top_marking: str
+    components: list[AssemblyComponent]
+    component_count: int
+
+    @model_validator(mode="after")
+    def _check_component_count(self) -> Self:
+        if self.component_count != len(self.components):
+            raise ValueError(
+                f"component_count ({self.component_count}) must equal len(components) ({len(self.components)})"
+            )
+        return self
+
+
+class ComponentSummary(CustomModel):
+    """Компонент в том виде, в каком его ВИДИТ МОДЕЛЬ (проекция `AssemblyComponent`).
+
+    Порт продолжает отдавать полный `AssemblyComponent` — коду нужны и габарит, и оси
+    стандартного изделия. Модели уходит только то, из чего она реально делает выводы:
+    для крепежа весь предмет разговора лежит в `name` («Болт 3М14x65 ГОСТ 15589-70»),
+    остальное было платой за контекст (см. `summary.py`).
+
+    `origin_mm` — [x, y, z] вставки, округлённые до микрометров: полная двоичная точность
+    (`-1.7147394615335543e-13`) — это шум, модель всё равно читает его как «примерно 0».
+    `status` — ТОЛЬКО аномалии (`excluded`/`invalid`/`not_loaded`); у здорового компонента
+    `None`, поэтому норма не стоит ни байта, а исключённый из сборки крепёж модель не
+    посчитает установленным.
+    """
+
+    identifier: str
+    marking: str
+    name: str | None
+    kind: ComponentKind
+    is_standard: bool
+    origin_mm: tuple[float, float, float]
+    status: list[str] | None = None
+
+
+class AssemblySummaryView(CustomModel):
+    """Состав сборки для модели: `AssemblyView` без полей, которыми она не пользуется."""
+
+    is_assembly: bool
+    top_marking: str
+    components: list[ComponentSummary]
+    component_count: int
+
+    @model_validator(mode="after")
+    def _check_component_count(self) -> Self:
+        if self.component_count != len(self.components):
+            raise ValueError(
+                f"component_count ({self.component_count}) must equal len(components) ({len(self.components)})"
+            )
+        return self
+
+
+class ComponentShowResult(CustomModel):
+    """Состояние одного запрошенного компонента в пакетном показе."""
+
+    identifier: str
+    found: bool
+    selected: bool
+    marking: str
+
+
+class ShowComponentsResult(CustomModel):
+    """Результат атомарного показа нескольких компонентов.
+
+    `components` сохраняет порядок входных идентификаторов. Найденные компоненты
+    выделяются одним вызовом KsAPI, затем выполняется одна команда zoom selected.
+    """
+
+    components: tuple[ComponentShowResult, ...] = Field(min_length=1)
+    zoomed: bool
+
+
+type ComponentIdentifiers = Annotated[list[str], Field(min_length=1)]

kompas_kernel/features/assembly_navigator/queries.py

@@ -0,0 +1,42 @@
+"""Framework-free public read API for the assembly navigator, over `KompasSession`.
+
+No Pydantic AI, no `kompas_copilot.bridge` import — the feature owns its own KsAPI reader
+(`ksapi/reader.py`) and pure mapper (`ksapi/mapping.py`); this module only wires them
+through one session callback.
+"""
+
+from __future__ import annotations
+
+from kompas_kernel.features.assembly_navigator.ksapi.mapping import build_assembly_view
+from kompas_kernel.features.assembly_navigator.ksapi.raw import RawAssembly
+from kompas_kernel.features.assembly_navigator.ksapi.reader import read_raw_assembly
+from kompas_kernel.features.assembly_navigator.models import AssemblyView
+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 read_assembly(session: KompasSession) -> AssemblyView:
+    """Прочитать компоненты верхнего уровня активной КОМПАС-Сборки (И1).
+
+    Не-сборка (ksDocumentPart, тип=4) — валидный ответ с `is_assembly=False`
+    и обычно пустым списком компонентов; не ошибка (ограничение снято).
+    Нет активного 3D-документа → `KompasError`.
+    """
+    raw = await session.run(
+        operation_name="assembly_navigator.read",
+        operation=_read_raw_assembly,
+    )
+    return build_assembly_view(raw)
+
+
+def _read_raw_assembly(context: KompasContext) -> RawAssembly:
+    raw = read_raw_assembly(context.modules, context.app)
+    logger.info(
+        event_name(LogDomain.BRIDGE, "ksapi_read_assembly", LogEventType.COMPLETED),
+        is_assembly=raw.is_assembly,
+        component_count=len(raw.components),
+    )
+    return raw

kompas_kernel/features/assembly_navigator/service.py

@@ -0,0 +1,31 @@
+"""`AssemblyNavigatorService` — thin holder of one `KompasSession`.
+
+Exists solely because composition and its typed fake need one object implementing the
+narrow consumer-owned Protocol declared in `core/capabilities/assembly_navigator.py`
+(принятое решение владельца 1) — no logic lives here, no multi-step use case. The
+session is a required dependency: this class neither creates nor closes it — the
+transport that built the session owns that lifecycle.
+"""
+
+from __future__ import annotations
+
+from kompas_kernel.features.assembly_navigator import commands, queries
+from kompas_kernel.features.assembly_navigator.models import (
+    AssemblyView,
+    ComponentIdentifiers,
+    ShowComponentsResult,
+)
+from kompas_kernel.kompas.session import KompasSession
+
+
+class AssemblyNavigatorService:
+    """Delegates `read_assembly`/`show_components` to `queries`/`commands` over one session."""
+
+    def __init__(self, session: KompasSession) -> None:
+        self._session = session
+
+    async def read_assembly(self) -> AssemblyView:
+        return await queries.read_assembly(self._session)
+
+    async def show_components(self, identifiers: ComponentIdentifiers) -> ShowComponentsResult:
+        return await commands.show_components(self._session, identifiers)

kompas_kernel/features/assembly_navigator/summary.py

@@ -0,0 +1,90 @@
+"""Проекция полного `AssemblyView` в то, что видит модель.
+
+Зачем слой: живой прогон 2026-08-05 («проверь ка мне крепежи», сборка из 58 компонентов)
+стоил 67.6 КиБ состава — из них ~85% занимали матрица 4×4, габарит и координаты в полной
+двоичной точности. Спул убрал этот объём из ответа тула, но модель вернула его в контекст
+чтением спул-файла. Настоящая причина не в чтении: модель ПОЛУЧАЛА данные, которыми не
+может пользоваться. Компактный состав той же сборки — 6.9 КиБ, он влезает в один ответ
+целиком, и спул на нём не срабатывает вовсе.
+
+Что осталось и почему: для сценария «проверь крепёж» весь предмет разговора лежит в
+`name` («Болт 3М14x65 ГОСТ 15589-70» — вид, диаметр, длина, ГОСТ), а `identifier` нужен
+как ключ для `show_component`. Координаты вставки дают группировку по узлам («эти четыре
+болта в одном фланце»), но округлённые до микрометров.
+
+Что срезано: матрица 4×4 (модель её не перемножает), габарит (bbox — размеры крепежа и так
+в обозначении), `StandardComponentInfo` (путь к библиотечному `.m3d` и оси, дублирующие
+`placement`), флаги в НОРМАЛЬНОМ состоянии. Аномалии не срезаны — см. `_status`.
+
+Полный `AssemblyView` никуда не делся: порт отдаёт его по-прежнему, коду доступны и
+габарит, и оси стандартных изделий (AGENTS.md / ADR 0005 — model-facing поверхность как
+view-слой над DTO, а не вместо них).
+"""
+
+from __future__ import annotations
+
+from kompas_kernel.features.assembly_navigator.models import (
+    AssemblyComponent,
+    AssemblySummaryView,
+    AssemblyView,
+    ComponentLoadState,
+    ComponentSummary,
+)
+
+_ORIGIN_DECIMALS = 3
+"""Микрометры: тоньше реального смысла для сборки и без хвоста двоичного шума."""
+
+
+def _round_mm(value: float) -> float:
+    # `+ 0.0` схлопывает -0.0 в 0.0: «-0.0» в выдаче читается как значащий знак, а это
+    # тот же ноль (координаты приходят как -1.7e-13, то есть ноль с точностью до шума).
+    return round(value, _ORIGIN_DECIMALS) + 0.0
+
+
+def _status(component: AssemblyComponent) -> list[str] | None:
+    """Только отклонения от нормы; у здорового компонента — `None`.
+
+    Норма молчит намеренно: `visible`/`valid`/`excluded`/`load_state` в штатных значениях
+    — это ~80 байт на компонент, которые ничего не сообщают. Отклонение же обязано дойти
+    до модели: крепёж, исключённый из сборки, не установлен, и вывод «болт на месте» по
+    такому компоненту был бы ложным.
+    """
+    status: list[str] = []
+    if component.excluded:
+        status.append("excluded")
+    if not component.valid:
+        status.append("invalid")
+    if component.load_state is not ComponentLoadState.FULL:
+        status.append(f"load_state={component.load_state.value}")
+    return status or None
+
+
+def summarize_component(component: AssemblyComponent) -> ComponentSummary:
+    """Спроецировать один компонент в model-facing вид."""
+    placement = component.placement
+    return ComponentSummary(
+        identifier=component.identifier,
+        marking=component.marking,
+        name=component.name,
+        kind=component.kind,
+        is_standard=component.is_standard,
+        origin_mm=(
+            _round_mm(placement.origin_x),
+            _round_mm(placement.origin_y),
+            _round_mm(placement.origin_z),
+        ),
+        status=_status(component),
+    )
+
+
+def summarize_assembly(view: AssemblyView) -> AssemblySummaryView:
+    """Спроецировать снимок сборки в то, что уходит модели.
+
+    Чистая функция: ни КОМПАС, ни сессия не нужны — проверяется юнит-тестом целиком.
+    """
+    return AssemblySummaryView(
+        is_assembly=view.is_assembly,
+        top_marking=view.top_marking,
+        components=[summarize_component(component) for component in view.components],
+        component_count=view.component_count,
+    )

kompas_kernel/features/document_session/__init__.py

@@ -0,0 +1,5 @@
+"""Document session capability: CAD context, geometry digest, screenshot, checkpoint/restore.
+
+Framework-free vertical slice over one `KompasSession` (E16.04b). Owns its own KsAPI
+context/screenshot/snapshot reading (`ksapi/`); no `kompas_copilot.bridge` import.
+"""

kompas_kernel/features/document_session/checkpointed.py

@@ -0,0 +1,165 @@
+"""One checkpoint decorator for every model-facing Python execution facade."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from enum import StrEnum
+from functools import wraps
+from typing import Protocol, assert_never
+
+from kompas_kernel.features.document_session.models import (
+    Checkpoint,
+    GuardReport,
+    GuardStatus,
+    RestoreResult,
+)
+from kompas_kernel.features.document_session.registry import CheckpointError
+from kompas_kernel.kompas.errors import KompasError
+from kompas_kernel.observability.logger import get_logger
+from kompas_kernel.observability.taxonomy import LogDomain, LogEventType, event_name
+
+logger = get_logger(__name__)
+
+
+class CheckpointGuard(Protocol):
+    """Session-scoped snapshot and rollback capability used by the decorator."""
+
+    async def capture(self, session_id: str) -> Checkpoint: ...
+
+    async def rollback(self, session_id: str, checkpoint_id: str) -> RestoreResult: ...
+
+
+class CheckpointAction(StrEnum):
+    """Caller-owned decision; the decorator owns how each action is executed."""
+
+    COMMIT = "commit"
+    ROLLBACK = "rollback"
+    NOT_EXECUTED = "not_executed"
+
+
+@dataclass(frozen=True, slots=True)
+class CheckpointDecision:
+    """Transaction action plus caller-specific explanation for the tool result."""
+
+    action: CheckpointAction
+    detail: str
+
+
+async def _capture(guard: CheckpointGuard, session_id: str) -> tuple[Checkpoint | None, GuardReport | None]:
+    try:
+        return await guard.capture(session_id), None
+    except (KompasError, CheckpointError) as exc:
+        logger.warning(
+            event_name(LogDomain.AGENT, "checkpointed_execute_capture", LogEventType.FAILED),
+            session_id=session_id,
+            error=str(exc),
+        )
+        return None, GuardReport(
+            status=GuardStatus.NOT_CAPTURED,
+            detail=f"Снимок перед исполнением снять не удалось ({exc}) — код не исполнялся.",
+        )
+
+
+async def _rollback(
+    guard: CheckpointGuard,
+    session_id: str,
+    checkpoint: Checkpoint,
+    reason: str,
+) -> GuardReport:
+    try:
+        restored = await guard.rollback(session_id, checkpoint.checkpoint_id)
+    except (KompasError, CheckpointError) as exc:
+        logger.warning(
+            event_name(LogDomain.AGENT, "checkpointed_execute_rollback", LogEventType.FAILED),
+            session_id=session_id,
+            checkpoint_id=checkpoint.checkpoint_id,
+            error=str(exc),
+        )
+        return GuardReport(
+            status=GuardStatus.ROLLBACK_FAILED,
+            detail=f"{reason} Откат к снимку не удался ({exc}) — состояние документа неизвестно.",
+            checkpoint_id=checkpoint.checkpoint_id,
+        )
+    if not restored.matches_checkpoint:
+        return GuardReport(
+            status=GuardStatus.ROLLBACK_FAILED,
+            detail=f"{reason} Откат выполнился, но документ НЕ совпал со снимком — продолжать нельзя.",
+            checkpoint_id=checkpoint.checkpoint_id,
+            matches_checkpoint=False,
+        )
+    return GuardReport(
+        status=GuardStatus.ROLLED_BACK,
+        detail=f"{reason} Документ возвращён к снимку перед этим вызовом.",
+        checkpoint_id=checkpoint.checkpoint_id,
+        matches_checkpoint=True,
+    )
+
+
+def _kept(checkpoint: Checkpoint, decision: CheckpointDecision) -> GuardReport:
+    return GuardReport(
+        status=GuardStatus.KEPT,
+        detail=(
+            f"{decision.detail} Checkpoint сохранён; при необходимости доступен через "
+            f"restore('{checkpoint.checkpoint_id}')."
+        ),
+        checkpoint_id=checkpoint.checkpoint_id,
+    )
+
+
+def checkpointed[**P, T](
+    *,
+    guard: Callable[P, CheckpointGuard],
+    session_id: Callable[P, str],
+    decide: Callable[[T], CheckpointDecision],
+    attach_guard: Callable[[T, GuardReport], T],
+    blocked_result: Callable[[GuardReport], T],
+) -> Callable[[Callable[P, Awaitable[T]]], Callable[P, Awaitable[T]]]:
+    """Decorate one operation with the canonical capture/decide/rollback mechanism.
+
+    The decorator owns every checkpoint side effect. Callers own only their typed
+    decision policy and the mechanical way their distinct result DTO carries a common
+    `GuardReport`. An unexpected exception is fail-closed: rollback is attempted and
+    the original exception is re-raised.
+    """
+
+    def _decorate(operation: Callable[P, Awaitable[T]]) -> Callable[P, Awaitable[T]]:
+        @wraps(operation)
+        async def _wrapped(*args: P.args, **kwargs: P.kwargs) -> T:
+            checkpoint_guard = guard(*args, **kwargs)
+            current_session_id = session_id(*args, **kwargs)
+            checkpoint, capture_failure = await _capture(checkpoint_guard, current_session_id)
+            if checkpoint is None:
+                if capture_failure is None:  # pragma: no cover - `_capture` preserves this invariant.
+                    raise AssertionError("checkpoint capture failed without GuardReport")
+                return blocked_result(capture_failure)
+
+            try:
+                result = await operation(*args, **kwargs)
+            except BaseException:
+                await _rollback(
+                    checkpoint_guard,
+                    current_session_id,
+                    checkpoint,
+                    "Исполнение завершилось неожиданным исключением.",
+                )
+                raise
+
+            decision = decide(result)
+            match decision.action:
+                case CheckpointAction.COMMIT | CheckpointAction.NOT_EXECUTED:
+                    report = _kept(checkpoint, decision)
+                case CheckpointAction.ROLLBACK:
+                    report = await _rollback(
+                        checkpoint_guard,
+                        current_session_id,
+                        checkpoint,
+                        decision.detail,
+                    )
+                case _ as unreachable:
+                    assert_never(unreachable)
+            return attach_guard(result, report)
+
+        return _wrapped
+
+    return _decorate