| --- |
| title: ParaPilot — Illinois Divorce Navigator |
| emoji: "⚖️" |
| colorFrom: indigo |
| colorTo: gray |
| sdk: docker |
| app_port: 8000 |
| pinned: true |
| short_description: Grounded, cited legal GPS for Illinois divorce |
| --- |
| |
| # ParaPilot |
|
|
| **A grounded, cited "legal GPS" for the Illinois divorce process — legal information, not legal advice.** |
|
|
| ParaPilot turns the maze of an Illinois divorce into a clear, conditional roadmap and a chat that *only* answers from official sources — every claim links to a citation, low-confidence questions are refused instead of guessed, and advice-seeking or out-of-scope questions are politely escalated to legal aid. |
|
|
| > ⚖️ **Legal information, not legal advice.** ParaPilot is an educational tool. It is not a lawyer, it cannot tell you what to do in your case, and using it does not create an attorney-client relationship. See the full disclaimer at the bottom. |
|
|
| --- |
|
|
| ## The problem |
|
|
| Getting divorced without a lawyer in Illinois is mostly a *procedural* problem, not a forms problem: |
|
|
| - **Existing tools solve the wrong half.** Guided form-fillers (ILAO, A2J Author) hand you a document but not the sequence — *what do I do, in what order, by when, and who do I call?* General case-trackers (Courtroom5) are reactive and not Illinois-family-law-specific. |
| - **The real questions are conditional.** *I can't find my spouse — now what? I can't make the hearing in person. I can't afford the filing fee. We have kids.* Each branch has its own forms, deadlines, and rules. |
| - **Generic AI is dangerous here.** A plain chatbot will confidently invent form numbers, fees, and deadlines, and will happily give "advice" — which for a legal product is both wrong and a liability. (See *FTC v. DoNotPay*, $193K, 2025.) |
|
|
| Nobody offers a **proactive, Illinois-family-law-specific conditional roadmap** that is grounded and refuses to hallucinate. ParaPilot does. |
|
|
| --- |
|
|
| ## What it does |
|
|
| Two cooperating layers, both of which **always cite their sources**: |
|
|
| 1. **A deterministic process model** — the Illinois divorce process encoded as a curated, version-controlled **state machine**. Because it's data, not generation, the roadmap can't hallucinate. It drives the visual stepper, "what's next," required forms (and *what each must contain*), deadlines, who-to-call, and the conditional branches (children, remote appearance, can't-locate-spouse, fee waiver). |
| 2. **Grounded RAG for the long tail** — free-form questions are answered by hybrid retrieval over a bundled, citation-tagged corpus, with **citation-restricted generation**, a **confidence score**, an **out-of-scope/advice classifier**, and a hard **refuse-and-escalate** path. |
|
|
| ```mermaid |
| flowchart TD |
| U[User question] --> SCOPE{Scope & UPL gate} |
| SCOPE -->|advice-seeking| REF[Refuse + escalate to legal aid] |
| SCOPE -->|non-IL / non-divorce| REF |
| SCOPE -->|in scope / uncertain| RET[Hybrid retrieval<br/>BM25 + TF-IDF over seed corpus] |
| RET --> CONF{Confidence ≥ threshold?} |
| CONF -->|no| REF |
| CONF -->|yes| GEN[Citation-restricted generation<br/>stub / Anthropic / OpenAI] |
| GEN --> CITE{Every claim cited?} |
| CITE -->|no| REF |
| CITE -->|yes| ANS[Grounded answer<br/>inline citations + confidence + disclaimer] |
| |
| subgraph Process model (deterministic) |
| SM[il/divorce state machine] --> ROAD[Visual roadmap:<br/>steps, forms, deadlines, branches] |
| end |
| |
| CORPUS[(Seed corpus<br/>ILAO · IL Courts · Rule 45 · Cook County)] --> RET |
| INGEST[ingest pipeline<br/>fetch → clean → chunk] -.refresh.-> CORPUS |
| classDef refuse fill:#fde68a,stroke:#d97706,color:#7c2d12; |
| class REF refuse; |
| ``` |
|
|
| The app has two views: |
|
|
| - **Roadmap** — a visual stepper of the process. Click a step → a panel with its summary, required forms + what each must contain, deadlines, who to call, citations, and next/branch options. Conditional branches are visible inline. |
| - **Ask** — a grounded chat. Answers show **inline clickable citations**, a **confidence meter**, and the disclaimer. Out-of-scope/advice → a visible refusal + escalation card. |
|
|
| --- |
|
|
| ## Results / impact |
|
|
| The headline artifact is an **anti-hallucination evaluation**: 53 curated Illinois-divorce Q&A (41 grounded, 12 out-of-scope/advice), each with a known answer and authoritative citation. We run the same questions through ParaPilot (grounded RAG + scope gate + citations) and through a **plain-LLM baseline with no retrieval, no scope gate, and no citations** — the way a generic chatbot behaves — and measure the delta. |
|
|
| > **Measured on a real model.** The table below is the live result with **ParaPilot's answers generated by Anthropic `claude-haiku-4-5`** — reproduce it with `make eval-live` (needs `ANTHROPIC_API_KEY`). The offline stub baseline is `make eval`. |
| > |
| > **One caveat, stated plainly:** the *ParaPilot* column is real model output; the *Plain LLM* column is a deterministic **simulation** of an ungrounded chatbot (answers everything, never cites, never refuses). Because the hallucination metric counts any *uncited* claim, an ungrounded model scores ~100% by construction — so the number that actually matters is **ParaPilot's own 3.8% hallucination rate and 85.3% groundedness on real generations**, not the headline delta. |
|
|
| | Metric | Plain LLM (ungrounded sim.) | ParaPilot on Haiku 4.5 | | |
| |---|---|---|---| |
| | **Hallucination rate** | 100.0% | **3.8%** | lower is better | |
| | Answer correctness (grounded Qs) | 0.0% | **100.0%** | higher is better | |
| | Groundedness / faithfulness | 0.0% | **85.3%** | higher is better | |
| | Citation accuracy | 0.0% | **100.0%** | higher is better | |
| | Refusal correctness (out-of-scope / advice) | 0.0% | **100.0%** | higher is better | |
|
|
| **How to read this.** A *hallucination* is any substantive claim not supported by a retrieved source — including answering a question that should have been refused. On real Haiku-generated answers, ParaPilot's grounded RAG + scope gate hold the hallucination rate to **3.8%** at **85.3% groundedness** (RAGAS-style: each cited claim must match the source it cites), while refusing every out-of-scope/advice question (100%) and citing every grounded answer (100%). The ungrounded baseline never cites or refuses — the failure mode grounded RAG exists to prevent. |
|
|
| The guardrails also hold on a **held-out adversarial set** (questions never used to tune anything): 11/11 — every out-of-scope/advice probe refused, every genuine in-scope question answered. |
|
|
| --- |
|
|
| ## Quickstart |
|
|
| Runs **fully offline with zero API keys** on a deterministic stub provider. |
|
|
| ```bash |
| # Python 3.9+; from the repo root |
| python -m pip install -r requirements.txt # core runtime (or: make install) |
| |
| make demo # -> http://127.0.0.1:8000 |
| ``` |
|
|
| Open **http://127.0.0.1:8000** for the Roadmap, or **/ask** for the grounded chat. |
|
|
| ```bash |
| make test # run the offline test suite (69 tests) |
| make eval-live # reproduce the table above on a REAL model (needs ANTHROPIC_API_KEY) |
| make eval # offline stub baseline, no keys (fast, deterministic) |
| make ingest # refresh the corpus from live IL sources (writes to data/corpus/_fetched/) |
| ``` |
|
|
| **Optional — use a real LLM.** Copy `.env.example` to `.env`, set `PARAPILOT_PROVIDER=anthropic` (or `openai`) and the matching API key. If the key or SDK is missing, ParaPilot transparently falls back to the stub — so everything still works offline. |
|
|
| --- |
|
|
| ## How it stays accurate & legal |
|
|
| ParaPilot is built to be trustworthy *by construction*, modeled on the *FTC v. DoNotPay* guardrails: |
|
|
| - **Citations on every claim.** Substantive answers are assembled only from retrieved official sources, and each claim carries a clickable `[n]` citation to its exact source chunk. The pipeline *drops any citation marker that doesn't resolve* and refuses if an answer can't be tied to a source. |
| - **Confidence + refusal.** Each answer has a confidence score derived from retrieval. Below threshold (or no good chunk), ParaPilot says *"I don't have a grounded answer for that"* and points to legal aid rather than guessing. |
| - **Out-of-scope refusal.** A transparent classifier blocks non-Illinois, non-divorce, and advice-seeking questions before they ever reach generation. When a question is *unsure*, it defers to retrieval confidence, with a hard negative-topic gate (bankruptcy, traffic, immigration, etc.). |
| - **Information, not advice (UPL).** ParaPilot explains *your options and the rule that applies* — never *which choice to make* or *how a judge will rule*. Advice-seeking phrasing gets a dedicated refusal: *"I can explain your options and the rule that applies, but I can't tell you which to choose."* |
| - **Escalation everywhere.** Every response object carries `disclaimer`, `citations[]`, `is_legal_information: true`, and an `escalation` block with one-click links to **ILAO Find Legal Help** and the **Illinois Lawyer Finder**. A first-run modal and a persistent footer reinforce this. |
| - **No fabricated specifics.** Exact form IDs, fees, and statutory deadlines are pulled from the cited sources or marked `verify: true` with the source URL to check — never invented. The **About** page renders the full verification checklist. (See the verify list at the end of this README.) |
|
|
| **Grounding sources** (each corpus chunk is tagged with its URL + retrieved date): |
|
|
| - [Illinois Legal Aid Online — Getting a divorce](https://www.illinoislegalaid.org/legal-information/getting-divorce) |
| - [Illinois Courts — Approved statewide forms (Divorce, Child Support & Maintenance)](https://www.illinoiscourts.gov/documents-and-forms/approved-forms/) |
| - Illinois Supreme Court **Rule 45** (remote appearances) + Rule 241 (remote testimony) |
| - [Circuit Court of Cook County — Remote court proceedings](https://www.cookcountycourtil.gov/about/remote-court-proceedings) |
| - Illinois Marriage and Dissolution of Marriage Act (IMDMA), **750 ILCS 5** |
|
|
| --- |
|
|
| ## Tech stack |
|
|
| - **Backend:** FastAPI (Python 3.9-compatible), server-rendered with **Jinja2 + htmx** — no SPA, fast first paint. |
| - **Process model:** YAML-defined state machine validated with Pydantic v2. |
| - **Retrieval:** hybrid **BM25** (compact, dependency-free) + **TF-IDF cosine** (scikit-learn) as an offline embedding fallback, score-fused. |
| - **Generation:** provider interface — deterministic **stub** (offline, extractive, can't hallucinate) + optional **Anthropic** / **OpenAI** behind the same contract. |
| - **Storage:** SQLite (saved progress) via SQLAlchemy. |
| - **UI:** Tailwind (vendored Play CDN, works offline), Inter, indigo/violet design system, light + dark, fully responsive. |
| - **Eval:** custom RAGAS-style harness (groundedness, citation accuracy, answer correctness, refusal correctness) + plain-LLM baseline. |
| - **Ops:** Docker + docker-compose, GitHub Actions CI (pytest on 3.9/3.11/3.12 + Docker smoke test). |
|
|
| --- |
|
|
| ## Deploy |
|
|
| ParaPilot is a single stateless container (SQLite on a small volume). |
|
|
| **Docker / docker-compose** |
| ```bash |
| make docker # build parapilot:latest |
| docker compose up # -> http://127.0.0.1:8000 |
| ``` |
|
|
| **Render** — New Web Service → Docker → health check path `/healthz`. No env vars required (offline stub). For a real LLM, add `PARAPILOT_PROVIDER` + the API key. |
|
|
| **Fly.io** — `fly launch` (detects the Dockerfile), then `fly deploy`. Mount a small volume at `/data` for the SQLite progress DB; internal port `8000`. |
|
|
| **Hugging Face Spaces (Docker SDK)** — point the Space at this repo; it builds the Dockerfile and serves on port `8000`. |
|
|
| --- |
|
|
| ## Screenshots |
|
|
| > _Add screenshots/GIFs here: the Roadmap stepper with a step panel open, an Ask answer with inline citations + confidence, and a refusal/escalation card. (Light + dark.)_ |
| > |
| > `docs/roadmap.png` · `docs/ask-grounded.png` · `docs/ask-refusal.png` |
|
|
| --- |
|
|
| ## Project layout |
|
|
| ``` |
| parapilot/ |
| app/ |
| main.py config.py db.py models.py schemas.py deps.py |
| process/ engine.py schema.py flows/il_divorce.yaml |
| rag/ corpus.py retriever.py generate.py citations.py |
| ingest/{run_ingest,clean,sources}.py |
| providers/{base,stub,anthropic_provider,openai_provider}.py |
| safety/ scope.py refusal.py disclaimers.py |
| eval/ gold_set.yaml run_eval.py metrics.py baseline.py |
| templates/ static/ # Tailwind design system (light + dark) |
| data/corpus/ # bundled offline seed snapshot (committed) |
| tests/ # 69 offline tests |
| Dockerfile docker-compose.yml .github/workflows/ci.yml Makefile |
| ``` |
|
|
| --- |
|
|
| ## Pending human verification (`verify: true`) |
|
|
| We never fabricate form IDs, fees, or deadlines. The following Illinois specifics are county- or document-dependent (or weren't fully stated on the public page) and are flagged in the seed flow for a human to confirm against the live source before publishing. They're also surfaced in-app on the **About** page. |
|
|
| | Item | What to verify | Source to check | |
| |---|---|---| |
| | **Filing fee amount** (`prepare_petition`) | Exact filing fee — set by each county circuit clerk; not a fixed statewide number. | [ILAO](https://www.illinoislegalaid.org/legal-information/getting-divorce) · [IL Courts forms](https://www.illinoiscourts.gov/forms/approved-forms/forms-circuit-court/divorce-child-support-maintenance) | |
| | **Service deadline** (`serve_respondent`) | Exact time by which service must be completed / proof filed before default. | [ILAO](https://www.illinoislegalaid.org/legal-information/getting-divorce) | |
| | **Respondent's response deadline** (`respondent_response`) | The exact number of days to appear/respond (printed on the summons; county rules). | [ILAO](https://www.illinoislegalaid.org/legal-information/getting-divorce) | |
| | **Parenting-education deadline** (`with_children`) | Confirm the "within 60 days of the first meeting" timing and approved-provider rules. | [ILAO](https://www.illinoislegalaid.org/legal-information/getting-divorce) | |
| | **Remote-appearance request deadline** (`remote_appearance`) | Each circuit/judge sets its own deadline and request procedure under Rule 45. | [Rule 45 announcement](https://www.illinoiscourts.gov/News/390/Illinois-Supreme-Court-Amends-Rules-to-Support-use-of-Remote-Hearings-in-Court-Proceedings/news-detail/) | |
| | **Service-by-publication procedure** (`service_by_publication`) | The exact affidavit form, notice period, newspaper, and publication fee (set locally). | [ILAO](https://www.illinoislegalaid.org/legal-information/getting-divorce) + circuit clerk | |
| | **Fee-waiver eligibility thresholds** (`fee_waiver`) | Income thresholds / public-benefit criteria — stated inside the Application PDF, not the web page. | [IL Courts fee-waiver](https://www.illinoiscourts.gov/forms/approved-forms/forms-approved-forms-circuit-court/fee-waiver-civil) | |
|
|
| > Note on form **codes**: the catalog labels shown for forms (e.g. `DWC Petition`, `DNC Judgment`, `DIV Summons`) are the labels used by illinoiscourts.gov's forms catalog, not statutory citations. The **form titles** are verbatim from the IL Courts site; confirm the current PDF before filing. |
|
|
| --- |
|
|
| ## ⚖️ Legal information, not legal advice |
|
|
| ParaPilot is an educational tool that explains the Illinois divorce (dissolution of marriage) process and points you to authoritative sources. **It provides legal information, not legal advice, and using it does not create an attorney-client relationship.** ParaPilot is not a lawyer and cannot tell you which choice is right for your situation. Court rules, forms, fees, and deadlines differ by county and change over time — before you rely on anything here, verify it against the cited official source, and for advice about your own case, talk to a licensed Illinois attorney or legal aid: **[ILAO — Find Legal Help](https://www.illinoislegalaid.org/get-legal-help)** · **[Illinois Lawyer Finder (ISBA)](https://www.isba.org/public/illinoislawyerfinder)**. Content is pending legal-aid review. |
|
|
| ## License |
|
|
| MIT © 2026 Laela Zorana — see [LICENSE](LICENSE). |
|
|
