programasweights 0.2.8__tar.gz → 0.3.1__tar.gz

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

@@ -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")  # "can wait"
+fn("Newsletter: spring picnic")  # "wait"
 
 # Compile your own from a description
 program = paw.compile(
@@ -28,7 +28,7 @@ program = paw.compile(
     compiler="paw-4b-qwen3-0.6b"  # or "paw-4b-gpt2" for smaller/faster
 )
 fn = paw.function(program.id)
-fn("{name: 'Alice',}")  # '{"name": "Alice"}'
+fn("{name: 'Alice',}")  # '{"name":"Alice"}'
 
 # Or compile and load in one step
 fn = paw.compile_and_load("Classify sentiment as positive or negative")
@@ -161,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
@@ -170,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()
@@ -192,10 +211,12 @@ paw.login()
 | `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. |
+| GPU/Metal errors on load | GPU backend not available or incompatible | Set `PAW_GPU_LAYERS=0` or pass `n_gpu_layers=0` to force CPU. |
 
 ## Performance
 
-- **First call** ~5-15s (loads base model). Subsequent calls 0.5-5s depending on input length.
+- **GPU acceleration** enabled by default (`n_gpu_layers=-1`). Uses Metal on Mac, CUDA on Linux, falls back to CPU automatically. If GPU causes issues, set `PAW_GPU_LAYERS=0` or pass `n_gpu_layers=0`.
+- **First call** ~1-5s (loads base model). Subsequent calls ~0.05-0.5s depending on input length and GPU availability.
 - **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.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: programasweights
-Version: 0.2.8
+Version: 0.3.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
@@ -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")          # "can wait"
+fn("Newsletter: spring picnic")          # "wait"
 
 # Compile your own from a description
 program = paw.compile(
@@ -57,7 +57,7 @@ program = paw.compile(
     slug="json-fixer"              # optional: creates username/json-fixer handle
 )
 fn = paw.function(program.slug)    # or paw.function(program.id)
-fn("{name: 'Alice',}")  # '{"name": "Alice"}'
+fn("{name: 'Alice',}")  # '{"name":"Alice"}'
 
 # Or compile and load in one step
 fn = paw.compile_and_load("Classify sentiment as positive or negative")
@@ -66,17 +66,20 @@ 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                    |
+
+|                 | 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                |
+| Local inference | ~0.05-0.5s per call   | ~0.03-0.3s per call  |
+| Runs in browser | No                    | Yes (WebAssembly)    |
 
 Default is Standard (Qwen3 0.6B). Use Compact (GPT-2) when you need smaller files or browser deployment.
 
+GPU acceleration is enabled by default (Metal on Mac, CUDA on Linux, falls back to CPU). Set `PAW_GPU_LAYERS=0` to force CPU if GPU causes issues.
+
 ## 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.
@@ -99,9 +102,9 @@ See the [browser SDK repo](https://github.com/programasweights/programasweights-
 
 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.
+> I want to use ProgramAsWeights (PAW) to create fuzzy text functions that run locally. Read the instructions at [https://programasweights.com/AGENTS.md](https://programasweights.com/AGENTS.md) and help me integrate it.
 
-Or save [`AGENTS.md`](https://programasweights.com/agents) to your project root — agents read it automatically.
+Or save `[AGENTS.md](https://programasweights.com/agents)` to your project root — agents read it automatically.
 
 ## When to Use PAW
 
@@ -145,4 +148,4 @@ paw login
 
 ## License
 
-MIT
+MIT

{programasweights-0.2.8 → programasweights-0.3.1}/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")          # "can wait"
+fn("Newsletter: spring picnic")          # "wait"
 
 # Compile your own from a description
 program = paw.compile(
@@ -27,7 +27,7 @@ program = paw.compile(
     slug="json-fixer"              # optional: creates username/json-fixer handle
 )
 fn = paw.function(program.slug)    # or paw.function(program.id)
-fn("{name: 'Alice',}")  # '{"name": "Alice"}'
+fn("{name: 'Alice',}")  # '{"name":"Alice"}'
 
 # Or compile and load in one step
 fn = paw.compile_and_load("Classify sentiment as positive or negative")
@@ -36,17 +36,20 @@ 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                    |
+
+|                 | 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                |
+| Local inference | ~0.05-0.5s per call   | ~0.03-0.3s per call  |
+| Runs in browser | No                    | Yes (WebAssembly)    |
 
 Default is Standard (Qwen3 0.6B). Use Compact (GPT-2) when you need smaller files or browser deployment.
 
+GPU acceleration is enabled by default (Metal on Mac, CUDA on Linux, falls back to CPU). Set `PAW_GPU_LAYERS=0` to force CPU if GPU causes issues.
+
 ## 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.
@@ -69,9 +72,9 @@ See the [browser SDK repo](https://github.com/programasweights/programasweights-
 
 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.
+> I want to use ProgramAsWeights (PAW) to create fuzzy text functions that run locally. Read the instructions at [https://programasweights.com/AGENTS.md](https://programasweights.com/AGENTS.md) and help me integrate it.
 
-Or save [`AGENTS.md`](https://programasweights.com/agents) to your project root — agents read it automatically.
+Or save `[AGENTS.md](https://programasweights.com/agents)` to your project root — agents read it automatically.
 
 ## When to Use PAW
 
@@ -115,4 +118,4 @@ paw login
 
 ## License
 
-MIT
+MIT

{programasweights-0.2.8 → programasweights-0.3.1}/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)  # "can wait"
+print(result)  # "wait"
 ```
 
 ## Compile Your Own
@@ -35,7 +35,7 @@ program = paw.compile(
 
 # Use the compiled program
 fn = paw.function(program.id)
-fn("{name: 'Alice', age: 30,}")  # '{"name": "Alice", "age": 30}'
+fn("{name: 'Alice', age: 30,}")  # '{"name":"Alice","age":30}'
 ```
 
 ## What Can You Build?

{programasweights-0.2.8 → programasweights-0.3.1}/programasweights/__init__.py

@@ -12,7 +12,7 @@ Quick start:
     # Compile your own from a description
     program = paw.compile("Fix malformed JSON: repair missing quotes and trailing commas")
     fn = paw.function(program.id)
-    fn("{name: 'Alice',}")  # '{"name": "Alice"}'
+    fn("{name: 'Alice',}")  # '{"name":"Alice"}'
 
 API reference:
     paw.compile(spec)          Compile a spec on the server, returns Program
@@ -27,7 +27,7 @@ try:
     from importlib.metadata import version as _meta_version
     __version__ = _meta_version("programasweights")
 except Exception:
-    __version__ = "0.2.8"
+    __version__ = "0.3.1"
 
 from .config import get_api_url, get_api_key, set_api_key
 
@@ -65,7 +65,7 @@ def compile(
         ... )
         >>> fn = paw.function(program.slug)  # or paw.function(program.id)
         >>> fn("{name: 'Alice',}")
-        '{"name": "Alice"}'
+        '{"name":"Alice"}'
     """
     from .client import PAWClient
     from ._output import status
@@ -74,7 +74,13 @@ def compile(
     result = client.compile(spec, compiler=compiler, name=name, tags=tags, public=public, slug=slug)
     label = f"{result.id}"
     if result.slug:
-        label += f" ({result.slug})"
+        ver_str = f" v{result.version}" if result.version and result.version > 1 else ""
+        action_str = ""
+        if result.version_action == "no_change":
+            action_str = " (no changes)"
+        elif result.version_action == "promoted":
+            action_str = " set as main"
+        label = f"{result.slug}{ver_str}{action_str}"
     status(f"Compiled: {label}")
     return result
 
@@ -84,6 +90,7 @@ def function(
     n_ctx: int = 2048,
     n_gpu_layers: int | None = None,
     verbose: bool = False,
+    offline: bool = False,
 ):
     """Load a compiled program for local inference via llama.cpp.
 
@@ -91,11 +98,15 @@ def function(
     Subsequent calls use the local cache.
 
     Args:
-        program_id: Program ID (str), slug, or a ``Program`` object from compile().
+        program_id: Program ID (str), slug (``da03/my-program``), pinned version
+            (``da03/my-program@v3``), or a ``Program`` object from compile().
         n_ctx: Context window size for llama.cpp.
-        n_gpu_layers: GPU layers (-1 = all, 0 = CPU only). Defaults to CPU.
-            Set ``PAW_GPU_LAYERS`` env var or pass explicitly for GPU acceleration.
+        n_gpu_layers: GPU layers (-1 = all GPU, 0 = CPU only). Defaults to -1
+            (auto-uses Metal/CUDA if available, safe fallback to CPU).
+            Set ``PAW_GPU_LAYERS=0`` env var to force CPU-only.
         verbose: Print llama.cpp debug output.
+        offline: Skip server check for slug resolution and use local cache only.
+            Also set via ``PAW_OFFLINE=1`` env var.
 
     Returns:
         A callable ``PawFunction`` that takes an input string and returns output.
@@ -105,8 +116,7 @@ def function(
         >>> fn("Urgent: the server is down!")
         'immediate'
 
-        >>> program = paw.compile("Classify sentiment")
-        >>> fn = paw.function(program)  # accepts Program object directly
+        >>> fn = paw.function("da03/my-program@v2")  # pinned version
     """
     if hasattr(program_id, 'id'):
         program_id = program_id.slug or program_id.id
@@ -116,21 +126,48 @@ def function(
     from .runtime_llamacpp import PawFunction
 
     if n_gpu_layers is None:
-        n_gpu_layers = int(os.environ.get("PAW_GPU_LAYERS", "0"))
+        n_gpu_layers = int(os.environ.get("PAW_GPU_LAYERS", "-1"))
 
     from ._output import status
 
     resolved_id = program_id
     if not re.fullmatch(r"[a-f0-9]{16,64}", program_id):
-        cached = get_cached_slug(program_id)
-        if cached:
-            resolved_id = cached
+        is_pinned = bool(re.search(r"@v\d+$", program_id))
+        use_offline = offline or os.environ.get("PAW_OFFLINE", "").strip() in ("1", "true", "yes")
+
+        if is_pinned:
+            cached = get_cached_slug(program_id)
+            if cached:
+                resolved_id = cached
+            else:
+                status(f"Resolving {program_id}...")
+                from .client import PAWClient
+                client = PAWClient(api_url=get_api_url(), api_key=get_api_key())
+                resolved_id = client.resolve_slug(program_id)
+                save_slug_mapping(program_id, resolved_id)
+        elif use_offline:
+            cached = get_cached_slug(program_id)
+            if cached:
+                resolved_id = cached
+            else:
+                raise RuntimeError(
+                    f"No cached version of '{program_id}'. Cannot resolve offline. "
+                    "Run once with internet to populate the cache."
+                )
         else:
-            status(f"Resolving {program_id}...")
             from .client import PAWClient
             client = PAWClient(api_url=get_api_url(), api_key=get_api_key())
-            resolved_id = client.resolve_slug(program_id)
-            save_slug_mapping(program_id, resolved_id)
+            try:
+                status(f"Resolving {program_id}...")
+                resolved_id = client.resolve_slug(program_id)
+                save_slug_mapping(program_id, resolved_id)
+            except Exception:
+                cached = get_cached_slug(program_id)
+                if cached:
+                    status(f"Warning: could not reach server, using cached version of {program_id}")
+                    resolved_id = cached
+                else:
+                    raise
 
     if not is_program_cached(resolved_id):
         from .client import PAWClient
@@ -221,6 +258,25 @@ def compile_and_load(
     return function(program, n_ctx=n_ctx, n_gpu_layers=n_gpu_layers, verbose=verbose)
 
 
+def list_versions(slug: str) -> dict:
+    """List all versions of a named program (slug).
+
+    Args:
+        slug: Slug in ``username/slug-name`` or bare ``slug-name`` format.
+
+    Returns:
+        Dict with ``slug``, ``main_version``, and ``versions`` list.
+
+    Example:
+        >>> versions = paw.list_versions("da03/bibtex-normalizer")
+        >>> for v in versions["versions"]:
+        ...     print(f"v{v['version']}: {v['program_id'][:12]} {'(main)' if v['is_main'] else ''}")
+    """
+    from .client import PAWClient
+    client = PAWClient(api_url=get_api_url(), api_key=get_api_key())
+    return client.list_slug_versions(slug)
+
+
 def list_programs(sort: str = "recent", per_page: int = 20, page: int = 1) -> dict:
     """List your compiled programs. Requires authentication (PAW_API_KEY).
 
@@ -242,6 +298,7 @@ __all__ = [
     "compile_and_load",
     "function",
     "list_programs",
+    "list_versions",
     "login",
     "get_api_url",
     "get_api_key",

{programasweights-0.2.8 → programasweights-0.3.1}/programasweights/client.py

@@ -27,6 +27,8 @@ class Program:
     compiler_snapshot: Optional[str] = None
     timings: Optional[dict] = None
     error: Optional[str] = None
+    version: Optional[int] = None
+    version_action: Optional[str] = None
 
 
 class PAWClient:
@@ -92,6 +94,8 @@ class PAWClient:
             compiler_snapshot=data.get("compiler_snapshot"),
             timings=data.get("timings"),
             error=data.get("error"),
+            version=data.get("version"),
+            version_action=data.get("version_action"),
         )
 
     def resolve_slug(self, slug: str) -> str:
@@ -182,6 +186,16 @@ class PAWClient:
         resp.raise_for_status()
         return resp.json()
 
+    def list_slug_versions(self, slug: str) -> dict:
+        """List all versions of a slug. Slug format: 'username/slug-name' or bare 'slug-name'."""
+        resp = httpx.get(
+            f"{self._api_url}/api/v1/programs/{slug}/versions",
+            headers=self._headers(),
+            timeout=10.0,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
     def list_programs(self, sort: str = "recent", per_page: int = 20, page: int = 1) -> dict:
         """List programs for the authenticated user."""
         resp = httpx.get(

{programasweights-0.2.8 → programasweights-0.3.1}/pyproject.toml

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