ProgramAsWeights

Compile natural language specs into tiny neural functions that run locally.

Define what a function should do in plain English. PAW compiles it into a small neural program that runs on your machine — no API keys at runtime, no internet needed after setup, fully deterministic.

Install

pip install programasweights --extra-index-url https://pypi.programasweights.com/simple/

Quick Start

import programasweights as paw

# Compile and load your own function
fn = paw.compile_and_load(
    "Classify if a message needs immediate attention or can wait. "
    "Return only 'immediate' or 'wait'."
)
fn("Urgent: the server is down!")        # "immediate"
fn("Newsletter: spring picnic")          # "wait"

# Compile once and save the program ID
program = paw.compile(
    "Fix malformed JSON: repair missing quotes and trailing commas"
)
print(program.id)  # Save this ID for future runs
fn = paw.function(program.id)
fn("{name: 'Alice',}")  # '{"name":"Alice"}'

If you specifically want the smaller browser-compatible runtime, pass compiler="paw-4b-gpt2". Otherwise, omit compiler and let the server default decide.

Remote inference (optional)

Use the hosted API for fast inference in around 150 ms, without a local model download.

import programasweights as paw

with paw.compile_and_load(
    "Classify if a message needs immediate attention or can wait. "
    "Return only 'immediate' or 'wait'.",
    remote=True,
) as remote_fn:
    print(remote_fn("Urgent: the server is down!"))

For direct HTTP calls, see the REST API reference.

Current Public Compilers

The current server default is Standard (paw-4b-qwen3-0.6b). Use Compact (paw-4b-gpt2) when you need smaller files or browser deployment.

If you need to inspect available compiler aliases programmatically, use paw.list_compilers().

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.

Constrained Decoding

In SDK 0.4.6+, a call accepts an optional logits_processor: an advanced hook for caller-supplied llama.cpp-compatible token constraints, not built-in regex or JSON-schema validation. It runs at every generation step. The default, None, keeps sampling unchanged.

import llama_cpp
# my_processor is your compatible callable: (input_ids, scores) -> scores.
fn("Office line: +1-555-666-7777", logits_processor=llama_cpp.LogitsProcessorList([my_processor]))

Processors see the full prompt and generated-token history, not just the output. Create or reset stateful processors for each call. Token limits and output whitespace trimming still apply, so validate the returned result.

Desktop and Offline Workflows

Prepare and inspect validated local assets without keeping a model loaded:

prepared = paw.prepare_program("da03/my-classifier")
assert prepared["offline_ready"]

fn = paw.function("da03/my-classifier", offline=True)
cached = paw.list_cached_programs()

offline=True (or PAW_OFFLINE=1) makes zero network calls and fails clearly if a required validated program, runtime, adapter, or base model is missing. Long-running finetune compiles can be queued with paw.compile_async(spec, compiler="paw-ft-bs48"); an explicit finetune compiler is required.

Load a saved current GGUF ZIP .paw bundle directly (SDK 0.4.5+):

from pathlib import Path
fn = paw.function(Path("classifier.paw"))

Local files are validated into a separate SHA-256 cache without changing the source or falling back to Hub lookup. Runtime metadata or the shared base model may still download; offline=True prohibits those requests. Legacy tensor-format .paw files are unsupported. Local-file inputs are supported by function, not prepare_program or is_offline_ready.

To run a base model without a compiled program, use paw.function(None, interpreter="gpt2"). See the Python API reference for supported models and options.

Local image functions

Install the optional image dependencies:

pip install "programasweights[vision]" --extra-index-url https://pypi.programasweights.com/simple/

Use prompt_template= (SDK 0.4.13+) to specify the complete prompt for text-only or image-capable base models. For Qwen3.5-0.8B with no adapter:

import programasweights as paw

prompt = (
    "<|im_start|>user\n{INPUT_0}\n{INPUT_1}<|im_end|>\n"
    "<|im_start|>assistant\n<think>\n\n</think>\n\n"
)
describe = paw.function(
    None, interpreter="Qwen/Qwen3.5-0.8B", prompt_template=prompt,
)
print(describe("Describe this image.", paw.Image("photo.png")))

{INPUT_0}, {INPUT_1}, etc. insert positional arguments into the prompt. Placeholders can repeat or appear in any order. The template supplies the model's role markers and assistant prefix. For text-only models such as Qwen/Qwen3-0.6B, pass string inputs.

Load a compiled image program with paw.function("./locator.paw"), then pass the arguments required by its prompt template.

See the image API reference for multiple images, input formats, and result metadata.

Browser SDK

Programs compiled with GPT-2 also run in the browser via WebAssembly. The initial model and program assets download automatically; inference then runs client-side.

npm install @programasweights/web

import paw from '@programasweights/web';

const fn = await paw.function('email-triage-browser');
const result = await fn('Urgent: the server is down!');
// result: "immediate"

If you load by program ID, browser inference only depends on Hugging Face-hosted assets. Slugs still need one PAW API lookup.

New browser-compatible programs are uploaded to Hugging Face asynchronously after compile. They are usually ready within a minute or two, but under load can take a few minutes, so a freshly compiled browser program may need a short wait before the JS SDK can load it.

See the browser SDK repo for full documentation.

Use with AI Agents

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.md and help me integrate it.

Or save [AGENTS.md](https://programasweights.com/agents) to your project root — agents read it automatically.

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

Authentication

# 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 programasweights.com/settings. Authenticated users get higher rate limits.

CLI

paw compile --spec "Extract error lines from logs" --json
paw run --program <program_id> --input "[ERROR] timeout" --json
paw run --program <program_id> --input "[ERROR] timeout" --offline --json
paw run --program <program_id> --input "[ERROR] timeout" --remote --json
paw login

--json gives structured output for programmatic use.

Links

• Website: programasweights.com
• Documentation: programasweights.readthedocs.io
• Python SDK: github.com/programasweights/programasweights-python
• Browser SDK: github.com/programasweights/programasweights-js
• Program Hub: programasweights.com/hub

License

MIT