Development | Kumoss

This guide covers contributing to Kumoss itself — running the repository’s own test suites, checks, and tooling. It does not cover deploying or operating Kumoss; for that, see Quickstart and Deploy to production.

Prerequisites

Before contributing, read Contributing for the Contributor License Agreement, the code of conduct, and the process for proposing a change.

Repository layout

The repository is a monorepo: the FastAPI core in core/, four sidecar services in services/, the React web application in client/web/, and the sidecar OpenAPI contracts in contracts/. See Architecture for how they fit together.

Running the stack for development

Copy each env.sample to a .env next to it (core/.env is required), set the two model strings in config.yaml, and run docker compose up --build. Quickstart is the step-by-step guide.

docker compose up --watch syncs core/ into the running container, but the server runs without --reload and does not pick up the change: run docker compose restart core after a sync (or docker compose up -d core). It does not sync config.yaml, which is baked into the image.

Core tests

Python 3.13, uv. pytest and pytest-cov are part of the tooling dependency group, so sync the project first:

cd core
uv sync --frozen --group tooling
uv run --no-sync pytest tests/

Async tests use unittest.IsolatedAsyncioTestCase (no pytest-asyncio plugin, no --asyncio-mode flag). core/tests/conftest.py supplies placeholder values for the LLM credential, the database URL and the mandatory KUMOSS_IAC_TOKEN that the configuration module validates at import; suites that talk to PostgreSQL or Redis need the compose stack (or point KUMOSS_SQL_DATABASE_URL and KUMOSS_REDIS_URL at your own instances).

Type checking

basedpyright lives in the tooling dependency group, which the project install above does not include; install the group first:

cd core
uv pip install --system --group tooling -r pyproject.toml
basedpyright

pyrightconfig.json only includes src/ — tests are not type-checked.

Frontend checks

Node 24:

cd client/web
npm ci
npm run lint
npm run test:ci
npm run build

Sidecar tests

Each sidecar service has its own tooling dependency group with pytest and its test helpers (the exact set differs per service):

cd services/<name>
uv sync --group tooling
uv run pytest

Linting and formatting

pre-commit run --all-files runs Ruff (ruff check and ruff format), the REUSE check, and gitleaks secret scanning. Install the hooks once with pre-commit install.

Continuous integration

Pull requests run Repolinter, the REUSE compliance check, the Conventional Commits check, and an offline Markdown link and anchor check, plus a Verify workflow: frontend type check, tests, and production build, and the pytest suite of each sidecar service. The core suite is not run in CI, so run it locally against the compose stack before opening a pull request.

Regenerating sidecar clients

Changing a sidecar’s behavior means updating its spec in contracts/openapi/, its conformance suite in contracts/conformance/, and regenerating the core’s client for that service. From core/, once per service:

uv run --group tooling openapi-python-client generate \
  --path ../contracts/openapi/<service>.v1.yaml \
  --config ../contracts/openapi-python-client.yaml \
  --meta none \
  --output-path src/clients/<service> \
  --overwrite

Regeneration drops the SPDX headers from the generated files; re-add them afterwards. Do not hand-edit anything under core/src/clients/{authz,iac,mapping,notifications}/.

Pull requests

Once your change is ready, Contributing covers the pull-request process and the checks it must pass.