r9s

The official Python SDK and CLI for the r9s API.

Quick start

Requires Python 3.11+

Install:

pip install r9s

Or directly execute the CLI:

uvx r9s

Set your API key via .env file (recommended) or environment variable:

# Option 1: Create .env in your project directory
cat > .env << 'EOF'
R9S_API_KEY=your_api_key
R9S_BASE_URL=https://api.r9s.ai/v1
R9S_MODEL=gpt-5-mini
EOF

# Option 2: Export environment variables
export R9S_API_KEY="your_api_key"

The CLI automatically loads .env from the current directory (SDK usage does not auto-load). Disable with R9S_NO_DOTENV=1.

CLI usage

Chat (interactive, streaming by default):

r9s chat

Chat (stdin, useful for scripts/pipes):

echo "hello" | r9s chat
cat image.png | r9s chat

Resume a saved chat session (interactive selection):

r9s chat --resume

Agents (versioned, with audit trails, stored under ~/.r9s/agents/<name>/):

# Create an agent
r9s agent create reviewer \
  --instructions "You are a code reviewer. Focus on bugs and security." \
  --model gpt-5-mini

# Chat with the agent
r9s chat --agent reviewer

# Agents support variables
r9s agent create code-reviewer \
  --instructions "Review {{language}} code for {{focus_areas}}" \
  --model gpt-5-mini

r9s chat --agent code-reviewer --var language=Python --var focus_areas="security, performance"

# Pull an agent definition from git
r9s agent pull github:my-org/agent-definitions --path agents/reviewer

Commands (saved as TOML under ~/.r9s/commands/<name>.toml, prompt template only):

r9s command create summarize --prompt "Summarize: {{args}}"

In interactive chat, commands are available as slash commands:

• /summarize hello world

Command templates:

• {{args}} is replaced by the slash command arguments.
• !{...} runs a local shell command (bash -lc ...) after confirmation; pass -y to skip confirmation.

Run apps with r9s env injected (supported: claude-code, cc):

r9s run cc --model "$R9S_MODEL"

Configure local tools (supported: claude-code, cc, codex, qwen-code):

r9s set claude-code
r9s reset claude-code

Enable bash completion:

eval "$(r9s completion bash)"

List available models:

r9s models
r9s models --details  # Show owner and creation date

Audio (TTS, transcription, translation):

# Text to speech
r9s audio speech "Hello world" -o hello.mp3
r9s audio speech "Welcome" -o welcome.wav -v nova

# Speech to text (transcription)
r9s audio transcribe recording.mp3
r9s audio transcribe meeting.wav -o transcript.txt -f text

# Translate audio to English
r9s audio translate chinese_audio.mp3 -o english.txt

See all options:

r9s -h
r9s chat -h
r9s agent -h
r9s command -h
r9s audio -h
r9s models -h
r9s run -h

Python SDK usage

Minimal example (reads R9S_API_KEY and optional R9S_BASE_URL from the environment):

from r9s.client import R9S

with R9S.from_env() as r9s:

    res = r9s.chat.create(model="gpt-4o-mini", messages=[
        {
            "role": "user",
            "content": "Hello, how are you?",
        },
    ], stream=False)

Advanced SDK usage: docs/sdk-advanced.md

Development

Clone and install in editable mode with dev dependencies:

git clone https://github.com/r9s-ai/r9s-python.git
cd r9s-python
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e ".[dev,test]"

Run tests:

pytest

Run linting/type checks:

ruff check src/
pyright
mypy src/