programasweights 0.2.8__tar.gz → 0.3.0__tar.gz

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

@@ -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()

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: programasweights
-Version: 0.2.8
+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.8 → programasweights-0.3.0}/programasweights/__init__.py

@@ -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.0"
 
 from .config import get_api_url, get_api_key, set_api_key
 
@@ -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,14 @@ 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.
         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 +115,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
@@ -122,15 +131,42 @@ def function(
 
     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 +257,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 +297,7 @@ __all__ = [
     "compile_and_load",
     "function",
     "list_programs",
+    "list_versions",
     "login",
     "get_api_url",
     "get_api_key",

{programasweights-0.2.8 → programasweights-0.3.0}/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.0}/pyproject.toml

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