Ripplect

Humanitarian strategy sandbox: crisis data, fragility simulation (TTC, Equity Shift), Success Twins (semantic project matching), and contrarian memos.

Stack: Backend: FastAPI (uvicorn). Frontend: Vite + React.

1. Build Parquet data (from repo root):

   python scripts/preprocess.py

   Produces backend/data/crises.parquet and backend/data/projects.parquet.

   Success Twin project data: The app loads projects from data/projects.parquet. If you see "Not enough projects in crisis country MLI" (or BFA/NER/TCD), seed at least 2 projects per epicenter:

   python -m backend.scripts.seed_epicenter_projects

   This adds synthetic MLI, BFA, NER, TCD projects to data/projects.parquet so "Find Success Twin" works for every epicenter.

2. Backend dependencies:

   pip install -r backend/requirements.txt

3. Frontend dependencies:

   cd frontend && pnpm install

   Or: npm install if you don’t use pnpm.

From repo root:

uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000

API: http://localhost:8000

cd frontend && pnpm dev

Or: npm run dev. App: http://localhost:5173 (or next free port).

Optional: set VITE_API_BASE_URL=http://localhost:8000 in frontend/.env.local (defaults to that if unset).

Single one-command smoketest (run from repo root):

python run_smoketest.py

Prints a dict of *_ok flags and a final line: All *_ok flags True: True or False. Exit code 0 only if all flags are True. Use before hacking, after pulling, and before demos.

Lightweight sanity check of HTTP endpoints (no server needed; uses FastAPI TestClient):

python backend/check_api_contract.py

Verifies GET /crises/, POST /simulate/, GET /twins/PRJ001, POST /memos/. Exits 0 on PASS, 1 on FAIL.

The “Similar Projects (VectorAI)” feature uses the Actian VectorAI DB beta for nearest-neighbor search over project embeddings. Without it, the backend falls back to in-memory search from parquet.

Clone and start the Actian VectorAI DB (gRPC default localhost:50051):

git clone https://github.com/hackmamba-io/actian-vectorAI-db-beta
cd actian-vectorAI-db-beta && docker compose up -d

Install the actiancortex wheel from the Actian repo (see that repo’s README for the latest install steps). Example:

pip install path/to/actian-vectorAI-db-beta/wheels/actiancortex-*.whl

Set in .env or .env.local (or export before running backend/ingestion):

Ensure project embeddings exist, then run the ingestion script (from repo root):

# Build project embeddings (if not already done)
python -m dataml.src.embeddings   # or your DataML pipeline

# Ingest into VectorAI DB
python -m backend.scripts.ingest_vectorai_projects

This reads dataml/data/processed/project_embeddings.parquet and batch-upserts into the Actian collection. Then “Find similar projects” in the app uses the real vector DB.

1. Start – Open the app. Left panel: “Configure Scenario.”
2. Pick a crisis – Choose one from the dropdown (e.g. “GHO Estimates (SYR 2024)”).
3. Set funding – Adjust Health Δ and WASH Δ (e.g. -1M Health, +0.5M WASH).
4. Set shocks – Optionally change Inflation %, Drought, Conflict level.
5. Run scenario – Click “Run Scenario.” Center “Impact” panel shows baseline vs scenario TTC and Equity Shift.
6. Find Success Twin – Right panel: click “Find Success Twin” for sample project PRJ001.
7. Generate memo – Click “Generate Memo.” Read title, body, and key risks.
8. Vary inputs – Change funding or shocks, run again, compare impact and memo.