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

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

cd senti
pip install -r requirements.txt

Step 3: Build Rust Math Engine

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

createdb senti_dev

Set in .env:

DATABASE_URL=postgresql://postgres:yourpassword@localhost:5432/senti_dev

Step 5: Run the Backend

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

cd frontend
npm install
npm run dev

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

Step 7: Run Tests

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.