kompas-kernel 0.0.1__py3-none-any.whl

kompas_kernel/kompas/objects.py

@@ -0,0 +1,93 @@
+"""Small shared KsAPI helpers reused by capability modules.
+
+Only read-only queries live here: constants class access, `IKompasDocument3D`
+cast, document path, string index parsing, and `IPart.GetGabarit` normalization.
+Everything is kept in one place (GPC8 reuse-first / GPC4 single source of truth)
+instead of duplicated per module.
+
+Перенесено из `bridge/kompas_ksapi/common.py` (E16.04) вместе с алиасом `Gabarit`
+(раньше жил в `bridge/kompas_ksapi/raw/assembly.py`), чтобы `features/*` не
+импортировали `kompas_copilot.bridge`. Прежде приватные имена (`_constants_class` и
+т.п.) стали публичными без смены поведения — сигнатуры и логика не менялись.
+"""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+from kompas_kernel.kompas.runtime import KsApiModules
+
+_GABARIT_VALUE_COUNT = 6
+
+# Габарит компонента из GetGabarit - кортеж (x1, y1, z1, x2, y2, z2) в мм.
+Gabarit = tuple[float, float, float, float, float, float]
+
+
+def constants_class(modules: KsApiModules) -> Any:
+    module = cast(Any, modules.constants)
+    return module.constants
+
+
+def constants3d_class(modules: KsApiModules) -> Any:
+    module = cast(Any, modules.constants3d)
+    return module.constants
+
+
+def as_document_3d(modules: KsApiModules, doc: Any) -> Any | None:
+    if doc is None:
+        return None
+    try:
+        doc3d = modules.ksapi.IKompasDocument3D(doc)
+    except Exception:
+        return None
+    return doc3d if doc3d else None
+
+
+def doc_path(doc: Any) -> str | None:
+    raw = doc.GetFullPath()
+    text = str(raw).strip() if raw is not None else ""
+    return text or None
+
+
+def doc_name(doc: Any) -> str | None:
+    """Короткое имя документа (`GetName()` — имя файла с расширением) или `None`.
+
+    У несохранённого документа КОМПАС отдаёт пустую строку (проверено живьём
+    2026-08-02: новый `ksDocumentPart` даёт `''` и в `GetName`, и в `GetFullPath`,
+    и в `GetPath`), поэтому пустая строка нормализуется в честный `None` — тем же
+    способом, что `doc_path` выше.
+    """
+    raw = doc.GetName()
+    text = str(raw).strip() if raw is not None else ""
+    return text or None
+
+
+def parse_index(identifier: str) -> int | None:
+    """Идентификатор компонента — строковый индекс из read_assembly. Нечисловой → None."""
+    try:
+        return int(identifier)
+    except (ValueError, TypeError):
+        return None
+
+
+def part_gabarit(part: Any, body_count: int) -> Gabarit | None:
+    if body_count == 0:
+        return None
+    raw = part.GetGabarit(True, True, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0)
+    if raw is None:
+        return None
+    values = tuple(raw)
+    if len(values) < _GABARIT_VALUE_COUNT + 1:
+        return None
+    ok = bool(values[0])
+    if not ok:
+        return None
+    coords = values[-_GABARIT_VALUE_COUNT:]
+    return (
+        float(coords[0]),
+        float(coords[1]),
+        float(coords[2]),
+        float(coords[3]),
+        float(coords[4]),
+        float(coords[5]),
+    )

kompas_kernel/kompas/platform.py

