docs/LOCAL_SETUP.md

# Senti AI — Local Development Setup

## Prerequisites

- **Python 3.12+**
- **Rust toolchain** (for building `senti_calc`)
- **PostgreSQL 14+** (or use SQLite for local dev)
- **Redis** (optional — falls back to `fakeredis` for dev)
- **Node.js 18+** (for frontend)

## Step 1: Clone and Environment

```bash
git clone <repo-url> senti_ai
cd senti_ai

# Copy environment config
cp .env.example .env

# Edit .env with your values — at minimum:
#   DATABASE_URL=sqlite:///senti_db.sqlite   (for local dev)
#   JWT_SECRET_KEY=<generate with: python -c "import secrets; print(secrets.token_hex(32))">
```

## Step 2: Python Dependencies

```bash
cd senti
pip install -r requirements.txt
```

## Step 3: Build Rust Math Engine

```bash
cd senti_calc
pip install maturin
maturin develop --release
cd ..

# Verify it works:
python -c "import senti_calc; print(senti_calc.paye_kenya_2024(95000))"
```

## Step 4: Database Setup

### Option A: SQLite (simplest for dev)
Set in `.env`:
```
DATABASE_URL=sqlite:///senti_db.sqlite
```
Tables are created automatically on first run.

### Option B: PostgreSQL
```bash
createdb senti_dev
```
Set in `.env`:
```
DATABASE_URL=postgresql://postgres:yourpassword@localhost:5432/senti_dev
```

## Step 5: Run the Backend

```bash
cd senti
python -m uvicorn backend.api.main:app --reload --port 8000
```

API is now at: `http://localhost:8000`
API docs at: `http://localhost:8000/docs`

## Step 6: Run the Frontend

```bash
cd frontend
npm install
npm run dev
```

Frontend is now at: `http://localhost:5173`

## Step 7: Run Tests

```bash
cd senti

# All tests
pytest tests/ -v

# Unit tests only
pytest tests/unit/ -v

# Integration tests
pytest tests/integration/ -v

# Specific module
pytest tests/unit/test_engines/test_formula_registry.py -v
```

## Common Issues

### `ModuleNotFoundError: No module named 'senti_calc'`
Build the Rust engine first: `cd senti_calc && maturin develop --release`

### `ModuleNotFoundError: No module named 'core'`
Run from the `senti/` directory, or set `PYTHONPATH=./senti`

### `JWT_SECRET_KEY not set`
Generate one: `python -c "import secrets; print(secrets.token_hex(32))"`
Add it to your `.env` file.

### Database connection errors
Check `DATABASE_URL` in `.env`. For local dev, use SQLite.