# Kamidso Next — Phase 1

Product architecture with an in-process execution engine. See [ARCHITECTURE.md](./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

```bash
# 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:

```bash
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](./NATIVE_DBGPT_MEMORY.md)

## Tests

```bash
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](./ARCHITECTURE.md) and [REPO_LAYOUT.md](./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](./COOLIFY.md).

See [REPO_LAYOUT.md](./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`