From 2bc68134627728d76a1308525ea9c04faad8d4b6 Mon Sep 17 00:00:00 2001 From: pyr0ball Date: Wed, 6 May 2026 08:52:00 -0700 Subject: [PATCH] =?UTF-8?q?docs(readme):=20landing=20page=20rewrite=20?= =?UTF-8?q?=E2=80=94=20gov't=20phone=20framing,=20prototype=20callout,=20I?= =?UTF-8?q?VR=20roadmap=20table,=20Twilio=20blocker=20noted?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 105 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 103 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 4d21238..a3e607d 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,104 @@ -# osprey +# Osprey -osprey by Circuit Forge LLC — Customer service — IVR queues, complaint letters, dispute tracking \ No newline at end of file +**Government hold-line automation — AI for the tasks the system made hard on purpose.** + +> **Status: Early Prototype / Not Production-Ready** +> The FTB (California Franchise Tax Board) dialer is built and functional in a local environment. The project is currently blocked on Twilio account approval. Do not attempt to use this in production. + +[![Status: Prototype](https://img.shields.io/badge/status-prototype-red)]() +[![License: BSL 1.1](https://img.shields.io/badge/license-BSL%201.1-orange)](LICENSE) +[![Forgejo](https://img.shields.io/badge/primary%20repo-Forgejo-orange)](https://git.opensourcesolarpunk.com/Circuit-Forge/osprey) + +--- + +## The problem + +Government phone lines are not slow by accident. Multi-hour hold queues, IVR (interactive voice response) trees designed to exhaust callers before reaching a human, and no callback option are standard features of systems built to discourage use. For people navigating taxes, benefits, immigration, or the DMV, a single phone call can consume an entire workday. For neurodivergent users and others for whom phone calls carry high executive-function cost, the barrier is not just inconvenient — it can be disqualifying. + +## What Osprey does + +- Dials the government phone line on your behalf +- Navigates IVR menus automatically using configurable DTMF (dual-tone multi-frequency) sequences +- Waits on hold so you do not have to +- Bridges the call to your phone number when a human agent answers +- Retries automatically if the line is busy or the call is dropped +- Keeps your call data local — nothing is routed through a third-party service beyond Twilio's voice infrastructure + +LLM support is optional. The dialer and hold automation work without any LLM configured. + +## Current status + +**Built:** +- FTB hold-line dialer prototype (`app/dialers/ftb.py`) + - Calls FTB main line (`800-852-5711`) via Twilio Voice API + - Navigates configurable DTMF IVR sequence (`OSPREY_IVR_SEQUENCE`) + - Bridges to user's number when a human answers (`OSPREY_BRIDGE_NUMBER`) + - Retries on rejection up to `OSPREY_MAX_RETRIES` times +- FastAPI backend (`api/`) + - `POST /transcribe` — raw audio to faster-whisper transcription + - `POST /transcribe/recording` — Twilio `` webhook handler + +**Blocked:** +- Twilio account pending approval — required before any live calls can be placed +- FTB IVR digit sequence not yet confirmed against a live call + +Tracking: [Circuit-Forge/osprey#1](https://git.opensourcesolarpunk.com/Circuit-Forge/osprey/issues/1) + +## Roadmap + +| Phase | Target agency | Notes | +|-------|---------------|-------| +| 1 | FTB (California Franchise Tax Board) | Prototype built, blocked on Twilio | +| 2 | IRS (Internal Revenue Service) | Federal tax line | +| 3 | SSA (Social Security Administration) | Benefits and disability | +| 4 | DMV (Department of Motor Vehicles) | State-by-state variation | +| 5 | USCIS (U.S. Citizenship and Immigration Services) | Immigration appointments and status | + +## Quick start + +> Installation instructions will be published once the Twilio blocker is resolved and the dialer has been validated against a live call. Watch [Circuit-Forge/osprey#1](https://git.opensourcesolarpunk.com/Circuit-Forge/osprey/issues/1) for updates. + +When ready, the service runs on port **8520**. + +```bash +./manage.sh start # Start the service +./manage.sh stop # Stop the service +./manage.sh status # Check running status +./manage.sh logs # Tail service logs +``` + +## Stack + +- **Python** — core runtime +- **FastAPI** — HTTP backend and Twilio webhook handler +- **Twilio Voice API** — PSTN (public switched telephone network) dialing, DTMF navigation, call bridging +- **faster-whisper** — local audio transcription (no cloud dependency) +- **circuitforge-core** — shared Circuit Forge scaffold + +## Twilio requirement + +Osprey requires a Twilio account with Voice API access. Twilio performs manual account review for new signups using telephony automation — this is the current blocker. Once approved: + +1. Set `TWILIO_ACCOUNT_SID` and `TWILIO_AUTH_TOKEN` in your environment +2. Configure `OSPREY_BRIDGE_NUMBER` with the phone number to bridge calls to +3. Set `OSPREY_IVR_SEQUENCE` with the DTMF digits for the target agency + +## Privacy + +Osprey is local-first. Your call configuration and transcription stay on your machine. Twilio handles the PSTN connection (unavoidable for telephony), but no call data is routed through Circuit Forge servers. + +## Documentation + +Full docs (when available): [docs.circuitforge.tech/osprey](https://docs.circuitforge.tech/osprey) + +## Forgejo-primary + +Osprey is developed and maintained on Forgejo at [git.opensourcesolarpunk.com/Circuit-Forge/osprey](https://git.opensourcesolarpunk.com/Circuit-Forge/osprey). GitHub and Codeberg are read-only mirrors. + +## License + +[Business Source License 1.1](LICENSE) — free for personal non-commercial self-hosting. Commercial use and SaaS re-hosting require a paid license. Converts to MIT after 4 years. + +--- + +*Circuit Forge LLC — Privacy · Safety · Accessibility*