programasweights 0.2.0__tar.gz → 0.2.1__tar.gz

{programasweights-0.2.0 → programasweights-0.2.1}/AGENTS.md

@@ -24,10 +24,9 @@ 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
-    slug="json-fixer"              # optional: creates da03/json-fixer handle
+    compiler="paw-4b-qwen3-0.6b"  # or "paw-4b-gpt2" for smaller/faster
 )
-fn = paw.function(program.slug)    # or paw.function(program.id)
+fn = paw.function(program.id)
 fn("{name: 'Alice',}")  # '{"name": "Alice"}'
 ```
 
@@ -72,38 +71,41 @@ Use this when you want to offload all computation to the user's browser: zero se
 - **Intent routing** — map user descriptions to the closest URL, menu item, or setting
 - **Agent preprocessing** — parse tool calls, validate outputs, route tasks
 
-## Authentication
+## Authentication (optional)
+
+Everything works without authentication. Sign in for higher rate limits and program naming.
 
 ```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 https://programasweights.com/settings
+Generate API keys at https://programasweights.com/settings. The SDK reads `PAW_API_KEY` from the environment automatically.
 
-The SDK automatically reads `PAW_API_KEY` from the environment. Authenticated users get higher rate limits (60 compiles/hr vs 5 for anonymous).
+| | Anonymous | Authenticated |
+|---|---|---|
+| Compile rate limit | 20/hr | 60/hr |
+| Name programs (slugs) | No | Yes |
 
 ## Program Naming
 
-Programs have an immutable hash ID (e.g. `a6b454023d41ac9ca845`). Authenticated
-users can optionally assign a slug at compile time to create a human-readable
-handle like `da03/json-fixer`. Both forms work everywhere:
+Every compiled program gets an immutable hash ID (e.g. `a6b454023d41ac9ca845`). Authenticated users can also assign a human-readable slug:
 
 ```python
-fn = paw.function("da03/json-fixer")     # by slug
-fn = paw.function("a6b454023d41ac9ca845") # by hash
+program = paw.compile("Classify sentiment", slug="my-classifier")
+# program.id   -> "a6b454023d41ac9ca845"
+# program.slug -> "da03/my-classifier"
+
+fn = paw.function("da03/my-classifier")  # by slug (requires auth to create)
+fn = paw.function("a6b454023d41ac9ca845") # by hash (always works)
 ```
 
 ## CLI
 
 ```bash
-paw compile --spec "Classify sentiment" --slug "my-classifier" --json
-paw run --program "da03/my-classifier" --input "I love this!" --json
-paw rename <program> <new-slug>   # rename a program's slug
-paw info <program>                # show program metadata
+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
 ```
 
@@ -112,9 +114,9 @@ paw login                         # save API key
 ## API
 
 ```python
-paw.compile(spec, slug="my-fn")   # Compile with optional slug
-paw.function(name_or_id)          # Load by slug or hash
-paw.login()                       # Save API key
+paw.compile(spec)                 # compile (returns Program with .id)
+paw.function(program_id_or_slug)  # load for local inference
+paw.login()                       # save API key
 ```
 
 ## Browse Programs

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: programasweights
-Version: 0.2.0
+Version: 0.2.1
 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.1/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.1/docs/api-reference/python-sdk.md

@@ -0,0 +1,107 @@
+# 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` | Program 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.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.1}/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`
 

{programasweights-0.2.0 → programasweights-0.2.1}/programasweights/__init__.py

