programasweights 0.2.0__tar.gz → 0.2.2__tar.gz

programasweights-0.2.2/.cursor/rules/sdk-publishing.mdc

@@ -0,0 +1,53 @@
+---
+description: SDK publishing workflow for Python and JavaScript packages
+alwaysApply: true
+---
+
+# SDK Publishing Rules
+
+## Public repos are the source of truth for published packages
+
+- **Python SDK**: https://github.com/programasweights/programasweights-python
+- **JS SDK**: https://github.com/programasweights/programasweights-js
+
+## Release workflow
+
+1. Make changes in the public repo (feature branch -> PR -> main)
+2. Bump version in `pyproject.toml` / `__init__.py` (Python) or `package.json` (JS)
+3. Run tests: `bash tests/test_sdk.sh` (Python) or `npm test && npx playwright test` (JS)
+4. Tag: `git tag -a vX.Y.Z -m "Release vX.Y.Z"`
+5. Build and publish from the tagged commit:
+   - Python: `python -m build && twine upload dist/*`
+   - JS: `npm publish --access public`
+6. Push tag: `git push origin vX.Y.Z`
+7. Verify: compare published package with repo (`pip download` / `npm pack` then diff)
+
+## Never do
+
+- Do NOT publish from the monorepo (`paw_discrete/programasweights/`) -- always use the public repos
+- Do NOT publish without tagging first
+- Do NOT forget to sync the monorepo after publishing (if changes originated there)
+- Do NOT use rsync/scp for code deployment -- always git push + git pull
+- Do NOT deploy to server without committing to git first
+
+## All repos are under github.com/programasweights/
+
+- `website` -- monorepo deployed to server (git push website main)
+- `programasweights-python` -- Python SDK (published to PyPI)
+- `programasweights-js` -- JS SDK (published to npm)
+
+## Wheel index
+
+Pre-built `llama-cpp-python` wheels are hosted at `pypi.programasweights.com`.
+Install command: `pip install programasweights --extra-index-url https://pypi.programasweights.com/simple/`
+If `llama-cpp-python` releases a new version, rebuild wheels on our servers and update the index.
+
+## PyPI credentials
+
+- Token in `~/.bashrc` on server 31.22.104.226 as `PYPI_API_TOKEN`
+- Upload via: `twine upload --username __token__ --password $PYPI_API_TOKEN`
+
+## npm credentials
+
+- Token in `~/.bashrc` on server 31.22.104.226 as `NPM_TOKEN`
+- Granular access token with publish permissions for `@programasweights` scope

{programasweights-0.2.0 → programasweights-0.2.2}/.cursor/rules/vllm-deployment.mdc

