typevet 0.1.0__tar.gz

typevet-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alberto-Codes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

typevet-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: typevet
+Version: 0.1.0
+Summary: Typed answers from model next-token probabilities, on llama.cpp and vLLM
+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`.
+- Install typevet from PyPI: `pip install typevet` or `uv add typevet`.
+  See [Install typevet](https://alberto-codes.github.io/typevet/how-to/install/).
+- typevet requires Python 3.12 or later.
+- Each tested pin has one receipt.
+  The receipt gives 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
+pip install typevet
+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.

typevet-0.1.0/README.md

@@ -0,0 +1,93 @@
+[![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`.
+- Install typevet from PyPI: `pip install typevet` or `uv add typevet`.
+  See [Install typevet](https://alberto-codes.github.io/typevet/how-to/install/).
+- typevet requires Python 3.12 or later.
+- Each tested pin has one receipt.
+  The receipt gives 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
+pip install typevet
+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.

typevet-0.1.0/pyproject.toml

@@ -0,0 +1,296 @@
+[project]
+name = "typevet"
+version = "0.1.0"
+description = "Typed answers from model next-token probabilities, on llama.cpp and vLLM"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+keywords = [
+    "evaluation",
+    "gemma",
+    "json-schema",
+    "llama-cpp",
+    "llm",
+    "structured-generation",
+    "structured-output",
+    "type-safe",
+    "vllm",
+]
+dependencies = [
+    "httpx>=0.28",
+    "jsonschema>=4.26.0",
+    "structlog>=24.1",
+]
+
+[[project.authors]]
+name = "Alberto-Codes"
+email = "alberto.codes.dev@gmail.com"
+
+[project.optional-dependencies]
+cli = ["typer>=0.12"]
+
+[project.urls]
+Homepage = "https://github.com/Alberto-Codes/typevet"
+Documentation = "https://alberto-codes.github.io/typevet/"
+Repository = "https://github.com/Alberto-Codes/typevet"
+Issues = "https://github.com/Alberto-Codes/typevet/issues"
+Changelog = "https://github.com/Alberto-Codes/typevet/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["uv_build>=0.11.20,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv_build]
+include = ["src/typevet/py.typed"]
+
+[tool.uv]
+default-groups = [
+    "dev",
+    "docs",
+]
+
+[tool.uv.workspace]
+members = ["evals"]
+
+[tool.uv.sources.typevet-evals]
+workspace = true
+
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+exclude = [
+    ".venv",
+    "__pycache__",
+    "*.egg-info",
+]
+
+[tool.ruff.lint]
+extend-select = [
+    "E402",
+    "E501",
+    "I",
+    "D",
+    "B",
+    "SIM",
+    "UP",
+    "RUF",
+    "PL",
+    "C901",
+    "TRY",
+    "PERF",
+    "S",
+    "G",
+]
+ignore = ["TRY003"]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 12
+
+[tool.ruff.lint.pylint]
+max-args = 7
+
+[tool.ruff.lint.pycodestyle]
+max-line-length = 100
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"**/tests/**/*.py" = [
+    "S101",
+    "D100",
+    "D101",
+    "D102",
+    "D103",
+    "D104",
+    "PLR2004",
+]
+"evals/src/typevet_evals/wheel_isolated.py" = ["S603"]
+"scripts/check_commit_msg.py" = ["S603"]
+"evals/src/typevet_evals/datasets/partner_guard.py" = [
+    "S603",
+    "S607",
+]
+
+[tool.ruff.lint.isort]
+known-first-party = [
+    "typevet",
+    "typevet_evals",
+]
+
+[tool.ruff.format]
+quote-style = "double"
+docstring-code-format = true
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = [
+    "tests",
+    "evals/tests",
+]
+markers = [
+    "unit: fast, isolated",
+    "contract: adapter behaviour against fakes",
+    "live: touches local llama.cpp; never in default CI",
+]
+addopts = [
+    "-ra",
+    "--strict-markers",
+    "--strict-config",
+    "--showlocals",
+    "-m",
+    "not live",
+]
+
+[tool.coverage.run]
+source = [
+    "typevet",
+    "typevet_evals",
+]
+
+[tool.coverage.report]
+fail_under = 90
+show_missing = true
+
+[tool.ty.src]
+include = [
+    "src",
+    "tests",
+    "scripts",
+    "evals/src",
+    "evals/tests",
+]
+
+[tool.importlinter]
+root_packages = [
+    "typevet",
+    "typevet_evals",
+]
+include_external_packages = true
+exclude_type_checking_imports = true
+
+[[tool.importlinter.contracts]]
+name = "Hexagonal layers"
+type = "layers"
+layers = [
+    "typevet.runtime",
+    "typevet.adapters.inbound",
+    "typevet.adapters.outbound",
+    "typevet.adapters.diagnostics",
+    "typevet.testing",
+    "typevet.ports",
+    "typevet.domain",
+]
+
+[[tool.importlinter.contracts]]
+name = "The library does not import the evals"
+type = "forbidden"
+source_modules = ["typevet"]
+forbidden_modules = ["typevet_evals"]
+
+[[tool.importlinter.contracts]]
+name = "Evaluation families"
+type = "layers"
+layers = [
+    "typevet_evals.cli | typevet_evals.gemma_native_vision_wheel_smoke | typevet_evals.psai_vision_probability_evidence | typevet_evals.wheel_isolated",
+    "typevet_evals.throughput",
+    "typevet_evals.vllm_acceptance",
+    "typevet_evals.instruction_variant | typevet_evals.cord",
+    "typevet_evals.psai_vision_consumer | typevet_evals.outcome_replay_metrics",
+    "typevet_evals.runner | typevet_evals.tpjep | typevet_evals.experiment_identity",
+    "typevet_evals.datasets",
+]
+
+[[tool.importlinter.contracts]]
+name = "Model framing stays off the serving backends"
+type = "forbidden"
+source_modules = ["typevet.adapters.outbound.gemma"]
+forbidden_modules = [
+    "typevet.adapters.outbound.llama_cpp",
+    "typevet.adapters.outbound.vllm",
+]
+
+[[tool.importlinter.contracts]]
+name = "Serving backends stay independent"
+type = "independence"
+modules = [
+    "typevet.adapters.outbound.llama_cpp",
+    "typevet.adapters.outbound.vllm",
+]
+
+[[tool.importlinter.contracts]]
+name = "Fakes stay off the adapters"
+type = "forbidden"
+source_modules = ["typevet.testing"]
+forbidden_modules = ["typevet.adapters"]
+
+[[tool.importlinter.contracts]]
+name = "Domain is IO-free"
+type = "forbidden"
+source_modules = ["typevet.domain"]
+forbidden_modules = [
+    "json",
+    "pathlib",
+    "os",
+    "io",
+    "logging",
+    "httpx",
+    "typer",
+    "jsonschema",
+    "structlog",
+]
+
+[tool.docvet]
+fail-on = [
+    "enrichment",
+    "freshness",
+    "coverage",
+    "griffe",
+    "presence",
+]
+exclude = [
+    "tests",
+    "scripts",
+    "evals/tests",
+]
+
+[tool.docvet.presence]
+min-coverage = 100.0
+
+[tool.typevet.commit-msg]
+allowed-authors = [
+    "alberto.nieto.80@gmail.com",
+    "alberto.codes.dev@gmail.com",
+    "github-actions[bot]@users.noreply.github.com",
+]
+coauthor-grandfather-through = "1b1d9a3cfde019c5dbfe164c1660f1d3be28b5ba"
+
+[dependency-groups]
+dev = [
+    "docvet[griffe]>=1.16.0",
+    "import-linter>=2.15",
+    "pre-commit>=4.6.2",
+    "pytest>=9.1.1",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.16.8",
+    "ty>=0.0.82",
+    "typevet-evals",
+]
+docs = [
+    "mkdocs>=1.6.1,<2",
+    "mkdocs-material>=9.7.7",
+    "mkdocstrings[python]>=1.0.6",
+    "pymdown-extensions>=12.1",
+]