oll.in — local dev-test manual

0 · Prerequisites tiny

• Python 3.11+ (3.12/3.13 fine) and git. macOS or Linux.
• No API keys, no Docker, no database. Everything runs in-process on synthetic data.
• The demo makes a throwaway venv at .venv-demo/ (gitignored) on first run; re-runs are instant.

1 · The showcase demo recommended — see all three POCs at once

1. Get the branch: git fetch origin && git checkout poc/ollin-demo (it merges PRs #86/#87/#88).
2. Run it: sh scripts/poc_demo.sh — first run builds the venv + installs the two services' deps (~1 min); later runs boot in seconds.
3. Open http://localhost:8099. Three panels: Your evidence · Your dossier (click "Generate the dossier") · Career Radar.
4. Stop it: Ctrl-C, or from another shell pkill -f demo/server.py.

Verify the API without the browser

With the server up, these three curls exercise the whole loop. Outputs shown are the real responses I got:

# Career Radar — the oll-scout tick (fixture jobs → scored)
curl -s localhost:8099/api/demo/radar | python3 -m json.tool
→ 7 matches, ranked. Top: 91 — Senior Backend Engineer (Python), Helvetia Fintech AG

# Grounding — cited retrieval over the synthetic corpus
curl -s -X POST localhost:8099/api/demo/ground -H 'content-type: application/json' -d '{}'
→ { backend, collection:"mem:user:synthetic-nadia", grounded:[…], evidence:[…], floor, context_blob }

# Grounding — the HONEST ABSTAIN path (off-corpus query)
curl -s -X POST 'localhost:8099/api/demo/ground?abstain=1' -H 'content-type: application/json' -d '{}'
→ { "abstained": true }   (cosine 0.072 < floor 0.08 — no fabricated citation)

# Dossier — the 3 verbs on the retrieved context (offline mock model)
curl -s -X POST localhost:8099/api/demo/dossier -H 'content-type: application/json' -d '{}'
→ { tailored_cv, cover_letter, interview_prep, citations }  provider=mock-offline

2 · Test each POC on its own tests · service · curl

Each POC is also its own branch you can check out and test in isolation. Standard house pattern: make a venv, install the service's requirements.txt + pytest, run the suite. Commands below are verified.

2a · Dossier verbs — poc/ollin-dossier-verbs (PR #87)

git checkout poc/ollin-dossier-verbs
cd services/oll-write
python3 -m venv .venv && . .venv/bin/activate
pip install -q -r requirements.txt pytest
python -m pytest -q                 # → 172 passed  (150 baseline + 22 new)
python scripts/poc_dossier.py       # offline: prints the 3 dossier outputs from synthetic CV+JD

Watch for the honest gap-marker in the CV output — e.g. [add: German level not stated in profile — confirm C1] — proof the "write only from the evidence, leave a gap rather than invent" rule fires.

2b · Career Radar — poc/oll-scout (PR #88)

git checkout poc/oll-scout
cd services/oll-scout
python3 -m venv .venv && . .venv/bin/activate
pip install -q -r requirements.txt pytest
python -m pytest -q                 # → 32 passed
python scout_cron.py --once         # ONE synthetic tick → prints the ranked digest

2c · Synthetic RAG — poc/ollin-rag-synthetic (PR #86)

git checkout poc/ollin-rag-synthetic
python3 scripts/poc/seed_synthetic_corpus.py     # ingest 5 synthetic docs / 26 chunks
python3 scripts/poc/retrieve_and_ground.py       # retrieve cited passages + show the abstain demo
python3 -m pytest scripts/poc/test_rag_poc.py -q # → 5 passed (relevance + abstain)

This fills a local RAG store with a synthetic candidate corpus and proves retrieval returns real cited passages and abstains on an off-corpus query. It uses a local stand-in (oll-memory's own default keyless embedder); it never touches the production memory service.

3 · What I verified run, not assumed

4 · What's real vs mock so you read the output right