Skip to content

⚙ Environment

Local setup for developing khata-app.

▶ Create The Venv

1
2
3
4
# PowerShell, from repo root
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev,doc]"

The repo is Python 3.13 compatible (dev venv runs 3.13.5). pyproject.toml declares the app dist as packages domain*, infra*, interfaces*.

📦 Key Tools

Tool Where Notes
pytest .venv\Scripts\pytest.exe Unit + integration tests
ruff .venv\Scripts\ruff.exe Lint/format checks
doc-forge .venv\Scripts\doc-forge.exe Docs engine (lib/api/wiki/MCP)
mypy (not installed) Optional type gate; stubs currently lint-clean instead

doc-forge is installed from the local aetos source (pip install -e "C:\Users\vishe\WorkSpace\code\aetos\doc-forge[mkdocs,mcp]"); it isn't on PyPI.

💡 Pin Note (Python 3.13)

MkDocs highlighter crashes on pygments 2.20 under 3.13 (filename=None bug). Keep pygments==2.19.2 in the khata venv:

1
.\.venv\Scripts\python.exe -m pip install "pygments==2.19.2"

🧭 Package Map

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
khata-app/
├── main.py, worker.py, init.py   # entrypoints + wiring
├── openapi.yaml                   # API contract (drives routing)
├── interfaces/                    # openapi handlers, sse, report, cli
├── domain/                        # models · ports · services · enrichment
├── infra/                         # mongo repos · cache · fetchers · llm pools
├── pipelines/                     # extraction families + enrichment nodes
├── tests/                         # unit + integration suites
├── docs/                          # lib sources, api, wiki, mcp bundles (generated + authored)
├── docforge.nav.yml               # lib navigation spec
└── py.typed (in each package)     # typed marker for stub distribution

Building Docs · Testing · Running The Service