programasweights 0.2.4__tar.gz → 0.2.7__tar.gz

programasweights-0.2.7/.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.4 → programasweights-0.2.7}/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,59 @@ 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.
+
+## Chaining Functions
+
+Multiple PAW functions can be composed for multi-step tasks:
+
+```python
+classifier = paw.compile_and_load("Classify the bug type. Return ONLY one of: off-by-one, type-error, other")
+fixer = paw.compile_and_load("Fix the bug described in the first line. Return only the corrected code.")
+
+label = classifier(code_snippet)
+if label != "other":
+    fix = fixer(f"{label}: {code_snippet}")
+```
+
+Chain them with regular Python logic.
+
+## Case Studies
+
+Production examples with iterative spec-tuning walkthroughs: [site navigation](https://programasweights.readthedocs.io/en/latest/case-studies/site-navigation/) (5-program pipeline, Cmd+K helper) and [semantic search](https://programasweights.readthedocs.io/en/latest/case-studies/semantic-search/) (reranking without a vector database).
+
+## Event-Driven 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
 
@@ -114,19 +158,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
 
@@ -143,7 +175,7 @@ fn = paw.function(program)              # accepts Program object, hash ID, or sl
 fn = paw.function("a6b454023d41ac9ca845")
 fn = paw.function("da03/my-classifier")
 
-result: str = fn(input_text: str, max_tokens=512, temperature=0.0)
+result: str = fn(input_text: str, max_tokens=None, temperature=0.0)
 
 fn = paw.compile_and_load(spec, compiler="paw-4b-qwen3-0.6b")
 
@@ -156,18 +188,19 @@ paw.login()
 
 | Error | Cause | Fix |
 |-------|-------|-----|
-| `httpx.HTTPStatusError: 404` on download | Program still uploading to CDN | SDK retries automatically. If persistent, recompile. |
+| `RuntimeError: assets not ready` on download | Program still generating after compile | SDK polls automatically for up to 30s. If persistent, recompile. |
 | `httpx.HTTPStatusError: 422` on compile | Spec too short (<10 chars) | Adjust spec length. |
 | `httpx.HTTPStatusError: 429` | Rate limit exceeded | Wait, or sign in for higher limits. |
 
 ## 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.
 
-## Browse Programs
+## Limits
+
+- 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.
 
-https://programasweights.com/hub

{programasweights-0.2.4 → programasweights-0.2.7}/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.2.4 (2026-04-01)
+
+- Download reliability: asset endpoints return 202 Retry-After when program is still generating, eliminating 404 race conditions
+- Guard local cleanup on HF upload success: files persist locally if upload fails
+- Stderr suppression now covers LoRA adapter loading (fixes CPU_REPACK warnings on 0.2.3)
+- Browser: fix LoRA switching bug (free old adapter + clear KV before loading new program)
+
+## 0.2.3 (2026-04-01)
+
+- Python 3.9 compatibility fix (`from __future__ import annotations`)
+
 ## 0.2.2 (2026-03-19)
 
 - Add `paw.compile_and_load()` convenience method (compile + load in one call)

{programasweights-0.2.4 → programasweights-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: programasweights
-Version: 0.2.4
+Version: 0.2.7
 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.4 → programasweights-0.2.7}/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.7/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.4 → programasweights-0.2.7}/docs/api-reference/python-sdk.md

@@ -32,15 +32,17 @@ Loads a compiled program and returns a callable. Downloads the program and base
 The returned callable:
 
 ```python
-output: str = fn(input_text, max_tokens=512, temperature=0.0)
+output: str = fn(input_text, max_tokens=None, temperature=0.0)
 ```
 
 | Parameter | Description |
 |-----------|-------------|
 | `input_text` | Input string for the program. |
-| `max_tokens` | Maximum tokens to generate (default `512`). |
+| `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.
+
 ## `paw.compile`
 
 ```python

programasweights-0.2.7/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.

programasweights-0.2.7/docs/case-studies/site-navigation.md

