openring 0.1.0__tar.gz

openring-0.1.0/.dockerignore

@@ -0,0 +1,12 @@
+.git
+.github
+.venv
+venv
+data
+tests
+docs
+**/__pycache__
+*.egg-info
+.pytest_cache
+.ruff_cache
+.env

openring-0.1.0/.env.example

@@ -0,0 +1,36 @@
+# --- Server ---------------------------------------------------------------
+# Bearer token for the REST API. Always set this before exposing the server.
+OPENRING_API_KEY=change-me
+# Dashboard password. Leave empty to choose it at http://localhost on the first visit; set it when
+# nobody opens the dashboard on the server itself (Docker, VPS). Reset: openring --reset-password
+OPENRING_PASSWORD=
+# Public https URL Twilio can reach (e.g. from `ngrok http 8000`)
+PUBLIC_URL=https://your-subdomain.ngrok-free.app
+# Optional: assistant used when a number has no assistant attached
+DEFAULT_ASSISTANT_ID=
+
+# --- Telephony (Twilio) ----------------------------------------------------
+TWILIO_ACCOUNT_SID=
+# Required to answer calls: it proves each webhook really comes from Twilio
+TWILIO_AUTH_TOKEN=
+# false skips that check (local tests only)
+VALIDATE_TWILIO_SIGNATURE=true
+
+# --- Speech-to-text --------------------------------------------------------
+# Deepgram gives US$200 of free credit to new accounts
+DEEPGRAM_API_KEY=
+
+# --- LLM (any OpenAI-compatible provider) ---------------------------------
+DEFAULT_LLM_PROVIDER=openai
+DEFAULT_LLM_MODEL=gpt-4.1-mini
+OPENAI_API_KEY=
+GROQ_API_KEY=
+OPENROUTER_API_KEY=
+DEEPSEEK_API_KEY=
+# OmniRoute (free gateway to 150+ free model providers)
+OMNIROUTE_BASE_URL=http://localhost:20128/v1
+OMNIROUTE_API_KEY=
+
+# --- Text-to-speech ---------------------------------------------------------
+# Leave empty to use Kokoro (free, runs locally)
+ELEVENLABS_API_KEY=

openring-0.1.0/.gitattributes

@@ -0,0 +1,3 @@
+# Shell scripts must keep Unix line endings, also on Windows checkouts.
+.githooks/* text eol=lf
+*.sh text eol=lf

openring-0.1.0/.githooks/check-leaks

@@ -0,0 +1,33 @@
+#!/bin/sh
+# Refuses to publish secrets or private notes. Plain sh and grep, so it runs in Git Bash, macOS and Linux.
+#   .githooks/check-leaks          checks the files staged for the next commit (the pre-commit hook)
+#   .githooks/check-leaks --all    checks every tracked file (CI)
+
+KEYS='gsk_[A-Za-z0-9]{20,}|sk-(proj-|ant-|or-v1-)?[A-Za-z0-9_-]{30,}|AC[0-9a-f]{32}|-----BEGIN [A-Z ]*PRIVATE KEY-----'
+fail=0
+
+if [ "$1" = "--all" ]; then
+  files=$(git ls-files)
+  content() { cat -- "$1" 2>/dev/null; }
+else
+  files=$(git diff --cached --name-only --diff-filter=ACMR)
+  content() { git show ":$1" 2>/dev/null; }
+fi
+
+for f in $files; do
+  case "$f" in
+    private/*|.env|*/.env|.env.*|*.db|*.sqlite)
+      [ "$f" = ".env.example" ] && continue
+      echo "check-leaks: $f must stay on your computer (it is private or holds secrets)"
+      fail=1
+      continue ;;
+  esac
+  if content "$f" | grep -Eq "$KEYS"; then
+    echo "check-leaks: $f contains something that looks like an API key or token"
+    content "$f" | grep -En "$KEYS" | cut -c1-60 | sed 's/^/    /'
+    fail=1
+  fi
+done
+
+[ $fail -eq 0 ] || echo "check-leaks: nothing was committed. Remove the secret, or keep the file out of git."
+exit $fail

openring-0.1.0/.githooks/pre-commit

