Metadata-Version: 2.4
Name: typevet
Version: 0.1.0.dev1
Summary: Type-safe structured generation under hexagonal architecture (llama.cpp first)
Keywords: evaluation,gemma,json-schema,llama-cpp,llm,structured-generation,structured-output,type-safe,vllm
Author: Alberto-Codes
Author-email: Alberto-Codes <alberto.codes.dev@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: httpx>=0.28
Requires-Dist: jsonschema>=4.26.0
Requires-Dist: structlog>=24.1
Requires-Dist: typer>=0.12 ; extra == 'cli'
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/Alberto-Codes/typevet
Project-URL: Documentation, https://alberto-codes.github.io/typevet/
Project-URL: Repository, https://github.com/Alberto-Codes/typevet
Project-URL: Issues, https://github.com/Alberto-Codes/typevet/issues
Project-URL: Changelog, https://github.com/Alberto-Codes/typevet/blob/main/CHANGELOG.md
Provides-Extra: cli
Description-Content-Type: text/markdown

[![CI](https://img.shields.io/github/actions/workflow/status/Alberto-Codes/typevet/ci.yml?branch=main&label=CI)](https://github.com/Alberto-Codes/typevet/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/github/actions/workflow/status/Alberto-Codes/typevet/docs.yml?branch=main&label=docs)](https://alberto-codes.github.io/typevet/)
[![Python](https://img.shields.io/badge/python-3.12-blue)](https://github.com/Alberto-Codes/typevet/blob/main/pyproject.toml)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![docs vetted](https://img.shields.io/badge/docs%20vetted-docvet-purple)](https://github.com/Alberto-Codes/docvet)

# typevet

Kind: landing page (the project overview; the one page that mixes kinds).

typevet is a Python library that asks a model typed questions and returns typed answers.
The three question types are `Noul` (yes or no), `Choice` (one label) and `Score` (one rubric level).
typevet computes each answer from the model's next-token probabilities, read before sampling.
typevet also returns JSON objects that pass a JSON Schema you supply, or it raises an error.
The receipts cover Gemma 4 31B on llama.cpp for local work and on vLLM for hosting.

Read the documentation at <https://alberto-codes.github.io/typevet/>.

## Status

- typevet is pre-1.0. The package version is `0.1.0`.
- typevet is not on PyPI yet.
  Build a wheel from a checkout and install it: see
  [Install typevet](https://github.com/Alberto-Codes/typevet/blob/main/docs/how-to/install.md).
- typevet requires Python 3.12 or later.
- Each backend has one tested model pin.
  The receipts give the full pin and its limits.

| Backend | Tested pin | Receipt |
|---|---|---|
| vLLM | `vllm/vllm-openai:v0.30.0`, BF16 `google/gemma-4-31B-it`, one H100 80 GB | [#170](https://github.com/Alberto-Codes/typevet/issues/170#issuecomment-5884707915) |
| llama.cpp | Build `b11223-4da633776`, local alias `gemma-4-31b-kv9-q4km-mm` | [#203](https://github.com/Alberto-Codes/typevet/issues/203#issuecomment-5882379255) |
| llama.cpp grammar | Build `b11243-fc07d781e`, Gemma 4 31B QAT Q4_0 GGUF | [#129](https://github.com/Alberto-Codes/typevet/issues/129#issuecomment-5892208050) |

Performance: on one H100 at concurrency level 64, 480 Banking77 records took 12.1 s at 39.6 records/s.
That run had 0 errors. Banking77 calibration passed; DIFrauD SMS failed parity (ECE 0.158 against 0.10). One run, one pod, one pin.
See [Performance on one H100](https://alberto-codes.github.io/typevet/reference/performance/)
and [Serve Gemma 4 31B on a rented H100](https://alberto-codes.github.io/typevet/how-to/serve-gemma-4-31b-on-a-rented-h100/).
A valid structure does not prove accuracy or calibration.
The receipts are small samples.

## Quickstart

Get one offline typed judgment from a scripted fake. This step needs no model.

```bash
uv sync
uv run python -c "
from typevet.domain import Noul
from typevet.runtime import ScoringJudgmentAdapter
from typevet.testing import ScriptedScoringFake
fake = ScriptedScoringFake(logprobs={'True': -0.2, 'False': -1.0})
port = ScoringJudgmentAdapter(fake, tokenize_content=lambda t: (ord(t[0]),))
r = port.judge('text', {'q': Noul(instructions='Ok?', criteria={'true': 'Y', 'false': 'N'})}, 'fake')
print('noul', r.nouls['q'].noul)
"
```

The command prints the probability of yes, near 0.69.
The [offline tutorial](https://github.com/Alberto-Codes/typevet/blob/main/docs/tutorials/first-typed-judgment-offline.md) explains each step.
Then connect a model server:

- To host typevet, follow [Serve typevet on vLLM](https://github.com/Alberto-Codes/typevet/blob/main/docs/how-to/serve-typevet-on-vllm.md).
- To run typevet locally, follow [Run Gemma 4 on llama.cpp](https://github.com/Alberto-Codes/typevet/blob/main/docs/how-to/run-gemma4-llamacpp.md).
- To call typevet from code, follow [Call typevet from Python](https://github.com/Alberto-Codes/typevet/blob/main/docs/how-to/call-typevet-from-python.md).

## Learn more

- [How typevet works with Gemma 4](https://github.com/Alberto-Codes/typevet/blob/main/docs/explanation/how-typevet-works-with-gemma-4.md)
  explains the scoring path, the two backends and the receipts.
- [Gemma 4 multimodal judgments](https://github.com/Alberto-Codes/typevet/blob/main/docs/explanation/gemma-4-multimodal-judgments.md)
  explains how images reach each backend, and the limits.
- [Native typed judgments](https://github.com/Alberto-Codes/typevet/blob/main/docs/explanation/native-typed-judgments.md) states the scope and the limitations.
- [The documentation index](https://github.com/Alberto-Codes/typevet/blob/main/docs/README.md) lists every page and its kind.

[TypeLLM](https://github.com/TypeLLM/TypeLLM) is a research reference for the decision model.
It is not a runtime dependency.

## For contributors

Read [CLAUDE.md](https://github.com/Alberto-Codes/typevet/blob/main/CLAUDE.md) first.
It states the gates, the issue workflow and the rules for agents and people.

```bash
uv sync
uv run pre-commit install -t pre-commit -t pre-push -t commit-msg
uv run pytest -q
```

The default test run skips live tests.
Pull requests and pushes to `main` run the hook stages in
[the CI workflow](https://github.com/Alberto-Codes/typevet/blob/main/.github/workflows/ci.yml).
[The writing system](https://github.com/Alberto-Codes/typevet/blob/main/docs/reference/writing-system.md) and
[the commit rules](https://github.com/Alberto-Codes/typevet/blob/main/docs/reference/commits.md) apply to every change.
