matchlab 0.1.0.dev1__tar.gz

matchlab-0.1.0.dev1/.github/actions/setup-toolchain/action.yml

@@ -0,0 +1,29 @@
+name: Setup toolchain
+description: Install uv with Python and optionally just
+
+inputs:
+  python-version:
+    description: Python version to install
+    required: false
+    default: "3.11"
+  install-just:
+    description: Whether to install just
+    required: false
+    default: "true"
+
+runs:
+  using: composite
+  steps:
+    - name: Install uv and Python
+      uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
+      with:
+        enable-cache: true
+        cache-dependency-glob: "uv.lock"
+        python-version: ${{ inputs.python-version }}
+
+    - name: Install just
+      if: ${{ inputs.install-just == 'true' }}
+      uses: extractions/setup-crate@7577c1bdf2d95e6d65d532788f35ed79d4b1dda2 # v2.0.1
+      with:
+        repo: casey/just
+        version: 1.55.1

matchlab-0.1.0.dev1/.github/dependabot.yml

@@ -0,0 +1,19 @@
+---
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      all-dependencies:
+        patterns:
+          - "*"
+  - package-ecosystem: uv
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      all-dependencies:
+        patterns:
+          - "*"

matchlab-0.1.0.dev1/.github/pull_request_template.md

@@ -0,0 +1,25 @@
+<!-- Give high level context to this PR -->
+
+## 🛠️ Changes proposed in this pull request
+
+* <!-- List the main changes you've made -->
+
+## 👀 Guidance to review
+
+<!-- Help reviewers know where to focus their efforts, or flag controversial decisions -->
+<!-- Add links and diagrams to explain decisions -->
+<!-- Point out any **breaking changes** -->
+
+## 🤖 AI declaration
+
+<!-- Declare code where AI was used, and how you ensured its quality -->
+
+## ✅ Checklist:
+
+- [ ] This is the smallest, simplest solution to the problem
+- [ ] I've read [our code standards](https://uktrade.github.io/matchlab/contributing/) and this code follows them  
+- [ ] All new code is tested
+- I've updated all relevant documentation (select all that apply)
+    - [ ] API documentation (docstrings and indexes)
+    - [ ] Tutorials
+    - [ ] Developer docs

matchlab-0.1.0.dev1/.github/skills/lucid-docs/README.md

@@ -0,0 +1,63 @@
+# Lucid docs v0.1
+
+Plain syntax. Precise terms. Necessary detail.
+
+Reduce reading effort without reducing technical depth.
+
+## Reader
+
+The skill defines a mid-level Python reader by assumed knowledge.
+
+It assumes comfort with idiomatic Python, common language features, standard library conventions, type hints, testing, and ordinary object-oriented design. It does not explain standard Python or established dependencies unless their local use is surprising. It explains repository-specific concepts, hidden constraints, surprising behaviour, and non-obvious interactions.
+
+The voice is direct when the repository supports a clear claim. Uncertainty is surfaced.
+
+## Repository glossary
+
+`docs/glossary.md` is the canonical source for repository-specific terminology. It is user-facing documentation and shared context for coding agents.
+
+The skill reads the glossary before editing documentation. It adds or updates terms that developers must understand as concepts, while excluding ordinary Python terms, obvious identifiers, and incidental implementation details.
+
+The glossary owns each canonical definition. Individual documents still provide enough local context to remain readable. Ambiguous or conflicting uses are reported rather than silently resolved.
+
+## Documentation locality
+
+Each explanation belongs at the narrowest scope that contains everyone who needs it:
+
+- module docstrings hold cross-cutting decisions, boundaries, and a short map
+- class and function docstrings hold the unit's contract and local why
+- inline comments hold the smallest-scope reason or constraint
+
+Shared reasoning is stated once and referred to by name. Shared contracts live at the abstraction that owns them. Implementations and overrides document only their differences.
+
+## Proportionality and comments
+
+Documentation depth follows conceptual weight, not line count. Simple units stay brief. `Args` and `Returns` sections appear only when they add information beyond the signature and type hints.
+
+A comment earns its place when it names a reasonable wrong turn, hidden constraint, or non-obvious consequence. The code remains responsible for routine mechanics.
+
+## Our style
+
+We want to establish a simple term to encapsulate our style as succinctly as possible.
+
+The established umbrella term is **plain language**, or **plain English** in a UK house style.
+
+Plain language is defined for an intended audience. It does not require replacing terms that the audience needs and understands. For developer documentation, this means simple sentence structure around exact technical vocabulary.
+
+The narrower linguistic operation is **syntactic simplification**: making sentence structure easier to parse while preserving meaning.
+
+The closest formal engineering analogue is **ASD-STE100 Simplified Technical English**. It constrains grammar and general vocabulary while permitting project-specific technical nouns and verbs. This skill borrows that distinction, but it does not claim ASD-STE100 compliance. The full standard is more restrictive and uses American English.
+
+For this project, the practical label is:
+
+> Plain English for technical readers.
+
+## Research links
+
+- ISO 24495-1 plain language standard: https://www.iso.org/obp/ui/#iso:std:iso:24495:-1:ed-1:v1:en
+- GOV.UK guidance on clear language for specialists: https://guidance.publishing.service.gov.uk/writing-to-gov-uk-standards/writing-guidelines/clear-language/
+- IEEE guidance on plain language for engineers: https://procomm.ieee.org/communication-resources-for-engineers/other-topics/plain-language/
+- ASD-STE100 official overview: https://www.asd-ste100.org/about_STE.html
+- Google guidance on short technical sentences: https://developers.google.com/tech-writing/one/short-sentences
+- Matt Pocock's domain-modelling skill: https://github.com/mattpocock/skills/tree/main/skills/engineering/domain-modeling
+- Martin Fowler on ubiquitous language: https://martinfowler.com/bliki/UbiquitousLanguage.html

