From 67010a0429d38d63833758498ef33267b47804a5 Mon Sep 17 00:00:00 2001 From: tegwick Date: Tue, 5 May 2026 00:53:28 +0200 Subject: [PATCH] Finish repository foundation workplan --- CLAUDE.md | 23 +++++++++-- README.md | 9 ++++ docs/stack-decision.md | 50 +++++++++++++++++++++++ pyproject.toml | 40 ++++++++++++++++++ src/kontextual_engine/__init__.py | 6 +++ tests/test_package_contract.py | 6 +++ workplans/KONT-WP-0001-repo-foundation.md | 9 ++-- 7 files changed, 137 insertions(+), 6 deletions(-) create mode 100644 docs/stack-decision.md create mode 100644 pyproject.toml create mode 100644 src/kontextual_engine/__init__.py create mode 100644 tests/test_package_contract.py diff --git a/CLAUDE.md b/CLAUDE.md index 05051a6..488ccf7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -13,8 +13,9 @@ At session start, orient from: 2. `INTENT.md` 3. `wiki/ProductRequirementsDocument.md` 4. `wiki/FunctionalRequirementsSpecification.md` -5. `docs/markitect-main-scope-assessment.md` -6. Active files in `workplans/` +5. `docs/stack-decision.md` +6. `docs/markitect-main-scope-assessment.md` +7. Active files in `workplans/` ## State Hub @@ -73,6 +74,23 @@ Prefer clean reimplementation around the new PRD/FRS. Use `markitect-main` as reference material for behavior, tests, and domain vocabulary, not as an architecture to copy wholesale. +## Stack And Commands + +- Python target: 3.12+ +- Distribution: `kontextual-engine` +- Import package: `kontextual_engine` +- Build backend: `setuptools` +- Test runner: `pytest` +- Source layout: `src/kontextual_engine` +- Service framework: FastAPI as an optional boundary after the programmatic API + stabilizes + +Run tests: + +```bash +python3 -m pytest +``` + ## Workplans Workplans live in `workplans/` and follow the Custodian ADR-001 convention: @@ -81,4 +99,3 @@ Workplans live in `workplans/` and follow the Custodian ADR-001 convention: kontextual-engine`, and `owner: codex`. - Tasks are embedded as headed sections with fenced `task` blocks. - State Hub may index these files, but the files remain authoritative. - diff --git a/README.md b/README.md index 7be4910..63a5795 100644 --- a/README.md +++ b/README.md @@ -9,5 +9,14 @@ Start here: - `wiki/ProductRequirementsDocument.md` - `wiki/FunctionalRequirementsSpecification.md` - `SCOPE.md` +- `docs/stack-decision.md` - `docs/markitect-main-scope-assessment.md` - `workplans/` + +## Development + +This repo uses Python 3.12+, setuptools, a `src/` package layout, and pytest. + +```bash +python3 -m pytest +``` diff --git a/docs/stack-decision.md b/docs/stack-decision.md new file mode 100644 index 0000000..34f098a --- /dev/null +++ b/docs/stack-decision.md @@ -0,0 +1,50 @@ +# 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. + diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..0e39c87 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,40 @@ +[build-system] +requires = ["setuptools>=69"] +build-backend = "setuptools.build_meta" + +[project] +name = "kontextual-engine" +version = "0.1.0" +description = "Headless knowledge runtime for persistent, operable structured knowledge" +readme = "README.md" +requires-python = ">=3.12" +license = { text = "MIT" } +dependencies = [ + "pydantic>=2.0", +] + +[project.optional-dependencies] +dev = [ + "pytest>=8", +] +service = [ + "fastapi>=0.110", + "uvicorn>=0.27", +] +storage = [ + "sqlalchemy>=2.0", +] +markdown = [ + "markitect-tool @ file:///home/worsch/markitect-tool", +] +llm = [ + "llm-connect @ file:///home/worsch/llm-connect", +] + +[tool.setuptools.packages.find] +where = ["src"] + +[tool.pytest.ini_options] +testpaths = ["tests"] +pythonpath = ["src"] + diff --git a/src/kontextual_engine/__init__.py b/src/kontextual_engine/__init__.py new file mode 100644 index 0000000..0d57a11 --- /dev/null +++ b/src/kontextual_engine/__init__.py @@ -0,0 +1,6 @@ +"""Headless knowledge runtime package.""" + +__all__ = ["__version__"] + +__version__ = "0.1.0" + diff --git a/tests/test_package_contract.py b/tests/test_package_contract.py new file mode 100644 index 0000000..2cd75de --- /dev/null +++ b/tests/test_package_contract.py @@ -0,0 +1,6 @@ +from kontextual_engine import __version__ + + +def test_package_exports_version() -> None: + assert __version__ == "0.1.0" + diff --git a/workplans/KONT-WP-0001-repo-foundation.md b/workplans/KONT-WP-0001-repo-foundation.md index 1bb94d8..5ad7256 100644 --- a/workplans/KONT-WP-0001-repo-foundation.md +++ b/workplans/KONT-WP-0001-repo-foundation.md @@ -4,11 +4,11 @@ type: workplan title: "Repository Foundation And State Hub Integration" domain: markitect repo: kontextual-engine -status: active +status: done owner: codex topic_slug: markitect created: "2026-05-03" -updated: "2026-05-03" +updated: "2026-05-05" state_hub_workstream_id: "52ff9c49-edcf-4150-8895-c6b31f5aa075" --- @@ -77,10 +77,13 @@ workplan files. ```task id: KONT-WP-0001-T005 -status: todo +status: done priority: medium state_hub_task_id: "616e0476-7b65-4079-b545-13e0fc9436f7" ``` Choose the first implementation stack, dependency manager, test command, and service framework. Record the decision before adding application code. + +Output: `docs/stack-decision.md`; executable scaffold added in `pyproject.toml`, +`src/kontextual_engine/`, and `tests/`.