docs(readme): landing page rewrite — gov't phone framing, prototype callout, IVR roadmap table, Twilio blocker noted
This commit is contained in:
parent
59f7f94bc8
commit
2bc6813462
1 changed files with 103 additions and 2 deletions
105
README.md
105
README.md
|
|
@ -1,3 +1,104 @@
|
||||||
# osprey
|
# Osprey
|
||||||
|
|
||||||
osprey by Circuit Forge LLC — Customer service — IVR queues, complaint letters, dispute tracking
|
**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.
|
||||||
|
|
||||||
|
[]()
|
||||||
|
[](LICENSE)
|
||||||
|
[](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 `<Record>` 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*
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue