programasweights 0.2.5__tar.gz → 0.2.8__tar.gz

programasweights-0.2.8/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.env
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+*.so

{programasweights-0.2.5 → programasweights-0.2.8}/AGENTS.md

@@ -3,7 +3,7 @@
 PAW compiles natural language specifications into tiny neural functions that run locally. Each function takes a single text input and returns a single text output. Use it when you need fuzzy text processing — classification, extraction, format repair, search, triage — that regex can't handle but a full LLM is overkill for.
 
 Website: https://programasweights.com
-Docs: https://programasweights.readthedocs.io
+Full documentation: https://programasweights.readthedocs.io
 
 ## Install
 
@@ -20,7 +20,7 @@ import programasweights as paw
 # "email-triage" is an official pre-compiled program (slug)
 fn = paw.function("email-triage")
 fn("Urgent: server is down!")  # "immediate"
-fn("Newsletter: spring picnic")  # "wait"
+fn("Newsletter: spring picnic")  # "can wait"
 
 # Compile your own from a description
 program = paw.compile(
@@ -37,16 +37,8 @@ fn("I love this!")  # "positive"
 
 ## Two Compilers
 
-| | Standard (Qwen3 0.6B) | Compact (GPT-2 124M) |
-|---|---|---|
-| Compiler name | `paw-4b-qwen3-0.6b` | `paw-4b-gpt2` |
-| Accuracy | Higher | Lower |
-| Base model size | 594 MB | 105 MB |
-| Program size | ~22 MB | ~5 MB |
-| Inference speed | ~90ms (server) | ~50ms (server) |
-| Runs in browser | No | Yes (must use this compiler) |
-
-Default is Standard. Use Compact for smaller files or browser deployment.
+- **Standard** (`paw-4b-qwen3-0.6b`) — higher accuracy, 594 MB base + ~22 MB/program. Default.
+- **Compact** (`paw-4b-gpt2`) — smaller (105 MB base + ~5 MB/program), runs in browser via WebAssembly.
 
 ## When to Use PAW
 
@@ -60,7 +52,9 @@ Default is Standard. Use Compact for smaller files or browser deployment.
 
 ## Writing Good Specs
 
-Description + examples. Use `Input: ... Output: ...` format.
+**The #1 practice: iterate with test cases.** Do not accept low performance on the first try. Build a test suite of input/output pairs, measure accuracy, then iteratively adjust wording and formatting until performance is good enough. Treat spec writing like software engineering: test, debug specific failures, fix the wording, retest.
+
+A good spec has a description plus `Input: ... Output: ...` examples.
 
 ```python
 fn = paw.compile_and_load("""
@@ -77,9 +71,17 @@ Output: delete
 """)
 ```
 
-- State output constraints explicitly if any: "Return ONLY one of: X, Y, Z"
-- Each function is stateless: one input, one output. No conversation history.
-- Write a few test inputs with expected outputs, then try different spec phrasings and pick the one that passes the most.
+**Spec-tuning tips:**
+
+- Each function is stateless: one text input, one text output. No conversation history.
+- **State output constraints explicitly**: "Return ONLY one of: X, Y, Z". Without this the model may produce free-form text.
+- **Include examples from your actual data**: Examples outperform prose-only descriptions.
+- **Debug failures before sweeping**: Look at specific failing examples and understand WHY before trying many variants.
+
+## Context Window
+
+- Spec + input + output share a ~2048 token context window. Inputs that exceed it will error.
+- `max_tokens` defaults to `None`: generation runs until EOS or the context limit.
 
 ## Chaining Functions
 
@@ -94,7 +96,35 @@ if label != "other":
     fix = fixer(f"{label}: {code_snippet}")
 ```
 
-Each function is independent -- chain them with regular Python logic.
+Chain them with regular Python logic.
+
+## Log Monitoring
+
+PAW functions can classify log output. Compile once with examples from your specific logs, then reuse the function locally forever:
+
+```python
+program = paw.compile("""
+Classify log lines. Return ONLY one word: ALERT or QUIET.
+
+Input: [step 100] loss=0.05 lr=0.0001
+Output: QUIET
+
+Input: [Checkpoint] Saved model at step 1000
+Output: ALERT
+
+Input: Traceback (most recent call last):
+Output: ALERT
+
+Input: Training complete. Final loss: 0.11
+Output: ALERT
+""")
+
+fn = paw.function(program.id)  # reuse with saved program.id
+fn("[step 200] loss=0.04")           # "QUIET"
+fn("[Checkpoint] Saved model")       # "ALERT"
+```
+
+Full tool with file watching, truncation, and stall detection: [examples/paw_monitor.py](https://github.com/programasweights/programasweights-python/blob/main/examples/paw_monitor.py)
 
 ## Browser / JavaScript SDK
 
@@ -129,19 +159,7 @@ Generate API keys at https://programasweights.com/settings.
 
 ## CLI
 
-```bash
-paw compile --spec "Classify sentiment" --json
-paw run --program <program_id> --input "I love this!" --json
-paw info <program_id>             # show program metadata
-paw rename <program_id> my-slug   # name a program (requires auth)
-paw login                         # save API key
-```
-
-`--json` gives structured output. Example:
-
-```json
-{"program_id": "a6b454023d41ac9ca845", "slug": null, "status": "ready", "error": null, "timings": {"total_ms": 2800}}
-```
+Commands: `paw compile --spec "..." --json`, `paw run --program <id> --input "..."`, `paw info <id>`, `paw rename <id> <slug>`, `paw login`. All support `--json` for structured output.
 
 ## Full API Reference
 
@@ -177,17 +195,12 @@ paw.login()
 
 ## Performance
 
-- **First call** ~500ms (loads base model). Subsequent calls ~50-90ms.
-- **Base model shared** across functions. Each LoRA adapter adds ~22 MB.
-- **Thread-safe** and **blocking**.
+- **First call** ~5-15s (loads base model). Subsequent calls 0.5-5s depending on input length.
+- **Base model shared** across functions on disk. Each LoRA adapter adds ~22 MB.
 - **Cache**: `~/.cache/programasweights/`. Override with `PAW_CACHE_DIR`.
 - **Offline** after first download.
 
-## Limits
-
-- Spec + input + output share a ~2048 token context window, and inputs that exceed the context window will error out (not silently truncated).
-- Setting `max_tokens` high is safe -- generation stops at EOS or when the window is full.
+## Case Studies
 
-## Browse Programs
+Detailed walkthroughs of building production systems with PAW, including what we tried and what we learned: [log monitoring](https://programasweights.readthedocs.io/en/latest/case-studies/log-monitoring/), [site navigation](https://programasweights.readthedocs.io/en/latest/case-studies/site-navigation/), [semantic search](https://programasweights.readthedocs.io/en/latest/case-studies/semantic-search/), [tool calling](https://programasweights.readthedocs.io/en/latest/case-studies/tool-calling/).
 
-https://programasweights.com/hub

{programasweights-0.2.5 → programasweights-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: programasweights
-Version: 0.2.5
+Version: 0.2.8
 Summary: Compile natural language specifications into neural programs that run locally via llama.cpp.
 Project-URL: Homepage, https://programasweights.com
 Project-URL: Repository, https://github.com/programasweights/programasweights-python
@@ -23,7 +23,7 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.9
 Requires-Dist: httpx<1.0,>=0.27.0
-Requires-Dist: llama-cpp-python<=0.3.18,>=0.3.0
+Requires-Dist: llama-cpp-python<=0.3.19,>=0.3.0
 Provides-Extra: test
 Requires-Dist: pytest; extra == 'test'
 Description-Content-Type: text/markdown
@@ -48,7 +48,7 @@ import programasweights as paw
 # Use a pre-compiled function (downloads once, runs locally forever)
 fn = paw.function("email-triage")
 fn("Urgent: the server is down!")        # "immediate"
-fn("Newsletter: spring picnic")          # "wait"
+fn("Newsletter: spring picnic")          # "can wait"
 
 # Compile your own from a description
 program = paw.compile(

{programasweights-0.2.5 → programasweights-0.2.8}/PYPI_README.md

@@ -18,7 +18,7 @@ import programasweights as paw
 # Use a pre-compiled function (downloads once, runs locally forever)
 fn = paw.function("email-triage")
 fn("Urgent: the server is down!")        # "immediate"
-fn("Newsletter: spring picnic")          # "wait"
+fn("Newsletter: spring picnic")          # "can wait"
 
 # Compile your own from a description
 program = paw.compile(

programasweights-0.2.8/README.md

@@ -0,0 +1,113 @@
+# ProgramAsWeights
+
+**Compile natural language specs into tiny neural functions that run locally.**
+
+Define what a function should do in plain English. PAW compiles it into a small neural program that runs on your machine — no API keys at runtime, no internet needed after setup, fully deterministic.
+
+## Install
+
+```bash
+pip install programasweights
+```
+
+## Quick Start
+
+```python
+import programasweights as paw
+
+# Use a pre-compiled function (downloads once, runs locally forever)
+fn = paw.function("email-triage")
+fn("Urgent: the server is down!")        # "immediate"
+fn("Newsletter: spring picnic")          # "can wait"
+
+# Compile your own from a description
+program = paw.compile(
+    "Fix malformed JSON: repair missing quotes and trailing commas",
+    compiler="paw-4b-qwen3-0.6b"  # or "paw-4b-gpt2" for smaller/faster
+)
+fn = paw.function(program.id)
+fn("{name: 'Alice',}")  # '{"name": "Alice"}'
+```
+
+## Two Compilers
+
+|                    | Standard (Qwen3 0.6B)   | Compact (GPT-2 124M)   |
+|--------------------|-------------------------|------------------------|
+| Compiler name      | `paw-4b-qwen3-0.6b`    | `paw-4b-gpt2`          |
+| Accuracy           | Higher                  | Lower                  |
+| Base model size    | 594 MB                  | 105 MB                 |
+| Program size       | ~22 MB                  | ~5 MB                  |
+| Inference speed    | ~90ms (server)          | ~50ms (server)         |
+| Runs in browser    | No                      | Yes                    |
+
+Default is Standard (Qwen3 0.6B). Use Compact (GPT-2) when you need smaller files or browser deployment.
+
+## Browser SDK
+
+Programs compiled with GPT-2 also run entirely in the browser via WebAssembly — no server needed, data never leaves the user's device.
+
+```bash
+npm install @programasweights/web
+```
+
+```javascript
+import paw from '@programasweights/web';
+
+const fn = await paw.function('programasweights/email-triage');
+const result = await fn('Urgent: the server is down!');
+// result: "immediate"
+```
+
+See the [browser SDK repo](https://github.com/programasweights/programasweights-js) for full documentation.
+
+## Use with AI Agents
+
+PAW works with Cursor, Claude, Codex, and other AI coding assistants. Paste this into your agent's chat:
+
+> I want to use ProgramAsWeights (PAW) to create fuzzy text functions that run locally. Read the instructions at https://programasweights.com/agents and help me integrate it.
+
+Or save [`AGENTS.md`](https://programasweights.com/agents) to your project root — agents read it automatically.
+
+## When to Use PAW
+
+- **Fuzzy search** — typo-tolerant matching, semantic search, near-duplicate detection
+- **Format repair** — fix broken JSON, normalize dates, repair malformed inputs
+- **Classification** — sentiment, urgency, categories defined in your own words
+- **Extraction** — emails, names, dates from messy unstructured text
+- **Log triage** — extract errors from verbose output, filter noise
+- **Intent routing** — map user descriptions to the closest URL, menu item, or setting
+- **Agent preprocessing** — parse tool calls, validate outputs, route tasks
+
+## Authentication
+
+```bash
+# Option 1: environment variable (recommended)
+export PAW_API_KEY=paw_sk_...
+
+# Option 2: CLI login (opens browser to generate key)
+paw login
+```
+
+Generate API keys at [programasweights.com/settings](https://programasweights.com/settings). Authenticated users get higher rate limits.
+
+## CLI
+
+```bash
+paw compile --spec "Extract error lines from logs" --json
+paw run --program <program_id> --input "[ERROR] timeout" --json
+paw login
+```
+
+`--json` gives structured output for programmatic use.
+
+## Links
+
+- **Website**: [programasweights.com](https://programasweights.com)
+- **Documentation**: [programasweights.readthedocs.io](https://programasweights.readthedocs.io)
+- **Python SDK**: [github.com/programasweights/programasweights-python](https://github.com/programasweights/programasweights-python)
+- **Browser SDK**: [github.com/programasweights/programasweights-js](https://github.com/programasweights/programasweights-js)
+- **Program Hub**: [programasweights.com/hub](https://programasweights.com/hub)
+
+## License
+
+MIT

{programasweights-0.2.5 → programasweights-0.2.8}/docs/adr/001-llama-cpp-over-pytorch.md

@@ -17,5 +17,5 @@ Replace the PyTorch runtime with llama-cpp-python (~80MB install). Use GGUF mode
 - Inference uses Metal (Mac), CPU (Linux/Windows) — no GPU required
 - Must pre-render chat templates server-side (no transformers tokenizer on client)
 - .paw format must change from v2 (safetensors) to v3 (GGUF adapter)
-- Base model is downloaded once (~623MB for Q6_K) and shared across all functions
+- Base model is downloaded once (~594 MB for Q6_K) and shared across all functions
 - Per-function adapter download is ~23MB (Q4_0, confirmed lossless at 4096-scale eval)

{programasweights-0.2.5 → programasweights-0.2.8}/docs/api-reference/cli.md

@@ -57,7 +57,7 @@ paw rename <program_id> <new-slug> [--json]
 | Argument | Description |
 |----------|-------------|
 | `program_id` | Program hash ID or current slug. |
-| `new-slug` | New slug name (2-50 chars, lowercase alphanumeric and hyphens). |
+| `new-slug` | New slug name (2-50 chars, lowercase alphanumeric and hyphens). Pass `""` to remove. |
 
 ## `paw info`
 

{programasweights-0.2.5 → programasweights-0.2.8}/docs/api-reference/python-sdk.md

@@ -41,7 +41,7 @@ output: str = fn(input_text, max_tokens=None, temperature=0.0)
 | `max_tokens` | Maximum tokens to generate. `None` (default) = use all remaining context window. |
 | `temperature` | Sampling temperature (default `0.0`). |
 
-**Context limits:** Spec + input + output share a ~2048 token window. If input + output together exceed the window, generation will error. For short inputs, high `max_tokens` is safe (stops at EOS). For long inputs, set `max_tokens` conservatively.
+**Context limits:** Spec + input + output share a ~2048 token window. Inputs that exceed it will error. `max_tokens` defaults to `None`: generation runs until EOS or the context limit.
 
 ## `paw.compile`
 

{programasweights-0.2.5 → programasweights-0.2.8}/docs/architecture.md

@@ -31,7 +31,7 @@ vLLM multi-LoRA serving on GPU 2 (or GPU 1 in 2-GPU config). Each compiled progr
 
 ## Inference (Client-side SDK)
 
-llama-cpp-python loads the base GGUF model (623MB, downloaded once) and hot-swaps Q4_0 adapters per function call. No PyTorch or transformers required.
+llama-cpp-python loads the base GGUF model (594 MB, downloaded once) and hot-swaps Q4_0 adapters per function call. No PyTorch or transformers required.
 
 ## GPU Assignment
 

programasweights-0.2.8/docs/case-studies/log-monitoring.md

@@ -0,0 +1,132 @@
+# Event-Driven Log Monitoring
+
+Long-running processes -- training runs, deployments, data pipelines -- produce thousands of log lines. You want to know when something important happens (checkpoint saved, error, completion) without watching the terminal. PAW lets you compile a classifier that runs locally and alerts on the lines that matter.
+
+**Full tool:** [examples/paw_monitor.py](https://github.com/programasweights/programasweights-python/blob/main/examples/paw_monitor.py) on GitHub.
+
+## How we built it
+
+### Attempt 1: Keyword matching
+
+The obvious first approach: grep for "error", "fail", "complete".
+
+**Result:** Too noisy. "error" matches "error_count=0" (routine metric). "complete" matches "batch complete" (every 10 seconds). Missing important lines like "Traceback" or "CUDA out of memory" that don't contain the keywords.
+
+**Lesson:** The whole reason to use PAW is that keyword matching can't express "important enough to interrupt me."
+
+### Attempt 2: One-shot description
+
+```
+Classify if this log line is important enough to alert on. Return ALERT or QUIET.
+```
+
+**Result:** Too vague. The model alerted on everything that looked unusual, including routine debug output. "Important" means different things in different contexts.
+
+**Lesson:** Don't rely on abstract instructions. The model needs concrete examples of what ALERT and QUIET look like in YOUR specific logs.
+
+### Attempt 3: Example-based spec
+
+```
+Classify log lines. Return ONLY one word: ALERT or QUIET.
+
+Input: [step 100] loss=0.05 lr=0.0001
+Output: QUIET
+
+Input: [Checkpoint] Saved model at step 1000
+Output: ALERT
+
+Input: Traceback (most recent call last):
+Output: ALERT
+
+Input: Training complete. Final loss: 0.11
+Output: ALERT
+```
+
+**Result:** This worked. The model learned the boundary between routine metrics (QUIET) and significant events (ALERT) from the examples. Adding 3-5 examples from actual logs was the key.
+
+**Lesson:** Include examples from your actual data. 3-5 representative examples consistently outperform prose-only descriptions.
+
+### Refinement: Developer feedback
+
+A developer using PAW for monitoring diffusion model training shared their experience. Key insights:
+
+- **Positive instructions work better than negative ones.** "Output ALERT only if X, Y, or Z" is more reliable than "Don't alert on routine output."
+- **The spec should match the monitoring context.** Different training phases produce different log patterns. Examples should cover the specific domain.
+- **Stall detection needs a separate mechanism.** PAW classifies what it sees -- it can't detect the absence of output. The monitoring tool needs a timer for "no new output in N minutes."
+
+## The solution
+
+### The spec
+
+```python
+program = paw.compile("""
+Classify log lines. Return ONLY one word: ALERT or QUIET.
+
+Input: [step 100] loss=0.05 lr=0.0001
+Output: QUIET
+
+Input: [Checkpoint] Saved model at step 1000
+Output: ALERT
+
+Input: Traceback (most recent call last):
+Output: ALERT
+
+Input: Training complete. Final loss: 0.11
+Output: ALERT
+""")
+
+fn = paw.function(program.id)
+```
+
+Compile once, save the program ID, reuse forever. The function runs locally with no internet after the first download.
+
+### The monitoring loop
+
+```python
+import time
+
+fn = paw.function("your-program-id")
+
+last_size = 0
+while True:
+    size = os.path.getsize(log_file)
+    if size > last_size:
+        with open(log_file) as f:
+            f.seek(last_size)
+            new_text = f.read()
+        last_size = size
+
+        # Truncate to last ~1000 chars to fit context window
+        chunk = new_text[-1000:] if len(new_text) > 1000 else new_text
+        result = fn(chunk)
+        if result.strip() == "ALERT":
+            send_notification(chunk)
+
+    time.sleep(10)
+```
+
+### Full tool
+
+The complete [paw_monitor.py](https://github.com/programasweights/programasweights-python/blob/main/examples/paw_monitor.py) adds:
+
+- **File watching** with `seek()` to only process new content
+- **Input truncation** to fit the ~2048 token context window
+- **Stall detection** -- alerts if no new output for a configurable timeout
+- **`--focus` and `--ignore`** flags to guide what the classifier pays attention to
+- **`--local` flag** to run entirely offline after first compile
+- **`--json` output** for integration with other tools
+
+## Adapting this for your use case
+
+1. **Collect 5-10 example log lines** from your actual process -- a mix of routine output and important events
+2. **Write a spec** with `Input: ... Output: ALERT/QUIET` pairs
+3. **Test with real logs** -- pipe a log file through the classifier and check which lines it flags
+4. **Iterate** -- if it alerts too much, add more QUIET examples. If it misses things, add ALERT examples.
+5. **Save the program ID** -- compile once, monitor forever
+
+## Takeaways
+
+- **Examples beat descriptions** for teaching the model your specific log patterns.
+- **Compile once, run forever.** The compiled function is cached locally and needs no internet.
+- **PAW classifies what it sees** -- combine with a timer for stall detection.
+- **Iterate with real data.** The first spec is rarely perfect. Test, check failures, adjust examples.

programasweights-0.2.8/docs/case-studies/semantic-search.md

@@ -0,0 +1,146 @@
+# Semantic Search Without a Vector Database
+
+Most websites rely on keyword search — PostgreSQL full-text search, Elasticsearch, or similar. These work for exact terms but miss intent: a search for "something that works in the browser" won't match a program described as "runs client-side via WebAssembly." Adding semantic understanding normally requires vector databases, embedding pipelines, and external services. PAW lets you add intent-aware reranking on top of your existing search — no infrastructure changes, no embeddings, no external dependencies.
+
+**Try it live:** Search at [programasweights.com/hub](https://programasweights.com/hub) — try queries like "something that works in the browser" or "not a classifier."
+
+## How we built it
+
+### Attempt 1: Numeric relevance scoring (1–10)
+
+The obvious approach: compile a scorer that rates each search result on a 1–10 scale.
+
+```
+Rate the relevance of this search result to the query on a scale of 1-10.
+Query: "counting tasks"
+```
+
+**Result:** The model clustered everything at 8–10. A search for "counting tasks" gave 9/10 to a sentiment classifier because it vaguely involved processing text. No discrimination.
+
+**Lesson:** Small models can't produce fine-grained numeric scores. They don't have a calibrated sense of what "7 vs 8" means.
+
+### Attempt 2: Binary yes/no
+
+Simplify to binary: is this result relevant or not?
+
+```
+Is this search result relevant to the query? Return YES or NO.
+```
+
+**Result:** Better discrimination, but couldn't distinguish "perfect match" from "vaguely related." Everything relevant got YES, so the top results were still unordered.
+
+**Lesson:** Binary lacks granularity. You need at least 3–4 buckets to produce a meaningful ranking.
+
+### Attempt 3: Discrete categories
+
+Use 3–4 named categories that map to sort order:
+
+```
+Rate how well the candidate matches the query.
+Return ONLY one of: exact_match, highly_relevant, somewhat_relevant, not_relevant
+```
+
+**Result:** Much better. The model could reliably distinguish "this is exactly what they asked for" from "this is tangentially related." Mapping `exact_match=3, highly_relevant=2, somewhat_relevant=1, not_relevant=0` produced clean rankings.
+
+**Lesson:** Discrete named categories work where numeric scales fail. The names give the model clear semantic anchors.
+
+### Attempt 4: Explicit exclusion rules
+
+A search for "not a classifier" still returned classifiers ranked highly. The model ignored the negation.
+
+**Fix:** Add an explicit rule for exclusions in the spec:
+
+```
+If the query excludes something, those candidates are not_relevant.
+```
+
+**Result:** Negation queries started working. "Not a classifier" correctly demoted classifiers.
+
+**Lesson:** State rules explicitly. Don't assume the model infers constraints from the query — spell them out in the spec.
+
+## The solution
+
+### Spec template
+
+```python
+SCORER_SPEC = """
+You are a search matcher. Rate how well the candidate matches the query.
+Match all constraints: {constraint_types}.
+If the query excludes something, those candidates are not_relevant.
+
+Query: "{query}"
+
+Return ONLY one of: exact_match, highly_relevant, somewhat_relevant, not_relevant
+"""
+
+scorer = paw.compile(SCORER_SPEC.format(
+    constraint_types="topic, author, and category",
+    query="counting tasks by da03",
+))
+```
+
+Replace `constraint_types` with whatever metadata your search results have (topic, author, date, category, price range, etc.).
+
+### Architecture
+
+```
+User query
+    │
+    ▼
+Keyword search (FTS / Elasticsearch / etc.)
+    │ returns top N candidates
+    ▼
+Compile PAW scorer for this query (cached by query text)
+    │
+    ▼
+Score each candidate ──► exact_match / highly_relevant / somewhat / not_relevant
+    │                         │
+    ▼                         ▼
+Map to integers          Sort descending
+    │
+    ▼
+Return reranked results
+```
+
+### Candidate formatting
+
+Each candidate is passed to the scorer as a text block. Include the fields that matter for your domain:
+
+```python
+SCORE_MAP = {"exact_match": 3, "highly_relevant": 2, "somewhat_relevant": 1, "not_relevant": 0}
+
+def rerank(query: str, candidates: list[dict]) -> list[dict]:
+    scorer = paw.compile_and_load(SCORER_SPEC.format(
+        constraint_types="topic, author, and category",
+        query=query,
+    ))
+
+    scored = []
+    for c in candidates:
+        text = f"Name: {c['name']}\nAuthor: {c['author']}\nDescription: {c['description']}"
+        label = scorer(text)
+        scored.append((SCORE_MAP.get(label, 0), c))
+
+    scored.sort(key=lambda x: x[0], reverse=True)
+    return [c for _, c in scored]
+```
+
+### Progressive UX
+
+Show keyword results immediately. If the server isn't busy, fire the reranking in the background and update the results once scoring completes. Users see instant results that get refined — no loading spinner.
+
+## Adapting this for your site
+
+1. **Start with your existing search.** PAW reranking is a layer on top — it doesn't replace your keyword search.
+2. **Pick your constraint types.** What metadata do your results have? Topic, author, price, date, location?
+3. **Compile a scorer** with the template above, replacing `constraint_types` and `query`.
+4. **Score your top 10–20 results.** Don't score everything — just the candidates that keyword search already found promising.
+5. **Build a test set** of 10–20 queries with known-good rankings. Iterate on the spec until it discriminates well.
+6. The scorer is cached by query text — repeated searches are instant.
+
+## Takeaways
+
+- **Discrete categories beat numeric scales** for small models. Use 3–4 named buckets.
+- **State constraints and exclusions explicitly** in the spec. The model won't infer them from the query alone.
+- **Rerank, don't replace.** Layer PAW scoring on top of existing keyword search for the best of both worlds.
+- **Test with adversarial queries** — negations, ambiguous terms, author-specific searches — to find spec weaknesses early.