Skip to content

Commit 438a4b7

Browse files
docs(readme): refresh front-of-fold + status table for Phase 5/5b/6
Update the README to reflect the actual current state: - Top: tests 41 -> 241 + 73 evals; add PWA + Evals badges; version 0.1.0 -> 0.6.0; status now reads "Phase 6 complete" - Surfaces table: add PWA URL, dashboard URL, journal link - "What's shipped vs deferred" replaces "what's mocked vs real": 18 line items covering Phase 1-6 each with shipped/deferred status - "What's next" replaces the original 6-item roadmap (most of which shipped). Now lists only the two operator-side wires + partner outreach + the deferred-with-design items pointing to PHASE6_DEFERRED.md The architecture-section content (Skills/sub-agents/hooks/MCP/ settings/CLAUDE.md tables) is unchanged because it ages well. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 1ffa505 commit 438a4b7

1 file changed

Lines changed: 43 additions & 28 deletions

File tree

‎README.md‎

Lines changed: 43 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -13,27 +13,32 @@ short_description: AI navigator for post-incarceration reentry in Texas
1313
# Pathways
1414

1515
[![CI](https://github.com/PrathikRavichandran/pathways/actions/workflows/ci.yml/badge.svg)](https://github.com/PrathikRavichandran/pathways/actions/workflows/ci.yml)
16-
[![Tests](https://img.shields.io/badge/tests-41%2F41%20passing-brightgreen)](https://github.com/PrathikRavichandran/pathways/actions)
16+
[![Evals](https://github.com/PrathikRavichandran/pathways/actions/workflows/evals.yml/badge.svg)](https://github.com/PrathikRavichandran/pathways/actions/workflows/evals.yml)
17+
[![Tests](https://img.shields.io/badge/tests-241%20unit%20%2B%2073%20evals-brightgreen)](https://github.com/PrathikRavichandran/pathways/actions)
1718
[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
1819
[![HF Space](https://img.shields.io/badge/%F0%9F%A4%97%20HF%20Space-live-yellow)](https://prathik10-pathways.hf.space/docs)
20+
[![PWA](https://img.shields.io/badge/PWA-pathways--iota.vercel.app-7AB182)](https://pathways-iota.vercel.app/)
1921

20-
A conversational AI navigator for people leaving incarceration in Texas. Built as a Claude Code architecture: layered **Skills**, **sub-agents**, **hooks**, **MCP servers**, **settings**, and a distributable **plugin** — composed into one reliable workflow for a safety-critical domain.
22+
A conversational AI navigator for people leaving incarceration in Texas. Built as a Claude Code architecture: layered **Skills**, **sub-agents**, **hooks**, **MCP servers**, **settings**, and a distributable **plugin**, composed into one reliable workflow for a safety-critical domain.
2123

22-
This repo is both a real product-in-progress *and* an opinionated demonstration of how Claude Code primitives compose when wrong answers cause real harm — legal misinformation, missed deadlines, lost benefits, or a missed crisis signal.
24+
This repo is both a real product-in-progress AND an opinionated demonstration of how Claude Code primitives compose when wrong answers cause real harm: legal misinformation, missed deadlines, lost benefits, or a missed crisis signal.
2325

24-
> **Status:** Active development. The architecture is complete and the demo flow runs end-to-end against real Texas statutory data. Tests: **150/150 passing** (hooks + LangGraph end-to-end across 6 conversation paths, plus regression tests for crisis-keyword phrasings discovered in live testing, plus the Phase 4 web channel). Twilio dispatch and live Pinecone are stubbed behind interfaces and documented in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
26+
> **Status:** Phase 6 complete. The system runs end-to-end across three audiences (SMS user, PWA user, caseworker dashboard) on the same FastAPI + LangGraph + Skills + MCP backend. Quality signal: **241 unit tests + 73 eval scenarios** all green; CI gates merges on a per-category pass rate with crisis at 100%. Two items remain deferred-with-design ([`docs/PHASE6_DEFERRED.md`](docs/PHASE6_DEFERRED.md)): MMS photo extraction and warm-transfer voice, both blocked by paid Twilio dependencies. The full chronological build is in [`docs/JOURNAL.md`](docs/JOURNAL.md).
2527
2628
---
2729

2830
## ⚡ Try it in 30 seconds
2931

3032
| Surface | URL | Try this |
3133
|---|---|---|
32-
| 🩺 **API health** | <https://prathik10-pathways.hf.space/health> | Returns `{"status":"ok","version":"0.1.0"}` |
33-
| 📚 **OpenAPI / Swagger** | <https://prathik10-pathways.hf.space/docs> | Interactive — try `/_debug/invoke` with `{"message":"Can I vote in Texas if I'm on parole?"}` |
34+
| 📱 **Live PWA** | <https://pathways-iota.vercel.app/> | Installable on iOS + Android home screens. Forest + Marigold palette, bilingual UI, four quick-start chips. |
35+
| 🩺 **API health** | <https://prathik10-pathways.hf.space/health> | Returns `{"status":"ok","version":"0.6.0", "channels":["sms","web"], "modules":["dashboard","parole_reminders","writeback"]}` |
36+
| 📚 **OpenAPI / Swagger** | <https://prathik10-pathways.hf.space/docs> | Interactive. Try `/_debug/invoke` with `{"message":"Can I vote in Texas if I'm on parole?"}` |
37+
| 📊 **Caseworker dashboard** | <https://prathik10-pathways.hf.space/dashboard/> | Token-gated. Demo mode accepts any `Authorization: Bearer <anything>`. Anonymized aggregates only; no PII ever stored. |
3438
| 🧠 **Architecture deep-dive** | [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Why each Claude Code primitive is load-bearing in a safety-critical domain |
3539
| 🎬 **Per-primitive walkthrough** | [`docs/SHOWCASE.md`](docs/SHOWCASE.md) | Code-trace tour: see exactly what a Skill, sub-agent, hook, and MCP server look like in practice |
36-
| 💬 **Sample conversations** | [`examples/sample_conversations.md`](examples/sample_conversations.md) | 5 fully-annotated SMS dialogues end-to-end (housing crisis, voting eligibility, multi-need, etc.) |
40+
| 📓 **Dev journal** | [`docs/JOURNAL.md`](docs/JOURNAL.md) | Public build log, six phases, every shipped feature dated |
41+
| 💬 **Sample conversations** | [`examples/sample_conversations.md`](examples/sample_conversations.md) | 5 fully-annotated SMS dialogues end-to-end |
3742

3843
### Install as a Claude Code plugin (loads all 7 Skills + 4 sub-agents + 3 hooks into your own session)
3944

@@ -200,30 +205,40 @@ license back.
200205

201206
You'll see: `intake-assessment` Skill auto-loads → routes to `housing-pathway` and `record-clearing-tx` → calls `pathways-corpus` and `tx-resources` MCP servers → `compliance-auditor` sub-agent validates citations → final response cites NICCC sections and offers SMS handoff to a real navigator.
202207

203-
## What's mocked vs. real
208+
## What's shipped vs. deferred
204209

205210
| Concern | Status |
206211
|---|---|
207-
| LangGraph state machine | **Real, runs.** 7 nodes wired (intake → retrieve → match → draft → audit → send/escalate), bounded revision loop |
208-
| All 7 Skills | Real, with realistic content (not stubs) |
209-
| All 4 sub-agents | Real definitions with frontmatter-enforced capability scoping |
210-
| All 3 hooks | Real, executable Python; **136/136 hook + graph tests passing** |
211-
| `pathways-corpus` MCP server | **Real**, 65 entries fetched from sll.texas.gov and NICCC, BM25 retrieval, tested |
212-
| `tx-resources` MCP server | **Real**, 18 curated TX reentry orgs, region-aware filter, tested |
213-
| `twilio-sms` MCP server | Interface defined, send is stubbed |
214-
| `pathways-postgres` MCP server | Interface defined, SQL views documented |
215-
| Pinecone | Local BM25 equivalent in demo; production upgrade path documented |
216-
| FastAPI ingress | **Real**, `/sms`, `/health`, `/_debug/invoke` routes, lifespan warm-up |
217-
| Tests | **136/136 passing**: hook unit tests + graph end-to-end tests + crisis-keyword regression suite covering live-discovered phrasings |
218-
219-
## What I'd build next, in order
220-
221-
1. **Real NICCC ingestion pipeline.** Currently 40 hand-curated excerpts. Production needs the full NICCC corpus chunked, embedded, and indexed with state filters.
222-
2. **Eval harness.** A 50-question Texas reentry rubric with ground-truth citations. LLM-as-judge for citation correctness, exact-match for eligibility outcomes. Run on every PR.
223-
3. **Twilio production wiring.** Webhook receiver, opt-in/opt-out compliance, message threading.
224-
4. **Multi-language.** Spanish first. The Texas reentry population includes a meaningful Spanish-monolingual subset.
225-
5. **Caseworker UI.** Next.js PWA wrapping the same backend, for navigators managing 30+ clients each.
226-
6. **B2B SaaS packaging.** Multi-tenant, per-org NICCC corpora (some orgs have state-specific addenda), org-scoped analytics.
212+
| LangGraph state machine (7 nodes; intake → retrieve → match → draft → audit → send/escalate; bounded revision loop) | **Real** |
213+
| 7 Skills + 4 sub-agents + 3 hooks (`.claude/`) | **Real**; plugin-installable via `claude plugin install .` |
214+
| `pathways-corpus` MCP server (BM25 + optional hybrid retrieval) | **Real**, 95 curated entries (federal CFR + TX statutes + NICCC) |
215+
| `tx-resources` MCP server (geo-aware nearby ranking) | **Real**, ~880 records after HRSA + curated orgs ingest; covers all 254 TX counties |
216+
| Multi-turn intake with checkpointer (Phase 1) | **Real**, Postgres-backed in prod, in-memory in tests |
217+
| Twilio webhook + signature verification + TCPA STOP/HELP/START (Phase 1) | **Real**, trial-mode aware |
218+
| Spanish + multi-need routing + Spanish crisis hook patterns (Phase 3) | **Real** |
219+
| PWA channel at `/web/*` + React 19 installable PWA (Phase 4) | **Real**, [live on Vercel](https://pathways-iota.vercel.app/) |
220+
| Provider-pluggable LLM (`pathways/llm/`) with Anthropic default + Gemini fallback (Phase 5) | **Real** |
221+
| Eval harness with 73 frozen scenarios + CI gate (Phase 5) | **Real**, crisis category must be 100% to merge |
222+
| Hybrid retrieval (BM25 + BGE-small dense, RRF fusion; opt-in) | **Real**, falls back to BM25 if sidecar or sentence-transformers missing |
223+
| Caseworker dashboard at `/dashboard/*` (Phase 5b) | **Real**, per-partner bearer auth + region scoping; demo mode for recruiter clicks |
224+
| Opt-in parole-reporting reminder (Phase 6) | **Queued**: API + intake hook + admin cron endpoint shipped; actual SMS send waits on the forward `thread_id → phone` map (see below) |
225+
| Anonymous monthly trend reports as Markdown export (Phase 6) | **Real**, `GET /dashboard/api/report.md` |
226+
| NGO write-back queue (Phase 6) | **Queued**: API + queue table shipped; actual SMS send waits on the same phone map |
227+
| MMS photo extraction of TDCJ release packet | **Deferred** ([`docs/PHASE6_DEFERRED.md`](docs/PHASE6_DEFERRED.md)): blocked on paid Twilio MMS + Claude vision spend |
228+
| Warm-transfer voice connect | **Deferred** ([`docs/PHASE6_DEFERRED.md`](docs/PHASE6_DEFERRED.md)): blocked on paid Twilio Voice |
229+
| Forward `thread_id → phone` resolver (encrypted) | **Deferred** ([`docs/PHASE6_DEFERRED.md`](docs/PHASE6_DEFERRED.md)): three lines from unblocking real-world send for both shipped queues |
230+
231+
## What's next
232+
233+
The technical surface is comprehensive. What it needs now is real users and real feedback.
234+
235+
**Operator-side wiring left to do** (~half a day):
236+
1. Set `PATHWAYS_ADMIN_TOKEN` on the HF Space and add a daily GitHub Actions cron to POST to `/admin/run-parole-reminders`.
237+
2. Wire the forward phone map (`pathways/sessions/phone_map.py` with a small `session_phones` table; encrypt with `PATHWAYS_PHONE_ENCRYPTION_KEY`). Until this is in place, both parole reminders and NGO write-back persist in their queues and the daily cron reports `skipped_no_phone` honestly.
238+
239+
**Then partner outreach.** The dashboard exists so partner NGOs can see what's flowing through their region; that conversation is what unlocks pilot users.
240+
241+
**Deferred-with-design.** MMS extraction and warm-transfer voice are documented in [`docs/PHASE6_DEFERRED.md`](docs/PHASE6_DEFERRED.md) with their blockers and unblock criteria. Both gate on paid Twilio features.
227242

228243
## Why I built this
229244

0 commit comments

Comments
 (0)