@@ -0,0 +1,40 @@
+"""Единственное место в `kompas/`, знающее, как называются файлы моста на этой ОС.
+
+KsAPICLink **кроссплатформенный**: тот же `ksapi.py`, который мы импортируем из
+`KOMPAS_BIN_DIR`, сам выбирает библиотеку строкой
+`LIB_NAME = 'ksAPICLink.dll' if os.name == 'nt' else 'libksAPICLink.so'`. На Linux
+установка лежит как `/opt/ascon/kompas3d-vXX/Bin/libksAPICLink.so` — тот же каталог
+`Bin` рядом с генерированными обёртками, что и на Windows. Поэтому продукт НЕ
+отказывает по имени ОС: отказ бывает только один — «в этом каталоге нет нужных
+файлов» (`runtime.validate_ksapi_runtime`).
+
+Здесь живёт ровно та же развилка, что у вендора, и больше ничего. Вынесена она
+отдельным файлом потому, что архитектурный гейт
+(`tests/architecture/test_layer_boundaries.py`) держит знание об ОС в счётном числе
+мест: иначе `os.name` расползётся по слоям и «поддержка Linux» станет непроверяемой.
+"""
+
+from __future__ import annotations
+
+import os
+
+# Windows: библиотека моста плюс сам `KOMPAS.exe` — он здесь признак «каталог тот
+# самый», а не то, что мы запускаем (КОМПАС поднимает пользователь).
+_WINDOWS_RUNTIME_FILES: tuple[str, ...] = ("ksAPICLink.dll", "KOMPAS.exe")
+
+# Прочие ОС: только библиотека. Имя исполняемого файла КОМПАС на Linux в продукте НЕ
+# зашито — оно не проверено живьём, а угаданное имя дало бы ложный отказ на исправной
+# установке. Признака «каталог тот самый» достаточно от самой `libksAPICLink.so`.
+_POSIX_RUNTIME_FILES: tuple[str, ...] = ("libksAPICLink.so",)
+
+
+def runtime_file_names(*, os_name: str) -> tuple[str, ...]:
+    """Платформенные файлы моста для `os_name` (значения — как у `os.name`).
+
+    Аргумент явный (GPC1), чтобы обе ветки проверялись тестами на любой машине, а не
+    только та, на которой сейчас идёт прогон.
+    """
+    return _WINDOWS_RUNTIME_FILES if os_name == "nt" else _POSIX_RUNTIME_FILES
+
+
+PLATFORM_RUNTIME_FILES: tuple[str, ...] = runtime_file_names(os_name=os.name)

kompas_kernel/kompas/runtime.py

