kontextual-engine/docs/stack-decision.md

Stack Decision

Date: 2026-05-05

Decision

kontextual-engine starts as a Python 3.12+ package with:

• Distribution name: kontextual-engine
• Import package: kontextual_engine
• Build backend: setuptools
• Test runner: pytest
• Source layout: src/kontextual_engine
• First service framework: FastAPI, added as an optional service extra

The first implementation should stabilize the programmatic API before exposing HTTP endpoints. The service layer should wrap the same contracts rather than becoming the architecture driver.

Initial Dependencies

Core dependencies:

• pydantic>=2.0 for explicit runtime models and validation.

Optional extras:

• dev: pytest
• service: fastapi, uvicorn
• storage: sqlalchemy
• markdown: local markitect-tool adapter dependency
• llm: local llm-connect adapter dependency

Rationale

The PRD/FRS describe a headless runtime, not a CLI-first tool. Python keeps the repo aligned with markitect-tool, llm-connect, and State Hub while allowing the engine to expose both programmatic and service interfaces.

FastAPI is appropriate for the service boundary because State Hub already uses that stack locally, but it remains optional until KONT-WP-0003 defines stable artifact, collection, storage, query, workflow, and context contracts.

Deferred Decisions

• Durable storage backend selection beyond initial repository interfaces.
• HTTP endpoint shape and versioning.
• Whether an administrative CLI is needed.
• Lockfile/SBOM source, once dependencies are installed in this repo.