Skip to content

Commit 364c846

Browse files
committed
Cookbooks: replace two monolithic pages with 16 focused recipes (real curated output, shared style guide)
1 parent 1b679db commit 364c846

23 files changed

Lines changed: 3501 additions & 2120 deletions

‎docs/cookbook-all-features.md‎

Lines changed: 0 additions & 1366 deletions
This file was deleted.

‎docs/cookbook-gemini-live.md‎

Lines changed: 0 additions & 747 deletions
This file was deleted.

‎docs/cookbooks/01-first-request.md‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# Your first request
2+
3+
**Problem** — You have a model name and a prompt, and three providers
4+
with three SDKs, three env vars, and three wire formats between you and
5+
a response. lm15 gives you one `Request` type and a router that turns
6+
the model string into the right provider — and can tell you exactly how
7+
it decided.
8+
9+
## Recipe
10+
11+
Keys first. lm15 reads nothing implicitly; you put keys in the
12+
environment, the router finds them there. This loader searches the
13+
current directory and its parents for a `.env` file:
14+
15+
```python
16+
import asyncio
17+
import os
18+
from pathlib import Path
19+
20+
from lm15 import (
21+
AnthropicLM, AsyncLMRouter, GeminiLM, LMRouter, Message, OpenAILM, Request,
22+
)
23+
24+
def load_env(filename=".env"):
25+
for directory in (Path.cwd(), *Path.cwd().parents):
26+
path = directory / filename
27+
if path.exists():
28+
for line in path.read_text().splitlines():
29+
line = line.strip().removeprefix("export ")
30+
if line and not line.startswith("#") and "=" in line:
31+
key, _, value = line.partition("=")
32+
os.environ.setdefault(key.strip(), value.strip().strip("\"'"))
33+
return path
34+
return None
35+
36+
print(load_env())
37+
```
38+
```output
39+
/home/maxime/Projects/lm15-dev/.env
40+
```
41+
42+
(From a shell, the one-liner is `export $(grep -v "^#" ../.env | xargs)`.)
43+
44+
Now the request. `LMRouter` is the front door: it maps
45+
`"gpt-4.1-mini"` to `OpenAILM`, builds the LM with the key from
46+
`$OPENAI_API_KEY`, and forwards the call.
47+
48+
```python
49+
router = LMRouter()
50+
response = router.complete(
51+
Request(model="gpt-4.1-mini", messages=(Message.user("Say hello in five words."),))
52+
)
53+
print(response.text)
54+
```
55+
```output
56+
Hello! Hope you're doing well.
57+
```
58+
59+
`response` is a frozen dataclass, not a provider blob. Print it and you
60+
see everything lm15 normalized:
61+
62+
```python
63+
print(response)
64+
```
65+
```output
66+
Response(
67+
text="Hello! Hope you're doing well.",
68+
model='gpt-4.1-mini-2025-04-14',
69+
finish_reason='stop',
70+
usage=Usage(input_tokens=13, output_tokens=8, …),
71+
id='resp_09b0…',
72+
provider_data=<dict: 35 keys>,
73+
)
74+
```
75+
76+
How did the router pick OpenAI? Ask it. `resolve()` is pure — no
77+
network, no key values read — and its return value is the explanation:
78+
79+
```python
80+
res = router.resolve("gpt-4.1-mini")
81+
print(res)
82+
print(res.provider, res.adapter, res.source, res.env_key)
83+
```
84+
```output
85+
'gpt-4.1-mini' -> provider 'openai' (OpenAILM); via built-in rule prefix='gpt-' — OpenAI GPT family (Responses API; use openai_chat: for Chat Completions); wire model 'gpt-4.1-mini'; key from $OPENAI_API_KEY.
86+
openai OpenAILM rule OPENAI_API_KEY
87+
```
88+
89+
A `provider:` prefix bypasses the rule table and is always unambiguous:
90+
91+
```python
92+
print(router.resolve("anthropic:claude-sonnet-4-5"))
93+
```
94+
```output
95+
'anthropic:claude-sonnet-4-5' -> provider 'anthropic' (AnthropicLM); via explicit provider prefix; wire model 'claude-sonnet-4-5'; key from $ANTHROPIC_API_KEY.
96+
```
97+
98+
The router never guesses. A string it cannot place raises
99+
`UnknownModelError` with the fixes spelled out:
100+
101+
```python
102+
router.resolve("qwen3.5:0.8b")
103+
```
104+
```output
105+
Traceback (most recent call last):
106+
…
107+
lm15.router.UnknownModelError: could not route model 'qwen3.5:0.8b': no provider prefix, no catalog supplied, and none of the 6 built-in rules matched. Use an explicit provider prefix, e.g. "anthropic:qwen3.5:0.8b" (known providers: anthropic, claude-code, gemini, openai, openai-codex, openai_chat). Or pass a model catalog: …
108+
```
109+
110+
The router is sugar, not a layer. The direct LM classes are first-class
111+
and take the same `Request`. The same prompt, three providers:
112+
113+
```python
114+
prompt = (Message.user("Say hello in five words."),)
115+
116+
openai_lm = OpenAILM(api_key=os.environ["OPENAI_API_KEY"])
117+
print(openai_lm.complete(Request(model="gpt-4.1-mini", messages=prompt)).text)
118+
119+
anthropic_lm = AnthropicLM(api_key=os.environ["ANTHROPIC_API_KEY"])
120+
print(anthropic_lm.complete(Request(model="claude-sonnet-4-5", messages=prompt)).text)
121+
122+
gemini_lm = GeminiLM(api_key=os.environ["GEMINI_API_KEY"])
123+
print(gemini_lm.complete(Request(model="gemini-3-flash-preview", messages=prompt)).text)
124+
```
125+
```output
126+
Hello there! Hope you're well!
127+
Hello, how are you today?
128+
Hello, how are you doing?
129+
```
130+
131+
`AsyncLMRouter` is the async mirror — `complete` is awaitable,
132+
`resolve()` stays sync because it is pure:
133+
134+
```python
135+
async def main():
136+
arouter = AsyncLMRouter()
137+
response = await arouter.complete(
138+
Request(model="gemini-3-flash-preview", messages=prompt)
139+
)
140+
print(response.text)
141+
142+
asyncio.run(main())
143+
```
144+
```output
145+
Hello, how are you today?
146+
```
147+
148+
## How it works
149+
150+
A `Request` is a frozen dataclass: a model string and a tuple of
151+
`Message` objects (plus optional `Config`, tools, and more in later
152+
recipes). `router.complete(request)` does three things: resolve the
153+
model string, build (and cache) the provider LM, and call its
154+
`complete()`. Resolution walks three fixed rungs — explicit
155+
`provider:` prefix, optional catalog, built-in prefix rules — first
156+
match wins, no fallback chains. The full grammar and the catalog rung
157+
are in [Using the router](../using-the-router.md).
158+
159+
Credentials follow the provider's manifest: `OpenAILM` declares
160+
`OPENAI_API_KEY`, and that is the only place the router looks unless
161+
you pass `RouterConfig(api_keys=...)`. A missing key raises
162+
`MissingCredentialError` at `lm()` time, not a 401 at request time.
163+
`resolve()` records *which* env var would be read, never its value.
164+
165+
Both paths — router and direct LM — produce the identical `Request`
166+
and identical wire bytes. lm15 deliberately does not retry, does not
167+
pool connections behind your back, and does not pick a model for you:
168+
one call in, one typed `Response` out.
169+
170+
## Variations
171+
172+
- **Keep the LM, drop the router.** `router.lm("gpt-4.1-mini")`
173+
returns a plain `OpenAILM`; configure it once and never resolve
174+
again.
175+
- **Direct LMs are for configuration, not preference.** Reach for them
176+
when you need a custom `base_url` or compat preset (ollama, vLLM —
177+
recipe [14](14-local-and-compatible-servers.md)) or when you are a
178+
library taking an LM object from your caller.
179+
- **Async direct LMs exist too**: `AsyncOpenAILM`, `AsyncAnthropicLM`,
180+
`AsyncGeminiLM`, same constructors, awaitable `complete`.
181+
- **OpenAI has two providers.** Bare `gpt-` routes to the Responses
182+
API (`OpenAILM`); `"openai_chat:gpt-4.1-mini"` selects Chat
183+
Completions (`OpenAIChatLM`). The resolve output above says so.
184+
185+
## See also
186+
187+
- [02 — Multi-turn conversations](02-conversations.md)
188+
- [04 — Controlling generation](04-generation-config.md)
189+
- [05 — Streaming](05-streaming.md)
190+
- [Using the router](../using-the-router.md) — grammar, catalogs, credentials
191+
- [15 — Errors, retries & testing](15-errors-and-testing.md)