@@ -0,0 +1,3 @@
+#!/bin/sh
+# Turn on once per clone with: git config core.hooksPath .githooks
+exec "$(dirname "$0")/check-leaks"

openring-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,58 @@
+name: Bug report
+description: Something doesn't work as expected
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting. Never paste API keys, tokens or phone numbers: replace them with `xxx`.
+        Found a security problem? Report it privately instead, see SECURITY.md.
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened
+      description: What you did, what you expected, and what happened instead.
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Create an assistant with ...
+        2. Start a browser test call
+        3. ...
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: OpenRing version
+      description: Shown under the logo in the dashboard, or in `GET /health`.
+      placeholder: "0.2.0"
+    validations:
+      required: true
+  - type: dropdown
+    id: install
+    attributes:
+      label: How do you run OpenRing?
+      options: ["npx openring", "pip / uv", "Docker", "From a git checkout"]
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      placeholder: Windows 11, macOS 15, Ubuntu 24.04 ...
+  - type: input
+    id: providers
+    attributes:
+      label: Providers involved
+      description: Speech-to-text, model, voice and telephony, if the problem is in a call.
+      placeholder: Deepgram nova-3, Groq openai/gpt-oss-20b, Kokoro, Twilio
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs
+      description: The terminal output around the error, with keys removed.
+      render: text

openring-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Report a security problem
+    url: https://github.com/elifalanrocha/openring/security/advisories/new
+    about: Please report vulnerabilities privately, not in a public issue.

openring-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,21 @@
+name: Feature request
+description: Suggest an idea, a provider to support or a Vapi feature to match
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What do you want to do?
+      description: The problem or use case, not only the solution. Who is it for (agency, developer, ...)?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: How could OpenRing help?
+      description: If Vapi already has this, link its docs; OpenRing keeps Vapi's JSON shape.
+  - type: dropdown
+    id: contribute
+    attributes:
+      label: Would you like to build it?
+      options: ["Yes, with some guidance", "Maybe", "No"]

openring-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,14 @@
+## What this changes
+
+<!-- One or two sentences. Link the issue it closes, e.g. "Closes #12". -->
+
+## How I tested it
+
+<!-- New or updated tests, and anything you checked by hand (dashboard, a browser test call, a phone call). -->
+
+## Checklist
+
+- [ ] `pytest` passes
+- [ ] `ruff check .` passes
+- [ ] New fields keep Vapi's JSON shape, and nothing existing was renamed
+- [ ] No keys, tokens or real phone numbers in code, tests or screenshots

openring-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install "ruff>=0.13"
+      - run: ruff check .
+      - name: Check the npm launcher parses
+        run: node --check bin/openring.js
+      - name: No secrets or private notes in the repository
+        run: sh .githooks/check-leaks --all
+
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python: ["3.11", "3.12", "3.13"]
+        # While the repository is private, Windows minutes count double and macOS ten times, so a plain
+        # push to main tests Linux only; pull requests, release tags and manual runs add Windows and macOS.
+        # Once the repository is public, Actions minutes are free: drop this condition.
+        include: ${{ fromJSON((github.event_name == 'push' && github.ref_type == 'branch') && '[]' || '[{"os":"windows-latest","python":"3.12"},{"os":"macos-latest","python":"3.12"}]') }}
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: pip install -e ".[dev,kokoro]"
+      - run: pytest -q
+
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - run: docker build -t openring:ci .
+      - name: The container answers /health
+        run: |
+          docker run -d --name openring -p 8000:8000 openring:ci
+          for i in $(seq 1 30); do curl -sf http://localhost:8000/health && exit 0; sleep 1; done
+          docker logs openring
+          exit 1

