Skip to content

Commit 48289fe

Browse files
committed
books
1 parent 1017815 commit 48289fe

33 files changed

Lines changed: 6567 additions & 5 deletions
Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
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
Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
# Chapter 1: One Function, Three Providers
2+
3+
This is a complete program that calls a language model:
4+
5+
```python
6+
import lm15
7+
8+
resp = lm15.complete("gemini-2.5-flash", "Say hello.", env=".env")
9+
print(resp.text)
10+
```
11+
```
12+
Hello! How can I help you today?
13+
```
14+
15+
Four lines. One of them is a blank. And if you've never called a language model from code before — if you've only ever used ChatGPT in a browser, typed into a box, and watched the reply appear — this is the moment where everything changes. That chat box is a toy. This is a tool. The difference is that you can put it inside a `for` loop.
16+
17+
We're going to build something with this tool. Over the course of this book, you'll construct a research assistant — a program that can search the web, read your documents, analyze images, reason through hard problems, and carry on a conversation while remembering everything you've discussed. It will run on whichever AI provider you want, switch between them on command, and cost you pennies.
18+
19+
But that's later. Right now, you need to get from zero to a working call. This chapter handles the plumbing — install, credentials, first call — and then takes the response apart so you know exactly what came back. It's not glamorous. It's the foundation everything else stands on.
20+
21+
## Install
22+
23+
```bash
24+
pip install lm15
25+
```
26+
27+
That finishes in under a second. I want to dwell on why, because it tells you something about the library you're about to use.
28+
29+
lm15 has zero dependencies. Not "a few small ones." Zero. It doesn't install `requests`, `httpx`, `aiohttp`, `pydantic`, `protobuf`, or any of the other packages that most AI libraries drag in. The HTTP calls go through Python's built-in `urllib`. The data types are frozen dataclasses from the standard library. The whole thing is 408 kilobytes on disk.
30+
31+
This is a deliberate design choice, not a limitation. Every dependency is a surface for breakage — version conflicts, security patches, install failures on weird platforms. A library with 55 dependencies (litellm) or 25 (google-genai) is 55 or 25 things that can go wrong before your code even runs. lm15 has you and the standard library. That's the full trust chain.
32+
33+
The cost of this choice is that lm15 won't give you async, won't give you connection pooling, won't give you a pretty progress bar. If you need those things, you'll reach for other tools later. But you'll be surprised how far you get without them.
34+
35+
## Get an API Key
36+
37+
Language model APIs are paid services — you need an account and a key. If you've never done this before, it feels like a bigger deal than it is. You go to a website, sign up, click "create API key," and copy a string. The whole process takes about two minutes.
38+
39+
You need a key from at least one of these three providers:
40+
41+
| Provider | Environment variable | Sign up |
42+
|---|---|---|
43+
| OpenAI | `OPENAI_API_KEY` | [platform.openai.com/api-keys](https://platform.openai.com/api-keys) |
44+
| Anthropic | `ANTHROPIC_API_KEY` | [console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys) |
45+
| Google Gemini | `GEMINI_API_KEY` | [aistudio.google.com/apikey](https://aistudio.google.com/apikey) |
46+
47+
Just one. If you have no existing account and no preference, start with Gemini — Google offers a free tier that's generous enough to follow this entire book without paying.
48+
49+
If you have keys for multiple providers, that's even better. lm15 can use all three simultaneously, and you'll want that flexibility later when we start picking models based on what they're good at.
50+
51+
### Storing your key
52+
53+
Create a file called `.env` in your project folder:
54+
55+
```
56+
GEMINI_API_KEY=AIza...
57+
```
58+
59+
Or, if you have several:
60+
61+
```
62+
OPENAI_API_KEY=sk-proj-abc123...
63+
ANTHROPIC_API_KEY=sk-ant-abc123...
64+
GEMINI_API_KEY=AIza...
65+
```
66+
67+
When you pass `env=".env"` to lm15, it reads this file and picks up every key it recognizes. The keys coexist peacefully — lm15 uses the right one based on which model you call.
68+
69+
Now: add `.env` to your `.gitignore`. Do it now. Not after you finish the chapter, not when you push to GitHub for the first time. Now.
70+
71+
```bash
72+
echo ".env" >> .gitignore
73+
```
74+
75+
API keys that leak to public repositories get scraped by bots within minutes. The resulting bill is not theoretical — it's happened to enough developers that GitHub now scans for exposed keys automatically. Your `.env` file is a wallet. Don't put it on the internet.
76+
77+
> **If you're working in a Jupyter notebook:** `env=".env"` resolves relative to your working directory, not the notebook file. If your notebook lives in `notebooks/` and your `.env` is at the project root, use `env="../.env"`. Or skip the file entirely: run `%env GEMINI_API_KEY=AIza...` in your first cell and omit `env=` from all calls. lm15 checks environment variables automatically.
78+
79+
Every code example in the rest of this book uses `env=".env"`. I'll stop mentioning it after this chapter.
80+
81+
## Your First Call
82+
83+
Here's that four-line program again, but this time, slow down and look at it:
84+
85+
```python
86+
import lm15
87+
88+
resp = lm15.complete("gemini-2.5-flash", "Say hello.", env=".env")
89+
print(resp.text)
90+
```
91+
```
92+
Hello! How can I help you today?
93+
```
94+
95+
`lm15.complete()` is a function call, not a method on some client object. There's no setup step. You don't create an instance of anything. The first argument is the model name — a plain string. The second is your prompt — also a string. `env=` points to your credentials. That's everything.
96+
97+
When you called this function, here's what lm15 did behind the scenes: it read your `.env` file, found your Gemini key, recognized from the prefix `"gemini-"` that this request goes to Google, constructed an HTTP request in Google's wire format, sent it to Google's `generateContent` endpoint, received the response, parsed it out of Google's JSON structure, and wrapped it in a clean `LMResponse` object. You saw none of that. You called a function and got text back.
98+
99+
Now try something more interesting:
100+
101+
```python
102+
resp = lm15.complete("gemini-2.5-flash",
103+
"What are the three most important things to understand about TCP?",
104+
env=".env",
105+
)
106+
print(resp.text)
107+
```
108+
```
109+
1. **Reliable delivery** — TCP guarantees that data arrives completely, in order, and without corruption, using acknowledgments and retransmission.
110+
111+
2. **Connection-oriented** — Before any data flows, TCP establishes a connection between sender and receiver through a three-way handshake (SYN, SYN-ACK, ACK).
112+
113+
3. **Flow and congestion control** — TCP dynamically adjusts transmission rate to avoid overwhelming the receiver or the network, using mechanisms like sliding windows and slow start.
114+
```
115+
116+
That response took about a second. The model didn't look anything up — it generated the answer from patterns in its training data, which is both the magic and the limitation of language models. It knows a lot, but it knows nothing that happened after its training cutoff, and it can't check whether what it's saying is true. Keep that in mind. We'll deal with it in Chapter 3, when we give the model tools to actually look things up.
117+
118+
## Taking the Response Apart
119+
120+
Let's look at what `complete()` actually returned. It's not just text — it's an `LMResponse` object with several fields, and understanding them now will save you confusion in every subsequent chapter.
121+
122+
```python
123+
resp = lm15.complete("gemini-2.5-flash",
124+
"What is the capital of France?", env=".env")
125+
126+
print(resp.text)
127+
print(resp.model)
128+
print(resp.finish_reason)
129+
print(resp.usage)
130+
```
131+
```
132+
The capital of France is Paris.
133+
gemini-2.5-flash
134+
stop
135+
Usage(input_tokens=8, output_tokens=9, total_tokens=17)
136+
```
137+
138+
**`resp.text`** is the part you'll use most — the model's text output as a single string. For a normal question-and-answer call, it's always populated. It returns `None` only in special cases — like when you ask a model to generate an image instead of text — which won't happen until Chapter 6.
139+
140+
**`resp.model`** is the model that actually responded. This sounds redundant — you just told it which model to use. But providers sometimes silently route you to a different version than the one you requested. OpenAI might point `gpt-4.1-mini` at a slightly updated variant. Gemini might resolve a model alias. If you're logging results or comparing models, always read this field rather than assuming the response came from exactly the string you passed in.
141+
142+
**`resp.finish_reason`** tells you why the model stopped talking. This is more important than it looks. `"stop"` means the model finished its thought naturally. `"length"` means it hit a token limit and was cut off mid-sentence — the response is incomplete. `"tool_call"` means the model wants to call a function, which is the entire mechanism behind Chapter 3. For now, you'll only see `"stop"`, but get in the habit of noticing it. A `"length"` hiding in production output is a silent bug.
143+
144+
**`resp.usage`** counts tokens. Tokens are the currency of language models — roughly three-quarters of a word in English, though the exact mapping depends on the model's tokenizer. Every call costs money, and `usage` tells you exactly how much work was done: `input_tokens` is what you sent, `output_tokens` is what the model generated, and `total_tokens` is the sum.
145+
146+
Here's what those tokens cost, in real money:
147+
148+
| Model | Input (per 1M tokens) | Output (per 1M tokens) | This call cost |
149+
|---|---|---|---|
150+
| `gemini-2.5-flash` | $0.15 | $0.60 | $0.000007 |
151+
| `gpt-4.1-mini` | $0.40 | $1.60 | $0.000018 |
152+
| `claude-sonnet-4-5` | $3.00 | $15.00 | $0.000159 |
153+
154+
That last column is for our 17-token call. Seven millionths of a dollar on Gemini. Even Claude — the most expensive — costs less than two hundredths of a cent. The cost only becomes meaningful at scale: a thousand calls, long prompts, large documents. But scale arrives faster than you expect, so I'll flag the cost implications throughout the book rather than ignoring them until the bill arrives.
155+
156+
## Switching Models
157+
158+
Now here's the thing that makes lm15 different from using a provider's SDK directly. Change the model name:
159+
160+
```python
161+
for name in ["gemini-2.5-flash", "gpt-4.1-mini", "claude-sonnet-4-5"]:
162+
resp = lm15.complete(name, "What is TCP in one sentence?", env=".env")
163+
print(f"{resp.model:>25} {resp.text}")
164+
```
165+
```
166+
gemini-2.5-flash TCP is a reliable, connection-oriented transport protocol that ensures ordered, error-checked delivery of data between applications over a network.
167+
gpt-4.1-mini TCP (Transmission Control Protocol) is a core Internet protocol that provides reliable, ordered, and error-checked delivery of data between applications over a network.
168+
claude-sonnet-4-5 TCP is a reliable, connection-oriented network protocol that ensures data is delivered accurately and in order between two devices by establishing a connection, breaking data into packets, and verifying their receipt.
169+
```
170+
171+
Three companies. Three APIs with completely different wire formats, authentication schemes, and response structures. And you switched between all three by changing a string.
172+
173+
This is not a small thing. If you'd done this with provider SDKs directly, you'd have three separate code paths — three imports, three client objects, three different ways to construct a message, three different response shapes to parse. You'd maintain that code forever. Every time a provider updates their SDK, you'd update your parser. lm15 absorbs all of that. You see one function, one response type, one set of fields.
174+
175+
The routing works by prefix matching: `gpt-*` goes to OpenAI, `claude-*` to Anthropic, `gemini-*` to Google. If you have a custom model name that doesn't follow this pattern — a fine-tune, a self-hosted model — you can pass `provider="openai"` explicitly. But for every model in this book, the name is enough.
176+
177+
## What Went In and What Came Out
178+
179+
Before we move on, I want to make sure the mental model is clear, because everything in this book builds on it.
180+
181+
You called a function. You passed in a model name and a prompt. You got back a frozen object with text, usage data, and metadata. The call was **stateless** — lm15 doesn't remember it, the model doesn't remember it, nothing was saved anywhere. If you call `complete()` again with a different prompt, the model has no idea you ever asked the first question.
182+
183+
That statelesness is a feature when you're doing one-off tasks — classify this, summarize that, translate this. It becomes a limitation when you want a conversation. We'll deal with that in Chapter 4.
184+
185+
For now, you have the foundation: one function that talks to any provider and returns a clean, consistent response. Every chapter from here adds one capability to this foundation. System prompts that shape behavior. Tools that let the model act. Memory that lets it remember. Streaming that makes it responsive. Each one is the same function with one more argument.
186+
187+
Let's start shaping the output. The model will do what you tell it — but you have to learn how to tell it.

0 commit comments

Comments
 (0)