# Osprey

**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 `<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*