kamidso-back/docs/kamidso

Kamidso Next — Phase 1

Product architecture with an in-process execution engine. See ARCHITECTURE.md for invariants and boundaries.

Prerequisites

• Python 3.11+, uv
• Node.js LTS
• MongoDB (local or Docker)
• Model API keys in environment (OPENAI_API_KEY, etc.)

Development

# Terminal 1 — Mongo
docker compose -f docker/kamidso/docker-compose.yml up -d

# Terminal 2 — API (this repository)
export KAMIDSO_ENV=development
export MONGODB_URI=mongodb://127.0.0.1:27017/kamidso
python -m kamidso.cli serve --host 127.0.0.1 --port 5670 --config configs/engine.toml

# Terminal 3 — Frontend repository
npm install && npm run dev

Or from this repository:

make dev

Open http://localhost:5173 — sign in with KAMIDSO_ADMIN_EMAIL / KAMIDSO_ADMIN_PASSWORD.

API boundary

Frontend and product clients use only /api/kamidso/v1/*. DB-GPT routes are internal implementation details.

Configuration

• Product: configs/kamidso/{development,production,test}.toml
• Engine: --config / KAMIDSO_ENGINE_CONFIG (default: configs/engine.toml)
• Secrets: environment variables (MONGODB_URI, KAMIDSO_JWT_SECRET, model keys)
• Native DB-GPT memory/prompt flags: NATIVE_DBGPT_MEMORY.md

Tests

python -m pytest tests/kamidso -q

Golden benchmark manifest: tests/kamidso/benchmarks/golden.yaml

Repository folders (keep)

These are required for Kamidso development and must not be removed during cleanup:

• docs/kamidso/ — product docs
• docker/ — Mongo compose and the Walmart sample CSV
• configs/ — engine and Kamidso configuration
• kamidso/ — product API plus execution engine
• frontend repository — web UI
• skills/ — analysis skills
• tests/kamidso/ — product tests

Product entry: kamidso serve, plus the frontend repository. See ARCHITECTURE.md and REPO_LAYOUT.md.

Production layout

Coolify deploys the frontend repository and this repository as two Dockerfile applications, with MongoDB as a separate database resource. See COOLIFY.md.

See REPO_LAYOUT.md for the tree. Summary:

• Product: kamidso/, configs/kamidso/, tests/kamidso/
• Engine: kamidso/engine/, configs/engine.toml, skills/
• Infra compose: docker/kamidso/docker-compose.yml
• Not in git: data/, logs/, .venv/, .env