Metadata-Version: 2.4
Name: avrik-server
Version: 1.0.0
Summary: Avrik server: readout, calibration, /v1/systemone API and inference backends.
Author: Avrik AI
Author-email: Avrik AI <avriktech.ai@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Requires-Dist: fastapi>=0.115,<1 ; extra == 'api'
Requires-Dist: uvicorn>=0.30,<1 ; extra == 'api'
Requires-Dist: httpx>=0.27,<1 ; extra == 'api'
Requires-Dist: pydantic>=2.8,<3 ; extra == 'api'
Requires-Dist: pyyaml>=6.0.3,<7 ; extra == 'api'
Requires-Dist: llama-cpp-python==0.3.35 ; extra == 'cpu'
Requires-Dist: numpy>=2.0 ; extra == 'cpu'
Requires-Dist: transformers>=5.17.0 ; extra == 'readout'
Requires-Dist: huggingface-hub>=0.30 ; extra == 'readout'
Maintainer: Avrik AI
Maintainer-email: Avrik AI <avriktech.ai@gmail.com>
Requires-Python: >=3.12
Project-URL: Homepage, https://www.avrik.ai
Project-URL: Models, https://huggingface.co/avrik-ai
Provides-Extra: api
Provides-Extra: cpu
Provides-Extra: readout
Description-Content-Type: text/markdown

# avrik-server

The run-time server for [Avrik](https://huggingface.co/avrik-ai) decision models: the
prompt renderer, the letter readout, calibration, the `/v1/systemone` HTTP API, and the
llama.cpp (CPU) and vLLM (GPU) backends.

An Avrik model reads a state and typed questions (yes/no, choice, score, multi-label) and
returns a calibrated probability distribution over each question's options, in one
forward pass with no generated text.

Most people install the [`avrik`](https://pypi.org/project/avrik/) CLI, which depends on
this package and runs it from a verified model download:

```bash
pip install llama-cpp-python==0.3.35 --no-deps --only-binary=:all: \
  --index-url https://abetlen.github.io/llama-cpp-python/whl/cpu
pip install "avrik[cpu]"
avrik pull Avrik-Lite-4B
avrik serve Avrik-Lite-4B        # http://127.0.0.1:8080
```

To call the API from Python, use [`avrik-sdk`](https://pypi.org/project/avrik-sdk/).

## What it does

1. **Renders** the state and question with a fixed prompt template whose SHA-256 is
   returned with every answer; options are letters A, B, C, ...
2. **Reads** the probability of every tokenizer form of each option letter (never top-k)
   and refuses the answer if the letters hold less than 98% of the probability mass.
3. **Calibrates** with per-type temperatures fitted for the exact build, bound to its hash;
   a calibration file for another build is refused.
4. **Answers** with the distribution, `top`, `margin`, `confidence`, `abstain`, and eight
   audit fields: model hash, adapter hash, calibration version, prompt-template SHA-256,
   allowed-token-set hash, input tokens, backend and precision.

## Extras

| Extra | Adds |
| --- | --- |
| `avrik-server[readout]` | tokenizer and chat template (`transformers`, no PyTorch) |
| `avrik-server[api]` | the HTTP server (FastAPI, uvicorn, httpx, pydantic) |
| `avrik-server[cpu]` | the llama.cpp backend (`llama-cpp-python` 0.3.35, numpy) |

The GPU backend talks to a vLLM server on loopback started with
`--logprobs-mode raw_logprobs`; see each model card for the exact command.

## Privacy

Inference makes no network calls, sends no telemetry and stores nothing. The server
listens on 127.0.0.1 unless you configure otherwise.

## Models

| Model | Tier | Hugging Face |
| --- | --- | --- |
| Avrik-Lite-4B | Edge (CPU) | [avrik-ai/Avrik-Lite-4B](https://huggingface.co/avrik-ai/Avrik-Lite-4B), [-GGUF](https://huggingface.co/avrik-ai/Avrik-Lite-4B-GGUF) |
| Avrik-Pro-12B | Pro (default) | [avrik-ai/Avrik-Pro-12B](https://huggingface.co/avrik-ai/Avrik-Pro-12B), [-GGUF](https://huggingface.co/avrik-ai/Avrik-Pro-12B-GGUF) |
| Avrik-Max-31B | Max | [avrik-ai/Avrik-Max-31B](https://huggingface.co/avrik-ai/Avrik-Max-31B) |

Built on Gemma 4 by Google (Apache-2.0). Licence: Apache-2.0. Security reports:
avriktech.ai@gmail.com.

Website: [www.avrik.ai](https://www.avrik.ai) · Models: [huggingface.co/avrik-ai](https://huggingface.co/avrik-ai) ·
[Acceptable use policy](https://huggingface.co/avrik-ai/Avrik-Pro-12B/blob/main/USE_POLICY.md)
