@@ -1,124 +1,172 @@
-# lm15 (Universal LM) — thin core, full plugin contract
+# lm15
 
 [![PyPI version](https://img.shields.io/pypi/v/lm15.svg)](https://pypi.org/project/lm15/)
-[![Python versions](https://img.shields.io/pypi/pyversions/lm15.svg)](https://pypi.org/project/lm15/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/pypi/pyversions/lm15.svg)](https://pypi.org/project/lm15/)
+[![MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-A universal LM core optimized for low import/runtime overhead with provider plugins.
+One interface for OpenAI, Anthropic, and Gemini. Zero dependencies.
 
-## Core architecture
+| | lm15 | google-genai | litellm |
+|---|---:|---:|---:|
+| **install** | 72ms | 137ms | 184ms |
+| **import** | 95ms | 2,656ms | 4,534ms |
+| **total (install → response)** | **1,090ms** | **3,992ms** | **5,840ms** |
+| dependencies | 0 | 25 | 55 |
+| disk footprint | 408K | 41M | 155M |
 
-- **Universal contract** (`types.py`): normalized request/response/stream/live types.
-- **Provider plugin contract** (`providers/base.py`): complete/stream/live/embeddings/files/batch/images/audio methods.
-- **Transport boundary** (`transports/*`): urllib and pycurl implementations.
-- **Capability resolver** (`capabilities.py`): static + optional hydration from models.dev.
-- **Model catalog bridge** (`model_catalog.py`): loads `https://models.dev/api.json`.
-- **Middleware pipeline** (`middleware.py`): retries/history/cache wrappers.
-- **Completeness harness** (`completeness/*`): fixture + live probes, score output.
+<sub>Median of 10 cold-start runs. Fresh venv, single completion against `gemini-3.1-flash-lite-preview`. [Benchmark source.](benchmarks/cold_start.sh)</sub>
 
-## Support matrix (current adapters)
+```python
+from lm15 import LMRequest, Message, Part, build_default
+
+lm = build_default()
+resp = lm.complete(LMRequest(
+    model="claude-sonnet-4-5",
+    messages=(Message(role="user", parts=(Part.text_part("Hello."),)),),
+))
+print(resp.message.parts[0].text)
+```
+
+Switch models by changing the string. Same types, same streaming protocol, same error hierarchy. That's it.
+
+> Yes, [we know](https://xkcd.com/927/).
 
-| Provider | complete | stream | embeddings | files | batches | images | audio | live |
-|---|---:|---:|---:|---:|---:|---:|---:|---:|
-| OpenAI | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
-| Anthropic | ✅ | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ |
-| Gemini | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
+## Why this exists
+
+Every LLM wrapper either (a) ships a massive SDK per provider or (b) papers over differences with a lossy abstraction. lm15 takes a different cut:
+
+- **Stdlib only.** No `requests`, no `httpx`, no `aiohttp`. Transport is `urllib` or optional `pycurl`.
+- **Frozen dataclasses all the way down.** `LMRequest` in, `LMResponse` out. No mutable builder chains, no hidden state.
+- **Nothing is hidden.** Provider-specific options pass through `Config.provider`. The normalized types cover the common surface; the escape hatch is always there.
+- **Plugin discovery via entry points.** Third-party providers install and register without touching lm15 core.
+
+## Install
+
+```bash
+pip install lm15            # stdlib transport (urllib)
+pip install lm15[speed]     # + pycurl transport
+```
+
+Set at least one provider key:
+
+```bash
+export OPENAI_API_KEY=sk-...
+export ANTHROPIC_API_KEY=sk-ant-...
+export GEMINI_API_KEY=...         # or GOOGLE_API_KEY
+```
+
+## Usage
+
+### Streaming
+
+```python
+req = LMRequest(model="gpt-4.1-mini", messages=(...))
+for event in lm.stream(req):
+    if event.type == "delta" and event.delta and event.delta.get("type") == "text":
+        print(event.delta["text"], end="")
+```
 
-## Quick start
+### Tool calling
 
 ```python
-from lm15 import Message, LMRequest, Part, build_default
+from lm15 import Tool, ToolConfig
 
-lm = build_default(use_pycurl=True)
-req = LMRequest(model="claude-sonnet-4-5", messages=(Message(role="user", parts=(Part.text_part("Say hi."),)),))
+tools = (Tool(name="get_weather", description="...", parameters={...}),)
+req = LMRequest(model="gemini-2.5-flash", messages=(...), tools=tools)
 resp = lm.complete(req)
-print(resp.message.parts[0].text)
+# resp.message.parts may contain Part(type="tool_call", ...)
+```
+
+### Embeddings, images, audio, files, batches
+
+```python
+lm.embeddings(EmbeddingRequest(model="text-embedding-3-small", input=["hello"]))
+lm.image_generate(ImageGenerationRequest(model="gpt-image-1", prompt="a cat"))
+lm.audio_generate(AudioGenerationRequest(model="gpt-4o-mini-tts", input="hi", voice="alloy"))
+lm.file_upload(FileUploadRequest(...), provider="openai")
+lm.batch_submit(BatchRequest(...))
 ```
 
-## External plugin adapters (no core PR)
+### Middleware
 
-LM15 auto-discovers installed entry-points in group `lm15.providers`.
+```python
+from lm15 import with_retries, with_cache, with_history
+
+lm.middleware.add(with_retries(max_retries=3))
+lm.middleware.add(with_cache())
+lm.middleware.add(with_history())
+```
+
+### External plugins
+
+Any installed package can register a provider adapter:
 
 ```toml
-# in external package pyproject.toml
+# pyproject.toml of the plugin package
 [project.entry-points."lm15.providers"]
 myprovider = "lm15_x_myprovider:build_adapter"
 ```
 
 ```python
-from lm15 import build_default
-
 lm = build_default(discover_plugins=True)
 ```
 
-## Optional models.dev hydration
+### models.dev catalog
+
+Hydrate model capabilities from the [models.dev](https://models.dev) catalog at startup:
 
 ```python
 lm = build_default(hydrate_models_dev_catalog=True)
 ```
 
-## Completeness
-
-```bash
-python3 completeness/runner.py --mode fixture --fail-under 1.0
-python3 completeness/runner.py --mode live --fail-under 0.0
-```
-
-Outputs:
-- `completeness/report.json`
-- `completeness/report.md`
+## Provider support
 
-## Packaging and publishing (uv + twine)
+| Capability | OpenAI | Anthropic | Gemini |
+|---|:---:|:---:|:---:|
+| complete | ✅ | ✅ | ✅ |
+| stream | ✅ | ✅ | ✅ |
+| embeddings | ✅ | — | ✅ |
+| files | ✅ | ✅ | ✅ |
+| batches | ✅ | ✅ | ✅ |
+| images | ✅ | — | ✅ |
+| audio | ✅ | — | ✅ |
+| live | — | — | — |
 
-```bash
-# build sdist + wheel
-uv run python -m build
-
-# upload to TestPyPI
-# twine upload --repository testpypi dist/*
+## Architecture
 
-# upload to PyPI
-# twine upload dist/*
+```
+LMRequest ──▶ UniversalLM ──▶ MiddlewarePipeline ──▶ ProviderAdapter ──▶ Transport
+                  │                                        │
+                  │ resolve_provider(model)                 │ build_request / parse_response
+                  ▼                                        ▼
+            capabilities.py                         providers/{openai,anthropic,gemini}.py
 ```
 
-## Known limitations
+- **`types.py`** — all request/response/stream types as frozen dataclasses
+- **`protocols.py`** — `LMAdapter` and `LiveSession` protocols
+- **`providers/base.py`** — `BaseProviderAdapter` with default `complete`/`stream` implementations over raw HTTP
+- **`transports/`** — `urllib` and `pycurl` backends behind a `Transport` protocol
+- **`capabilities.py`** — model→provider resolution + optional models.dev hydration
+- **`middleware.py`** — composable retry / cache / history wrappers
+- **`plugins.py`** — entry-point discovery for third-party adapters
 
-- Realtime/live protocol parity is not fully implemented across all providers.
-- Completeness score is tied to the current fixture matrix; it is not a guarantee of full vendor API parity.
-- Provider-specific advanced options are partially passthrough (`config.provider`) and not all are normalized.
+## Docs
 
-## Environment variables
+| Topic | Path |
+|---|---|
+| Getting started | [`docs/GETTING_STARTED.md`](docs/GETTING_STARTED.md) |
+| Core concepts | [`docs/CONCEPTS.md`](docs/CONCEPTS.md) |
+| Architecture | [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) |
+| Provider contract | [`docs/CONTRACT.md`](docs/CONTRACT.md) |
+| Error handling | [`docs/ERRORS.md`](docs/ERRORS.md) |
+| Streaming | [`docs/STREAMING.md`](docs/STREAMING.md) |
+| Writing an adapter | [`docs/ADAPTER_GUIDE.md`](docs/ADAPTER_GUIDE.md) |
+| Adding a provider | [`docs/ADD_PROVIDER_GUIDE.md`](docs/ADD_PROVIDER_GUIDE.md) |
+| Completeness testing | [`docs/COMPLETENESS.md`](docs/COMPLETENESS.md) |
+| Production checklist | [`docs/PRODUCTION_CHECKLIST.md`](docs/PRODUCTION_CHECKLIST.md) |
 
-- `OPENAI_API_KEY`
-- `ANTHROPIC_API_KEY`
-- `GEMINI_API_KEY` or `GOOGLE_API_KEY`
+**Cookbooks:** [`docs/COOKBOOKS/`](docs/COOKBOOKS/) — 8 progressive examples from basic text to plugin development.
 
-## Docs
+## License
 
-### Core
-
-- `docs/GETTING_STARTED.md`
-- `docs/CONCEPTS.md`
-- `docs/ARCHITECTURE.md`
-- `docs/CONTRACT.md`
-- `docs/ERRORS.md`
-- `docs/STREAMING.md`
-- `docs/COMPLETENESS.md`
-- `docs/PRODUCTION_CHECKLIST.md`
-
-### Provider development
-
-- `docs/ADAPTER_GUIDE.md`
-- `docs/ADD_PROVIDER_GUIDE.md`
-- `docs/COOKBOOK_TEMPLATE.md`
-
-### Cookbooks (learning order)
-
-- `docs/COOKBOOKS/01-basic-text.md`
-- `docs/COOKBOOKS/02-streaming.md`
-- `docs/COOKBOOKS/03-tools.md`
-- `docs/COOKBOOKS/04-multimodal.md`
-- `docs/COOKBOOKS/05-files-batches.md`
-- `docs/COOKBOOKS/06-reliability.md`
-- `docs/COOKBOOKS/07-external-plugins.md`
-- `docs/COOKBOOKS/08-models-dev-hydration.md`
+MIT
@@ -0,0 +1,112 @@
+#!/bin/bash
+# Cold-start benchmark: fresh venv → install → import → client → API call.
+# Measures end-to-end latency for a single completion against Gemini.
+#
+# Requirements: uv, GEMINI_API_KEY set.
+# Usage: bash benchmarks/cold_start.sh [RUNS]
+set -e
+
+RUNS=${1:-10}
+MODEL="gemini-3.1-flash-lite-preview"
+PROMPT="Reply with exactly: ok"
+WORKDIR=$(mktemp -d)
+CSVFILE="benchmarks/cold_start_results.csv"
+
+trap "rm -rf $WORKDIR" EXIT
+
+bench_one() {
+    local label=$1 pkg=$2 script=$3
+
+    for i in $(seq 1 $RUNS); do
+        rm -rf "$WORKDIR/venv"
+
+        t_start=$(python3 -c "import time; print(time.perf_counter())")
+
+        uv venv "$WORKDIR/venv" -q 2>/dev/null
+        uv pip install -q $pkg --python "$WORKDIR/venv/bin/python" 2>/dev/null
+
+        t_installed=$(python3 -c "import time; print(time.perf_counter())")
+
+        result=$("$WORKDIR/venv/bin/python" -c "$script" 2>&1)
+
+        install_ms=$(python3 -c "print(f'{1000*($t_installed - $t_start):.0f}')")
+        rest_ms=$(echo "$result" | grep TIMINGS | sed 's/.*import=\([0-9]*\)ms client=\([0-9]*\)ms call=\([0-9]*\)ms total=\([0-9]*\)ms/\1 \2 \3 \4/')
+        import_ms=$(echo $rest_ms | cut -d' ' -f1)
+        client_ms=$(echo $rest_ms | cut -d' ' -f2)
+        call_ms=$(echo $rest_ms | cut -d' ' -f3)
+        code_total=$(echo $rest_ms | cut -d' ' -f4)
+
+        echo "$label,$i,$install_ms,$import_ms,$client_ms,$call_ms,$code_total"
+    done
+}
+
+LM15_SCRIPT="
+import time, sys, os
+t0 = time.perf_counter()
+from lm15 import LMRequest, Message, Part, build_default
+t_import = time.perf_counter()
+lm = build_default(use_pycurl=False)
+t_client = time.perf_counter()
+req = LMRequest(model='$MODEL', messages=(Message(role='user', parts=(Part.text_part('$PROMPT'),)),))
+resp = lm.complete(req)
+t_call = time.perf_counter()
+print(f'TIMINGS import={1000*(t_import-t0):.0f}ms client={1000*(t_client-t_import):.0f}ms call={1000*(t_call-t_client):.0f}ms total={1000*(t_call-t0):.0f}ms', file=sys.stderr)
+"
+
+LITELLM_SCRIPT="
+import time, sys, os
+t0 = time.perf_counter()
+import litellm
+t_import = time.perf_counter()
+t_client = time.perf_counter()
+resp = litellm.completion(model='gemini/$MODEL', messages=[{'role': 'user', 'content': '$PROMPT'}])
+t_call = time.perf_counter()
+print(f'TIMINGS import={1000*(t_import-t0):.0f}ms client={1000*(t_client-t_import):.0f}ms call={1000*(t_call-t_client):.0f}ms total={1000*(t_call-t0):.0f}ms', file=sys.stderr)
+"
+
+GENAI_SCRIPT="
+import time, sys, os
+t0 = time.perf_counter()
+from google import genai
+t_import = time.perf_counter()
+client = genai.Client(api_key=os.environ['GEMINI_API_KEY'])
+t_client = time.perf_counter()
+resp = client.models.generate_content(model='$MODEL', contents='$PROMPT')
+t_call = time.perf_counter()
+print(f'TIMINGS import={1000*(t_import-t0):.0f}ms client={1000*(t_client-t_import):.0f}ms call={1000*(t_call-t_client):.0f}ms total={1000*(t_call-t0):.0f}ms', file=sys.stderr)
+"
+
+echo "library,run,install_ms,import_ms,client_ms,call_ms,code_total_ms" | tee "$CSVFILE"
+
+bench_one "lm15" "lm15" "$LM15_SCRIPT" | tee -a "$CSVFILE"
+bench_one "litellm" "litellm" "$LITELLM_SCRIPT" | tee -a "$CSVFILE"
+bench_one "google-genai" "google-genai" "$GENAI_SCRIPT" | tee -a "$CSVFILE"
+
+echo ""
+echo "=== Medians ==="
+python3 -c "
+import csv
+from collections import defaultdict
+
+rows = defaultdict(list)
+with open('$CSVFILE') as f:
+    for r in csv.DictReader(f):
+        lib = r['library']
+        rows[lib].append({k: int(v) for k, v in r.items() if k not in ('library', 'run')})
+
+def median(vals):
+    s = sorted(vals)
+    n = len(s)
+    return s[n//2] if n % 2 else (s[n//2-1] + s[n//2]) // 2
+
+print(f'| {\"\":15s} | {\"install\":>9s} | {\"import\":>9s} | {\"client\":>9s} | {\"call\":>9s} | {\"total\":>9s} |')
+print(f'|{\"\":-<17s}|{\"\":-<11s}|{\"\":-<11s}|{\"\":-<11s}|{\"\":-<11s}|{\"\":-<11s}|')
+for lib in ['lm15', 'google-genai', 'litellm']:
+    data = rows[lib]
+    install = median([d['install_ms'] for d in data])
+    imp = median([d['import_ms'] for d in data])
+    cli = median([d['client_ms'] for d in data])
+    call = median([d['call_ms'] for d in data])
+    total = median([d['code_total_ms'] for d in data])
+    print(f'| {lib:15s} | {install:7d}ms | {imp:7d}ms | {cli:7d}ms | {call:7d}ms | {total:7d}ms |')
+"