@@ -22,7 +22,7 @@ API reference:
     paw.api_key                API key (set via login() or PAW_API_KEY env var)
 """
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 
 from .config import get_api_url, get_api_key, set_api_key
 

{programasweights-0.2.0 → programasweights-0.2.1}/programasweights/cli.py

@@ -27,7 +27,8 @@ def cmd_compile(args):
     if not args.json:
         print(f"Compiling: {args.spec[:80]}...")
 
-    program = paw.compile(args.spec, compiler=args.compiler, slug=getattr(args, 'slug', None))
+    public = not getattr(args, 'private', False)
+    program = paw.compile(args.spec, compiler=args.compiler, slug=getattr(args, 'slug', None), public=public)
 
     if args.json:
         print(json.dumps({
@@ -170,6 +171,7 @@ def main():
     p.add_argument("--spec", required=True, help="Natural language specification")
     p.add_argument("--compiler", default="paw-4b-qwen3-0.6b", help="Compiler model")
     p.add_argument("--slug", default=None, help="URL-safe handle (e.g. 'message-classifier')")
+    p.add_argument("--private", action="store_true", help="Make program private (not listed on hub)")
     p.add_argument("--json", action="store_true", help="JSON output")
 
     p = sub.add_parser("run", help="Run a program locally via llama.cpp")

{programasweights-0.2.0 → programasweights-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "programasweights"
-version = "0.2.0"
+version = "0.2.1"
 description = "Compile natural language specifications into neural programs that run locally via llama.cpp."
 readme = "PYPI_README.md"
 requires-python = ">=3.9"

{programasweights-0.2.0 → programasweights-0.2.1}/server/api/routes/compile.py

@@ -162,16 +162,23 @@ async def submit_compile(
                     "message": "Authentication required to set a program slug.",
                     "request_id": request_id,
                 })
-            existing_alias = await db.execute(
+            existing_name = await db.execute(
                 select(Alias).where(Alias.owner_id == user.id, Alias.slug_name == req.slug)
             )
-            if existing_alias.scalar_one_or_none():
+            if existing_name.scalar_one_or_none():
                 raise HTTPException(status_code=409, detail={
                     "error": "slug_taken",
                     "message": f"You already have a program named '{req.slug}'. Choose a different name.",
                     "request_id": request_id,
                 })
-            db.add(Alias(slug_name=req.slug, program_id=pid, owner_id=user.id))
+            existing_program_alias = await db.execute(
+                select(Alias).where(Alias.owner_id == user.id, Alias.program_id == pid)
+            )
+            old = existing_program_alias.scalar_one_or_none()
+            if old:
+                old.slug_name = req.slug
+            else:
+                db.add(Alias(slug_name=req.slug, program_id=pid, owner_id=user.id))
             await db.commit()
             username = user.username or f"user-{user.id}"
             created_slug = f"{username}/{req.slug}"

{programasweights-0.2.0 → programasweights-0.2.1}/server/api/routes/programs.py

@@ -490,12 +490,14 @@ async def update_program(
                     "error": "slug_taken",
                     "message": f"You already have a program named '{raw_slug}'.",
                 })
-            old_aliases = await db.execute(
+            old_alias_r = await db.execute(
                 select(Alias).where(Alias.program_id == program.id, Alias.owner_id == user.id)
             )
-            for old in old_aliases.scalars().all():
-                await db.delete(old)
-            db.add(Alias(slug_name=raw_slug, program_id=program.id, owner_id=user.id))
+            old_alias = old_alias_r.scalar_one_or_none()
+            if old_alias:
+                old_alias.slug_name = raw_slug
+            else:
+                db.add(Alias(slug_name=raw_slug, program_id=program.id, owner_id=user.id))
             username = user.username or f"user-{user.id}"
             created_slug = f"{username}/{raw_slug}"
         else:
@@ -695,9 +697,9 @@ async def create_alias(
     )
     old_alias = existing_program.scalar_one_or_none()
     if old_alias:
-        await db.delete(old_alias)
-
-    db.add(Alias(slug_name=raw_slug, program_id=program.id, owner_id=user.id))
+        old_alias.slug_name = raw_slug
+    else:
+        db.add(Alias(slug_name=raw_slug, program_id=program.id, owner_id=user.id))
     await db.commit()
     username = user.username or f"user-{user.id}"
     return {"slug": f"{username}/{raw_slug}", "program_id": program.id}

{programasweights-0.2.0 → programasweights-0.2.1}/tests/test_sdk.py

@@ -328,3 +328,117 @@ class TestAuth:
         assert result.returncode == 0
         data = json.loads(result.stdout)
         assert data.get("program_id")
+
+
+# ── Phase 9: Slug validation ──
+
+
+class TestSlugValidation:
+    @needs_auth
+    def test_slug_too_short(self):
+        old_key = paw.api_key
+        try:
+            paw.api_key = API_KEY
+            with pytest.raises(Exception) as exc_info:
+                paw.compile("Classify text.", slug="x")
+            assert "422" in str(exc_info.value) or "invalid" in str(exc_info.value).lower()
+        finally:
+            paw.api_key = old_key
+
+    @needs_auth
+    def test_slug_invalid_characters(self):
+        old_key = paw.api_key
+        try:
+            paw.api_key = API_KEY
+            with pytest.raises(Exception):
+                paw.compile("Classify text.", slug="BAD SLUG!")
+        finally:
+            paw.api_key = old_key
+
+    @needs_auth
+    def test_slug_with_uppercase_rejected(self):
+        old_key = paw.api_key
+        try:
+            paw.api_key = API_KEY
+            with pytest.raises(Exception):
+                paw.compile("Classify text.", slug="MyProgram")
+        finally:
+            paw.api_key = old_key
+
+
+# ── Phase 10: Privacy ──
+
+
+class TestPrivacy:
+    @needs_auth
+    def test_compile_private_program(self):
+        import httpx
+        old_key = paw.api_key
+        try:
+            paw.api_key = API_KEY
+            program = paw.compile("Private test program for counting vowels.", public=False)
+            assert program.id
+
+            resp = httpx.get(
+                f"{paw.api_url}/api/v1/programs/{program.id}",
+                timeout=10.0,
+            )
+            assert resp.status_code == 404, "Private program should return 404 to unauthenticated users"
+        finally:
+            paw.api_key = old_key
+
+    @needs_auth
+    def test_compile_public_default(self):
+        import httpx
+        old_key = paw.api_key
+        try:
+            paw.api_key = API_KEY
+            program = paw.compile("Public test program for counting words.")
+            assert program.id
+
+            resp = httpx.get(
+                f"{paw.api_url}/api/v1/programs/{program.id}",
+                timeout=10.0,
+            )
+            assert resp.status_code == 200, "Public program should be accessible"
+        finally:
+            paw.api_key = old_key
+
+
+# ── Phase 11: CLI rename ──
+
+
+class TestCLIRename:
+    @needs_auth
+    def test_cli_rename(self):
+        import time
+        old_key = paw.api_key
+        try:
+            paw.api_key = API_KEY
+            program = paw.compile("Test rename program for validation.")
+            slug = f"rename-test-{int(time.time()) % 100000}"
+
+            result = subprocess.run(
+                [sys.executable, "-m", "programasweights.cli",
+                 "--api-key", API_KEY,
+                 "rename", program.id, slug, "--json"],
+                capture_output=True, text=True,
+            )
+            assert result.returncode == 0
+            data = json.loads(result.stdout)
+            assert data.get("slug")
+            assert slug in data["slug"]
+        finally:
+            paw.api_key = old_key
+
+    @needs_auth
+    def test_cli_compile_private(self):
+        result = subprocess.run(
+            [sys.executable, "-m", "programasweights.cli",
+             "--api-key", API_KEY,
+             "compile", "--spec", "Private CLI test.", "--private", "--json"],
+            capture_output=True, text=True,
+        )
+        assert result.returncode == 0
+        data = json.loads(result.stdout)
+        assert data.get("program_id")

{programasweights-0.2.0 → programasweights-0.2.1}/tests/test_sdk.sh

@@ -39,7 +39,7 @@ PY="$VENV_DIR/bin/python"
 # Step 2: Install from PyPI (timed)
 echo ">>> Installing programasweights from PyPI..."
 START=$(date +%s)
-$PIP install programasweights --extra-index-url "$EXTRA_INDEX" -q 2>&1
+$PIP install --no-cache-dir programasweights --extra-index-url "$EXTRA_INDEX" -q 2>&1
 END=$(date +%s)
 INSTALL_TIME=$((END - START))
 echo "    Install time: ${INSTALL_TIME}s"

{programasweights-0.2.0 → programasweights-0.2.1}/web-app/frontend/src/components/AboutPage.tsx

@@ -140,7 +140,7 @@ const AboutPage: React.FC = () => {
             },
             {
               q: 'Python or JavaScript?',
-              a: 'Use the Python SDK (pip install programasweights) for backend servers and scripts. Use the browser SDK (npm install @programasweights/web) for client-side web apps where data stays on the user\'s device.',
+              a: 'Use the Python SDK (pip install programasweights --extra-index-url https://pypi.programasweights.com/simple/) for backend servers and scripts. Use the browser SDK (npm install @programasweights/web) for client-side web apps where data stays on the user\'s device.',
             },
           ].map((faq) => (
             <div key={faq.q}>