@@ -0,0 +1,186 @@
+"""Generated KsAPICLink loader and the single sequential worker runtime."""
+
+from __future__ import annotations
+
+import asyncio
+import importlib.util
+import queue
+import sys
+import threading
+from collections.abc import Callable
+from concurrent.futures import Future
+from dataclasses import dataclass
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+
+from kompas_kernel.kompas.errors import KompasError
+from kompas_kernel.kompas.platform import PLATFORM_RUNTIME_FILES
+from kompas_kernel.observability.logger import get_logger
+from kompas_kernel.observability.taxonomy import LogDomain, LogEventType, event_name
+
+logger = get_logger(__name__)
+
+# Генерированные SWIG-обёртки одинаковы на любой ОС; библиотека моста (и на Windows
+# `KOMPAS.exe`) зависит от платформы — их имена приходят из `kompas/platform.py`,
+# единственного владельца этого знания.
+_GENERATED_WRAPPER_FILES: tuple[str, ...] = ("ksapi.py", "constants.py", "constants3d.py")
+
+REQUIRED_RUNTIME_FILES: tuple[str, ...] = (*_GENERATED_WRAPPER_FILES, *PLATFORM_RUNTIME_FILES)
+
+_WORKER_PHASE = "ksapi_worker"
+
+
+@dataclass(frozen=True)
+class KsApiRuntimeConfig:
+    """Explicit path and required files for one KOMPAS binary tree."""
+
+    bin_dir: Path
+    required_files: tuple[str, ...] = REQUIRED_RUNTIME_FILES
+
+
+@dataclass(frozen=True)
+class KsApiModules:
+    """Generated wrapper modules loaded from one KOMPAS binary tree."""
+
+    ksapi: ModuleType
+    constants: ModuleType
+    constants3d: ModuleType
+
+
+@dataclass(frozen=True)
+class _Task:
+    """One heterogeneous callback queued for the worker thread."""
+
+    fn: Callable[[], Any]
+    future: Future[Any]
+
+
+class KsApiWorker:
+    """One background thread serializing calls into one KOMPAS application."""
+
+    def __init__(self, *, thread_name: str, stop_timeout_s: float) -> None:
+        self._queue: queue.SimpleQueue[_Task | None] = queue.SimpleQueue()
+        self._thread = threading.Thread(target=self._run, name=thread_name, daemon=True)
+        self._stop_timeout_s = stop_timeout_s
+        self._started = False
+        self._stopped = False
+
+    def start(self) -> None:
+        """Start exactly once."""
+        if self._started:
+            raise RuntimeError("KsApiWorker already started")
+        self._started = True
+        self._thread.start()
+        logger.info(event_name(LogDomain.BRIDGE, _WORKER_PHASE, LogEventType.STARTED), thread=self._thread.name)
+
+    def _run(self) -> None:
+        while True:
+            task = self._queue.get()
+            if task is None:
+                return
+            if not task.future.set_running_or_notify_cancel():
+                continue
+            try:
+                result = task.fn()
+            except Exception as exc:
+                task.future.set_exception(exc)
+            else:
+                task.future.set_result(result)
+
+    def is_current_thread(self) -> bool:
+        """Whether the caller is executing inside this worker's callback."""
+        return threading.current_thread() is self._thread
+
+    def _enqueue[T](self, fn: Callable[[], T]) -> Future[T]:
+        if not self._started or self._stopped:
+            raise RuntimeError("KsApiWorker is not running")
+        future: Future[T] = Future()
+        self._queue.put(_Task(fn=fn, future=future))
+        return future
+
+    def submit[T](self, fn: Callable[[], T]) -> T:
+        """Run ``fn`` on the worker and block the calling thread."""
+        return self._enqueue(fn).result()
+
+    async def submit_async[T](self, fn: Callable[[], T]) -> T:
+        """Run ``fn`` on the worker without blocking the event loop."""
+        return await asyncio.wrap_future(self._enqueue(fn))
+
+    def stop(self) -> None:
+        """Stop once; repeated close calls are harmless."""
+        if not self._started or self._stopped:
+            return
+        self._stopped = True
+        self._queue.put(None)
+        self._thread.join(timeout=self._stop_timeout_s)
+        logger.info(event_name(LogDomain.BRIDGE, _WORKER_PHASE, LogEventType.COMPLETED), thread=self._thread.name)
+
+
+def runtime_config_from_bin_dir(bin_dir: Path | None) -> KsApiRuntimeConfig:
+    """Build fail-fast runtime config from an explicit settings value."""
+    if bin_dir is None:
+        raise KompasError(
+            "KOMPAS_BIN_DIR is not set. Set it to the KOMPAS Bin(x64) directory "
+            "with ksapi.py, constants.py, constants3d.py, ksAPICLink.dll and KOMPAS.exe."
+        )
+    return KsApiRuntimeConfig(bin_dir=bin_dir)
+
+
+def validate_ksapi_runtime(config: KsApiRuntimeConfig) -> None:
+    """Validate the binary tree before importing generated wrappers."""
+    if not config.bin_dir.exists():
+        raise KompasError(f"KOMPAS_BIN_DIR does not exist: {config.bin_dir}")
+    if not config.bin_dir.is_dir():
+        raise KompasError(f"KOMPAS_BIN_DIR is not a directory: {config.bin_dir}")
+
+    missing = [name for name in config.required_files if not (config.bin_dir / name).is_file()]
+    if missing:
+        raise KompasError(f"KOMPAS_BIN_DIR is missing required runtime files: {', '.join(missing)}")
+
+
+def load_ksapi_runtime(config: KsApiRuntimeConfig) -> KsApiModules:
+    """Import generated wrapper modules from an explicit runtime directory."""
+    validate_ksapi_runtime(config)
+    bin_dir = config.bin_dir.resolve()
+    _ensure_sys_path(bin_dir)
+    return KsApiModules(
+        constants=_import_runtime_module("constants", bin_dir / "constants.py"),
+        constants3d=_import_runtime_module("constants3d", bin_dir / "constants3d.py"),
+        ksapi=_import_runtime_module("ksapi", bin_dir / "ksapi.py"),
+    )
+
+
+def _ensure_sys_path(bin_dir: Path) -> None:
+    text = str(bin_dir)
+    if text not in sys.path:
+        sys.path.insert(0, text)
+
+
+def _import_runtime_module(name: str, path: Path) -> ModuleType:
+    existing = sys.modules.get(name)
+    if existing is not None:
+        existing_file = _module_file(existing)
+        if existing_file == path.resolve():
+            return existing
+        raise KompasError(
+            f"Cannot load KOMPAS runtime module {name!r} from {path}: module already loaded from {existing_file}"
+        )
+
+    spec = importlib.util.spec_from_file_location(name, path)
+    if spec is None or spec.loader is None:
+        raise KompasError(f"Cannot create import spec for KOMPAS runtime module {name!r}: {path}")
+
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[name] = module
+    try:
+        spec.loader.exec_module(module)
+    except Exception:
+        sys.modules.pop(name, None)
+        raise
+    return module
+
+
+def _module_file(module: ModuleType) -> Path | None:
+    raw = getattr(module, "__file__", None)
+    return None if raw is None else Path(str(raw)).resolve()

kompas_kernel/kompas/session.py

