Metadata-Version: 2.5
Name: llm-ports
Version: 1.4.0
Summary: Thin Protocols for LLM work (Generator, Embedder, Reranker, Tracer, PromptSource, Judge, ...) and the one call path around them: roles from a tier table, prompt packs with a frozen content sha, per-call graders, named outcomes. Frameworks live behind the ports; pydantic-ai is the first adapter.
Project-URL: Homepage, https://github.com/mjdevaccount/llm-ports
Project-URL: Repository, https://github.com/mjdevaccount/llm-ports
Project-URL: Issues, https://github.com/mjdevaccount/llm-ports/issues
Project-URL: Changelog, https://github.com/mjdevaccount/llm-ports/blob/main/CHANGELOG.md
Project-URL: Decisions, https://github.com/mjdevaccount/llm-ports/tree/main/docs/adr
License-Expression: MIT
License-File: LICENSE
Keywords: evals,grounding,hexagonal-architecture,llm,observability,ports-and-adapters,pydantic,pydantic-ai
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Pydantic :: 2
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: jinja2>=3.1
Requires-Dist: pydantic>=2.12
Requires-Dist: pyyaml>=6.0
Provides-Extra: all
Requires-Dist: httpx2>=2.12; extra == 'all'
Requires-Dist: httpx>=0.27; extra == 'all'
Requires-Dist: langfuse<6,>=5.0.2; extra == 'all'
Requires-Dist: opentelemetry-api>=1.30; extra == 'all'
Requires-Dist: opentelemetry-semantic-conventions>=0.58b0; extra == 'all'
Requires-Dist: pydantic-ai-slim[openai]<3,>=2.57; extra == 'all'
Requires-Dist: pydantic-evals<3,>=2.57; extra == 'all'
Requires-Dist: sqlglot>=30.22; extra == 'all'
Requires-Dist: tenacity>=8.2; extra == 'all'
Provides-Extra: evals
Requires-Dist: pydantic-evals<3,>=2.57; extra == 'evals'
Provides-Extra: http
Requires-Dist: httpx>=0.27; extra == 'http'
Provides-Extra: langfuse
Requires-Dist: langfuse<6,>=5.0.2; extra == 'langfuse'
Provides-Extra: lettucedetect
Requires-Dist: lettucedetect>=0.1.6; extra == 'lettucedetect'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.30; extra == 'otel'
Requires-Dist: opentelemetry-semantic-conventions>=0.58b0; extra == 'otel'
Provides-Extra: pydantic-ai
Requires-Dist: httpx2>=2.12; extra == 'pydantic-ai'
Requires-Dist: httpx>=0.27; extra == 'pydantic-ai'
Requires-Dist: pydantic-ai-slim[openai]<3,>=2.57; extra == 'pydantic-ai'
Requires-Dist: tenacity>=8.2; extra == 'pydantic-ai'
Provides-Extra: sql
Requires-Dist: sqlglot>=30.22; extra == 'sql'
Description-Content-Type: text/markdown

# llm-ports

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

[![PyPI](https://img.shields.io/pypi/v/llm-ports?include_prereleases)](https://pypi.org/project/llm-ports/)
[![Python](https://img.shields.io/pypi/pyversions/llm-ports)](https://pypi.org/project/llm-ports/)
[![ci](https://github.com/mjdevaccount/llm-ports/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mjdevaccount/llm-ports/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/mjdevaccount/llm-ports/graph/badge.svg)](https://codecov.io/gh/mjdevaccount/llm-ports)
[![docs](https://img.shields.io/badge/docs-mjdevaccount.github.io-blue)](https://mjdevaccount.github.io/llm-ports/)
[![license](https://img.shields.io/pypi/l/llm-ports)](https://github.com/mjdevaccount/llm-ports/blob/main/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) ·
`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.

```python
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](https://github.com/mjdevaccount/llm-ports/blob/main/docs/adr/0001-named-outcomes-never-raise.md))

**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](https://github.com/mjdevaccount/llm-ports/blob/main/docs/adr/0002-grounded-prose-by-construction.md),
[ADR-0003](https://github.com/mjdevaccount/llm-ports/blob/main/docs/adr/0003-the-number-law-compares-by-value.md))

**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](https://github.com/mjdevaccount/llm-ports/blob/main/docs/adr/0008-prompt-packs-named-by-content-sha.md))

**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](https://github.com/mjdevaccount/llm-ports/blob/main/docs/adr/0006-data-rights-in-prov-o-terms.md))

**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](https://github.com/mjdevaccount/llm-ports/blob/main/docs/adr/0007-one-observation-lifecycle.md))

## 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
call                                    generate(): the one call path
grounding | prompts | observability
ports                                   Protocols and value types, zero I/O
```

## Links

[Documentation](https://mjdevaccount.github.io/llm-ports/) ·
[examples](https://github.com/mjdevaccount/llm-ports/tree/main/examples) ·
[changelog](https://github.com/mjdevaccount/llm-ports/blob/main/CHANGELOG.md) ·
[decision records](https://github.com/mjdevaccount/llm-ports/tree/main/docs/adr) ·
[contributing](https://github.com/mjdevaccount/llm-ports/blob/main/CONTRIBUTING.md)

### 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.
