programasweights 0.2.7__tar.gz → 0.3.0__tar.gz

{programasweights-0.2.7 → programasweights-0.3.0}/AGENTS.md

@@ -78,6 +78,11 @@ Output: delete
 - **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
 
 Multiple PAW functions can be composed for multi-step tasks:
@@ -93,11 +98,7 @@ if label != "other":
 
 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
+## Log Monitoring
 
 PAW functions can classify log output. Compile once with examples from your specific logs, then reuse the function locally forever:
 
@@ -160,6 +161,22 @@ Generate API keys at https://programasweights.com/settings.
 
 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.
 
+## Versioning
+
+Slugs support version history. Recompiling with the same slug creates a new version:
+
+```python
+p1 = paw.compile("Count words v1", slug="word-counter")  # v1
+p2 = paw.compile("Count words v2", slug="word-counter")  # v2 (auto-bumps)
+
+fn = paw.function("da03/word-counter")     # resolves to main (latest)
+fn = paw.function("da03/word-counter@v1")  # pinned to v1
+
+versions = paw.list_versions("da03/word-counter")  # all versions
+```
+
+Pinned versions (`@v1`) are immutable and cached locally forever. Bare slugs always check the server for the latest main version (falls back to cache if offline).
+
 ## Full API Reference
 
 ```python
@@ -169,16 +186,19 @@ program = paw.compile(
     slug=None,                          # URL-safe handle (requires auth)
     public=True,                        # list on public hub
 )
-# Returns: Program(id, slug, status, timings, error)
+# Returns: Program(id, slug, status, version, version_action, timings, error)
 
 fn = paw.function(program)              # accepts Program object, hash ID, or slug
 fn = paw.function("a6b454023d41ac9ca845")
 fn = paw.function("da03/my-classifier")
+fn = paw.function("da03/my-classifier@v2")  # pinned version
+fn = paw.function("da03/my-classifier", offline=True)  # skip server check
 
 result: str = fn(input_text: str, max_tokens=None, temperature=0.0)
 
 fn = paw.compile_and_load(spec, compiler="paw-4b-qwen3-0.6b")
 
+versions = paw.list_versions("da03/my-classifier")  # version history
 programs = paw.list_programs(sort="recent", per_page=20)  # requires auth
 
 paw.login()
@@ -199,8 +219,7 @@ paw.login()
 - **Cache**: `~/.cache/programasweights/`. Override with `PAW_CACHE_DIR`.
 - **Offline** after first download.
 
-## Limits
+## Case Studies
 
-- 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.
+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/).
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: programasweights
-Version: 0.2.7
+Version: 0.3.0
 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

{programasweights-0.2.7 → programasweights-0.3.0}/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.7 → programasweights-0.3.0}/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.7 → programasweights-0.3.0}/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.7 → programasweights-0.3.0}/docs/api-reference/rest-api.md

@@ -34,7 +34,11 @@ Compile a specification.
 | `name` | string | No | Display title. Auto-generated if omitted. |
 | `tags` | string[] | No | Tags for discovery. |
 
-**Response (JSON):** includes `job_id`, `status`, `program_id`, `slug` (if created), `pseudo_program`, and `timings`.
+**Response:**
+- **202 Accepted** on success — JSON with `job_id`, `status`, `program_id`, `slug` (if created), `pseudo_program`, and `timings`
+- **400** — unknown compiler
+- **422** — spec too short, too long, or token limit exceeded
+- **500** — compilation failed (server error)
 
 ### `POST /infer`
 
@@ -88,7 +92,11 @@ Owner-only fields: `public`, `name`, `tags`. Any authenticated user can set thei
 
 ### `GET /programs/{id_or_slug}/download`
 
-Redirects to the Hugging Face CDN for the `.paw` artifact. Private programs return 404 to non-owners.
+Downloads the `.paw` artifact. Returns one of:
+- **302** redirect to HuggingFace CDN (program already uploaded)
+- **200** file from server (freshly compiled, not yet on HF)
+- **202 Accepted** with `Retry-After` header (program assets still generating, retry after the indicated seconds)
+- **404** if program not found or private and not owned by the requester
 
 ### `GET /programs/resolve/{slug}`
 

{programasweights-0.2.7 → programasweights-0.3.0}/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.3.0/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.