|
| 1 | +# Book 1 — Practical Multi-Model AI in Python with lm15 |
| 2 | + |
| 3 | +**Analog:** R for Data Science |
| 4 | +**Audience:** Python developers with no prior LLM API experience |
| 5 | +**Length:** ~300 pages |
| 6 | +**Prerequisite:** Basic Python (functions, dicts, loops, pip) |
| 7 | +**Ships with:** lm15 v1.0 |
| 8 | + |
| 9 | +--- |
| 10 | + |
| 11 | +## Thesis |
| 12 | + |
| 13 | +You don't need three SDKs, fifty dependencies, or a framework to use LLMs in Python. One import, one function, one string to switch models. This book takes you from zero to production-grade LLM calls in the simplest possible way. |
| 14 | + |
| 15 | +--- |
| 16 | + |
| 17 | +## Part I — First Contact |
| 18 | + |
| 19 | +### Chapter 1: One Function, Three Providers |
| 20 | + |
| 21 | +- What lm15 is and why it exists (zero deps, frozen dataclasses, stdlib transport) |
| 22 | +- `pip install lm15` |
| 23 | +- Getting API keys (OpenAI, Anthropic, Gemini) — where, how, cost expectations |
| 24 | +- The `.env` file pattern — `env=".env"`, `.gitignore` hygiene |
| 25 | +- `lm15.complete("gpt-4.1-mini", "Hello.")` — your first call |
| 26 | +- Anatomy of `LMResponse`: `.text`, `.model`, `.finish_reason`, `.usage` |
| 27 | + |
| 28 | +### Chapter 2: Switching Models |
| 29 | + |
| 30 | +- Change the string, change the model: `gpt-4.1-mini` → `claude-sonnet-4-5` → `gemini-2.5-flash` |
| 31 | +- Same code, same response type, same fields |
| 32 | +- When to use `provider=` for custom/fine-tuned model names |
| 33 | +- Cost and latency differences between providers (ballpark) |
| 34 | + |
| 35 | +### Chapter 3: Controlling Output |
| 36 | + |
| 37 | +- `system=` — shaping model behavior |
| 38 | +- `temperature=` — deterministic vs creative |
| 39 | +- `max_tokens=` — capping response length |
| 40 | +- `top_p=`, `stop=` — advanced sampling controls |
| 41 | +- Config-from-dict pattern: `lm15.complete(**config, prompt="...")` |
| 42 | + |
| 43 | +--- |
| 44 | + |
| 45 | +## Part II — Conversations |
| 46 | + |
| 47 | +### Chapter 4: The Model Object |
| 48 | + |
| 49 | +- `lm15.model()` — configure once, call many times |
| 50 | +- Why stateful vs stateless: when each matters |
| 51 | +- Bound config: system prompt, temperature, max_tokens |
| 52 | +- Per-call overrides: `gpt("Be creative.", temperature=1.5)` |
| 53 | + |
| 54 | +### Chapter 5: Multi-Turn Conversation |
| 55 | + |
| 56 | +- Automatic history tracking |
| 57 | +- `gpt("My name is Max.")` → `gpt("What's my name?")` |
| 58 | +- Inspecting history: `gpt.history`, entry structure |
| 59 | +- Clearing history: `gpt.history.clear()` |
| 60 | +- Explicit multi-turn with `messages=[Message.user(...), Message.assistant(...), ...]` |
| 61 | + |
| 62 | +### Chapter 6: Derived Models and Reuse |
| 63 | + |
| 64 | +- Immutable derivation: `with_model()`, `with_system()`, `with_tools()`, `with_provider()` |
| 65 | +- Original unchanged, new copy returned |
| 66 | +- Pattern: base config object + per-task derivations |
| 67 | +- `cache=True` for local response caching |
| 68 | + |
| 69 | +--- |
| 70 | + |
| 71 | +## Part III — Tools |
| 72 | + |
| 73 | +### Chapter 7: Auto-Execute Tools |
| 74 | + |
| 75 | +- Pass a Python function, get tool calling for free |
| 76 | +- Schema inference from type hints + docstring |
| 77 | +- Single tool: `tools=[get_weather]` |
| 78 | +- Multiple tools: `tools=[search, calculator]` |
| 79 | +- What happens under the hood: model calls → lm15 executes → model gets result → final text |
| 80 | + |
| 81 | +### Chapter 8: Manual Tool Loops |
| 82 | + |
| 83 | +- `Tool` objects with explicit JSON Schema |
| 84 | +- The loop: `resp.finish_reason == "tool_call"` → execute → `submit_tools()` → repeat |
| 85 | +- Why manual: async tools, approval gates, side effects, multimodal tool results |
| 86 | +- Multi-hop: model calls multiple tools across multiple rounds |
| 87 | + |
| 88 | +### Chapter 9: Built-In Tools |
| 89 | + |
| 90 | +- `tools=["web_search"]` — provider-side server tools |
| 91 | +- `resp.citations` — accessing source URLs and titles |
| 92 | +- Provider support matrix for built-in tools |
| 93 | + |
| 94 | +### Chapter 10: Tool Design Patterns |
| 95 | + |
| 96 | +- Naming and description best practices (the model reads them) |
| 97 | +- Parameter design: simple types, required vs optional |
| 98 | +- Error handling in tool functions |
| 99 | +- Tools that return structured data vs prose |
| 100 | + |
| 101 | +--- |
| 102 | + |
| 103 | +## Part IV — Multimodal |
| 104 | + |
| 105 | +### Chapter 11: Images |
| 106 | + |
| 107 | +- `Part.image(url=...)` — image from URL |
| 108 | +- `Part.image(data=..., media_type=...)` — image from bytes |
| 109 | +- Vision: describe, analyze, compare images |
| 110 | +- Image generation: `output="image"`, `resp.image` |
| 111 | +- Cross-model: generate on GPT, describe on Claude |
| 112 | + |
| 113 | +### Chapter 12: Documents |
| 114 | + |
| 115 | +- `Part.document(url=...)` and `Part.document(data=..., media_type=...)` |
| 116 | +- PDF analysis, contract review, summarization |
| 117 | +- `lm15.upload()` — provider file API for large documents |
| 118 | +- Upload on model objects: `claude.upload("file.pdf")` |
| 119 | + |
| 120 | +### Chapter 13: Audio and Video |
| 121 | + |
| 122 | +- `Part.video(url=...)` — video understanding (Gemini) |
| 123 | +- Audio generation: `output="audio"`, `resp.audio` |
| 124 | +- Cross-modal pipelines: generate audio → transcribe with another model |
| 125 | +- Provider capability matrix for media types |
| 126 | + |
| 127 | +### Chapter 14: Mixed-Media Prompts |
| 128 | + |
| 129 | +- Lists as prompts: `["Describe this.", Part.image(...), "Focus on colors."]` |
| 130 | +- Combining text, images, documents in one call |
| 131 | +- When to use single calls vs pipelines |
| 132 | + |
| 133 | +--- |
| 134 | + |
| 135 | +## Part V — Streaming |
| 136 | + |
| 137 | +### Chapter 15: Text Streaming |
| 138 | + |
| 139 | +- `lm15.stream(...).text` — the simple iterator |
| 140 | +- Print-as-you-go pattern |
| 141 | +- When streaming matters: UX, long responses, time-to-first-token |
| 142 | + |
| 143 | +### Chapter 16: Event Streaming |
| 144 | + |
| 145 | +- Full event loop: `text`, `thinking`, `tool_call`, `tool_result`, `finished` |
| 146 | +- `match event.type` pattern |
| 147 | +- `stream.response` — materialized response after consumption |
| 148 | +- Token counts and finish reason from the finished event |
| 149 | + |
| 150 | +### Chapter 17: Streaming with Tools and Reasoning |
| 151 | + |
| 152 | +- Streaming + auto-execute tools: tool calls and results appear as events |
| 153 | +- Streaming + `reasoning=True`: thinking tokens stream before text |
| 154 | +- Streaming on model objects: `gpt.stream(...)` — records to history |
| 155 | +- Building responsive UIs with streaming events |
| 156 | + |
| 157 | +--- |
| 158 | + |
| 159 | +## Part VI — Production |
| 160 | + |
| 161 | +### Chapter 18: Prompt Caching |
| 162 | + |
| 163 | +- `prompt_caching=True` — what it does per provider |
| 164 | +- Agent loop caching: advancing breakpoint pattern |
| 165 | +- Per-part cache hints: `Part.document(..., cache=True)` |
| 166 | +- Reading cache metrics: `resp.usage.cache_read_tokens`, `cache_write_tokens` |
| 167 | +- Provider behavior differences (Anthropic explicit, OpenAI automatic, Gemini CachedContent) |
| 168 | + |
| 169 | +### Chapter 19: Reasoning / Extended Thinking |
| 170 | + |
| 171 | +- `reasoning=True` — enable chain-of-thought |
| 172 | +- `resp.thinking` — reading the model's reasoning |
| 173 | +- Fine-grained control: `reasoning={"budget": 10000}`, `reasoning={"effort": "high"}` |
| 174 | +- When reasoning helps: math, logic, multi-step planning |
| 175 | +- Cost implications: reasoning tokens count |
| 176 | + |
| 177 | +### Chapter 20: Reliability |
| 178 | + |
| 179 | +- `retries=` on model objects |
| 180 | +- Timeout configuration |
| 181 | +- Error types and what to catch |
| 182 | +- Prefill: `prefill="{"` — steering output format |
| 183 | +- Defensive patterns: fallback models, token budget guards |
| 184 | + |
| 185 | +### Chapter 21: Discovery and Introspection |
| 186 | + |
| 187 | +- `lm15.models()` — list all available models |
| 188 | +- Filter by provider, capabilities, modalities |
| 189 | +- `lm15.providers_info()` — which providers are configured |
| 190 | +- Pattern: pick model from discovered list instead of hardcoding |
| 191 | +- `lm15.providers()` — env var names per provider |
| 192 | + |
| 193 | +--- |
| 194 | + |
| 195 | +## Appendices |
| 196 | + |
| 197 | +- A: Full `complete()` / `stream()` parameter reference |
| 198 | +- B: `LMResponse` field reference |
| 199 | +- C: `Usage` field reference |
| 200 | +- D: Provider support matrix |
| 201 | +- E: Environment variable reference |
0 commit comments