{"id":50525539,"url":"https://github.com/maximbilan/habla-core","last_synced_at":"2026-06-03T07:31:19.729Z","repository":{"id":356505647,"uuid":"1159079160","full_name":"maximbilan/habla-core","owner":"maximbilan","description":"FastAPI backend for real-time phone-call translation and AI agent mode using Amazon Nova 2 Sonic and Twilio","archived":false,"fork":false,"pushed_at":"2026-05-08T11:11:12.000Z","size":188,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-08T12:17:54.151Z","etag":null,"topics":["amazon-nova","fastapi","python","realtime-audio","speech-translation","twilio","voice-ai","websocket"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maximbilan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-16T09:39:47.000Z","updated_at":"2026-05-08T11:11:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/maximbilan/habla-core","commit_stats":null,"previous_names":["maximbilan/habla-core"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/maximbilan/habla-core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximbilan%2Fhabla-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximbilan%2Fhabla-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximbilan%2Fhabla-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximbilan%2Fhabla-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maximbilan","download_url":"https://codeload.github.com/maximbilan/habla-core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximbilan%2Fhabla-core/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33853984,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amazon-nova","fastapi","python","realtime-audio","speech-translation","twilio","voice-ai","websocket"],"created_at":"2026-06-03T07:31:18.719Z","updated_at":"2026-06-03T07:31:19.721Z","avatar_url":"https://github.com/maximbilan.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Habla Core\n\nAWS/Nova backend for Habla app.\n\nThis service supports both iOS modes:\n\n- **Live Call Mode**: low-latency bidirectional phone-call translation\n- **Agent Mode**: autonomous caller agent with transcript + verified-facts signals\n\nSystem architecture and sequence diagrams: [`architecture.md`](architecture.md)  \nDirect Agent Mode flow diagram: [`architecture.md#61-agent-mode-runtime-sequence`](architecture.md#61-agent-mode-runtime-sequence).\n\n## Current Implementation Summary\n\n### Live Call Mode (fast audio path)\n\n- Uses two Amazon Nova 2 Sonic sessions per call:\n  - iOS -\u003e callee language (to Twilio/PSTN)\n  - callee -\u003e iOS language (back to app)\n- Streams audio in both directions continuously\n- Optimized for latency: translation call mode focuses on audio forwarding\n\n### Agent Mode\n\n- Twilio call orchestration with model-driven agent conversation.\n- WebSocket events for:\n  - call status\n  - agent status (`listening/thinking/speaking`)\n  - transcript and transcript updates\n  - critical confirmations\n  - verified facts summar.\n\n### Caller ID Isolation\n\n- Caller ID verification/list/delete endpoints are provided\n- Ownership is enforced per device via `X-Habla-Device-ID`\n- Shared ownership state is delegated to `habla-accounts` (`HABLA_ACCOUNTS_*`)\n\n## API Surface\n\n### Translation\n\n- `GET /`\n- `GET /translation/languages`\n- `POST /call`\n- `POST /call/{sid}/end`\n- `GET /call/{sid}/status`\n- `POST /twilio/webhook` (compatibility TwiML endpoint)\n- `WS /ws/{call_sid}`\n- `WS /twilio/media-stream`\n\n### Agent\n\n- `POST /agent/call`\n- `POST /agent/call/{call_sid}/end`\n- `GET /agent/call/{call_sid}/status`\n- `POST /agent/twilio/webhook/{call_sid}`\n- `WS /agent/ws/{call_sid}`\n- `WS /agent/twilio/media-stream/{call_sid}`\n\n### Caller ID\n\n- `POST /caller-id/verify/start`\n- `GET /caller-id/verify/status/{phone_number}`\n- `GET /caller-id/list`\n- `DELETE /caller-id/{sid}`\n\n## Request Authentication\n\nIf `HABLA_SECRET` is set, iOS-facing REST + WS routes require:\n\n- `Authorization: HMAC_SHA256(HABLA_SECRET, HABLA_APP_BUNDLE_ID)`\n\nCaller ID ownership-sensitive routes also require:\n\n- `X-Habla-Device-ID`\n\n## Supported Languages\n\n- `en-US`, `en-GB`, `en-AU`, `en-IN`\n- `es-US`, `fr-FR`, `de-DE`, `it-IT`, `pt-BR`, `hi-IN`\n\n## Local Development\n\n### 1) Install\n\n```bash\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\n# test-only deps\npip install pytest httpx\n```\n\n### 2) Configure\n\n```bash\ncp .env.example .env\n```\n\nRequired groups:\n\n- AWS credentials + `AWS_REGION`\n- Twilio credentials + `TWILIO_FROM_NUMBER`\n- `PUBLIC_URL` reachable by Twilio\n\nOptional/conditional:\n\n- `HABLA_SECRET`, `HABLA_APP_BUNDLE_ID`\n- `HABLA_ACCOUNTS_BASE_URL`, `HABLA_ACCOUNTS_SERVICE_TOKEN`, `HABLA_ACCOUNTS_TIMEOUT_SECONDS`\n\n### 3) Run\n\n```bash\nuvicorn app.main:app --host 0.0.0.0 --port 8000 --reload\n```\n\n## Tests\n\n```bash\npython -m compileall app tests\nPYTHONPATH=. pytest -q\n```\n\n## Deployment (EC2)\n\nMain branch deploy is handled by `.github/workflows/deploy-ec2.yml`:\n\n- runs syntax validation\n- rsyncs source to EC2\n- installs dependencies in server venv\n- restarts `habla-core` systemd service\n- runs local health check (`http://127.0.0.1:8000/`)\n\nRequired GitHub variables/secrets are defined in the workflow (`EC2_*`, `EC2_SSH_PRIVATE_KEY`).\n\n## Repository Layout\n\n```text\napp/\n  main.py\n  config.py\n  models.py\n  call_manager.py\n  translation_bridge.py\n  nova_sonic.py\n  audio_utils.py\n  request_auth.py\n  twilio_handler.py\n  language_support.py\n  caller_id/\n  agent/\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaximbilan%2Fhabla-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaximbilan%2Fhabla-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaximbilan%2Fhabla-core/lists"}