Metadata-Version: 2.4
Name: vera-s1
Version: 0.1.6
Summary: vera-spark, vera-core, vera-core-2 and vera-large: calibrated System One decision models
License-Expression: Apache-2.0
Project-URL: vera-spark, https://huggingface.co/scar-ai/vera-spark
Project-URL: vera-core, https://huggingface.co/scar-ai/vera-core
Project-URL: vera-core-2, https://huggingface.co/scar-ai/vera-core-2
Project-URL: vera-large, https://huggingface.co/scar-ai/vera-large
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: torch>=2.4
Requires-Dist: transformers>=5.0
Requires-Dist: huggingface_hub>=0.25
Requires-Dist: safetensors>=0.4
Provides-Extra: fast
Requires-Dist: flash-linear-attention; extra == "fast"
Provides-Extra: vllm
Requires-Dist: vllm>=0.29; extra == "vllm"

# vera-s1

Python package and Jev-compatible HTTP server for the **vera** System One decision models:
[vera-spark](https://huggingface.co/scar-ai/vera-spark) (~630M, compact),
[vera-core](https://huggingface.co/scar-ai/vera-core) (~2B),
[vera-core-2](https://huggingface.co/scar-ai/vera-core-2) (~2B) and
[vera-large](https://huggingface.co/scar-ai/vera-large) (~26B, most accurate, GPU only).

Give a vera model a state (text or JSON) and typed questions; it returns typed answers with calibrated probabilities
in one forward pass. It never generates text.

```bash
pip install vera-s1            # add [fast] for flash-linear-attention (faster vera-core on GPU)
```

```python
import vera

agent = vera.load("scar-ai/vera-spark")       # or "scar-ai/vera-core", "scar-ai/vera-core-2", "scar-ai/vera-large"
result = agent.predict(
    "Hi, we were billed twice for March. Please refund the duplicate today or we will cancel our plan.",
    {"department": {"type": "choice", "instructions": "Which department should handle this?",
                    "criteria": {"billing": "invoices, payments, refunds", "technical": "bugs, outages",
                                 "other": "everything else"}},
     "churn_risk": {"type": "noul", "instructions": "Does the user threaten to cancel or leave?"}})
print(result["answers"])
```

Question types: `choice` (2 to 255 options), `score` (2 to 10 ordered levels) and `noul` (yes/no probability).

## HTTP server

```bash
vera-serve --model scar-ai/vera-core --port 8200
curl -s localhost:8200/v1/systemone -H 'Content-Type: application/json' -d '{
  "state": "I was charged twice. Please fix this ASAP.",
  "questions": {"billing": {"type": "noul", "instructions": "Is this ticket about billing?"}}}'
```

Same request and response shape as Jev's `POST /v1/systemone`. Binds `127.0.0.1` by default and has no
authentication: put it behind your own gateway before exposing it.

By default a request is fitted to the model's trained budget: long option descriptions and questions are shortened
and an oversized state keeps its head and tail. `--no-caps` (or `VERA_NO_CAPS=1`, or `vera.load(..., no_caps=True)`)
reads every request whole instead. vera-core-2 and vera-large always read requests whole.

## vLLM engine

vera-core, vera-core-2 and vera-large can run their backbone on vLLM (GPU, vLLM 0.29 or newer), behind the same
HTTP API:

```bash
pip install "vera-s1[vllm]"
vera-serve --model scar-ai/vera-core-2 --engine vllm --port 8200
vera-serve --model scar-ai/vera-large --engine vllm --tensor-parallel-size 2 --port 8200   # or 1 on a 96 GB+ GPU
```

or in Python: `vera.load("scar-ai/vera-core-2", engine="vllm")`. vLLM runs the fine-tuned backbone and returns its
hidden states; the decision head runs on top, so answers match the default engine up to bf16 differences. The backbone
is exported to a plain Qwen3.5 checkpoint on first use and cached in `~/.cache/vera/vllm`. A request longer than
`--max-model-len` (default 32,768 tokens for vera-core-2 and vera-large, 8,192 for vera-core) is refused, never cut.
`--gpu-memory-utilization` defaults to 0.5, or 0.9 for vera-large (~51 GB of bf16 weights). Plain
`vllm serve` does not work on these repos: vera scores options and never generates text. vera-spark has no vLLM path.

Requires Python 3.10+ and transformers 5+. A GPU (CUDA or ROCm) is recommended; Apple MPS is not supported (CPU is
used on Macs).
