llm-ports 0.12.1.dev14__tar.gz

llm_ports-0.12.1.dev14/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

llm_ports-0.12.1.dev14/.github/workflows/ci.yml

@@ -0,0 +1,152 @@
+# llm-ports' own gate. Every job starts from `permissions: {}` and grants only what it needs.
+#
+#   lint         ruff check + ruff format --check, pre-commit (all files), actionlint + zizmor over
+#                the workflows
+#   pytest       the locked suite on 3.12 / 3.13 / 3.14 / 3.15 (ubuntu) and 3.13 (windows), with a
+#                coverage floor (pyproject `[tool.coverage.report] fail_under`, raised only); one leg
+#                uploads to Codecov over OIDC.
+#   test-lowest  every direct dependency at its declared lower bound (`--resolution lowest-direct`)
+#   build        sdist + wheel, `twine check --strict`
+#   test         the one required check: green only when every job above is
+#   gitleaks / dup-code   ci-kit's reusable workflows, called the way every consumer calls them
+#
+# release.yml calls this whole workflow (`workflow_call`) before it builds anything to publish.
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+  workflow_call:
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  lint:
+    name: lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+      - run: uv sync --frozen --group lint
+      - name: ruff check
+        run: uv run --no-sync ruff check --output-format=github .
+      - name: ruff format
+        run: uv run --no-sync ruff format --check .
+      - name: pre-commit
+        run: uv run --no-sync pre-commit run --all-files --show-diff-on-failure
+      - name: actionlint
+        run: uv run --no-sync actionlint
+      - name: zizmor
+        env:
+          GH_TOKEN: ${{ github.token }} # online audits (impostor commits, known-vulnerable actions)
+        run: uv run --no-sync zizmor --format=github .
+
+  pytest:
+    name: pytest (${{ matrix.os }}, ${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    permissions:
+      contents: read
+      id-token: write # Codecov OIDC upload, no stored token
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python: ["3.12", "3.13", "3.14", "3.15"]
+        include:
+          - { os: windows-latest, python: "3.13" }
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --frozen
+      - name: pytest
+        run: uv run --no-sync pytest -q --cov --cov-report=term --cov-report=xml
+      - name: codecov
+        if: matrix.os == 'ubuntu-latest' && matrix.python == '3.13'
+        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
+        with:
+          use_oidc: true
+          files: coverage.xml
+          fail_ci_if_error: true
+
+  test-lowest:
+    name: test-lowest (lowest-direct, 3.12)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          python-version: "3.12"
+      # Every extra CI can install (lettucedetect pulls torch; its tests run over a stub detector).
+      - run: uv venv
+      - run: uv pip install --resolution lowest-direct -e ".[evals,langfuse,otel,sql]" --group dev
+      - run: uv pip list
+      - name: pytest
+        run: .venv/bin/python -m pytest -q
+
+  build:
+    name: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+      - run: uv build
+      - name: twine check
+        run: uv run --frozen --only-group lint twine check --strict dist/*
+
+  # The required status check is named `test`; it aggregates every job above so a new leg is
+  # covered without editing branch protection.
+  test:
+    name: test
+    if: always()
+    needs: [lint, pytest, test-lowest, build]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions: {}
+    steps:
+      - uses: re-actors/alls-green@b5b5b37504aa4183270bd3d855c52a67f212be35 # v1.3.0
+        with:
+          jobs: ${{ toJSON(needs) }}
+
+  gitleaks:
+    name: gitleaks (secret scan)
+    permissions:
+      contents: read
+      pull-requests: read
+    uses: mjdevaccount/ci-kit/.github/workflows/gitleaks.yml@v1
+    with:
+      mode: history
+
+  # The same code written twice fails the PR: ci-kit's `ci-dup-code` (jscpd behind a shrink-only
+  # fingerprint baseline, ci/jscpd-baseline.json). A NEW clone >= 70 tokens / 7 lines between two
+  # tracked files fails; a removed one may re-freeze smaller (`--write-baseline` refuses to grow).
+  # Reports as "dup-code / lint".
+  dup-code:
+    permissions:
+      contents: read
+    uses: mjdevaccount/ci-kit/.github/workflows/dup-code.yml@v1

llm_ports-0.12.1.dev14/.github/workflows/release.yml

@@ -0,0 +1,110 @@
+# Publishing. Two triggers, one pipeline, one index:
+#
+#   push of a `v*` tag   ci (the whole gate, reused) -> build X.Y.Z -> PyPI
+#                                                              -> GitHub release with dist/* attached
+#   workflow_dispatch    ci -> build a PEP 440 dev release -> PyPI
+#
+# The dispatch build is `X.Y.Z.devN` (N = this workflow's run number): pyproject's version when it is
+# already a dev version, else the next patch (0.12.0 -> 0.12.1.devN). Installers skip pre-releases
+# unless asked (`pip install --pre`), so a dev upload is the end-to-end dry run of a real release.
+#
+# Uploads use PyPI trusted publishing: GitHub's OIDC token is exchanged for a short-lived upload
+# token, so no secret is stored. PyPI's publisher names this repo, this file and the `pypi`
+# environment; renaming any of the three breaks publishing.
+#
+# The GitHub release does NOT depend on the PyPI upload: consumers pin the wheel URL
+#   llm-ports @ https://github.com/mjdevaccount/llm-ports/releases/download/vX.Y.Z/llm_ports-X.Y.Z-py3-none-any.whl
+# and that asset must exist for every tag whatever the index did. A tag that does not match
+# pyproject's version publishes nothing.
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  ci:
+    name: ci
+    permissions:
+      contents: read
+      id-token: write # ci.yml's Codecov upload
+      pull-requests: read # ci-kit gitleaks
+    # A job-level reusable workflow resolves from this commit, never the runner's filesystem; the
+    # `$/` self-repository form is not yet parsed by actionlint 1.7.12.
+    uses: ./.github/workflows/ci.yml # zizmor: ignore[self-repository]
+
+  build:
+    name: build
+    needs: ci
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          enable-cache: false # a release builds from a clean resolve, never a shared cache
+      - name: tag matches pyproject version
+        if: github.event_name == 'push'
+        run: |
+          v=$(uv version --short)
+          [ "v$v" = "$GITHUB_REF_NAME" ] || { echo "::error::tag $GITHUB_REF_NAME != pyproject v$v"; exit 1; }
+      - name: dev version
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          case "$(uv version --short)" in
+            *.dev*) uv version --frozen --bump "dev=$GITHUB_RUN_NUMBER" ;;
+            *) uv version --frozen --bump patch --bump "dev=$GITHUB_RUN_NUMBER" ;;
+          esac
+      - run: uv build --no-sources
+      - name: twine check
+        run: uv run --frozen --only-group lint twine check --strict dist/*
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  pypi:
+    name: publish (PyPI)
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/project/llm-ports/
+    permissions:
+      id-token: write # trusted publishing; the action also uploads PEP 740 attestations
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
+
+  github-release:
+    name: GitHub release
+    if: github.event_name == 'push'
+    needs: build # never on `pypi`: the wheel URL consumers pin must exist whatever the index did
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write # create the release and upload its assets
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - name: create release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          # no --clobber fallback: a published wheel's bytes are what consumers locked a hash of
+          gh release create "$GITHUB_REF_NAME" dist/* --repo "$GITHUB_REPOSITORY" --verify-tag \
+            --title "$GITHUB_REF_NAME" --generate-notes

llm_ports-0.12.1.dev14/.github/zizmor.yml

@@ -0,0 +1,9 @@
+# zizmor (run in ci.yml's lint job). Third-party actions are pinned by commit SHA; ci-kit's
+# reusable workflows are this owner's own and ship fixes by moving their `v1` tag, so a ref pin is
+# the contract there.
+rules:
+  unpinned-uses:
+    config:
+      policies:
+        "mjdevaccount/*": ref-pin
+        "*": hash-pin

llm_ports-0.12.1.dev14/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+dist/
+.coverage
+.coverage.*
+coverage.xml

llm_ports-0.12.1.dev14/.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+# Run in CI (ci.yml, lint job) and locally after `uv run pre-commit install`.
+repos:
+  - repo: local
+    hooks:
+      # Docstrings state the contract; deployment and incident detail lives in docs/adr and
+      # CHANGELOG.md (CONTRIBUTING.md). The lookahead admits one string: `GenRequest.label`'s
+      # default value is public behaviour until 1.0 renames it.
+      - id: no-deployment-vocabulary
+        name: no deployment vocabulary in the package
+        language: pygrep
+        entry: 'EDGE|edge-host|\bbox[_-](?!chat")|Tradier|trade[-_.]data|narrator|\b\d+B\b|20\d\d-\d\d-\d\d'
+        files: ^llm_ports/
+        types: [python]

llm_ports-0.12.1.dev14/CHANGELOG.md

@@ -0,0 +1,237 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html). Why a design is the way it is lives in
+[`docs/adr/`](docs/adr/).
+
+## [Unreleased]
+
+### Added
+
+- Releases publish to PyPI through trusted publishing (no stored token), with PEP 740
+  attestations; a tag still attaches the wheel and sdist to a GitHub release, independently of the
+  upload. A manual run of `release.yml` uploads a `.devN` pre-release as the dry run.
+- Package metadata: project URLs, classifiers and keywords.
+- CI: `actionlint` over the workflows; `ci.yml` is callable (`workflow_call`), and a release runs
+  all of it before building.
+
+## [0.12.0] - 2026-11-03
+
+No behaviour change and no public name change; the release carries documentation, tooling and
+dependency floors.
+
+### Added
+
+- `numbers.law_text(mode, *, web)`: the number law's one English statement, beside the check it
+  states (`numbers.loose`). `judge_sampling.rubric` composes it; its output is byte-identical to
+  0.11.0 for every grounding mode and web flag, pinned by `tests/test_rubric_golden.py`.
+- Architecture decision records `docs/adr/0001`–`0008` (MADR), holding the rationale and the
+  measured evidence that used to live in docstrings.
+- `CONTRIBUTING.md`: the docstring rules, where history goes, how to release.
+- A `pre-commit` hook that rejects deployment vocabulary in `llm_ports/`, run in CI.
+- CI: pytest on Python 3.12, 3.13, 3.14 and 3.15 (Ubuntu) and 3.13 (Windows); the suite at every
+  dependency's declared lower bound (`--resolution lowest-direct`); a branch-coverage floor with
+  Codecov upload over OIDC; `ruff format --check`; `twine check --strict` on the build; `zizmor`
+  over the workflows; every workflow defaults to `permissions: {}`.
+
+### Changed
+
+- Every docstring states the contract in Google style, with invariants in an `Invariants:`
+  section; ruff's `D` rules (Google convention) enforce the layout.
+- The tree is formatted with `ruff format`.
+- Dependency floors match what is tested: `pydantic>=2.12` (already required by
+  `pydantic-ai-slim>=2.57`) and, for the `sql` extra, `sqlglot>=30.22`. Older sqlglot drops
+  `LIMIT ALL` at parse time, so `sql_guard.guard` capped the query instead of refusing it.
+
+### Fixed
+
+- `content.print_gate` and `DataClass.allows` document the `ValueError` they raise for an audience
+  outside `AUDIENCES`; the old text said `print_gate` never raised.
+
+## [0.11.0] - 2026-11-03
+
+### Added
+
+- `ports.Reranker`, the tenth port, and `Reranked` (scores in input order, order-only; never
+  raises for a model, wire or gate failure). Also exported from the package root.
+- `reranker_http`: `HttpReranker` over the Cohere/Jina-shaped `/rerank` wire, `payload`,
+  `scores_from`. Every document is scored exactly once (indices exactly `0..n-1`) and every score
+  is finite, or the result is `invalid`.
+- `observation`: `observe(tracer, ...)` opens one generation around a block and ends it once
+  (`ERROR` and `latency_ms` on an exception); `PortObservation` (was `call._PortObservation`) with
+  `usage_counts()` and `fail(exc, metadata)`; `opt_int`. A call that reported neither usage count
+  stamps `tokens_unmeasured: true`. `call.tracer_trace` is built on `observe`.
+- `langfuse_tracer` (extra `langfuse`): `LangfuseTracer(client, ..., on_event=)`,
+  `LangfuseGeneration`, `usage_details`, `trace_id`.
+- `langfuse_prompt_source`: `LangfusePromptSource(client, seed_for, ..., on_event=)`; the repo
+  leads and the label mirrors. Duck-typed client, no SDK import.
+- `otel_gen_ai` (extra `otel`): `gen_ai_span`, `record_gen_ai` (back-dated), `GenAiRecorder`;
+  attribute names from `opentelemetry-semantic-conventions`, emitting `gen_ai.provider.name`
+  beside the deprecated `gen_ai.system`.
+- `sql_guard` (extra `sql`): `guard(sql, policy)`, `SqlGuardPolicy` (with `dialect`, default
+  postgres), `SqlGuardError`, `FORBIDDEN_NODES`, `POSTGRES_DENY_FUNCTIONS`.
+- `testing.StubReranker`; `testing_langfuse` (extra `langfuse`): `LangfuseRig`, `observed`,
+  `FakeLangfusePrompts`, `RefusingLangfuse`.
+
+### Changed
+
+- `index_order.IndexOrderedTransport` moved out of `pydantic_ai_embedder` (still importable
+  there, the same object) and also orders `/rerank` replies' `results`.
+
+## [0.10.0] - 2026-11-03
+
+### Added
+
+- `pydantic_evals_judge` (extra `evals`): `PydanticEvalsJudge(role, model=|model_for=)`,
+  `JUDGE_PROFILE`, `clean_reason`, `verdict_of`, `judge_inputs`.
+- `judge_sampling`: `Seen`, `seen_for`, `schema_of`, `judge_input`, `reply_text`, `sample_key`,
+  `selected`, `rubric(role, seen, *, platform, mode, today, tz_label)`, `verdict_label`.
+- `lettucedetect_grounder` (extra `lettucedetect`): `LettuceDetectGrounder`, `load_detector`,
+  `Detector`, `MODEL`, `MAX_CONTEXT_CHARS`, `WINDOW_REASON`.
+- `grounder_http`: `HttpGrounder`, `GrounderUnavailable`, `payload`.
+- `claim_refute`: `refute_slots`, `refute_prompt(pack, ...)`, `refute(generate, role, *, pack, ...)`,
+  `RefuteClaim`, `GenerateFn`.
+- `json_schema`: `research_schema`, `RESEARCH_ANALYSIS`, `ANALYSIS_KEY`, `without_analysis`,
+  `research(generate, role, ...)`.
+- `testing.StubDetector`.
+
+## [0.9.0] - 2026-11-03
+
+### Added
+
+- `chunking`: `chunk_text`, `break_floor`, `max_chars_for_chunks`, `content_hash`,
+  `should_ingest`, `CHUNK_CHARS`, `CHUNK_OVERLAP`.
+- `retrieval_metrics`: `first_rank`, `hit_at_k`, `reciprocal_rank`, `agree_at_k`, `mean`, `clears`.
+- `reference`: `GauntletEvaluator`, `NumberLawGrounder`, `RepoPromptSource`, `NoopTracer`,
+  `NoopGeneration`.
+- `pydantic_ai_replay`: `Recorder`, `replay`, `Recording`, `key`, `NotRecorded`.
+- `testing.StubCiter`, `testing.StubPromptSource`; `ports.Seed` (also exported from the root).
+- `call_graders.TEXT_ONLY_GRADERS`, `graders_for_inputs`.
+
+### Changed
+
+- `call.generate` drops `TEXT_ONLY_GRADERS` for a call with `images=` or the new `web=True`, so an
+  image or a web tier no longer fails `numbers_from_inputs` by construction. With no `trace` hook
+  the call observes into `tracer_trace(NoopTracer())`, the package's one null sink.
+
+## [0.8.1] - 2026-11-03
+
+### Fixed
+
+- `IndexOrderedTransport` re-sorts an `/embeddings` reply's `data` by `index`. pydantic-ai drops
+  `index`, so a server answering out of order put every vector on its neighbour's row, which the
+  count check cannot see. `openai_compatible_embeddings` always wraps its transport with it.
+
+## [0.8.0] - 2026-11-03
+
+### Added
+
+- `ports.Embedder`, the ninth port, and `Embedded(vectors, outcome, stamp, reason, input_tokens)`:
+  one vector per text in one named space; `input_tokens=None` when the wire reported no usage.
+- `pydantic_ai_embedder.PydanticAIEmbedder` on pydantic-ai's `OpenAIEmbeddingModel`: count and
+  dimension checks (a short batch or a wrong dimension is `invalid`, never a partial result),
+  batching, an asymmetric query prefix, and the generator's never-raise outcome classification.
+- `openai_compatible_embeddings(base_url, model_name, key, transport=)`.
+- `testing.StubEmbedder`: deterministic hashed unit vectors.
+
+## [0.7.0] - 2026-11-03
+
+### Added
+
+- `content`: `ContentItem` (`prov:Entity`), `Activity` (`prov:Activity`), `DataClass` (rights
+  `public < owned < licensed < scraped`, `private`, `link_required`; `join` takes the most
+  restrictive), `CEILING` per audience, and `print_gate(item, audience) -> GateVerdict`: ok, or one
+  named refusal (`rights`, `unclaimed`, `uncited`, `unsourced`, `link`).
+
+## [0.6.0] - 2026-10-31
+
+### Added
+
+- `slots.to_prose(text)`: context a digit-free grammar can read with no figure to reach for. Every
+  digit run is removed whole (`numbers.DIGITS`), every character outside `PROSE_CHARS` becomes a
+  space.
+
+### Fixed
+
+- `__version__` matches the package version (it said 0.3.0).
+
+## [0.5.0] - 2026-10-31
+
+### Added
+
+- `call_graders.nullable_paths(model)`: the nullable leaf paths of a pydantic model.
+
+### Changed
+
+- `call_graders.schema_complete` reads a None on a nullable pydantic field as an answer; a None on
+  a required field still fails, and a dict value is graded as before.
+
+## [0.4.0] - 2026-10-29
+
+### Added
+
+- `numbers.loose(text, allowed, words_ok)`: the number law in one function. Digit runs by value
+  not in `allowed`, then spelled numbers and number-word tails not in `words_ok`, in order and
+  named.
+- `grounding.loose`, `slots.loose`; `grounding.belt` and `slots.belt` count `loose`.
+
+### Changed
+
+- `numbers.uncited` is `loose` sorted into the cited-spans shape (same results on every pinned case).
+- `call_graders.numbers_from_inputs` scores the distinct figures of `loose`, so spelled numbers
+  count; the prompt's own words and a `%` license them.
+
+## [0.3.0] - 2026-10-28
+
+### Added
+
+- `slots`: grounded prose by construction. `PROSE_CHARS`, `prose_pattern`, `slot_pattern` (the
+  digit-free grammar), `SLOT`, `ID`, `cited`, `fill`, `problems` (unknown slot, stray brace, cited
+  twice), `belt` over filled text.
+- `numbers.canon` and `numbers.digits`: digit runs compare by value ("2.20" == "2.2").
+
+### Changed
+
+- `grounding.belt` compares digit runs by value.
+
+## [0.2.0] - 2026-10-23
+
+### Added
+
+- `grounding`: `Problem(path, reason, detail="")`, `describe`, `retry_message`,
+  `belt(text, allowed, words_ok, *, strip_links)`, `allowed_numbers(texts)`.
+- `failure_reason(exc, *, with_cause=False)`: an optional ` <- <cause reason>` tail, cut by the
+  same body-safe rule and within `REASON_MAX`.
+
+## [0.1.1] - 2026-10-22
+
+### Added
+
+- `py.typed` (PEP 561).
+- A release workflow: a `v*` tag builds the wheel and sdist from the tagged commit, refuses a
+  tag that does not match the package version, and attaches both to a GitHub release.
+
+## [0.1.0] - 2026-10-22
+
+### Added
+
+- The ports (Protocols and frozen value types), roles over a consumer's tier table, prompt packs
+  named by content sha, per-call graders, `generate()` with named outcomes and `Hooks`, the
+  pydantic-ai `Generator` adapter, and test doubles.
+
+[Unreleased]: https://github.com/mjdevaccount/llm-ports/compare/v0.12.0...HEAD
+[0.12.0]: https://github.com/mjdevaccount/llm-ports/compare/v0.11.0...v0.12.0
+[0.11.0]: https://github.com/mjdevaccount/llm-ports/compare/v0.10.0...v0.11.0
+[0.10.0]: https://github.com/mjdevaccount/llm-ports/compare/v0.9.0...v0.10.0
+[0.9.0]: https://github.com/mjdevaccount/llm-ports/compare/v0.8.1...v0.9.0
+[0.8.1]: https://github.com/mjdevaccount/llm-ports/compare/v0.8.0...v0.8.1
+[0.8.0]: https://github.com/mjdevaccount/llm-ports/compare/v0.7.0...v0.8.0
+[0.7.0]: https://github.com/mjdevaccount/llm-ports/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/mjdevaccount/llm-ports/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/mjdevaccount/llm-ports/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/mjdevaccount/llm-ports/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/mjdevaccount/llm-ports/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/mjdevaccount/llm-ports/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/mjdevaccount/llm-ports/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/mjdevaccount/llm-ports/releases/tag/v0.1.0

llm_ports-0.12.1.dev14/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing
+
+## Setup
+
+```
+uv sync                      # the locked dev environment
+uv run pre-commit install    # the docstring-vocabulary hook, on every commit
+uv run pytest -q --cov       # the suite, with the coverage floor
+uv run ruff check . && uv run ruff format --check .
+```
+
+CI (`.github/workflows/ci.yml`) runs the same commands on Python 3.12–3.14 and Windows, plus the
+suite at every dependency's declared lower bound, `twine check --strict` on the build, and
+`zizmor` over the workflows.
+
+## Docstrings
+
+A docstring states the contract. Its reader is someone calling the function, not someone
+auditing why it was written.
+
+1. **Contract only.** What it does, `Args:`, `Returns:`, `Raises:` (or that it never raises), in
+   the present tense, Google style. Rules that always hold go in an `Invariants:` section.
+2. **No history and no deployment detail.** No incident dates, replay counts, host, service or
+   consumer names, model sizes, or ticket ids. A *compatibility fact* stays ("llama.cpp's grammar
+   compiler ignores `maxLength` beside `pattern`"). The *reason* for a design choice moves to an
+   ADR, and the docstring keeps a one-line pointer (`Rationale: ADR-0002.`).
+3. **Emphasis by structure, not capitals.** An invariant goes in `Invariants:`; a warning goes in
+   its own sentence. Capitals are for constants and acronyms.
+4. **Neutral examples.** Orders, documents, tickets, invoices.
+
+`ruff` enforces the Google layout (`D` rules). A `pre-commit` hook (`.pre-commit-config.yaml`)
+rejects deployment vocabulary in `llm_ports/`.
+
+## Where history goes
+
+- **What changed**: `CHANGELOG.md` ([Keep a Changelog](https://keepachangelog.com/en/1.1.0/)).
+- **Why, with the evidence**: `docs/adr/NNNN-title.md` ([MADR](https://adr.github.io/madr/)).
+  Evidence is stated without naming the system it came from ("on a production summarizer, 40 of
+  64 replies invented a figure with the instruction in place").
+
+## Releasing
+
+Bump `version` in `pyproject.toml`, move `Unreleased` in `CHANGELOG.md` under the new version, and
+merge. Then push a `vX.Y.Z` tag on `main`. `release.yml` runs the whole of `ci.yml`, checks the tag
+against the version, builds, runs `twine check --strict`, then, independently of each other,
+uploads to PyPI (trusted publishing through the `pypi` environment, with PEP 740 attestations) and
+attaches the wheel and sdist to a GitHub release. The release assets never wait on the upload:
+consumers that pin the wheel URL get it whatever PyPI did. A published file is never replaced.
+
+To dry-run the pipeline, run `release.yml` from `main` by hand (`gh workflow run release.yml`). It
+uploads a dev release, `X.Y.Z.devN` with N the run number, which installers take only when asked
+(`pip install --pre`).

llm_ports-0.12.1.dev14/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mjdevaccount
+
+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.