matchlab-0.1.0.dev1/.github/skills/lucid-docs/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: lucid-docs
+description: Edit Python documentation, docstrings, comments, and repository terminology in plain English for technical readers. Reduce reading effort while preserving precise terms, contracts, design reasons, warnings, and non-obvious behaviour.
+license: CC0-1.0
+compatibility: Designed for coding agents that can inspect a repository and edit text files.
+---
+
+# Lucid docs
+
+## Goal
+
+Rewrite the specified documentation to reduce reading effort. Do not cut technical depth.
+
+Write in plain English for technical readers:
+
+> Plain syntax. Precise terms. Necessary detail.
+
+Fluent, sophisticated prose is NOT plain English for technical readers. Rewrite sentence structure ruthlessly. Use short sentences and direct verbs. Reduce ideas per sentence, but keep precise technical terms.
+
+Pay particular attention to the glossary.
+
+Ensure you run all three final checks.
+
+## Reader
+
+The reader is a mid-level Python developer, with a B2 CEFR reading level (Flesch-Kincaid Grade 8-9).
+
+Assume the reader can read idiomatic Python and understands common language features, standard library conventions, type hints, testing, and ordinary object-oriented design.
+
+Do not explain standard Python or established dependencies unless their use here differs from normal expectations. Explain repository-specific concepts, hidden constraints, surprising behaviour, and non-obvious interactions.
+
+State verified behaviour directly. Surface genuine uncertainty instead of weakening every claim.
+
+## Repository language
+
+Treat `docs/glossary.md` as the source of truth for repository-specific terms. Read it before editing documentation.
+
+Add or update a term when the reader must understand it as a concept. Include domain concepts, named workflows, architectural concepts, and important local distinctions. Exclude ordinary Python terms, obvious identifiers, and incidental implementation details.
+
+Write the glossary for developers as well as agents. Use the same plain, precise style as the rest of the documentation. Let the glossary own the canonical definition, while each document supplies enough local context to remain readable.
+
+Do not invent a definition or silently resolve conflicting uses. Report ambiguity when the repository does not support one clear meaning.
+
+## Editing
+
+Read enough code, tests, types, nearby documentation, and glossary entries to preserve the meaning.
+
+Keep information that helps a developer:
+
+- use the code correctly
+- understand a design choice
+- preserve an invariant
+- predict a side effect or failure
+- follow a non-obvious interaction
+- avoid a footgun
+
+Then tighten the prose:
+
+1. Put the main point first.
+2. Give each sentence one job, but clarity always outranks brevity.
+3. Put the subject and verb early.
+4. Prefer direct verbs to noun-heavy phrases.
+5. Remove words that add no meaning.
+6. Keep exact technical terms.
+7. Check that no condition, warning, or consequence was lost.
+
+Do not mistake prose that reads fluently and is technically sophisticated for plain English for technical readers. 
+
+Do not minimise the diff on the documentation you've been asked to review. Assume it has been written maximally, and your job is to rewrite minimally. Plain syntax. Precise terms. Necessary detail.
+
+## House style
+
+- Use British English.
+- Use sentence case headings.
+- Do not use semicolons.
+- Remove colons and dashes unless they truly simplify.
+- Do not start sentences with the FANBOYS set (for, and, nor, but, or, yet, so) unless the sentence stands alone, with its own subject, verb, and stated reason.
+- Use present tense for current behaviour.
+- Use one term for one concept.
+- Describe earlier or planned code only in migration guides.
+
+## Python documentation
+
+Put each explanation at the narrowest scope that contains everyone who needs it. State shared reasoning once, then refer to it by name instead of repeating it.
+
+Use module docstrings for cross-cutting design decisions, boundaries, and a short map of what the module contains. Explain why the module has its current shape, without reference to past or future code states outside of migration guides. Do not restate its implementation.
+
+Use class and function docstrings for the unit's contract and local why. Record the invariant it relies on, the footgun it avoids, or the important alternative it rejects. Let names, signatures, and type hints carry what they already express.
+
+Use inline comments for the smallest-scope fact or reason. Place them beside the lines they explain. A comment earns its place when it names a reasonable wrong turn, hidden constraint, or non-obvious consequence. Let the code express routine mechanics.
+
+Match documentation to conceptual weight. Keep simple units brief. Do not add `Args` or `Returns` sections merely because a function has parameters or returns a value. Give fuller treatment to contracts, decisions, and risks that need it.
+
+Document a shared contract at the highest abstraction that owns it. Overrides and implementations document only their differences, added constraints, and surprising behaviour.
+
+Mention another part of the codebase only when the interaction affects correct use or safe maintenance.
+
+## Final check
+
+The result should be easier to read and no less exact.
+
+### Phase 1
+
+Confirm that:
+
+- the first sentence carries the main point
+- each sentence is easy to parse
+- precise technical vocabulary remains
+- repository-specific terms match `docs/glossary.md`
+- new or changed concepts are reflected in the glossary
+- each explanation sits at the narrowest useful scope
+- documentation depth matches conceptual weight
+- shared contracts are stated once at the abstraction that owns them
+- comments add reasoning the code cannot show
+- design reasons and warnings remain
+- every claim is supported by the repository
+- the prose describes the code that exists now, not past or future states
+
+### Phase 2
+
+Perform a final check of the readability score and house style:
+
+```bash
+uv run .github/skills/lucid-docs/readability.py <path>
+```
+
+This takes the following options:
+
+* `--top <int>`: only show the N hardest-to-read blocks per file
+* `--rules`: comma-separated rule ids to run (default: all)
+  * `pleng001` readability score
+  * `pleng002` colon/semicolon/dash
+  * `pleng003` FANBOYS sentence openers
+
+Ensure an acceptable reading level for the reader. You may make allowances for the requirements of technical writing.
+
+Colons and dashes are permissable only if they truly simplify.
+
+This script is a spot-check, not the target. It cannot detect banned words or fluent-but-wordy prose. 
+
+### Phase 3
+
+Reread each file in its entirety, assuming it does not yet read as plain English.
+
+For each paragraph, find the sentence a plain English reader would stumble on, state why to yourself, then change it. Only move on once you cannot find one.
+
+Do not attempt to minimise churn.
+
+## Output
+
+Edit the requested documentation and `docs/glossary.md` in place when tools allow it.
+
+Report the files changed, unresolved terminology, and any claim that could not be verified. Keep the report brief.

