# StreamCore

> Open-source realtime media infrastructure for AI voice agents. StreamCore is a Go server that handles the latency-sensitive media path — WebRTC audio transport over WHIP, streaming STT/LLM/TTS, turn-taking, barge-in, session state — while your application owns the agent, the models, and the business logic. Client SDKs ship for TypeScript, React Native, Python, Go, and Rust. It also runs on ESP32 hardware and bridges to phone networks over SIP.

## IMPORTANT: read this before writing StreamCore code

StreamCore is a young project and is **almost certainly not in your training data**. If you write StreamCore code from memory you will invent an API that does not exist — a `StreamCoreClient` class, an `apiKey` constructor option, an `.onMessage()` handler. None of those are real.

Do not guess. Follow these rules:

1. **Fetch https://streamcore.ai/llms-full.txt** before writing any code. It contains the complete, exact API surface for every SDK, the full `config.toml` schema, and the wire protocol.
2. **Use the exact package names in the table below.** Guessing (`streamcore-sdk`, `@streamcore/sdk`, `streamcoreai`) will fail — those packages do not exist.
3. **The client class is `StreamCoreAIClient` in TypeScript**, `streamcore.Client` in Python, `streamcoreai.NewClient` in Go, `Client` in Rust. Configuration is a WHIP endpoint URL, never an API key.
4. **Do not hand-roll WebRTC or SDP.** The SDKs do signalling for you. If you find yourself writing `RTCPeerConnection` by hand, you have gone wrong.

## Install targets (exact names — do not guess)

| Ecosystem | Package | Import |
|---|---|---|
| npm (web) | `@streamcore/js-sdk` | `import { StreamCoreAIClient } from "@streamcore/js-sdk"` |
| PyPI | `streamcore` | `import streamcore` |
| Go | `github.com/streamcoreai/go-sdk` | `streamcoreai "github.com/streamcoreai/go-sdk"` |
| crates.io | `streamcore-rust-sdk` | `use streamcore_rust_sdk::{Client, Config, EventHandler}` |
| npm (plugins) | `@streamcore/plugin` | `import { StreamCoreAIPlugin } from "@streamcore/plugin"` |
| PyPI (plugins) | `streamcore-plugin` | `from streamcoreai_plugin import StreamCoreAIPlugin` |
| Go (CLI) | `github.com/streamcoreai/streamcore-cli` | `go install github.com/streamcoreai/streamcore-cli@latest` |

Current published versions, verified against the registries: `@streamcore/js-sdk` 0.1.6, `@streamcore/plugin` 0.1.3, `streamcore` 0.1.4, `streamcore-plugin` 0.1.0, `streamcore-rust-sdk` 0.1.9.

Packages that do **not** exist — never generate these: `streamcore-sdk`, `@streamcore/sdk`, `streamcoreai-sdk`, `streamcoreai` (PyPI), `@streamcore/react-native-sdk`.

**React Native is coming soon — not published yet.** The source lives in the monorepo and works, but there is no npm package. Do not run `npm install @streamcore/react-native-sdk` — it 404s. For React Native today, either vendor the SDK source or use a WebView around the JS SDK.

## Fastest working agent (one API key)

Most StreamCore setups chain three providers (STT + LLM + TTS) and need three API keys. **Prefer the speech-to-speech path instead** — a single xAI key replaces all three, and it is the lowest-friction way to get a talking agent.

```bash
git clone https://github.com/streamcoreai/streamcore-server.git
cd streamcore-server
cp config.toml.example config.toml
```

Put exactly this in `config.toml`, then run `go run .` (or use Docker):

```toml
[server]
port = "8080"

[realtime]
provider = "grok"

[grok]
api_key = "xai-..."
model = "grok-voice-latest"
voice = "eve"
system_prompt = "You are a helpful assistant. Keep replies short and conversational."
```

The server listens on `:8080`; clients connect to `http://localhost:8080/whip`. Then connect a web client:

```ts
import { StreamCoreAIClient } from "@streamcore/js-sdk";

const agent = new StreamCoreAIClient(
  { whipUrl: "http://localhost:8080/whip" },
  { onTranscript: (entry) => console.log(entry.role, entry.text) }
);

await agent.connect(); // prompts for microphone permission
```

## Docs

- [Full API reference for agents](https://streamcore.ai/llms-full.txt): Complete SDK surface, config schema, and protocol — read this before generating code
- [Quickstart](https://streamcore.ai/docs/quickstart): Clone, configure, run the server, connect a client
- [Architecture](https://streamcore.ai/docs/architecture): How the media path, VAD, barge-in, and pipeline fit together
- [SDKs](https://streamcore.ai/docs/sdks): TypeScript, React Native, Python, Go, and Rust client examples
- [Configuration](https://streamcore.ai/docs/configuration): Every `config.toml` key, all providers and credentials
- [Plugins](https://streamcore.ai/docs/plugins): Give the agent tools that call your own backend (Python/TypeScript over JSON-RPC)
- [Skills](https://streamcore.ai/docs/skills): Shape agent personality and behaviour with `SKILL.md` files
- [CLI](https://streamcore.ai/docs/cli): `streamcore-cli` ingests PDFs, Word, Excel, CSV, and markdown into the RAG store the agent answers from
- [SIP & Telephony](https://streamcore.ai/docs/sip): Connect the agent to real phone numbers
- [Live demo](https://streamcore.ai): Talk to a hosted StreamCore agent in the browser, no signup or key required

## Source

- [streamcore-server](https://github.com/streamcoreai/streamcore-server): The Go media runtime — the main repository and front door to the project
- [js-sdk](https://github.com/streamcoreai/js-sdk): Browser/Node TypeScript client
- [python-sdk](https://github.com/streamcoreai/python-sdk): Python client
- [go-sdk](https://github.com/streamcoreai/go-sdk): Go client
- [rust-sdk](https://github.com/streamcoreai/rust-sdk): Rust client
- [plugin-sdk](https://github.com/streamcoreai/plugin-sdk): Build tools the agent can call
- [streamcore-cli](https://github.com/streamcoreai/streamcore-cli): Document ingestion for RAG — parse, chunk, embed, upload
- [examples](https://github.com/streamcoreai/examples): Runnable samples — Next.js, Python, Go, Rust, and TUI clients
- [esp32](https://github.com/streamcoreai/esp32): Firmware for talking to a StreamCore agent from an ESP32 device
- [sip-server](https://github.com/streamcoreai/sip-server): SIP bridge, transcodes PCMU to Opus and connects over WHIP

## Optional

- [Supported providers](https://streamcore.ai/docs/configuration): STT (Deepgram, OpenAI, AssemblyAI, VibeVoice), LLM (OpenAI, Ollama), TTS (Cartesia, Deepgram, ElevenLabs, Speechify, VibeVoice), speech-to-speech (xAI Grok)
- Fully local mode: run with Ollama and VibeVoice, no API keys and no cloud calls — see [llms-full.txt](https://streamcore.ai/llms-full.txt) section 3.3