sw-ourbox-apps-compass

Compass is a mobile-first, local-first civic decision-support app for OurBox.

It now uses a guided conversation instead of a questionnaire wall:

• upload exactly one voter-information packet per workspace
• build a packet-derived conversation backbone before the first question
• start with rapport, then packet priorities, then final review, then explicit report confirmation
• keep the workflow state machine authoritative
• preserve Markdown + YAML artifact provenance for packet, memory, turns, fit, comparison, report, and reply-audio outputs
• export a personalized report as PDF and DOCX
• render a reproducible demo/tutorial MP4 from saved artifacts

Runtime model

Compass supports the same local-first reasoning split in two modes:

1. heuristic for deterministic CI and verification
2. llama_cpp for a local llama.cpp OpenAI-compatible server running Qwen

Model target:

• upstream repo: Qwen/Qwen3-4B-GGUF
• preferred file: Qwen3-4B-Q4_K_M.gguf

Reply audio target:

• TTS: espeak-ng
• reply format: WAV

CI uses mock TTS. Local pre-release smoke is expected to use real local reply-audio binaries.

Quickstart

cd apps/ourbox-compass
python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8080

Useful runtime env vars:

• COMPASS_RUNTIME_MODE=heuristic|llama_cpp
• COMPASS_LLM_BASE_URL=http://127.0.0.1:8081
• COMPASS_LLM_MODEL=Qwen3-4B-Q4_K_M
• COMPASS_TTS_PROVIDER=mock|espeak-ng

Verification

Bundled official voter-guide PDFs are intentionally not shipped in this repo.

Run verification against an external directory or external zip:

python scripts/run_verification.py \
  --external-guides-zip /path/to/official_voter_guides_examples.zip \
  --output-root verification/generated

or:

python scripts/run_verification.py \
  --guides-root /path/to/extracted-guides \
  --output-root verification/generated

Then capture:

• pytest -q > verification/generated/pytest-results.txt
• bash scripts/check-apps-manifest.sh > verification/generated/check-apps-manifest.txt