openring-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,71 @@
+name: Release
+
+# Pushing a tag like v0.2.0 publishes that version to PyPI, then the `npx openring` launcher to npm.
+# Both use trusted publishing (OpenID Connect): no tokens are stored in this repository.
+# One-time setup is described in docs/releasing.md.
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: The tag matches every version number
+        id: version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          py=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          init=$(python -c "import re; print(re.search(r'__version__ = \"(.+)\"', open('openring/__init__.py').read())[1])")
+          npm=$(node -p "require('./package.json').version")
+          echo "tag=$tag pyproject=$py __init__=$init package.json=$npm"
+          [ "$tag" = "$py" ] && [ "$tag" = "$init" ] && [ "$tag" = "$npm" ]
+          echo "version=$tag" >> "$GITHUB_OUTPUT"
+      - run: pip install -e ".[dev,kokoro]"
+      - run: pytest -q
+
+  pypi:
+    needs: check
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # trusted publishing
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  npm:
+    # After PyPI: the launcher installs exactly this version from there.
+    needs: [check, pypi]
+    runs-on: ubuntu-latest
+    environment: npm
+    permissions:
+      id-token: write  # trusted publishing and provenance
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with:
+          node-version: "24"  # trusted publishing needs npm 11.5.1 or later
+          registry-url: https://registry.npmjs.org
+      - name: Publish (npm trusts this workflow only once the package exists)
+        run: |
+          if npm view openring version > /dev/null 2>&1; then
+            npm publish --provenance --access public
+          else
+            echo "::warning::openring is not on npm yet: publish the first version by hand, see docs/releasing.md"
+          fi

openring-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Secrets and local data: never commit these
+.env
+.env.*
+!.env.example
+data/
+*.db
+*.db-journal
+*.sqlite
+
+# Maintainers' private notes (plans, strategy); see CLAUDE.md
+private/
+
+# Local Claude Code settings
+.claude/settings.local.json
+CLAUDE.local.md
+
+# Python and tools
+.venv/
+venv/
+__pycache__/
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+
+# Node
+node_modules/
+
+# Editors and OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db

openring-0.1.0/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to OpenRing are listed here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-10-30
+
+The first public release. Everything below is new.
+
+### Voice agents
+
+- Vapi-compatible REST API for assistants (`/assistant`), phone numbers (`/phone-number`), calls
+  (`/call`) and tools (`/tool`): existing Vapi clients work by changing the base URL.
+- Inbound phone calls through Twilio, and outbound calls with `POST /call`.
+- Talk to an assistant from the browser, with no phone number needed.
+- Assistant tools in Vapi's format: `function`, `endCall` and `transferCall`.
+- Import assistants, tools and phone numbers from a Vapi-compatible API.
+- Per-turn latency on every call, in Vapi's `artifact.performanceMetrics` shape, and Vapi-style
+  `end-of-call-report` webhooks.
+
+### Providers
+
+- Models from any OpenAI-compatible provider: OpenAI, Groq, OpenRouter, DeepSeek, OmniRoute or a
+  custom URL.
+- Speech to text with Deepgram; voices from ElevenLabs or Kokoro, a free voice that runs on your
+  computer.
+- Connect providers from the dashboard: each key is checked with the provider before it's saved, and
+  OpenRouter offers one-click sign-in.
+
+### Dashboard
+
+- Overview with calls, minutes, success rate, response time and the platform fee you didn't pay.
+- Assistants, phone numbers, calls with transcripts and latency, providers and settings, in light and
+  dark themes.
+- Sign-in with a password; the API keeps its Bearer key.
+
+### Running it
+
+- One command: `npx openring` installs everything, including Python, and opens the dashboard.
+- Docker image and `docker-compose.yml`.
+- Twilio webhooks are rejected unless their signature checks out.

openring-0.1.0/CLAUDE.md

