FAQ¶
When to read: You have a specific question before cloning or after a first run. For setup failures see TROUBLESHOOTING.
Do I need an OpenAI (or other LLM) API key?¶
No. The default insight is a template filled from gold KPIs. The critic checks numbers against the warehouse. make e2e / ./scripts/verify.sh run with no cloud LLM.
Optional LLM wording is PARTIAL: set OPERATOR_ETL_INSIGHT_BACKEND=llm after uv sync --extra llm. Local Ollama: OPERATOR_ETL_LLM_BASE_URL=http://127.0.0.1:11434/v1 and OPERATOR_ETL_LLM_MODEL=llama3.2:3b. Missing extra, missing key, or a failed call falls back to the template. Not proven with a live API in CI. Install: LLM.md. Cards: MODELS.md. Screenshots: TOUR.md.
How do I install a local model?¶
Install Ollama, pull llama3.2:3b, then point Operator ETL at http://127.0.0.1:11434/v1. Full recipe: LLM.md. You do not need a discrete GPU (Apple Silicon Metal or CPU). Which tag and RAM: MODELS.md.
Does gold JSON leave my machine?¶
Template: no. Ollama on localhost: no — JSON stays on-box. OpenAI API / Cloud Run with insight_backend=llm: yes — numeric gold KPIs go to the host. Comment bodies still never go. That boundary is NIST Map: NIST.md · MODELS.md.
Are you NIST certified?¶
No. We align selected practices from AI RMF 1.0, AI 600-1 (only the generative risks this demo mitigates), and SP 800-122. We do not claim NIST certification, FedRAMP, or an ATO. NIST.md.
Is this production-ready FOIA software?¶
No. It is a reproducible demo / reference architecture. Proven locally: ingest, regex PII, quarantine, gold, LangGraph, critic, MCP allowlist. Not proven in CI: live GCP, Presidio, officer approval UI, Regulations.gov.
See FINAL-REVIEW.md · RISKS.md. Safe public claim: clone and run ./scripts/verify.sh.
What is medallion?¶
A three-layer warehouse: keep the raw file, keep only valid rows, publish only counts and rates. The medal names (bronze / silver / gold) are labels for trust, not metal. We add quarantine for bad rows with a reason. Lesson: PATTERNS.md. One-liners: GLOSSARY.md.
Can I use this for data that is not FOIA?¶
Yes, as a pattern. The repo already runs a second domain (orders) on the same critic and policy plane. You change schema, gold SQL, and the insight template — you do not remove bronze, quarantine, the critic, or the MCP allowlist. Sketches for 311, grants, inspections: APPLY.md. YAML how-to: ADD-A-SOURCE.md.
What should I know about residual risk?¶
Green verify.sh does not mean production FOIA software. Regex PII misses names/addresses; the critic matches digits not meaning; LLM fallback can still look complete; cloud llm sends gold KPI JSON off-box; HITL is a graph status, not an approval product. Briefing: RISKS.md.
Why do 2 of 12 comments go to quarantine?¶
The sample CSV includes rows that should fail validation: empty body and an invalid timestamp (not-a-date). Quarantine keeps them with error text. That is the point — bad rows are not silent.
After verify: silver=10, quarantined=2. Details: WALKTHROUGH.
Are the emails and SSNs in samples/ real?¶
No. They are synthetic test patterns (jane.doe@example.com, 123-45-6789). Do not commit real FOIA records. Do not post the raw CSV on social without saying it is fake PII.
DuckDB vs BigQuery — which do I use?¶
| Environment | Warehouse |
|---|---|
| Laptop / CI / first clone | DuckDB file (OPERATOR_ETL_WAREHOUSE) |
| GCP staging (PARTIAL) | BigQuery via Terraform — SCALING |
Same graph nodes and critic. Lift is a backend swap, not a rewrite of policy.
Can I give an agent the whole warehouse?¶
No. MCP exposes three tools: get_gold_metrics, run_quality_sql (allowlisted IDs only), get_run_status. Vault decrypt and ad-hoc SQL are denied. MCP.
What security controls run in CI?¶
Every push and PR runs the proof gate (e2e + FOIA demo), Docker build, gitleaks, bandit (SAST on src/), and pip-audit (SCA on frozen deps). Bandit and pip-audit are GitHub Actions jobs, not pytest. Guide: SECURITY-HARDENING.md.
Is rate limiting production-grade?¶
No. The graph-runner uses an in-process per-client sliding window (RATE_LIMIT_PER_MINUTE, default 60). That is enough for a single instance. Multi-instance or public traffic needs Cloud Armor or an API gateway. RISKS.md.
Why does a second ingest report rows_in=0?¶
Idempotency. The file content hash is stored in ingest_files. Re-dropping the same CSV skips bronze. Fresh warehouse: ./scripts/demo_mvp.sh or verify.sh.
The GitHub repo says public in the docs — is it public?¶
The license is Apache-2.0 and docs assume a public clone URL. Visibility is a GitHub setting. If clone fails with 404, the repo may still be private — ask the owner, or use a fork you can access.
Where is the wiki vs the PDF pack?¶
| Surface | Use |
|---|---|
This wiki (docs/ + GitHub Pages) |
Browse and learn without attaching files |
| share/ | One-pager / slides / white paper PDF for interviews |
okf/ |
Agent-oriented knowledge bundle |
Always invite ./scripts/verify.sh in posts.
How do versions work? Will docs PRs keep bumping the package?¶
No. Merging to master updates the wiki only. A git tag (v0.5.0-beta.1, then v0.5.0) publishes the GitHub Release, GHCR image, and GitHub Packages wheel. Daily PRs append to CHANGELOG [Unreleased] and do not change pyproject.toml. Tags are never moved; a bad beta is followed by -beta.2. VERSIONING.md.
How do I add my own CSV?¶
See ADD-A-SOURCE.md. Register it in pipelines/*.yaml, add a sample, add a test.