@@ -0,0 +1,195 @@
+"""One lifecycle owner and execution boundary for a visible KOMPAS instance."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from kompas_kernel.kompas.errors import KompasError, KompasReentryError
+from kompas_kernel.kompas.runtime import (
+    KsApiModules,
+    KsApiRuntimeConfig,
+    KsApiWorker,
+    load_ksapi_runtime,
+    runtime_config_from_bin_dir,
+)
+from kompas_kernel.observability.logger import get_logger
+from kompas_kernel.observability.taxonomy import LogDomain, LogEventType, event_name
+
+logger = get_logger(__name__)
+
+KSAPI_WORKER_THREAD_NAME = "kompas-ksapi-sequential"
+KSAPI_WORKER_STOP_TIMEOUT_S = 5.0
+_OPERATION_PHASE = "kompas_session_operation"
+
+type RuntimeLoader = Callable[[KsApiRuntimeConfig], KsApiModules]
+
+
+@dataclass(frozen=True, slots=True)
+class KompasContext:
+    """Raw SDK context valid only for the duration of one session callback."""
+
+    modules: KsApiModules
+    app: Any
+
+
+class KompasSession:
+    """Own one worker, generated runtime modules, and one visible KOMPAS app."""
+
+    def __init__(
+        self,
+        *,
+        worker: KsApiWorker,
+        config: KsApiRuntimeConfig,
+        runtime_loader: RuntimeLoader,
+    ) -> None:
+        self._worker = worker
+        self._config = config
+        self._runtime_loader = runtime_loader
+        self._modules: KsApiModules | None = None
+        self._app: Any | None = None
+        self._connected = False
+        self._closed = False
+
+    async def connect(self) -> None:
+        """Load wrappers and attach to the already-open visible KOMPAS exactly once."""
+        if self._connected:
+            raise KompasError("KOMPAS session is already connected")
+        if self._closed:
+            raise KompasError("KOMPAS session is already closed")
+        self._worker.start()
+        try:
+            modules, app = await self._worker.submit_async(self._load_and_connect_on_thread)
+        except Exception as exc:
+            self._closed = True
+            self._worker.stop()
+            self._raise_as_kompas("session.connect", exc)
+        self._modules = modules
+        self._app = app
+        self._connected = True
+        logger.info(event_name(LogDomain.CAD, "ksapi_connect", LogEventType.COMPLETED))
+
+    def _load_and_connect_on_thread(self) -> tuple[KsApiModules, Any]:
+        modules = self._runtime_loader(self._config)
+        app = modules.ksapi.GetKompas()
+        if app is None:
+            raise KompasError(
+                "Откройте КОМПАС: KsAPICLink не видит открытый visible KOMPAS.exe. Backend не запускает КОМПАС сам."
+            )
+        return modules, app
+
+    async def aclose(self) -> None:
+        """Stop only the worker; never close the user's KOMPAS application."""
+        self._ensure_not_reentrant("session.close")
+        if self._closed:
+            return
+        self._closed = True
+        self._connected = False
+        self._modules = None
+        self._app = None
+        self._worker.stop()
+
+    async def run[T](
+        self,
+        *,
+        operation_name: str,
+        operation: Callable[[KompasContext], T],
+    ) -> T:
+        """Execute a complete typed operation as one atomic worker queue item."""
+        self._validate_operation(operation_name)
+        self._ensure_not_reentrant(operation_name)
+        self._ensure_connected()
+        logger.info(
+            event_name(LogDomain.BRIDGE, _OPERATION_PHASE, LogEventType.STARTED),
+            operation_name=operation_name,
+        )
+        try:
+            result = await self._worker.submit_async(lambda: operation(self._context()))
+        except Exception as exc:
+            logger.warning(
+                event_name(LogDomain.BRIDGE, _OPERATION_PHASE, LogEventType.FAILED),
+                operation_name=operation_name,
+                error=str(exc),
+            )
+            self._raise_as_kompas(operation_name, exc)
+        logger.info(
+            event_name(LogDomain.BRIDGE, _OPERATION_PHASE, LogEventType.COMPLETED),
+            operation_name=operation_name,
+        )
+        return result
+
+    def run_sync[T](
+        self,
+        *,
+        operation_name: str,
+        operation: Callable[[KompasContext], T],
+    ) -> T:
+        """Synchronous form of :meth:`run` for non-async integration seams."""
+        self._validate_operation(operation_name)
+        self._ensure_not_reentrant(operation_name)
+        self._ensure_connected()
+        logger.info(
+            event_name(LogDomain.BRIDGE, _OPERATION_PHASE, LogEventType.STARTED),
+            operation_name=operation_name,
+        )
+        try:
+            result = self._worker.submit(lambda: operation(self._context()))
+        except Exception as exc:
+            logger.warning(
+                event_name(LogDomain.BRIDGE, _OPERATION_PHASE, LogEventType.FAILED),
+                operation_name=operation_name,
+                error=str(exc),
+            )
+            self._raise_as_kompas(operation_name, exc)
+        logger.info(
+            event_name(LogDomain.BRIDGE, _OPERATION_PHASE, LogEventType.COMPLETED),
+            operation_name=operation_name,
+        )
+        return result
+
+    def _context(self) -> KompasContext:
+        modules = self._modules
+        app = self._app
+        if modules is None or app is None:
+            raise KompasError("KOMPAS session is not connected; call connect() first")
+        return KompasContext(modules=modules, app=app)
+
+    def _ensure_connected(self) -> None:
+        if not self._connected or self._closed:
+            raise KompasError("KOMPAS session is not connected; call connect() first")
+
+    def _ensure_not_reentrant(self, operation_name: str) -> None:
+        if self._worker.is_current_thread():
+            raise KompasReentryError(f"KOMPAS session re-entry is forbidden from a worker callback: {operation_name}")
+
+    @staticmethod
+    def _validate_operation(operation_name: str) -> None:
+        if not operation_name.strip():
+            raise ValueError("operation_name must be a non-empty string")
+
+    @staticmethod
+    def _raise_as_kompas(operation_name: str, exc: Exception) -> None:
+        if isinstance(exc, KompasError):
+            raise exc
+        raise KompasError(f"{operation_name}: KsAPI error — {type(exc).__name__}: {exc}") from exc
+
+
+async def create_kompas_session(config: KsApiRuntimeConfig) -> KompasSession:
+    """Create and connect one session with one worker; no singleton or second owner."""
+    session = KompasSession(
+        worker=KsApiWorker(
+            thread_name=KSAPI_WORKER_THREAD_NAME,
+            stop_timeout_s=KSAPI_WORKER_STOP_TIMEOUT_S,
+        ),
+        config=config,
+        runtime_loader=load_ksapi_runtime,
+    )
+    await session.connect()
+    return session
+
+
+async def create_kompas_session_from_bin_dir(bin_dir: Path | None) -> KompasSession:
+    """Build an explicit runtime config and return its connected session."""
+    return await create_kompas_session(runtime_config_from_bin_dir(bin_dir))

