Metadata-Version: 2.5
Name: kompas-kernel
Version: 0.0.2
Summary: Framework-neutral foundation shared by KOMPAS Copilot and standalone integrations
Requires-Python: >=3.12
Requires-Dist: pillow>=12.3.0
Requires-Dist: pydantic<3,>=2.11
Requires-Dist: pyyaml>=6
Requires-Dist: structlog>=25.3
Description-Content-Type: text/markdown

# kompas-kernel

Framework-neutral foundation for working with a live KOMPAS-3D session, shared by
KOMPAS Copilot and standalone KOMPAS integrations (including the planned
`kompas3d-bridge-mcp` server).

## What it owns

- `kompas_kernel.kompas` — session, worker, runtime and units. Raw KsAPI handles never
  leave the session callback; callers get typed DTOs and errors.
- `kompas_kernel.features` — framework-free capability slices: `document_session`
  (context, digest, screenshot, checkpoint/restore), `ksapi_automation` (static gate,
  execution seam and the canonical checkpointed `run_python`), `part_authoring`,
  `assembly_navigator`, `geometry_3d`, `wrench_clearance`.
- `kompas_kernel.ksapi_static` — static knowledge about the installed KsAPI build:
  recipe catalog, generated-wrapper grep, name inventory and reusable gate facts. It
  knows nothing about RAG runtime, the live session or `run_python` sandbox policy.
- `kompas_kernel.standards` — neutral normative DTOs, curated tables and pure
  norm-selection functions.
- `kompas_kernel.observability` — logging runtime and taxonomy, configured explicitly
  rather than from application settings.
- `kompas_kernel.utils` — shared Pydantic validation policy (`CustomModel`) and atomic
  filesystem primitives.

## What it does not own

No agent loop, no LLM settings, no HTTP or MCP transport, no model-facing tool
descriptions. Those belong to the consumer: in Copilot they live in
`kompas_copilot.core` and `kompas_copilot.transports`.

The dependency is one-way — `kompas_kernel` never imports `kompas_copilot`, and that is
enforced by `tests/architecture/test_layer_boundaries.py` plus a clean-venv import check
of the built wheel.

Public modules are imported explicitly; `kompas_kernel` itself has no eager imports.

## Mandatory mutation policy

Every model-facing Python execution path goes through one shared decorator,
`kompas_kernel.features.document_session.checkpointed`. Both `run_python`
(`features.ksapi_automation.run_python`) and `build_geometry`
(`features.part_authoring.build_geometry`) apply it exactly once, in the domain layer,
so a transport cannot reach the raw runner and skip the checkpoint. Without a captured
checkpoint the code is not executed at all; a failure after execution starts triggers
rollback.
