Welcome to the rho/llm Tutorial Suite! This directory contains a comprehensive guide to mastering the rho/llm library—a production-grade Go wrapper for Large Language Models (LLMs) featuring built-in streaming, multi-key failover, and agentic workflows.
The rho/llm library provides a unified interface for interacting with various LLM providers, including:
- Cloud: Anthropic (Claude), Google (Gemini), OpenAI, Groq, Mistral, xAI.
- Local: Ollama, vLLM, LM Studio.
This suite contains 21 tutorials ranging from basic text completion to advanced stress-testing of concurrent multi-key auth pools.
The library source is at github.com/bds421/rho-llm.
The tutorials are organized by complexity and feature set:
| # | Topic | Key Concepts |
|---|---|---|
| 01-02 | Core Basics | Complete & Stream APIs, Roles, Tokens. |
| 03-04 | Agency & Logic | Tool Use (Function Calling) & Extended Thinking (Reasoning). |
| 05-07 | Production Readiness | Error Classification, Backoff, Cost Estimation, Logging Middleware. |
| 08-10 | Advanced Flows | Multi-key Failover, System Prompts, Multi-turn Chat, Streaming Tools. |
| 11-13 | Reliability | Abort Control, Request Overrides, Deep Registry Inspection. |
| 14-15 | Ecosystem | Provider Presets, No-Auth detection, Multi-provider comparisons, Thinking/Reasoning content, live integration tests. |
| 16-18 | Internals | AuthPool mechanisms, Named Error Constructors, Content Model (Multimodal, Image/Vision), live vision integration tests. |
| 19 | Validation | Concurrent Stress Tests, Race-condition validation, Performance Benchmarks. |
| 20 | Capability Testing | Multi-model regression matrix, YAML-driven test cases (L1 factual → L5 epistemic logic/clock trisection), multi-language (EN/DE/ES), -config and -short flags, report generation. |
| 21 | Tool Use Benchmark | Agentic tool-use loop with mock responses (no external dependencies), YAML-driven multi-model test matrix, parallel-by-provider execution, markdown report generation. |
- Go 1.26.1+
- API Keys for Gemini, Anthropic, or OpenAI (optional if using Ollama)
Create a .env file in the llm directory (or export the variables):
GEMINI_API_KEY=your_key_here
ANTHROPIC_API_KEY=your_key_hereEach tutorial is a standalone Go program. Change to the tutorial's directory and run it:
cd 01_basic
go run main.go- Consolidated QA Report: Includes the 100% API coverage cross-reference, tutorial execution logs, and tracked bug reports.
- Stress Test Details: Deep dive into the 49+ tests that ensure library stability.
- Capability Test Reports: Multi-model regression results across reasoning and formatting tasks (generated locally, not checked in).
See CHANGELOG.md for version history.
All components (especially AuthPool and PooledClient) are verified with Go's -race detector and benchmarked for zero-allocation performance in hot paths.