matchlab-0.1.0.dev1/.github/skills/lucid-docs/readability.py

@@ -0,0 +1,310 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# dependencies = ["textstat", "typer"]
+# ///
+"""Run plain-English rules over .py or .md files, one line per finding.
+
+Rules (run all by default, or pick with --rules):
+
+    pleng001  Flesch-Kincaid readability score per block
+    pleng002  sentences containing a colon, semicolon, or dash
+    pleng003  sentences opening with a FANBOYS conjunction
+
+A "block" is a docstring, comment run (for .py) or a paragraph (for .md).
+Blocks below TRIVIAL_WORDS are skipped from scoring entirely (the maths is
+meaningless on 1-3 word fragments). Blocks below MIN_WORDS are still scored
+but flagged low_confidence.
+
+Usage:
+    python readability.py <path> [<path> ...]
+    uv run readability.py <path> [<path> ...] [--top N] [--rules pleng002]
+"""
+
+import ast
+import json
+import re
+import tokenize
+from collections.abc import Iterator
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+
+import textstat
+import typer
+
+MIN_WORDS = 30
+TRIVIAL_WORDS = 5
+
+FANBOYS = {"for", "and", "nor", "but", "or", "yet", "so"}
+
+SENTENCE_SPLIT = re.compile(r"(?<=[.!?])\s+")
+PUNCT_MARKS = re.compile(r"[;:]|—|–|(?<=\s)-(?=\s)")
+LEADING_WORD = re.compile(r"^[\"'“‘(]*([A-Za-z]+)")
+INLINE_CODE = re.compile(r"`([^`]*)`")
+
+
+class Rule(StrEnum):
+    """Plain-English rule ids, in the order they run and print."""
+
+    READABILITY = "pleng001"
+    PUNCTUATION = "pleng002"
+    FANBOYS = "pleng003"
+
+
+RULE_DESCRIPTIONS = {
+    Rule.READABILITY: "Flesch-Kincaid readability score per block",
+    Rule.PUNCTUATION: "sentences containing a colon, semicolon, or dash",
+    Rule.FANBOYS: "sentences opening with a FANBOYS conjunction",
+}
+
+
+def strip_inline_code(text: str) -> str:
+    """Drop backticks but keep the token inside, so identifiers stay readable."""
+    return INLINE_CODE.sub(r"\1", text)
+
+
+def sentences_of(text: str) -> list[str]:
+    """Split a block into sentences (naive, on . ! ?), dropping empty fragments."""
+    parts = SENTENCE_SPLIT.split(text.replace("\n", " "))
+    return [s.strip() for s in parts if s.strip()]
+
+
+@dataclass
+class BlockScore:
+    """The readability result for one block, or the reason it wasn't scored."""
+
+    label: str
+    words: int
+    status: str  # "", "low_confidence", "trivial"
+    grade: float | None
+    ease: float | None
+
+
+def score_block(label: str, text: str) -> BlockScore:
+    """Score a block, or mark it trivial instead of scoring meaningless text."""
+    word_count = len(text.split())
+    if word_count < TRIVIAL_WORDS:
+        return BlockScore(label, word_count, "trivial", None, None)
+    grade = textstat.flesch_kincaid_grade(text)
+    ease = textstat.flesch_reading_ease(text)
+    status = "low_confidence" if word_count < MIN_WORDS else ""
+    return BlockScore(label, word_count, status, grade, ease)
+
+
+def format_score(score: BlockScore) -> str:
+    """Format a scored block as a single key=value line."""
+    status = f" status={score.status}" if score.status else ""
+    return (
+        f"{score.label} words={score.words}{status} "
+        f"flesch_kincaid_grade={score.grade} flesch_reading_ease={score.ease}"
+    )
+
+
+def punctuation_sentences(text: str) -> list[str]:
+    """Return each sentence in text that contains a colon, semicolon, or dash."""
+    return [s for s in sentences_of(text) if PUNCT_MARKS.search(s)]
+
+
+def fanboys_sentences(text: str) -> list[tuple[str, str]]:
+    """Return (word, sentence) pairs for sentences opening with a FANBOYS word."""
+    found = []
+    for s in sentences_of(text):
+        m = LEADING_WORD.match(s)
+        if m and m.group(1).lower() in FANBOYS:
+            found.append((m.group(1).lower(), s))
+    return found
+
+
+def blocks_from_comments(path: Path) -> Iterator[tuple[str, str]]:
+    """Yield (label, text) pairs for each run of consecutive whole-line comments."""
+    with open(path, "rb") as f:
+        run: list = []
+        start_line = None
+        prev_line = None
+        for tok in tokenize.tokenize(f.readline):
+            if tok.type != tokenize.COMMENT:
+                continue
+            text = tok.string.lstrip("#").strip()
+            if run and prev_line == tok.start[0] - 1:
+                run.append(text)
+            else:
+                if run:
+                    yield f"line={start_line} block=comment", " ".join(run)
+                run = [text]
+                start_line = tok.start[0]
+            prev_line = tok.start[0]
+        if run:
+            yield f"line={start_line} block=comment", " ".join(run)
+
+
+def blocks_from_py(path: Path) -> Iterator[tuple[str, str]]:
+    """Yield (label, text) pairs for each docstring and comment block in a .py file."""
+    tree = ast.parse(path.read_text())
+    doc_nodes = (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.Module)
+    for node in ast.walk(tree):
+        if not isinstance(node, doc_nodes):
+            continue
+        doc = ast.get_docstring(node)
+        if not doc:
+            continue
+        name = getattr(node, "name", "module")
+        line = getattr(node, "lineno", 1)
+        yield f"line={line} block={name}", strip_inline_code(doc)
+    for label, text in blocks_from_comments(path):
+        yield label, strip_inline_code(text)
+
+
+def blocks_from_md(path: Path) -> Iterator[tuple[str, str]]:
+    """Yield (label, paragraph) pairs for each paragraph, with markup stripped."""
+    text = path.read_text()
+    # Blank out code blocks but keep their newlines, so line numbers stay accurate.
+    text = re.sub(
+        r"```.*?```", lambda m: "\n" * m.group(0).count("\n"), text, flags=re.DOTALL
+    )
+    text = strip_inline_code(text)
+    text = re.sub(r"!\[.*?\]\(.*?\)", "", text)  # images
+    text = re.sub(r"\[([^\]]*)\]\([^)]*\)", r"\1", text)  # links
+    text = re.sub(r"^#{1,6}\s*", "", text, flags=re.MULTILINE)  # headings
+    text = re.sub(r"\*\*([^*]+)\*\*", r"\1", text)  # bold
+    text = re.sub(r"\*([^*]+)\*", r"\1", text)  # italic
+    # admonition marker lines (mkdocs-style), e.g. !!! warning "title"
+    text = re.sub(r'^!!!\s+\S+(\s+".*?")?\s*$', "", text, flags=re.MULTILINE)
+
+    table_row = re.compile(r"^\s*\|.*\|\s*$")
+    para_lines: list = []
+    start_line = None
+    for i, raw_line in enumerate(text.split("\n"), start=1):
+        if table_row.match(raw_line):
+            if para_lines:
+                yield f"line={start_line} block=paragraph", "\n".join(para_lines)
+            para_lines, start_line = [], None
+            continue
+        if raw_line.strip():
+            if start_line is None:
+                start_line = i
+            para_lines.append(raw_line)
+        else:
+            if para_lines:
+                yield f"line={start_line} block=paragraph", "\n".join(para_lines)
+            para_lines, start_line = [], None
+    if para_lines:
+        yield f"line={start_line} block=paragraph", "\n".join(para_lines)
+
+
+def score_file(path: Path, top: int | None, rules: list[Rule]) -> None:
+    """Extract blocks from a file, print a summary, then each active rule's findings."""
+    if path.suffix == ".py":
+        blocks = list(blocks_from_py(path))
+    elif path.suffix == ".md":
+        blocks = list(blocks_from_md(path))
+    else:
+        typer.echo(f"Unsupported file type: {path.suffix}", err=True)
+        return
+
+    if not blocks:
+        print(f"file={path} status=no_prose_found")
+        return
+
+    summary = [f"file={path}"]
+
+    scored: list[BlockScore] = []
+    if Rule.READABILITY in rules:
+        scores = [score_block(label, text) for label, text in blocks]
+        scored = [s for s in scores if s.grade is not None]
+        trivial = sum(1 for s in scores if s.status == "trivial")
+        low_conf = sum(1 for s in scores if s.status == "low_confidence")
+        worst = max((s.grade for s in scored), default=None)
+        worst_str = f"{worst:.1f}" if worst is not None else "none"
+        summary.append(f"blocks={len(blocks)}")
+        summary.append(f"trivial={trivial}")
+        summary.append(f"low_confidence={low_conf}")
+        summary.append(f"worst_grade={worst_str}")
+
+    punct_flags: list[tuple[str, str]] = []
+    if Rule.PUNCTUATION in rules:
+        punct_flags = [
+            (label, s) for label, text in blocks for s in punctuation_sentences(text)
+        ]
+        summary.append(f"punctuation_flags={len(punct_flags)}")
+
+    fanboys_flags: list[tuple[str, str, str]] = []
+    if Rule.FANBOYS in rules:
+        fanboys_flags = [
+            (label, word, s)
+            for label, text in blocks
+            for word, s in fanboys_sentences(text)
+        ]
+        summary.append(f"fanboys_flags={len(fanboys_flags)}")
+
+    print(" ".join(summary))
+
+    if Rule.READABILITY in rules:
+        shown = scored
+        if top is not None:
+            shown = sorted(scored, key=lambda s: s.grade, reverse=True)[:top]
+        for score in shown:
+            print(format_score(score))
+
+    for label, sentence in punct_flags:
+        print(f"{label} sentence={json.dumps(sentence)}")
+
+    for label, word, sentence in fanboys_flags:
+        print(f"{label} word={word} sentence={json.dumps(sentence)}")
+
+
+def parse_rules(value: str | None) -> list[Rule]:
+    """Parse a comma-separated --rules value, defaulting to every rule."""
+    if not value:
+        return list(Rule)
+    selected: list[Rule] = []
+    for token in value.split(","):
+        token = token.strip()
+        if not token:
+            continue
+        try:
+            selected.append(Rule(token))
+        except ValueError:
+            valid = ", ".join(r.value for r in Rule)
+            typer.echo(f"Unknown rule: {token}. Valid: {valid}", err=True)
+            raise typer.Exit(1) from None
+    return selected
+
+
+def main(
+    paths: list[Path] = typer.Argument(  # noqa: B008
+        ..., help="One or more .py/.md files or directories to score."
+    ),
+    top: int | None = typer.Option(
+        None, "--top", help="Show only the N worst-scoring blocks per file."
+    ),
+    rules: str | None = typer.Option(
+        None,
+        "--rules",
+        help="Comma-separated rule ids to run (default: all). "
+        + "; ".join(f"{r.value}={d}" for r, d in RULE_DESCRIPTIONS.items()),
+    ),
+) -> None:
+    """Score .py/.md files or directories against one or more plain-English rules."""
+    selected_rules = parse_rules(rules)
+
+    files: list = []
+    for path in paths:
+        if not path.exists():
+            typer.echo(f"Path not found: {path}", err=True)
+            raise typer.Exit(1)
+        if path.is_dir():
+            found = sorted(p for p in path.rglob("*") if p.suffix in (".py", ".md"))
+            if not found:
+                typer.echo(f"No .py or .md files found under {path}", err=True)
+                raise typer.Exit(1)
+            files.extend(found)
+        else:
+            files.append(path)
+
+    for file in files:
+        score_file(file, top=top, rules=selected_rules)
+
+
+if __name__ == "__main__":
+    typer.run(main)

matchlab-0.1.0.dev1/.github/workflows/cd.yml

@@ -0,0 +1,74 @@
+name: CD
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0
+
+      - name: Setup toolchain
+        uses: ./.github/actions/setup-toolchain
+        with:
+          install-just: "false"
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload package artifacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: package-dist
+          path: ./dist
+
+      - name: Build documentation
+        run: uv run mkdocs build
+
+      - name: Upload documentation artifact
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: site/
+
+  deploy-package:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+
+    environment: pypi
+
+    steps:
+      - name: Download package artifacts
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: package-dist
+          path: ./dist
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+
+  deploy-docs:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+      contents: read
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy documentation to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0