kompas_kernel/kompas/units.py

@@ -0,0 +1,48 @@
+"""Normalize raw CAD-kernel values to the public millimetre contract."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import assert_never
+
+MM_PER_CM = 10.0
+
+
+class SourceUnit(StrEnum):
+    """Unit attached to a value read from the CAD kernel."""
+
+    MM = "mm"
+    CM = "cm"
+
+
+def length_to_mm(value: float, source: SourceUnit) -> float:
+    """Convert a length to millimetres."""
+    match source:
+        case SourceUnit.MM:
+            return value
+        case SourceUnit.CM:
+            return value * MM_PER_CM
+        case _:
+            assert_never(source)
+
+
+def area_to_mm2(value: float, source: SourceUnit) -> float:
+    """Convert an area to square millimetres."""
+    match source:
+        case SourceUnit.MM:
+            return value
+        case SourceUnit.CM:
+            return value * MM_PER_CM * MM_PER_CM
+        case _:
+            assert_never(source)
+
+
+def volume_to_mm3(value: float, source: SourceUnit) -> float:
+    """Convert a volume to cubic millimetres."""
+    match source:
+        case SourceUnit.MM:
+            return value
+        case SourceUnit.CM:
+            return value * MM_PER_CM * MM_PER_CM * MM_PER_CM
+        case _:
+            assert_never(source)

kompas_kernel/ksapi_static/__init__.py

@@ -0,0 +1,8 @@
+"""Static knowledge of the installed KsAPI build: recipes, wrapper grep, name inventory
+and reusable fact violations. This package does NOT know the RAG runtime or a live
+`KompasSession` — those stay in Copilot (`kompas_copilot.knowledge`). The `run_python`
+sandbox policy (import/call allowlists, namespace-drift check) is a separate kernel
+package, `kompas_kernel.features.ksapi_automation` (E17.04e), which consumes these
+reusable facts as a parameter rather than duplicating them. No eager re-export, same as
+the rest of `kompas_kernel`.
+"""