# BrainstormRouter Python SDK

[![PyPI version](https://img.shields.io/pypi/v/brainstormrouter.svg)](https://pypi.org/project/brainstormrouter/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

Drop-in replacement for the OpenAI Python SDK with intelligent routing, memory, guardrails, and governance across 247 model endpoints.

## Install

```bash
pip install brainstormrouter
```

## Quick Start

```python
from brainstormrouter import BrainstormRouter

client = BrainstormRouter(api_key="brk_...")

# OpenAI-compatible — works with LangChain, LlamaIndex, CrewAI, etc.
response = client.chat.completions.create(
    model="anthropic/claude-sonnet-4",
    messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)
```

Use `"auto"` as the model to let BrainstormRouter's Thompson sampling pick the best model:

```python
response = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Explain quantum computing"}],
)
```

## Streaming

```python
stream = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Write a poem"}],
    stream=True,
)
for chunk in stream:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="")
```

## Memory (4-Block RMM)

```python
# Append a memory entry
client.memory.append("User prefers concise answers", block="semantic")

# List memory entries
result = client.memory.entries()

# List memory blocks with entry counts
result = client.memory.blocks()

# Bootstrap memory from documents
client.memory.init([{"content": "Product requirements doc...", "source": "prd.md"}])
```

## Guardrails

```python
# Test content against guardrail pipeline
result = client.guardrails.test(
    content="Check this message for PII",
    direction="inbound",
)
```

## Provider Keys (BYOK)

```python
# Register your own provider key
client.providers.register("anthropic", api_key="sk-ant-...")

# Validate a key with a live request
result = client.providers.test("anthropic", "sk-ant-...")
```

## Configuration

```python
client = BrainstormRouter(
    api_key="brk_...",                     # or set BRAINSTORMROUTER_API_KEY env var
    base_url="https://api.brainstormrouter.com",  # default
)
```

## Resources

- [Documentation](https://docs.brainstormrouter.com)
- [API Reference](https://api.brainstormrouter.com/openapi.json)
- [Full API Reference (llms-full.txt)](https://brainstormrouter.com/llms-full.txt)
- [GitHub](https://github.com/justinjilg/brainstormrouter)
- [Dashboard](https://brainstormrouter.com/dashboard)

## License

MIT
