Tutorial suite release: v0.3.6.
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 25 tutorials and test suites, plus a root demo (26 Go modules), using rho-llm v0.14.0.
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 | Live model tool-use loop with mocked tool responses, YAML-driven multi-model test matrix, parallel-by-provider execution, markdown report generation. |
| 22 | HTTP Tool Use Benchmark | Live model tool-use loop against a running cloud-ctl HTTP server. |
| 23 | Food-photo Nutrition Evaluation | Vision, forced structured tool results, reference error metrics, Nutrition5k and SNAPMe evaluation guidance; offline unit tests. |
| 24 | Speech-to-Text Compare | Browser recording sent in parallel to Google (Gemini 3.5 Transcribe, Flash Lite), OpenAI (gpt-transcribe, gpt-4o-mini-transcribe) and xAI (Grok) via TranscribeAudio; vocabulary biasing, latency, cost and word error rate side by side; offline break tests. |
| 25 | Drift Canary | Detect a nerfed, quantized or rerouted model API: seeded tasks with exact checkers (intent understanding from real agent sessions, agentic record work, quantization-sensitive precision), JSONL run logs with served model/tokens/latency/refusals, paired McNemar/Fisher comparison against a baseline; offline tests. |
- Go 1.27.3+
- API Keys for Gemini, Anthropic, or OpenAI (optional if using Ollama)
Create a .env file in the repository root (or export the variables):
GEMINI_API_KEY=your_key_here
ANTHROPIC_API_KEY=your_key_hereTutorials 01–18 are standalone Go programs. Export the environment variables, change to the tutorial's directory, and run it:
cd 01_basic
go run main.gomake build-all compiles all 25 modules, including test binaries, without running them. make vet-all checks every module. make test-all also runs tutorial 19's mock-based stress tests and tutorial 23's and tutorial 24's offline tests with the race detector; it does not run live provider benchmarks. Tutorial 23's CLI explicitly sends the selected image to a provider when run, and tutorial 24's page sends each recording to every configured provider; their tests do not.
Tutorials 20–22 are live benchmarks. Tutorial 20's -short flag only reduces the language matrix; it still calls models. Tutorial 21 mocks tools, not model responses. Tutorial 22 also requires a running cloud-ctl HTTP server. Run these suites explicitly when their services and credentials are configured.
- Historical QA Report: Includes an earlier API coverage cross-reference, tutorial execution logs, and tracked bug reports; it is not a coverage audit of v0.14.0.
- 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.
Tutorial 19 exercises AuthPool and PooledClient with mocks and Go's -race detector. Offline checks verify compilation and mock behavior; live model behavior requires the opt-in integration tests and benchmarks.