‎docs/cookbooks/02-conversations.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
# Multi-turn conversations
2+
3+
**Problem** — you want the model to remember earlier turns, but lm15 has
4+
no session object, no `chat.append()`, no hidden state. The conversation
5+
is a tuple of `Message` values that you build, extend, and persist
6+
yourself — which also means you can inspect, edit, and replay it.
7+
8+
Keys loaded as in [recipe 01](01-first-request.md).
9+
10+
## Recipe
11+
12+
A conversation starts as a tuple with one user message. `complete()`
13+
returns a `Response`; `response.text` is the assistant's reply as a
14+
string.
15+
16+
```python
17+
import json
18+
import pathlib
19+
20+
from lm15 import LMRouter, Message, Request, messages_from_json, messages_to_json
21+
22+
router = LMRouter()
23+
history = (Message.user("Pick a prime number between 80 and 90. Answer with the number only."),)
24+
25+
response = router.complete(Request(model="gpt-4.1-mini", messages=history))
26+
print(response.text)
27+
```
28+
```output
29+
83
30+
```
31+
32+
To take another turn, build a *new* tuple: the old history, the
33+
assistant's full message (`response.message`, not just its text), and
34+
your next user message. Messages are frozen; `(*history, ...)` is the
35+
append operation.
36+
37+
```python
38+
history = (*history, response.message, Message.user("Add 6 to it. Number only."))
39+
40+
response = router.complete(Request(model="gpt-4.1-mini", messages=history))
41+
print(response.text)
42+
```
43+
```output
44+
89
45+
```
46+
47+
`Message.text` is the per-message convenience: the joined text when the
48+
message is text-only, `None` if it carries any other part (a tool call,
49+
an image). That strictness is deliberate — a transcript printer that
50+
silently drops tool calls is a bug factory.
51+
52+
```python
53+
history = (*history, response.message)
54+
for m in history:
55+
print(f"{m.role:>9}: {m.text}")
56+
```
57+
```output
58+
user: Pick a prime number between 80 and 90. Answer with the number only.
59+
assistant: 83
60+
user: Add 6 to it. Number only.
61+
assistant: 89
62+
```
63+
64+
To persist the conversation, `messages_to_json` produces plain dicts in
65+
lm15's canonical JSON shape — `json.dumps` away from disk.
66+
67+
```python
68+
path = pathlib.Path("conversation.json")
69+
path.write_text(json.dumps(messages_to_json(history), indent=2))
70+
print(path.read_text()[:200])
71+
```
72+
```output
73+
[
74+
{
75+
"role": "user",
76+
"parts": [
77+
{
78+
"type": "text",
79+
"text": "Pick a prime number between 80 and 90. Answer with the number only."
80+
}
81+
]
82+
},
83+
…
84+
```
85+
86+
Loading it back round-trips to equal `Message` values. The history is
87+
provider-neutral, so the same transcript can continue on a different
88+
model.
89+
90+
```python
91+
restored = tuple(messages_from_json(json.loads(path.read_text())))
92+
print(restored == history)
93+
94+
response = router.complete(Request(
95+
model="gemini-3-flash-preview",
96+
messages=(*restored, Message.user("What number did we end on, and is it prime?")),
97+
))
98+
print(response.text)
99+
```
100+
```output
101+
True
102+
We ended on 89, and it is a prime number.
103+
```
104+
105+
## How it works
106+
107+
Chat APIs are stateless: every request carries the whole conversation,
108+
and the provider replays it. lm15 mirrors that on the surface instead of
109+
hiding it. `Request.messages` is a tuple of frozen `Message` values;
110+
each `Message` is a role plus a tuple of typed parts (`TextPart`,
111+
`ToolCallPart`, …). Nothing in the library mutates or remembers them —
112+
the LM objects and the router hold no conversation state, so the same
113+
`history` tuple can be sent to two providers, forked into two branches,
114+
or trimmed for context-window budget, all with ordinary tuple code.
115+
116+
Append `response.message`, never a hand-built
117+
`Message.assistant(response.text)`. The full message preserves
118+
non-text parts — tool calls, thinking blocks, provider continuation
119+
state — that the next turn may depend on. `Response.text` exists for
120+
display; `response.message` is the thing that goes back on the wire.
121+
122+
`messages_to_json` / `messages_from_json` implement lm15's canonical
123+
JSON form for messages — the format specified in
124+
[Serde rules](../serde-rules.md), not any provider's wire shape. That is
125+
why a transcript saved mid-conversation with OpenAI loads and continues
126+
on Gemini: translation to provider wire format happens later, inside
127+
each LM's `build_request`. Binary parts (images, audio) serialize too;
128+
their bytes are base64 inside the JSON, so transcripts with media get
129+
large.
130+
131+
What lm15 deliberately does not do: truncation, summarization, sliding
132+
windows, token counting. Context management is policy, and the tuple is
133+
the whole interface for implementing yours.
134+
135+
## Variations
136+
137+
- **Async mirror.** Identical shapes with `AsyncLMRouter`; only the call
138+
is awaited:
139+
140+
```python
141+
from lm15 import AsyncLMRouter
142+
143+
router = AsyncLMRouter()
144+
response = await router.complete(Request(model="gpt-4.1-mini", messages=history))
145+
history = (*history, response.message)
146+
```
147+
148+
- **Mid-conversation instructions.** `Message.developer("...")` injects
149+
high-authority instructions at any position without restarting the
150+
conversation. OpenAI sees a native `developer` role; Anthropic and
151+
Gemini get a user message with a `[developer]` prefix. See
152+
[recipe 03](03-system-prompts.md).
153+
- **Assistant prefill.** End `messages` with a partial
154+
`Message.assistant(...)` and the model continues it — Anthropic honors
155+
the prefix verbatim; Gemini usually continues it; OpenAI's Responses
156+
API tends to answer fresh instead:
157+
158+
```python
159+
req = Request(
160+
model="claude-sonnet-4-5",
161+
messages=(
162+
Message.user("What is 2 + 2? Answer in one short sentence."),
163+
Message.assistant("Arr, as a pirate I"),
164+
),
165+
)
166+
print(repr(router.complete(req).text))
167+
```
168+
```output
169+
"'d say 2 + 2 be 4, matey!"
170+
```
171+
172+
- **Branching.** Tuples make forks free: keep `base = history[:4]` and
173+
extend it two different ways; the shared prefix is the same objects,
174+
which also keeps provider prompt caches warm
175+
([recipe 11](11-caching.md)).
176+
- **`Message.text` vs `Response.text`.** `Message.text` is `None` for
177+
any mixed-part message. `Response.text` is slightly more forgiving on
178+
its own `message` — it joins the `TextPart`s of a reply that also
179+
carries thinking or citations. For transcripts, filter explicitly with
180+
`m.parts_of(TextPart)`.
181+
- **Lists are rejected loudly.** `Message.parts` must be `Part` objects;
182+
passing a raw string raises
183+
`TypeError: Message.parts must be Part objects; use Message.user('text') for strings`.
184+
The factory methods (`Message.user`, `.assistant`, `.developer`,
185+
`.tool`) are the intended constructors.
186+
187+
## See also
188+
189+
- [01 — Your first request](01-first-request.md) — router setup and key loading.
190+
- [03 — System & developer prompts](03-system-prompts.md) — where instructions go.
191+
- [06 — Function tools](06-function-tools.md) — tool calls and results in the history tuple.
192+
- [11 — Prompt caching](11-caching.md) — long shared prefixes, paid once.
193+
- [Serde rules](../serde-rules.md) — the canonical JSON format behind `messages_to_json`.

0 commit comments

Comments
 (0)