Skip to main content

llm-ports

LLM calls that end in a named outcome, and prose whose numbers can't be invented.

PyPI Python ci codecov docs license

pip install "llm-ports[pydantic-ai]"

The core needs only pydantic, jinja2 and pyyaml. Each integration is an extra: pydantic-ai (generator, embedder, replay) · http (reranker, grounder client) · langfuse (tracer, prompt source, test rig) · otel (GenAI spans) · evals (pydantic-evals judge) · sql (SQL guard) · market (work-market packs from other distributions, pluggy) · lettucedetect (span grounder; large, pulls torch) · all (everything but lettucedetect). Importing an adapter without its extra fails with the line that installs it.

Quickstart

No network and no key: StubGenerator stands in for the model.

import asyncio

from pydantic import BaseModel, Field

from llm_ports import Role as BaseRole
from llm_ports import generate, load_tiers
from llm_ports.grounding import slots
from llm_ports.testing import StubGenerator  # real use: adapters.pydantic_ai.PydanticAIGenerator

TIERS = load_tiers(
    {
        "models": {"small": "gpt-5-nano"},
        "ladder": {"fast": 30.0},
        "tiers": {"default": {"model": "small", "timeout": "fast"}},
    }
)


class Role(BaseRole):
    TIERS = TIERS.tiers


SUMMARIZE = Role("orders.summarize", tier="default")
facts = {"count": "3", "total": "$1,284.50"}  # code renders every value, once


class Summary(BaseModel):  # the grammar has no digit token:
    text: str = Field(pattern=slots.slot_pattern(facts, 200))  # the model can only cite {id}


async def main() -> None:
    model = StubGenerator(Summary(text="Your {count} items came to {total}."))
    res = await generate(SUMMARIZE, prompt="Summarize the order.", output=Summary, generator=model)
    if res.outcome == "ok":
        prose = slots.fill(res.value.text, facts)
        assert slots.belt(prose, facts) == 0  # zero invented figures, by construction
        print(prose)  # Your 3 items came to $1,284.50.

    down = StubGenerator(lambda req, out: 1 / 0)  # the wire fails ...
    res = await generate(SUMMARIZE, prompt="Summarize the order.", output=Summary, generator=down)
    print(res.outcome, res.reason)  # ... 'unavailable', never a traceback


asyncio.run(main())

Concepts

Named outcomes. A model call ends in one of ok | gated | unavailable | request_fault | truncated | invalid, with a short reason, and never raises for a model, wire or gate failure. A fallback policy is a match on the outcome, not a tower of except clauses. (ADR-0001)

Grounded prose by construction. Code renders every figure once, under a digit-free id. The output grammar has no digit token, so the model cites {total} and cannot write a number at all; code fills the slots, and a belt over the filled text counts the figures no source rendered. That count is zero by construction, so a non-zero count is an alarm, not an error rate. (ADR-0002, ADR-0003)

Roles and tiers. A Role names one generation surface (feature.action) and resolves to a tier in a table the consumer owns: which model, whether it is self-hosted, which timeout rung. Feature code carries no model or timeout literal.

Prompt packs. A prompt is a versioned directory of templates, named by the sha of its text, so an output row records exactly which prompt produced it and an edited prompt is never mistaken for the one that was evaluated. (ADR-0008)

Provenance and the print gate. Every output is a PROV-O entity carrying its claims and the evidence each cites; print_gate answers whether it may be shown to an audience, with one named refusal when it may not. (ADR-0006)

One observation per call. A call is traced as one generation, opened once and ended once, with unmeasured usage flagged rather than recorded as zero. (ADR-0007)

Design

Hexagonal: the ports are ours and small, the adapters are thin wrappers over the libraries that already do the work (structured output, retries and validation come from pydantic-ai behind the Generator port). The layers, enforced by import-linter:

adapters | testing                      vendor SDKs live only here, one extra each
evals | rag | provenance | market       market: background actions a scheduler claims
call                                    generate(): the one call path
grounding | prompts | observability
ports                                   Protocols and value types, zero I/O

Documentation · examples · changelog · decision records · contributing

Known

  • Dependency ranges are the widest range CI proves. Every floor is installed and tested by the test-lowest job (--resolution lowest-direct); an upper bound is a major-version guard only (pydantic-ai-slim<3, langfuse<6); uv.lock tracks the latest releases (Renovate refreshes it) and the pytest matrix runs on it.
  • pydantic-ai (2.57 through 2.65) emits a PydanticAIDeprecationWarning when an OpenAI-compatible provider is given an httpx.AsyncClient; it takes httpx2.AsyncClient and drops httpx in v3. The adapters build an httpx client because a consumer's transport= is an httpx transport, so moving to httpx2 changes that argument's type.

MIT licensed.

Metadata

Release files for llm-ports 1.26.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for llm-ports 1.26.1
File Size Uploaded Provenance Actions
llm_ports-1.26.1.tar.gz 974.2 kB With provenance Details for llm_ports-1.26.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for llm-ports 1.26.1
File Interpreter ABI Platform Actions
llm_ports-1.26.1-py3-none-any.whl Python 3 none any Details for llm_ports-1.26.1-py3-none-any.whl

Total release size: 1.4 MB

Release files / llm_ports-1.26.1.tar.gz

Download URL llm_ports-1.26.1.tar.gz
Size 974.2 kB
Tags Source
SHA-256 checksum
How to use checksums
cab068e32ce891a268659fc2b30195c6a6649c46ff6a5ddc1b33ff38487b3bb3
BLAKE2b-256 checksum
How to use checksums
1f7db5bce3819ce15aa46ae0f0269b528fa16ab3941a008565bdc53b49f61ac4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / llm_ports-1.26.1-py3-none-any.whl

Download URL llm_ports-1.26.1-py3-none-any.whl
Size 406.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4d331e0c727384985153914c90612e5524ce6a1f2dd85ed71922cae09e898523
BLAKE2b-256 checksum
How to use checksums
4f66d24239b0639eb061146e950328976deef20494e1dfe205af6f2f4483bd5a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Security for llm-ports 1.26.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for llm_ports-1.26.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.26.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page