@@ -13,14 +13,26 @@ All server code lives at `/root/paw-website/` (git clone of `programasweights/we
 
 **Deployment (the ONLY way to update code):**
 ```bash
-# Local: push changes
-git push origin main
+# Local: commit and push to the website repo
+git push website main
 
-# Server: pull and restart
-cd /root/paw-website && git pull
-cd server && bash scripts/start_all.sh
+# Server: pull, build frontend, restart backend
+cd /root/paw-website && git fetch origin && git reset --hard origin/main
+cd web-app/frontend && npm run build && rsync -a --delete dist/ /data/paw-frontend/
+cd /root/paw-website/server && bash scripts/restart.sh
 ```
 
+**IMPORTANT:** `dist/` is in `.gitignore`. Frontend must be built on the server after pull.
+
+**Repos (all under github.com/programasweights/):**
+- `website` -- monorepo (server, frontend, web-sdk, docs). Deployed to server.
+- `programasweights-python` -- Python SDK source. Published to PyPI.
+- `programasweights-js` -- JS SDK source. Published to npm.
+
+**Local remote setup:**
+- `origin` = `yuntian-group/programasweights` (private monorepo)
+- `website` = `programasweights/website` (public, deployed to server)
+
 **NEVER use rsync or scp for code.** Model weights use scp between servers.
 
 ### GPU Layout

programasweights-0.2.2/AGENTS.md

@@ -0,0 +1,194 @@
+# ProgramAsWeights (PAW)
+
+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 PAW 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
+
+## Install
+
+```bash
+pip install programasweights --extra-index-url https://pypi.programasweights.com/simple/
+```
+
+## Usage
+
+```python
+import programasweights as paw
+
+# Use a pre-compiled function (downloads once, runs locally forever)
+# "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"
+
+# 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"}'
+
+# Or compile and load in one step
+fn = paw.compile_and_load("Classify sentiment as positive or negative")
+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 when you need smaller files or browser deployment.
+
+## 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
+
+## Writing Good Specs
+
+The spec is the most important input. It defines what your function does.
+
+**Structure:** Description + examples. Use `Input: ... Output: ...` format.
+
+```python
+fn = paw.compile_and_load("""
+Classify user intent. Return ONLY one of: search, create, delete, other.
+
+Input: Find the latest report
+Output: search
+
+Input: Make a new folder
+Output: create
+
+Input: Remove old backups
+Output: delete
+
+Input: What time is it
+Output: other
+""")
+```
+
+**Tips:**
+- **5-10 examples** is the sweet spot. More helps for ambiguous tasks.
+- For classifiers, add **negative examples** ("Input: ... Output: NONE") to reduce false positives.
+- Explicitly state output constraints: "Return ONLY one of: X, Y, Z"
+- Spec + examples must fit in ~2048 tokens total (~1500 words).
+- Each function is stateless: one input, one output. No conversation history.
+
+## Browser / JavaScript SDK
+
+Programs compiled with `paw-4b-gpt2` also run entirely in the browser via WebAssembly.
+
+```bash
+npm install @programasweights/web
+```
+
+```javascript
+import paw from '@programasweights/web';
+
+const fn = await paw.function('programasweights/email-triage');
+const result = await fn('Urgent: server is down!');
+// result: "immediate"
+```
+
+## Authentication (optional)
+
+Everything works without authentication. Sign in for higher rate limits and program naming.
+
+```bash
+export PAW_API_KEY=paw_sk_...
+```
+
+Generate API keys at https://programasweights.com/settings.
+
+| | Anonymous | Authenticated |
+|---|---|---|
+| Compile rate limit | 20/hr | 60/hr |
+| Name programs (slugs) | No | Yes |
+
+## 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", "timings": {"total_ms": 2800}}
+```
+
+## Full API Reference
+
+```python
+# Compile a spec into a neural program
+program = paw.compile(
+    spec,                               # natural language specification (str)
+    compiler="paw-4b-qwen3-0.6b",      # compiler model name
+    slug=None,                          # optional: URL-safe handle (requires auth)
+    public=True,                        # list on public hub
+)
+# Returns: Program(id: str, slug: str|None, status: str, timings: dict, error: str|None)
+
+# Load a program for local inference
+fn = paw.function(program)              # accepts Program object, hash ID, or slug
+fn = paw.function("a6b454023d41ac9ca845")  # by hash
+fn = paw.function("da03/my-classifier")    # by slug
+
+# The callable signature:
+result: str = fn(input_text: str, max_tokens=512, temperature=0.0)
+
+# Compile and load in one step
+fn = paw.compile_and_load(spec, compiler="paw-4b-qwen3-0.6b")
+
+# List your programs (requires auth)
+programs = paw.list_programs(sort="recent", per_page=20)
+
+# Save API key
+paw.login()
+```
+
+## Common Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `httpx.HTTPStatusError: 404` on download | Program still uploading to CDN | SDK retries automatically. If persistent, recompile. |
+| `httpx.HTTPStatusError: 422` on compile | Spec too short (<10 chars) or too long | Adjust spec length. |
+| `httpx.HTTPStatusError: 429` | Rate limit exceeded | Wait, or sign in for higher limits. |
+| `FileNotFoundError: No prompt_template.txt` | Program not cached and download failed | Check network; the program may not exist. |
+
+## Performance Notes
+
+- **First call**: ~500ms (loads base model into memory). Subsequent calls: ~50-90ms.
+- **Base model shared**: Multiple functions share one 594 MB model in memory. Each LoRA adapter adds ~22 MB.
+- **Thread-safe**: Same function can be called from multiple threads.
+- **Blocking**: Each `fn()` call blocks until inference completes.
+- **Cache location**: `~/.cache/programasweights/`. Set `PAW_CACHE_DIR` to override.
+- **Offline**: After first download, functions work without internet.
+
+## Browse Programs
+
+https://programasweights.com/hub
+
+## Add PAW to Your Project
+
+Copy this file into your project as AGENTS.md:
+https://programasweights.com/agents

{programasweights-0.2.0 → programasweights-0.2.2}/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.2.2 (2026-03-19)
+
+- Add `paw.compile_and_load()` convenience method (compile + load in one call)
+- `paw.function()` now accepts a `Program` object directly (not just string ID)
+- Add `paw.list_programs()` for authenticated users to list their programs
+- Suppress `llama.cpp` stderr noise by default; use `verbose=True` to enable
+- Rewritten AGENTS.md with spec-writing tips, full API reference, common errors, and performance notes
+
 ## 0.2.0 (2026-04-01)
 
 First public release.

{programasweights-0.2.0 → programasweights-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: programasweights
-Version: 0.2.0
+Version: 0.2.2
 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
@@ -58,6 +58,10 @@ program = paw.compile(
 )
 fn = paw.function(program.slug)    # or paw.function(program.id)
 fn("{name: 'Alice',}")  # '{"name": "Alice"}'
+
+# Or compile and load in one step
+fn = paw.compile_and_load("Classify sentiment as positive or negative")
+fn("I love this!")  # "positive"
 ```
 
 ## Two Compilers

{programasweights-0.2.0 → programasweights-0.2.2}/PYPI_README.md

@@ -28,6 +28,10 @@ program = paw.compile(
 )
 fn = paw.function(program.slug)    # or paw.function(program.id)
 fn("{name: 'Alice',}")  # '{"name": "Alice"}'
+
+# Or compile and load in one step
+fn = paw.compile_and_load("Classify sentiment as positive or negative")
+fn("I love this!")  # "positive"
 ```
 
 ## Two Compilers

programasweights-0.2.2/docs/api-reference/cli.md

@@ -0,0 +1,90 @@
+# CLI Reference
+
+The `paw` command-line interface mirrors the Python SDK. Install from PyPI; the entry point is `paw`.
+
+```bash
+pip install programasweights --extra-index-url https://pypi.programasweights.com/simple/
+```
+
+## Global options
+
+| Option | Description |
+|--------|-------------|
+| `--api-url` | Override the API base URL (default: `https://programasweights.com`). |
+| `--api-key` | API key for authenticated requests. Also reads `PAW_API_KEY` env var. |
+| `--json` | Machine-readable JSON output (supported by all subcommands). |
+
+## `paw compile`
+
+Compile a natural-language specification on the server.
+
+```bash
+paw compile --spec "Classify message urgency" [--compiler paw-4b-qwen3-0.6b] [--slug my-classifier] [--json]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--spec` | Specification text to compile (required). |
+| `--compiler` | Compiler model (default: `paw-4b-qwen3-0.6b`). |
+| `--slug` | URL-safe handle (e.g. `my-classifier`). Creates a `username/slug` alias. Requires auth. |
+| `--json` | JSON output with `program_id`, `slug`, `status`, `timings`. |
+
+## `paw run`
+
+Run inference locally against a compiled program.
+
+```bash
+paw run --program <id_or_slug> --input "your text" [--max-tokens 512] [--temperature 0.0] [--json]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--program` | Program hash ID, slug (e.g. `da03/my-classifier`), or official name (e.g. `email-triage`). |
+| `--input` | Input text for the program. |
+| `--max-tokens` | Maximum tokens to generate (default: 512). |
+| `--temperature` | Sampling temperature (default: 0.0). |
+| `--verbose` | Print llama.cpp debug output. |
+| `--json` | JSON output with `program`, `input`, `output`. |
+
+## `paw rename`
+
+Set or change a program's slug handle. Requires authentication.
+
+```bash
+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). |
+
+## `paw info`
+
+Show metadata for a program.
+
+```bash
+paw info <program_id_or_slug> [--json]
+```
+
+## `paw login`
+
+Save an API key for authenticated requests.
+
+```bash
+paw login [key]
+```
+
+If `key` is provided, saves it directly. If omitted, opens the browser to generate one at `programasweights.com/settings`.
+
+## Agent workflow example
+
+```bash
+PROGRAM_ID=$(paw compile --spec "Classify urgency" --json | jq -r '.program_id')
+paw run --program "$PROGRAM_ID" --input "Please review by EOD" --json
+```
+
+## Related
+
+- [Python SDK Reference](python-sdk.md)
+- [REST API Reference](rest-api.md)

programasweights-0.2.2/docs/api-reference/python-sdk.md

@@ -0,0 +1,137 @@
+# Python SDK Reference
+
+The `programasweights` package compiles natural language specs into neural programs that run locally.
+
+## Install
+
+```bash
+pip install programasweights --extra-index-url https://pypi.programasweights.com/simple/
+```
+
+## Import
+
+```python
+import programasweights as paw
+```
+
+## `paw.function`
+
+```python
+fn = paw.function(name_or_id, n_ctx=2048, n_gpu_layers=0, verbose=False)
+```
+
+Loads a compiled program and returns a callable. Downloads the program and base model on first use; cached locally after that. Works offline after first download.
+
+| Parameter | Description |
+|-----------|-------------|
+| `name_or_id` | A `Program` object, hash ID (e.g. `a6b454023d41ac9ca845`), slug (e.g. `da03/my-classifier`), or official shorthand (e.g. `email-triage`). |
+| `n_ctx` | Context length for the local runtime (default `2048`). |
+| `n_gpu_layers` | GPU layers to offload (`0` = CPU-only, `-1` = all). Set `PAW_GPU_LAYERS` env var as default. |
+| `verbose` | Enable verbose logging (default `False`). |
+
+The returned callable:
+
+```python
+output: str = fn(input_text, max_tokens=512, temperature=0.0)
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `input_text` | Input string for the program. |
+| `max_tokens` | Maximum tokens to generate (default `512`). |
+| `temperature` | Sampling temperature (default `0.0`). |
+
+## `paw.compile`
+
+```python
+program = paw.compile(
+    spec,
+    compiler="paw-4b-qwen3-0.6b",
+    name=None,
+    tags=None,
+    public=True,
+    slug=None,
+)
+```
+
+Compiles a natural language spec on the server. Returns a `Program` object.
+
+| Parameter | Description |
+|-----------|-------------|
+| `spec` | Natural language specification (10-8000 chars). |
+| `compiler` | Compiler name: `paw-4b-qwen3-0.6b` (Standard) or `paw-4b-gpt2` (Compact). |
+| `name` | Display title for the hub (auto-generated if omitted). |
+| `tags` | Tags for discovery (list of strings, max 10). |
+| `public` | Whether to list on the public hub (default `True`). |
+| `slug` | URL-safe handle (e.g. `my-classifier`). Creates a `username/slug` alias. Requires authentication. |
+
+**Return value** -- `Program` object:
+
+| Attribute | Description |
+|-----------|-------------|
+| `id` | Hash-based program identifier. Use with `paw.function(program.id)`. |
+| `slug` | Full slug handle (e.g. `da03/my-classifier`) if one was created, `None` otherwise. |
+| `status` | `"ready"` on success, `"failed"` on error. |
+| `compiler_snapshot` | Exact compiler version used. |
+| `timings` | Timing metadata from the server. |
+| `error` | Error message when compilation fails. |
+
+## `paw.compile_and_load`
+
+```python
+fn = paw.compile_and_load(spec, compiler="paw-4b-qwen3-0.6b", **kwargs)
+```
+
+Convenience method that compiles a spec and immediately loads the result for local inference. Equivalent to `paw.function(paw.compile(spec, ...).id)`. Returns a callable.
+
+Accepts all the same parameters as `paw.compile`.
+
+## `paw.list_programs`
+
+```python
+result = paw.list_programs(sort="recent", per_page=20)
+```
+
+Returns a dict with the authenticated user's compiled programs. Requires authentication.
+
+| Parameter | Description |
+|-----------|-------------|
+| `sort` | Sort order: `"recent"` (default), `"votes"`, `"recommended"`. |
+| `per_page` | Number of results per page (default `20`). |
+
+**Return value** -- dict:
+
+| Key | Description |
+|-----|-------------|
+| `programs` | List of program dicts with `id`, `spec`, `name`, `compiler`, etc. |
+| `total` | Total number of programs. |
+
+## `paw.login`
+
+```python
+paw.login(key=None)
+```
+
+Saves an API key for authenticated requests. If `key` is provided, saves it directly. If omitted, opens the browser to generate a key at `programasweights.com/settings`.
+
+Keys are stored in `~/.config/programasweights/config.json` and loaded automatically on subsequent imports.
+
+You can also set the `PAW_API_KEY` environment variable instead:
+
+```bash
+export PAW_API_KEY=paw_sk_...
+```
+
+## Configuration
+
+| Name | Description |
+|------|-------------|
+| `paw.api_url` | Base URL for API requests. Default: `https://programasweights.com`. Override with `PAW_API_URL` env var. |
+| `paw.api_key` | API key for authenticated calls. Set via `paw.login()` or `PAW_API_KEY` env var. |
+| `paw.__version__` | Installed package version string. |
+
+## Related
+
+- [CLI Reference](cli.md)
+- [REST API Reference](rest-api.md)
+- [Naming Programs](../getting-started/naming-programs.md)

{programasweights-0.2.0 → programasweights-0.2.2}/docs/api-reference/rest-api.md

@@ -69,39 +69,50 @@ List or search programs.
 
 ### `GET /programs/{id_or_slug}`
 
-Program detail including aliases, specification, and pseudo-program where exposed by policy.
+Program detail. Accepts hash ID or slug. Private programs return 404 to non-owners.
 
-### `GET /programs/{id}/download`
+**Response** includes: `id`, `name`, `spec`, `interpreter`, `public`, `aliases`, `user_slug`, `author`, `tags`, `upvotes`, `downloads`, `created_at`.
 
-Redirects to the Hugging Face CDN for the `.paw` artifact download.
+### `PATCH /programs/{id_or_slug}`
+
+Update program metadata. **Authentication required.**
+
+Owner-only fields: `public`, `name`, `tags`. Any authenticated user can set their own `slug`.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `public` | boolean | Visibility (owner only). |
+| `name` | string | Display title, max 100 chars (owner only). |
+| `tags` | string[] | Tags, max 5 items (owner only). |
+| `slug` | string | URL-safe handle, 2-50 chars, `^[a-z0-9][a-z0-9-]*[a-z0-9]$`. Creates/replaces your alias for this program. |
+
+### `GET /programs/{id_or_slug}/download`
+
+Redirects to the Hugging Face CDN for the `.paw` artifact. Private programs return 404 to non-owners.
 
 ### `GET /programs/resolve/{slug}`
 
-Resolve a slug or alias to a canonical `program_id`.
+Resolve a slug (e.g. `da03/my-classifier` or bare `email-triage`) to a canonical `program_id`.
 
 ### `POST /programs/{id}/alias`
 
-Create an alias for the program. **Authentication required.**
-
-**Request body (JSON):**
+Create or update your alias for a program. **Authentication required.** If you already have an alias for this program, it is replaced (atomic update).
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `slug` | string | Alias slug to register. |
+| `slug` | string | Slug name, 2-50 chars, lowercase alphanumeric and hyphens. |
 
-### `POST /programs/{id}/vote`
+### `POST /programs/{id_or_slug}/vote`
 
-Submit a vote for a program. **Authentication required.**
-
-**Request body (JSON):**
+Submit a vote. **Authentication required.**
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `vote` | integer | `1` (up) or `-1` (down). |
+| `vote` | integer | `1` (upvote) or `-1` (downvote). Same value again removes the vote. |
 
 ### `GET /programs/{id}/cases` and `POST /programs/{id}/cases`
 
-Community feedback and case submission for a program. Method-specific payloads follow the server schema for each verb.
+Community case submission for a program.
 
 ### `GET /auth/github`