{"id":36953862,"url":"https://github.com/stimm-ai/stimm","last_synced_at":"2026-02-28T04:52:18.186Z","repository":{"id":327924714,"uuid":"1109753883","full_name":"stimm-ai/stimm","owner":"stimm-ai","description":"The Open Source Voice Agent Platform. Orchestrate ultra-low latency AI pipelines for real-time conversations over WebRTC.","archived":false,"fork":false,"pushed_at":"2025-12-15T16:18:46.000Z","size":10022,"stargazers_count":28,"open_issues_count":1,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-18T09:37:15.253Z","etag":null,"topics":["conversational-ai","docker","livekit","livekit-sdk","livekit-server","llm","low-latency","orchestration","python","realtime","stt","tts","voice-agent","voice-ai","voice-assistant","voicebot","webrtc"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stimm-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2025-12-04T08:34:52.000Z","updated_at":"2025-12-17T17:56:38.000Z","dependencies_parsed_at":"2025-12-10T12:03:56.728Z","dependency_job_id":null,"html_url":"https://github.com/stimm-ai/stimm","commit_stats":null,"previous_names":["stimm-ai/stimm"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/stimm-ai/stimm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stimm-ai%2Fstimm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stimm-ai%2Fstimm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stimm-ai%2Fstimm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stimm-ai%2Fstimm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stimm-ai","download_url":"https://codeload.github.com/stimm-ai/stimm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stimm-ai%2Fstimm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28385686,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T12:01:30.995Z","status":"ssl_error","status_checked_at":"2026-01-13T12:00:09.625Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["conversational-ai","docker","livekit","livekit-sdk","livekit-server","llm","low-latency","orchestration","python","realtime","stt","tts","voice-agent","voice-ai","voice-assistant","voicebot","webrtc"],"created_at":"2026-01-13T12:54:08.049Z","updated_at":"2026-02-28T04:52:18.179Z","avatar_url":"https://github.com/stimm-ai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# stimm\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/assets/logo_stimm_h.png\" alt=\"stimm logo\" width=\"360\" /\u003e\n\u003c/p\u003e\n\nDual-agent voice orchestration built on [livekit-agents](https://github.com/livekit/agents):\none agent talks fast, one agent thinks deep, both collaborate in real-time.\n\n## Why Stimm\n\n- Low-latency conversational voice loop (`VAD → STT → fast LLM → TTS`).\n- High-capability supervisor loop (tool use, planning, contextual steering).\n- Typed protocol for Python + TypeScript supervisors.\n- Runtime-safe provider contract + generated provider catalog from LiveKit docs.\n- Integrator-friendly onboarding flow (discover providers first, install extras second).\n\n## Install\n\n```bash\n# 1) Core package only (best first step for setup wizards)\npip install stimm\n\n# 2) Install only the providers selected by the user\npip install stimm[deepgram,openai]\n\n# Optional: install all runtime-supported providers\npip install stimm[all]\n\n# TypeScript supervisor client\nnpm install @stimm/protocol\n```\n\nPlugin dependencies are installed in the integrator app environment. Stimm does\nnot vendor provider plugin code inside its wheel.\n\n## Wizard-first Provider Flow\n\nFor onboarding UIs, use the catalog API to display providers/parameters, then\nderive extras from the user selection:\n\n```python\nfrom stimm import extras_install_command, get_provider_catalog\n\ncatalog = get_provider_catalog()  # exhaustive stt/tts/llm + parameters\ncmd = extras_install_command(stt=\"deepgram\", tts=\"openai\", llm=\"azure-openai\")\nprint(cmd)  # pip install stimm[deepgram,openai]\n```\n\nAfter extras installation, restart the Python process before instantiating\nLiveKit plugin classes.\n\nExtension/wizard migration details are documented in\n[docs/EXTENSION_WIZARD_INTEGRATION.md](docs/EXTENSION_WIZARD_INTEGRATION.md).\n\n## Quick Start\n\n### Voice Agent (Python)\n\n```python\nfrom stimm import VoiceAgent\nfrom livekit.plugins import deepgram, openai, silero\n\nagent = VoiceAgent(\n    stt=deepgram.STT(),\n    tts=openai.TTS(),\n    vad=silero.VAD.load(),\n    fast_llm=openai.LLM(model=\"gpt-4o-mini\"),\n    buffering_level=\"MEDIUM\",\n    mode=\"hybrid\",\n    instructions=\"You are a helpful voice assistant.\",\n)\n\nif __name__ == \"__main__\":\n    from livekit.agents import WorkerOptions, cli\n    cli.run_app(WorkerOptions(entrypoint_fnc=agent.entrypoint))\n```\n\n### Supervisor (Python)\n\n```python\nfrom stimm import Supervisor, TranscriptMessage\n\n\nclass MySupervisor(Supervisor):\n    async def on_transcript(self, msg: TranscriptMessage):\n        if not msg.partial:\n            result = await my_big_llm.process(msg.text)\n            await self.instruct(result.text, speak=True)\n```\n\n### Supervisor (TypeScript)\n\n```typescript\nimport { StimmSupervisorClient } from \"@stimm/protocol\";\n\nconst client = new StimmSupervisorClient({\n  livekitUrl: \"ws://localhost:7880\",\n  token: supervisorToken,\n});\n\nclient.on(\"transcript\", async (msg) =\u003e {\n  if (!msg.partial) {\n    const result = await myAgent.process(msg.text);\n    await client.instruct({ text: result, speak: true, priority: \"normal\" });\n  }\n});\n\nawait client.connect();\n```\n\n## Core Concepts\n\n## Dual-Agent Architecture\n\nStimm is fundamentally built around two cooperating agents:\n\n- `VoiceAgent`: optimized for low-latency spoken interaction.\n- `Supervisor`: optimized for deeper reasoning, planning, and tool orchestration.\n\nThey exchange typed protocol messages over LiveKit data channels, allowing fast\nturn-by-turn response while retaining high-level control and context.\n\n| Component | Role |\n|---|---|\n| `VoiceAgent` | Handles live turn-by-turn speech interaction |\n| `Supervisor` | Watches transcript and steers behavior asynchronously |\n| `StimmProtocol` | Structured messages over LiveKit data channels |\n\nModes:\n\n- `autonomous`: voice agent acts independently.\n- `relay`: voice agent only speaks supervisor instructions.\n- `hybrid` (default): autonomous with supervisor steering.\n\nPre-TTS buffering levels:\n\n- `NONE`, `LOW`, `MEDIUM` (default), `HIGH`.\n\n## Developer Workflow\n\n```bash\n# Install dev dependencies\npip install -e \".[dev]\"\n\n# Local infra\ndocker compose up -d\n\n# Build local artifacts + sync providers + validate runtime contract\nbash scripts/dev_build.sh\n\n# Tests / lint\npytest\nruff check src/ tests/\n\n# Catalog/contract checks (CI-equivalent)\npython3 scripts/sync_livekit_plugins.py --check\npython3 scripts/validate_runtime_contract.py --import-check\n```\n\n`scripts/dev_build.sh` is the single local command to rebuild protocol artifacts\nand provider metadata from the LiveKit source of truth.\n\n## Documentation\n\n- Docusaurus docs site source: [website](website)\n- Extension wizard integration: [website/docs/integrations/wizard.md](website/docs/integrations/wizard.md)\n- Supervisor observability integration: [website/docs/integrations/supervisor-observability.md](website/docs/integrations/supervisor-observability.md)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstimm-ai%2Fstimm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstimm-ai%2Fstimm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstimm-ai%2Fstimm/lists"}