@@ -0,0 +1,127 @@
+# Natural Language Site Navigation
+
+Every website with more than a handful of pages forces users to click through menus and navigation layers to find what they need. A Cmd+K / "Quick Find" helper that understands natural language can route users instantly — but normally requires a full LLM backend. PAW lets you build this with a pipeline of tiny compiled functions.
+
+**Try it live:** Press Cmd+K (or Ctrl+K) on [programasweights.com](https://programasweights.com) and type something like "how do I run in the browser" or "where do I get an API key."
+
+## How we built it
+
+### Attempt 1: Generate the URL directly
+
+The simplest idea: compile one program with all your pages listed in the spec, ask it to output the matching URL.
+
+```
+Given a user query, return the URL of the most relevant page.
+Pages: /playground, /hub, /browser, /docs, /settings, /about
+```
+
+**Result:** The model hallucinated plausible-sounding but wrong paths (`/programs`, `/SDK`, `/api`). Small models are unreliable at generating precise strings from memory.
+
+**Lesson:** Don't ask the model to generate structured output like URLs. It will hallucinate.
+
+### Attempt 2: Reframe as classification
+
+Instead of generating URLs, output a digit: 1 = Playground, 2 = Hub, 3 = Browser, etc. The frontend maps digits to actual routes.
+
+```
+Classify the user's intent. Return ONLY a single digit.
+1 = Create or compile a new program
+2 = Browse or search existing programs
+3 = Run a program in the browser
+...
+0 = None of the above
+```
+
+**Result:** Accuracy jumped from ~67% to ~88%. Classification is far more reliable than generation for routing.
+
+**Lesson:** Reframe generation tasks as classification whenever possible. Output a label or digit, map it to the real value in your code.
+
+### Attempt 3: Add Q&A support
+
+Users don't only navigate — they also ask questions ("is PAW free?", "what languages are supported?"). We tried adding Q&A to the same program.
+
+**Result:** Cramming routing + Q&A into one spec degraded both tasks. The model couldn't handle the complexity.
+
+**Lesson:** One program, one job. When accuracy drops, split the task.
+
+### Attempt 4: Multi-program pipeline
+
+Split into specialized programs, each doing one thing well:
+
+1. **Page classifier** — routes to a page or says "this is a question"
+2. **Question-type classifier** — is it a yes/no question or a how/what question?
+3. **Yes/no answerer** — answers factual yes/no questions (facts baked into the spec)
+4. **How/what answerer** — answers descriptive questions
+5. **Answer validator** — checks "does this answer actually address the question?"
+
+The validator was the key final addition. Without it, the pipeline would sometimes produce answers like "yes" for "what is the license?" — grammatically fine but useless. The validator catches these.
+
+**Result:** The pipeline handles navigation, FAQ, and edge cases reliably. Each program compiles in seconds and runs in milliseconds.
+
+## The solution
+
+```python
+import programasweights as paw
+
+router = paw.function("my-page-router")
+q_type = paw.function("my-question-type")
+yes_no = paw.function("my-yes-no-answerer")
+howto  = paw.function("my-howto-answerer")
+validator = paw.function("my-answer-validator")
+
+def handle_query(user_query: str):
+    destination = router(user_query)
+    if destination != "0":
+        return {"action": "navigate", "page": PAGES[int(destination)]}
+
+    category = q_type(user_query)
+    if category == "yes_no":
+        answer = yes_no(user_query)
+    elif category == "how_what":
+        answer = howto(user_query)
+    else:
+        return {"action": "fallback", "message": "Try browsing the docs."}
+
+    if validator(f"Q: {user_query}\nA: {answer}") != "valid":
+        return {"action": "fallback", "message": "I'm not sure. Try the docs."}
+
+    return {"action": "answer", "text": answer}
+```
+
+Each program has a focused spec. For example, the page classifier:
+
+```python
+router = paw.compile("""
+Classify the user's intent. Return ONLY a single digit.
+1 = Create or compile something new
+2 = Browse or search existing items
+3 = Run something in the browser
+4 = Read documentation
+5 = Manage account or API keys
+0 = None of the above (likely a question)
+
+Input: how do I get started
+Output: 4
+
+Input: browse community programs
+Output: 2
+
+Input: is it free?
+Output: 0
+""")
+```
+
+## Adapting this for your site
+
+1. **List your pages** with short descriptions of what users do there
+2. **Compile a classifier** that maps intents to page numbers
+3. **Test with 20-30 real queries** your users would type — iterate on the spec wording
+4. If users also ask questions, add Q&A programs and a validator
+5. Each program compiles once and is cached forever — the pipeline runs locally with no API calls
+
+## Takeaways
+
+- **Classification beats generation** for routing. Output a label, map it in code.
+- **Multiple small programs beat one complex program.** When accuracy drops, split.
+- **A validator catches failures** the other programs miss — cheap insurance.
+- **Iterate with real queries.** Build a small test set, measure, adjust wording, repeat.

{programasweights-0.2.4 → programasweights-0.2.7}/docs/index.md

@@ -20,7 +20,7 @@ result = fn("Thesis defense committee needs your signature by EOD")
 print(result)  # "immediate"
 
 result = fn("Department newsletter: spring picnic next Friday")
-print(result)  # "wait"
+print(result)  # "can wait"
 ```
 
 ## Compile Your Own