9router-python

Python SDK + CLI for the 9Router AI gateway.

One tiny library to talk to an OpenAI-compatible gateway that routes to Gemini, NVIDIA, OpenRouter, Groq, Ollama, Tavily and Exa — chat, images, TTS, STT, embeddings and web search/fetch — all through a single local endpoint, with automatic fallback between providers.

$ pip install 9router-python

---

✨ Features

Capability	SDK method	CLI command
💬 Chat (with streaming)	client.chat() / chat_stream()	ninerouter chat
🌀 Embeddings	client.embeddings()	ninerouter embed
🖼️ Image generation	client.image()	ninerouter image
🔊 Text-to-speech	client.tts()	ninerouter tts
🎙️ Speech-to-text	client.stt()	ninerouter stt
🔎 Web search	client.web_search()	ninerouter web search
📄 Fetch URL → markdown	client.web_fetch()	ninerouter web fetch
⚙️ Models & health	client.models(), health()	ninerouter models, health

Everything runs through one base URL. Configure once, use everywhere.

---

⚡ Quickstart

🚀 30 seconds to first chat

$ pip install 9router-python
$ ninerouter chat "Hello, world!" --stream
Hello! 👋 How can I help you today?

That's it. One gateway, one SDK, every capability.

Chat

from ninerouter import NineRouter

with NineRouter() as client:
    reply = client.chat("Explain a monad in one sentence")
    print(reply.text)

Stream tokens as they arrive:

for chunk in client.chat_stream("Write a haiku about Python"):
    print(chunk.content, end="", flush=True)

Generate an image

image = client.image("a watercolor of mountains at sunrise")
open("out.png", "wb").write(image.content)

Text-to-speech

audio = client.tts("Olá, mundo!", voice="pt-BR-FernandaNeural", model="gemini/gemini-3.1-flash-tts-preview")
open("speech.wav", "wb").write(audio)

Speech-to-text

text = client.stt(file=("recording.wav", open("recording.wav", "rb").read()))
print(text.text)

Embeddings — RAG-ready

vector = client.embeddings("The quick brown fox")[0]
curl_similarity = sum(a * b for a, b in zip(vector, other))

Web search & fetch

results = client.web_search("9Router open source")
for r in results.results:
    print(r.title, "-", r.url)

page = client.web_fetch("https://example.com")
print(page.content.text)

---

🖥️ CLI

ninerouter                          # help
ninerouter health                   # gateway status
ninerouter models --kind chat       # list chat models
ninerouter chat "Hello" --stream    # chat with streaming
ninerouter embed "text"             # embedding vector
ninerouter image "a red fox" --out fox.png
ninerouter tts "Hello" --voice pt-BR-FernandaNeural
ninerouter stt recording.wav
ninerouter web search "9Router"
ninerouter web fetch https://example.com
ninerouter config                   # show effective config

---

🔧 Configuration

Resolution order: CLI flags > environment variables > defaults.

Setting	Env var	Default
Base URL	NINEROUTER_URL	http://localhost:20128
API key	NINEROUTER_KEY	(optional)

export NINEROUTER_URL="http://localhost:20128"
export NINEROUTER_KEY="sk-..."     # optional if gateway has auth disabled

The key is only sent when non-empty, so a gateway running with requireApiKey=false works out of the box.

---

⚠️ Gateway quirks handled for you

• SSE-by-default: the gateway often streams SSE even when stream isn't set — the client parses both JSON and SSE transparently.
• TTS: some OpenRouter TTS models return 502 upstream errors; prefer a gemini/* TTS model.
• STT: multipart upload with gemini/* or groq/whisper-* models.
• Web search/fetch use provider (not model), e.g. tavily, exa, or the search-combo.
• Combos (owned_by: "combo", like Code) auto-fallback across providers — great defaults for chat.

---

📦 Install & develop

pip install -e .[dev]
pytest                     # mocked unit tests
pytest -m live             # live tests (needs a running gateway)

Requires Python 3.9+.

---

🧰 Why 9Router?

9Router gives you keyless access to dozens of AI providers with automatic fallback, so your app keeps working even if one provider's quota or free tier runs out. This SDK removes the friction: you get a typed, tested Python client and a friendly CLI without caring about which endpoint each provider uses.

---

🔒 Privacy & Security

This SDK is a thin HTTP client — it does not hold AI provider keys, does not upload your prompts anywhere other than the gateway you point it at, and ships no telemetry.

• No secrets in the client. An optional API key is read from the environment (NINEROUTER_KEY) and sent only to your configured gateway.
• Nothing leaves your network except to the gateway you configure. The SDK never sends data to the SDK author or any third party.
• The gateway holds the keys. Provider API keys (Gemini, NVIDIA, Tavily, …) live in your 9Router gateway on your machine/VM — not in this library.
• Supply-chain hygiene. Only two runtime dependencies (httpx, typer), both widely trusted. CI runs unit tests on every push across Python 3.9/3.11/3.13.
• No-secrets guardrail. A test in CI scans the repo for committed credentials and fails the build if anything slips in.

See SECURITY.md for the full policy and how to report a vulnerability privately.

---

📄 License

MIT © (ChristopherDond)

---

🇧🇷 Português

SDK Python + CLI para o gateway de IA 9Router.

Um único pacote para conversar com um gateway compatível com a API da OpenAI que roteia Gemini, NVIDIA, OpenRouter, Groq, Ollama, Tavily e Exa — chat, imagens, TTS, STT, embeddings e busca web, com fallback automático entre provedores.

pip install 9router-python
ninerouter chat "Olá, mundo!" --stream

Consulte a seção Features e Quickstart acima — a API e o CLI são idênticos. Para configurar, veja Configuration.

Exemplo rápido (PT)

from ninerouter import NineRouter

with NineRouter() as client:
    print(client.chat("Me conta uma piada"))

⬆ back to top