Programasweights

---
name: programasweights
description: Compile a natural-language spec into a tiny neural function that runs locally with ProgramAsWeights (PAW). Use it for fuzzy text-in / text-out tasks that a regex can't handle but that are too slow, costly, or overkill to send to a full LLM on every item - classify, categorize, label, or tag text (sentiment, urgency, intent, topic, spam, support tickets, ALERT vs QUIET log lines); extract fields from messy text (emails, names, dates, IDs, invoice numbers); repair or normalize formats (broken JSON, dates); fuzzy or typo-tolerant matching, near-duplicate detection, and deduplication; map a misspelled value to the closest option; semantic search; log and error triage; and intent routing. Compile once on the hosted API, then run the function locally and offline via the Python or browser/JavaScript SDK; cheaper and faster than calling a large model per item. Not for long-form generation, open-ended chat, writing code, or multi-step reasoning.
license: MIT
version: 0.1.0
metadata:
  short-description: Compile fuzzy text-in/text-out functions that run locally
---

# ProgramAsWeights (PAW)

ProgramAsWeights compiles a short natural-language spec into a tiny neural function
("neural software") that takes one text input and returns one text output and runs
locally. You compile once on the hosted API; the resulting function then runs locally
and offline forever.

- Website: https://programasweights.com
- Docs: https://programasweights.readthedocs.io

## When to use this

Reach for PAW when a task is fuzzy `text -> text` and you want it cheap, fast, local,
and repeatable:

- **Classification / categorization** - sentiment, urgency, intent, topic, spam, or `ALERT` vs `QUIET` log lines.
- **Extraction** - pull emails, names, dates, IDs, or fields out of messy/unstructured text.
- **Format repair / normalization** - fix broken JSON, normalize dates, clean inconsistent inputs.
- **Fuzzy matching** - typo-tolerant matching, near-duplicate detection, map a phrase to the closest option.
- **Triage / routing** - filter noise from logs, route a request to the right handler.

It replaces a brittle regex or an expensive per-item LLM call with one small function
that, after compiling, runs in roughly 0.05-0.5s locally with no network.

## When NOT to use it

- Long-form or open-ended generation (essays, code, chat) - use a full LLM instead.
- Multi-step reasoning, math, or tasks that need broad world knowledge.
- Anything that is not single text in -> single text out. Functions are stateless and
  share a ~2048-token window across spec + input + output.

## How to use it (the workflow)

**1. Compile your own function.** Describe the behavior you need:

```python
import programasweights as paw

program = paw.compile(
    "Classify if a message needs immediate attention or can wait. "
    "Return only 'immediate' or 'wait'."
)
fn = paw.function(program.id)
fn("Urgent: server is down!")        # "immediate"
fn("Newsletter: spring picnic")      # "wait"
```

**2. Include examples in your spec.** A good spec is a description PLUS a few
`Input: ... Output: ...` examples and an explicit output constraint:

```python
import programasweights as paw

program = paw.compile("""
Classify support tickets. Return ONLY one of: billing, bug, feature, other.

Input: I was charged twice this month
Output: billing

Input: The export button does nothing
Output: bug

Input: Please add a dark mode
Output: feature
""")
fn = paw.function(program.id)

fn("my card got charged again")   # "billing"
```

**3. Iterate with test cases - the #1 practice.** Do not accept the first result.
Build a small set of input/expected pairs, measure accuracy, then refine the wording
and examples and recompile until it is good enough. Treat it like software: test, debug
the specific failures, fix the spec, retest. A minimal eval loop:

```python
import programasweights as paw

tests = [
    {"input": "I was charged twice this month", "expected": "billing"},
    {"input": "The export button does nothing", "expected": "bug"},
    {"input": "Please add a dark mode",          "expected": "feature"},
]

program = paw.compile(open("spec.txt").read())
fn = paw.function(program.id)
results = [(t, fn(t["input"]).strip()) for t in tests]
misses = [(t, got) for t, got in results if got != t["expected"]]
print(f"accuracy: {(len(tests) - len(misses)) / len(tests):.0%}")
for t, got in misses:        # inspect failures, then fix the spec + recompile
    print("FAIL:", t["input"], "-> got", repr(got), "want", repr(t["expected"]))
```

See `references/writing-good-specs.md` for how to debug the misses.

**4. Save the program id or slug and reuse it locally.** Inference needs no server after
the first asset download.

```python
print(program.id)  # Save the tested program's ID
```

On future runs, load that ID:

```python
import programasweights as paw

saved_program_id = "PASTE_YOUR_PROGRAM_ID_HERE"
fn = paw.function(saved_program_id)
```

Compile outside request handlers and reuse the loaded function across calls.

For optional remote inference, use `paw.function(..., remote=True)` or the hosted
HTTP API for fast inference in around 150 ms, without a local model download.
See both examples in `references/api.md`.

## Install

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

Browser / JavaScript: `npm install @programasweights/web`. Functions compiled with
`compiler="paw-4b-gpt2"` run client-side via WebAssembly. See `references/browser-sdk.md`.

## What runs where (data flow - read before using)

- **Compile** sends your spec to the hosted PAW API (`https://programasweights.com`) and
  returns a program id. Do not put secrets in a spec.
- **Inference runs locally** through the SDK and works offline after the first download.
- **Auth is optional** - anonymous use works. Sign in only for higher compile rate limits
  and named slugs (`export PAW_API_KEY=paw_sk_...`).

## More detail (load on demand)

- Full API, compilers, versioning, chaining, auth: `references/api.md`
- Writing and debugging specs: `references/writing-good-specs.md`
- Browser / JavaScript SDK: `references/browser-sdk.md`
- Common errors and fixes: `references/troubleshooting.md`
- Worked case studies (log monitoring, semantic search, tool calling): https://programasweights.readthedocs.io