chore: import upstream snapshot with attribution

2026-07-13 12:22:33 +08:00
commit fc4fcbab58
1848 changed files with 472303 additions and 0 deletions
@@ -0,0 +1,111 @@
+---
+summary: "Deepgram provider: API key setup, project discovery, and usage-breakdown metrics."
+read_when:
+  - Debugging Deepgram API key or project selection
+  - Updating Deepgram usage parsing or menu display
+  - Explaining Deepgram setup to users
+---
+
+# Deepgram Provider
+
+[Deepgram](https://deepgram.com) is a speech AI platform that provides APIs for speech-to-text, text-to-speech, audio intelligence, and related voice features.
+
+## Authentication
+
+Deepgram uses API key authentication. Get your API key from the [Deepgram Console](https://console.deepgram.com).
+
+The API key must have access to the project you want to query. For usage data, the key also needs the `usage:read` scope for that project.
+
+### Environment Variables
+
+Set the `DEEPGRAM_API_KEY` environment variable:
+
+```bash
+export DEEPGRAM_API_KEY="dg_..."
+```
+
+Optionally set a Deepgram project ID:
+
+```bash
+export DEEPGRAM_PROJECT_ID="your-project-uuid"
+```
+
+If `DEEPGRAM_PROJECT_ID` is omitted, CodexBar calls Deepgram's project list endpoint and aggregates usage across all projects visible to the API key.
+
+### Settings
+
+You can also configure the API key and optional project ID in CodexBar Settings → Providers → Deepgram.
+
+### CLI config
+
+```bash
+printf '%s' "$DEEPGRAM_API_KEY" | codexbar config set-api-key --provider deepgram --stdin
+```
+
+## Data Source
+
+The Deepgram provider fetches summarized usage data from the Deepgram Management API.
+
+1. **Projects API** (`/v1/projects`): Lists projects visible to the API key when no project ID is configured.
+2. **Usage Breakdown API** (`/v1/projects/{PROJECT_ID}/usage/breakdown`): Returns summarized project usage over a date range. The response includes fields such as `start`, `end`, `resolution`, and `results`.
+
+Each usage result may include:
+
+* `start`
+* `end`
+* `hours`
+* `total_hours`
+* `agent_hours`
+* `tokens_in`
+* `tokens_out`
+* `tts_characters`
+* `requests`
+
+Deepgram's usage breakdown endpoint supports querying with `start` and `end` date parameters. The response includes summarized usage results for the selected period.
+
+## Display
+
+The Deepgram menu card shows:
+
+* **Usage notes**: Request count, total audio hours, total billable hours, agent hours, token totals, and TTS characters when returned by Deepgram
+* **Identity**: Project name, project ID, or aggregated project count
+
+Deepgram does not currently provide a credit balance through this provider. The provider displays usage, not remaining credits.
+
+## CLI Usage
+
+```bash
+codexbar --provider deepgram
+codexbar -p dg  # alias
+```
+
+## Environment Variables
+
+* **DEEPGRAM_API_KEY**: Your Deepgram API key. Required.
+* **DEEPGRAM_PROJECT_ID**: Optional Deepgram project UUID. Leave unset to aggregate all visible projects.
+* **DEEPGRAM_API_URL**: Override the base API URL. Optional, defaults to `https://api.deepgram.com/v1`.
+  Override values must be explicit HTTPS URLs or bare hosts/paths that CodexBar normalizes to HTTPS. Explicit
+  `http://` URLs fail closed before the Deepgram API key is attached to a request. For local proxy testing, use an
+  HTTPS listener or omit the scheme and let CodexBar normalize the override to HTTPS.
+
+## Permissions
+
+The API key must have permission to read usage data for the configured project.
+
+If the key is valid but lacks the correct scope, Deepgram may return an error like:
+
+```text
+INSUFFICIENT_PERMISSIONS
+Your account does not have the required scope to perform that action for this project.
+Check that your account has the 'usage:read' scope for this project.
+```
+
+In that case, create or update a Deepgram API key with the `usage:read` scope for the target project.
+
+## Notes
+
+* Deepgram usage data is project-scoped.
+* The project ID should be the project UUID, not just the project display name.
+* The provider uses `Authorization: Token <API_KEY>` for requests.
+* This provider currently reports usage metrics, not credit balance or per-request cost.
+* Summarized usage data is not limited to 90 days, while console logs are limited to 90 days.