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 23 tutorials and test suites, plus a root demo (24 Go modules), using rho-llm v0.7.5.
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. |
- Go 1.26.8+
- 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 24 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 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; its 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.7.5.
- 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.