@@ -0,0 +1,101 @@
+# OpenRing: project context for Claude
+
+OpenRing is an open-source, self-hosted alternative to paid voice AI agent platforms. People run it on
+their own machine or server with their own provider keys, so there is **no per-minute platform fee**.
+Its API is **Vapi-compatible**: existing clients migrate by changing the base URL. Code, commits and
+docs are in English (README.pt-BR.md is the exception). See CONTRIBUTING.md for setup and rules.
+
+## Architecture
+
+- `openring/api.py` FastAPI app: Vapi-style REST (`/assistant`, `/phone-number`, `/call`), Twilio
+  voice webhook (`POST /twilio/voice`, validates `X-Twilio-Signature`, refuses calls while
+  `TWILIO_AUTH_TOKEN` is unset unless `VALIDATE_TWILIO_SIGNATURE=false`), media websocket
+  (`/ws/twilio`: one connection per call, it atomically claims the queued call via `Store.claim`;
+  the assistant comes from the call record, never from stream parameters), `POST /call/web`
+  (browser test call: answers the dashboard's WebRTC offer with Pipecat's `SmallWebRTCConnection`
+  and runs the call as a background task; non-trickle ICE), `POST /call` (outbound, Vapi body:
+  creates a queued `outboundPhoneCall`, Twilio REST places it with
+  `Url=$PUBLIC_URL/twilio/voice?callId=...`; signatures cover the query string; `POST /twilio/status`
+  ends calls that never connected with Vapi's endedReason), dashboard at `/`, `/health`,
+  `GET /stats` (overview numbers, `openring/stats.py`).
+- Dashboard login (`openring/auth.py`, like OmniRoute): one password per server, scrypt hash in the DB
+  `settings` table; sessions in the `sessions` table as `HttpOnly`/`SameSite=Strict` cookies. Requests
+  authorize with the Bearer API key OR session cookie + `X-OpenRing: dashboard` header (CSRF guard).
+  `/auth/state|setup|login|logout|password`; the first password is chosen only from direct localhost
+  or set by `OPENRING_PASSWORD`; `openring --reset-password` clears it. `/dashboard/info` (session only)
+  gives the Settings/Providers pages the API key, URLs and which provider keys are set (never the keys).
+- `openring/bot.py` one live call: `run_call(transport, sample_rate=...)` runs Pipecat's pipeline
+  transport -> STT -> LLM -> TTS; `twilio_transport` (8 kHz) and `web_transport` (WebRTC) build the
+  transport. First message, end-call phrases, saves transcript and per-turn latency
+  (`artifact.performanceMetrics`, Vapi's shape, in ms, from Pipecat's `UserBotLatencyObserver`),
+  sends Vapi-style `end-of-call-report` to `server.url`. Services are built in a worker thread.
+- `openring/providers.py` maps the Vapi assistant JSON to a stack using Vapi's provider names (`ALIASES`
+  for other spellings). LLM: OpenAI-compatible APIs (`LLM_PROVIDERS`: openai, anthropic, google, groq,
+  openrouter, deepseek, xai, cerebras, together-ai, deepinfra, perplexity-ai, mistral, fireworks, ollama,
+  omniroute) + `custom-llm` with `model.url`. STT (`STT_SERVICES`): deepgram, assembly-ai, gladia, soniox,
+  cartesia, 11labs. TTS (`TTS_SERVICES`): 11labs, kokoro (free, local, default), cartesia, deepgram (Vapi
+  short voice names -> `aura-2-<name>-en`), openai, rime-ai, neuphonic, smallest-ai, inworld. Defaults
+  (nova-3, af_heart) apply only to their own provider. Kokoro uses the
+  int8 model (~120 MB with voices) in `~/.cache/pipecat/kokoro-onnx`: `warm_up()` at startup
+  downloads it if missing (atomic `.part` rename) and loads it once; Pipecat's per-service model
+  load is patched to share that instance. Calls refuse Kokoro with a progress message until ready.
+- Groq's catalog changed in 2026: Llama 3.x is gone; use `openai/gpt-oss-20b` (fast) or
+  `openai/gpt-oss-120b`. Groq's Cloudflare returns 403 to Python's default urllib User-Agent.
+- `openring/tools.py` Vapi tools: `function` (POSTs Vapi's `tool-calls` message to `tool.server.url` or the
+  assistant's `server.url`, reads `{"results": [{"toolCallId", "result"|"error"}]}`), `endCall`
+  (endedReason `assistant-ended-call`), `transferCall` (waits until the bot stops speaking, keeps Pipecat's
+  Twilio serializer from hanging up, then redirects the call with `<Dial>` TwiML; endedReason
+  `assistant-forwarded-call`; browser calls can't transfer). `model.tools` + saved `/tool` docs via
+  `model.toolIds`; unsupported types are skipped with a warning. Registered with `llm.register_function`
+  and `ToolsSchema` on the LLMContext; the transcript keeps `tool_calls` / `tool_call_result` rows.
+- `openring/importer.py` + `POST /import {baseUrl, apiKey}`: copies tools, assistants and Twilio numbers from
+  any Vapi-compatible API (pages back with `createdAtLt`), drops source-owned fields and secrets, remaps
+  `model.toolIds`, marks docs with `importedFrom` so a re-import updates them; reports per-assistant problems
+  (unsupported providers/tools) without refusing the import. Dashboard: **Import** on the Assistants page.
+- `openring/store.py` SQLite document store (JSON docs) for assistants, phone_numbers, calls, tools.
+- `openring/static/index.html` single-file dashboard (vanilla JS, no build step), styled after OmniRoute:
+  sidebar with sections, dark/light theme, big-number cards, tabs. Pages: Home (overview + get started),
+  Assistants (tiles; editor with Setup/JSON tabs), Phone numbers, Calls (filters; detail with transcript,
+  per-turn latency, JSON), Providers, Settings (API access, password).
+- `openring/__main__.py` `openring` command: first run creates `~/.openring/.env` with a generated
+  `OPENRING_API_KEY`, DB at `~/.openring/openring.db`, binds 127.0.0.1:8000.
+- `bin/openring.js` + `package.json` npm launcher: installs uv if missing, runs
+  `uv tool run --python 3.12 --from "openring[kokoro]==<package.json version>" openring` (the PyPI release
+  matching the launcher), opens the browser. `OPENRING_SOURCE` (e.g. `file:///C:/openring` or a git URL)
+  runs that source instead. Until the first PyPI release, `npx` needs `OPENRING_SOURCE`.
+- Releases (`docs/releasing.md`): tag `vX.Y.Z` -> `.github/workflows/release.yml` checks the tag matches
+  `pyproject.toml`, `openring/__init__.py` and `package.json`, tests, publishes to PyPI, then npm. Trusted
+  publishing (OIDC), no stored tokens; npm's first version is published by hand (npm needs the package to
+  exist before trusting a workflow).
+- Built on Pipecat 1.15 (services use `Settings(...)` objects; VAD via
+  `LLMUserAggregatorParams(vad_analyzer=SileroVADAnalyzer())`).
+
+## Commands
+
+```bash
+pip install -e ".[dev,kokoro]"   # dev install
+pytest                           # incl. a simulated Twilio call and a real local WebRTC call
+python -m openring               # run server (reads ./.env and ~/.openring/.env)
+npx openring                     # one-command run, once released on npm and PyPI
+```
+
+Only one server can use port 8000; stop the old one first, or pass `--port`.
+
+## Phone testing notes
+
+- A Twilio trial account calls only verified numbers, through Twilio's shared "Sandbox Number". That
+  sandbox's proxy re-signs webhooks (they fail validation with the account token) and the media stream
+  never opens, so callers hear silence. Test with an inbound call to a number you bought, or upgrade.
+- The Calls API on trial rejects the `Method`/`StatusCallbackMethod` parameters.
+- To reach a local server, use a tunnel (`cloudflared tunnel --url http://localhost:8000`). Quick-tunnel
+  URLs change on every start: update `PUBLIC_URL` and the number's voice webhook.
+
+## Conventions
+
+- Keep the Vapi JSON shape for any new field; prefer adding over renaming.
+- Every feature gets a test; `pytest` and `ruff check .` must pass before pushing.
+- Never commit `.env` or keys. Don't use Vapi's name or logo except to say "Vapi-compatible".
+- Third-party licenses are listed in THIRD_PARTY.md; update it when dependencies change.
+
+Maintainers keep private notes (plans, status, working rules) outside git; Claude loads them when present:
+@private/CLAUDE.md

openring-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Code of Conduct
+
+OpenRing follows the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+In short: be respectful and welcoming, assume good intent, give and take feedback gracefully, and keep
+discussions about the work. Harassment, insults, sexualized language or imagery, and publishing others'
+private information are not acceptable, in any project space or when representing the project.
+
+## Reporting
+
+Report unacceptable behavior to the maintainer at **alan.rocha@realvalorai.com.br**. Every report is
+reviewed promptly and kept confidential. Maintainers may remove comments, commits or other
+contributions that break this code, and may ban people who repeatedly or seriously do so, following the
+Contributor Covenant's enforcement guidelines.

openring-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,65 @@
+# Contributing to OpenRing
+
+Thanks for helping. OpenRing is a self-hosted voice AI agent platform with a Vapi-compatible API, so the
+most useful contributions make it easier to run, cheaper per minute, or more compatible with existing
+Vapi clients. Small pull requests get merged fastest.
+
+New here? Look for issues labeled
+[`good first issue`](https://github.com/elifalanrocha/openring/labels/good%20first%20issue).
+
+## Set up
+
+You need Python 3.11 or later and, to try the npm launcher, Node.js 18 or later.
+
+```bash
+git clone https://github.com/elifalanrocha/openring
+cd openring
+python -m venv .venv
+source .venv/bin/activate          # Windows: .venv\Scripts\activate
+pip install -e ".[dev,kokoro]"
+pytest                             # about 20 s; includes a simulated Twilio call and a local WebRTC call
+python -m openring                 # dashboard at http://localhost:8000
+```
+
+The first start downloads the free Kokoro voice (about 120 MB). Provider keys go in `~/.openring/.env`
+or are added from the dashboard's Providers page; see [.env.example](.env.example).
+
+## Where things are
+
+| Path | What it does |
+| --- | --- |
+| `openring/api.py` | FastAPI app: the Vapi-style REST API, Twilio webhooks, the media websocket and the dashboard routes |
+| `openring/bot.py` | One live call: the Pipecat pipeline transport → speech-to-text → model → voice |
+| `openring/providers.py` | Maps a Vapi assistant JSON to providers; add an OpenAI-compatible model provider with one line in `LLM_PROVIDERS` |
+| `openring/keys.py` | Connects providers from the dashboard: checks a key with the provider, then saves it |
+| `openring/store.py` | SQLite document store for assistants, phone numbers, calls and tools |
+| `openring/static/index.html` | The whole dashboard: one file, vanilla JavaScript, no build step |
+| `bin/openring.js` | The `npx openring` launcher |
+| `tests/` | pytest suite; every feature has a test here |
+
+## Rules of the road
+
+- **Keep the Vapi JSON shape.** A new field uses Vapi's name and structure when Vapi has one. Prefer
+  adding fields over renaming them, so existing clients keep working.
+- **Every change comes with a test**, and `pytest` and `ruff check .` must pass. CI runs both on
+  Linux, Windows and macOS.
+- **Never commit keys, tokens or `.env` files**, not even in tests: use obviously fake values.
+  Run `git config core.hooksPath .githooks` once, and a pre-commit check stops you if you try; CI runs
+  the same check.
+- **No paid service is required to run the tests.** Mock provider HTTP calls (see `tests/test_keys.py`).
+- **Say "Vapi-compatible"**, and don't use Vapi's name or logo in any other way.
+- Lines are up to 120 characters; `ruff check . --fix` sorts imports.
+
+## Pull requests
+
+1. Open an issue first for anything larger than a bug fix, so we can agree on the approach.
+2. Branch from `main`, keep the change focused, and describe what it does and how you tested it.
+3. Fill in the pull request template; a maintainer reviews within a few days.
+
+By contributing, you agree that your work is released under the [MIT License](LICENSE).
+
+## Security problems
+
+Please don't open a public issue for a vulnerability. See [SECURITY.md](SECURITY.md).
+
+Everyone taking part follows the [Code of Conduct](CODE_OF_CONDUCT.md).

openring-0.1.0/Dockerfile

@@ -0,0 +1,12 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+RUN apt-get update && apt-get install -y --no-install-recommends ffmpeg && rm -rf /var/lib/apt/lists/*
+COPY pyproject.toml README.md ./
+COPY openring ./openring
+RUN pip install --no-cache-dir ".[kokoro]"
+
+ENV OPENRING_DB_PATH=/data/openring.db HOST=0.0.0.0 OPENRING_HOME=/data
+VOLUME ["/data"]
+EXPOSE 8000
+CMD ["openring"]

openring-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alan Rocha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.