flyleaf 0.5.0__py3-none-any.whl

flyleaf/card.py

@@ -0,0 +1,161 @@
+# Copyright 2026 Krishna Dahale
+# SPDX-License-Identifier: Apache-2.0
+"""Write model-card scaffolds. A person completes the blanks."""
+
+import re
+from pathlib import Path
+
+from flyleaf.citations import citation_payload
+from flyleaf.scan import scan_path
+
+
+def write_cards(path: Path, output: Path, force: bool = False) -> list[Path]:
+    """Write one scaffold per declared system, then one per loose component.
+
+    Existing files are left in place unless `force` is set. A scaffold is
+    written under `output`, never at a declared card path, so an unfinished
+    draft is never counted as documentation.
+    """
+    inventory = scan_path(path)
+    output.mkdir(parents=True, exist_ok=True)
+    written: list[Path] = []
+
+    for system in inventory.get("systems") or []:
+        members = [
+            component
+            for component in inventory["components"]
+            if component["system"] == system["name"]
+        ]
+        if not members:
+            continue
+        destination = output / f"{_slug(system['name'])}.md"
+        if destination.exists() and not force:
+            continue
+        destination.write_text(_render_system(system, members, inventory), encoding="utf-8")
+        written.append(destination)
+
+    for component in inventory["components"]:
+        if component["system"]:
+            continue
+        destination = output / _filename(component["id"])
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        if destination.exists() and not force:
+            continue
+        destination.write_text(_render(component, inventory), encoding="utf-8")
+        written.append(destination)
+    return written
+
+
+def _filename(component_id: str) -> Path:
+    return Path(component_id.replace(":", ".") + ".md")
+
+
+def _slug(name: str) -> str:
+    return re.sub(r"[^A-Za-z0-9._-]+", "-", name).strip("-") or "system"
+
+
+def _render(component: dict, inventory: dict) -> str:
+    evidence = "\n".join(_evidence_lines(component))
+    citation_ids = _citation_ids([component])
+    return _page(
+        identity=[f"Component: `{component['id']}`"],
+        model_section=f"Framework: {component['framework']}\n\nEvidence:\n\n{evidence}",
+        hints="\n".join(f"- {hint['text']}" for hint in component["review_hints"]),
+        sources="\n\n".join(_source(inventory, item) for item in citation_ids),
+        pack=inventory["citation_pack"]["version"],
+    )
+
+
+def _render_system(system: dict, members: list[dict], inventory: dict) -> str:
+    identity = [f"System: `{system['name']}`"]
+    if system["owner"]:
+        identity.append(f"Owner: {system['owner']}")
+    if system["card"]:
+        identity.append(f"Declared card path: `{system['card']}`")
+    identity.append(
+        "This system is declared in `.flyleaf/systems.toml`. The components below "
+        "are the evidence flyleaf found in it. One system, one card."
+    )
+
+    blocks = [f"Frameworks: {', '.join(system['frameworks'])}", "", "Components:", ""]
+    for component in members:
+        blocks.append(f"### `{component['path']}` ({component['framework']})")
+        blocks.append("")
+        blocks.extend(_evidence_lines(component))
+        blocks.append("")
+    hints: list[str] = []
+    for component in members:
+        for hint in component["review_hints"]:
+            line = f"- {hint['text']}"
+            if line not in hints:
+                hints.append(line)
+    return _page(
+        identity=identity,
+        model_section="\n".join(blocks).rstrip(),
+        hints="\n".join(hints),
+        sources="\n\n".join(_source(inventory, item) for item in _citation_ids(members)),
+        pack=inventory["citation_pack"]["version"],
+    )
+
+
+def _evidence_lines(component: dict) -> list[str]:
+    return [
+        f"- line {item['line']}: `{item['text']}` ({item['kind']})"
+        for item in component["evidence"]
+    ]
+
+
+def _citation_ids(components: list[dict]) -> list[str]:
+    citation_ids: list[str] = []
+    for component in components:
+        for citation_id in component["documentation_citation_ids"]:
+            if citation_id not in citation_ids:
+                citation_ids.append(citation_id)
+    for component in components:
+        for hint in component["review_hints"]:
+            for citation_id in hint["citation_ids"]:
+                if citation_id not in citation_ids:
+                    citation_ids.append(citation_id)
+    return citation_ids
+
+
+def _page(identity: list[str], model_section: str, hints: str, sources: str, pack: str) -> str:
+    header = "\n\n".join(identity)
+    return (
+        f"# Model card\n\n"
+        f"{header}\n\n"
+        f"Citation pack: {pack}\n\n"
+        f"flyleaf prepared this page. A person completes it. "
+        f"The scaffold does not decide the use case, the legal role, or whether a duty applies.\n\n"
+        f"## Purpose\n\n"
+        f"What this system is for:\n\n"
+        f"## Role\n\n"
+        f"Who provides the model, and who deploys the system. Read Article 3(3) and Article 3(4).\n\n"
+        f"Provider or deployer:\n\n"
+        f"## Data\n\n"
+        f"Training data, prompts, and personal data involved:\n\n"
+        f"## Model\n\n"
+        f"{model_section}\n\n"
+        f"## Limitations\n\n"
+        f"Known limits and failure modes:\n\n"
+        f"## Human oversight\n\n"
+        f"Who reviews outputs before they affect a person:\n\n"
+        f"## Use case\n\n"
+        f"Annex III category, if any. Leave this blank when none applies. "
+        f"The library name does not answer it.\n\n"
+        f"## Areas the scan asked a person to review\n\n"
+        f"{hints}\n\n"
+        f"## Sources\n\n"
+        f"{sources}\n"
+    )
+
+
+def _source(inventory: dict, citation_id: str) -> str:
+    citation = inventory["citations"].get(citation_id) or citation_payload(citation_id)
+    return (
+        f"### {citation['pinpoint']}\n\n"
+        f"{citation['instrument']} ({citation['celex']}), status {citation['status']}.\n\n"
+        f"> {citation['quote']}\n\n"
+        f"{citation['note']}\n\n"
+        f"{citation['source_url']}"
+    )

flyleaf/citations.py

@@ -0,0 +1,188 @@
+# Copyright 2026 Krishna Dahale
+# SPDX-License-Identifier: Apache-2.0
+"""Versioned citations for review findings.
+
+Edit this module when the Official Journal changes a provision the tool cites.
+Bump PACK_VERSION and add a CHANGELOG entry in the same change. Reports copy
+the version so an older run still names the text it used.
+"""
+
+from dataclasses import dataclass
+
+PACK_VERSION = "2026.07.27"
+AS_OF = "2026-07-27"
+
+_AI_ACT_URL = "https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32024R1689"
+_AMENDMENT_URL = "https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32026R1744"
+
+
+@dataclass(frozen=True)
+class Citation:
+    id: str
+    instrument: str
+    celex: str
+    pinpoint: str
+    quote: str
+    note: str
+    source_url: str
+    status: str = "current"
+
+
+CITATIONS: dict[str, Citation] = {
+    "art-3-provider": Citation(
+        id="art-3-provider",
+        instrument="Regulation (EU) 2024/1689",
+        celex="32024R1689",
+        pinpoint="Article 3(3)",
+        quote=(
+            "provider means a natural or legal person, public authority, agency or other body "
+            "that develops an AI system or a general-purpose AI model or that has an AI system "
+            "or a general-purpose AI model developed and places it on the market or puts the AI "
+            "system into service under its own name or trademark, whether for payment or free of charge"
+        ),
+        note=(
+            "Use this definition to decide whether you provide the model. "
+            "An import of a hosted API does not settle that question."
+        ),
+        source_url=_AI_ACT_URL,
+    ),
+    "art-3-deployer": Citation(
+        id="art-3-deployer",
+        instrument="Regulation (EU) 2024/1689",
+        celex="32024R1689",
+        pinpoint="Article 3(4)",
+        quote=(
+            "deployer means a natural or legal person, public authority, agency or other body "
+            "using an AI system under its authority except where the AI system is used in the "
+            "course of a personal non-professional activity"
+        ),
+        note=(
+            "Use this definition to decide whether you deploy someone else's system. "
+            "Points (3) and (4) of Article 3 were not the points amended by Regulation (EU) 2026/1744."
+        ),
+        source_url=_AI_ACT_URL,
+    ),
+    "art-6-annex-iii": Citation(
+        id="art-6-annex-iii",
+        instrument="Regulation (EU) 2024/1689",
+        celex="32024R1689",
+        pinpoint="Article 6(2) and Annex III",
+        quote=(
+            "In addition to the high-risk AI systems referred to in paragraph 1, "
+            "AI systems referred to in Annex III shall be considered to be high-risk."
+        ),
+        note=(
+            "Annex III is a list of use cases. A library name is not one of those use cases. "
+            "Fill in the purpose yourself, then read Article 6(3) for the derogation. "
+            "Regulation (EU) 2026/1744 inserted Article 6(1a) to (1c) on safety components. "
+            "It left this Article 6(2) sentence in place."
+        ),
+        source_url=_AI_ACT_URL,
+    ),
+    "art-11-annex-iv": Citation(
+        id="art-11-annex-iv",
+        instrument="Regulation (EU) 2024/1689",
+        celex="32024R1689",
+        pinpoint="Article 11(1) and Annex IV",
+        quote=(
+            "The technical documentation of a high-risk AI system shall be drawn up before that "
+            "system is placed on the market or put into service and shall be kept up to date."
+        ),
+        note=(
+            "This duty applies to high-risk systems. The scan cannot tell whether this component is one. "
+            "Regulation (EU) 2026/1744 replaced the second subparagraph of Article 11(1): "
+            "SMEs, including start-ups, and small mid-caps may supply the Annex IV elements "
+            "in a simplified form once the Commission establishes that form. "
+            "A missing or stale model card is a gap in the repository. "
+            "It is not a finding that Article 11 has been breached."
+        ),
+        source_url=_AI_ACT_URL,
+    ),
+    "art-50-interaction": Citation(
+        id="art-50-interaction",
+        instrument="Regulation (EU) 2024/1689",
+        celex="32024R1689",
+        pinpoint="Article 50(1)",
+        quote=(
+            "Providers shall ensure that AI systems intended to interact directly with natural persons "
+            "are designed and developed in such a way that the natural persons concerned are informed "
+            "that they are interacting with an AI system, unless this is obvious from the point of view "
+            "of a natural person who is reasonably well-informed, observant and circumspect, taking into "
+            "account the circumstances and the context of use."
+        ),
+        note=(
+            "Read this when people interact with generated output. "
+            "The scan does not see the interface, so it cannot tell whether the duty applies. "
+            "Regulation (EU) 2026/1744 replaced Article 50(7), which concerns codes of "
+            "practice for marking synthetic content."
+        ),
+        source_url=_AI_ACT_URL,
+    ),
+    "art-53-gpai": Citation(
+        id="art-53-gpai",
+        instrument="Regulation (EU) 2024/1689",
+        celex="32024R1689",
+        pinpoint="Article 53(1)",
+        quote=(
+            "Providers of general-purpose AI models shall: "
+            "(a) draw up and keep up to date the technical documentation of the model"
+        ),
+        note=(
+            "Article 53 binds the provider of the general-purpose model. "
+            "Calling that provider's API does not, by itself, make the caller that provider."
+        ),
+        source_url=_AI_ACT_URL,
+    ),
+    "art-113-application": Citation(
+        id="art-113-application",
+        instrument="Regulation (EU) 2026/1744",
+        celex="32026R1744",
+        pinpoint="Article 113, third paragraph, point (c), of Regulation (EU) 2024/1689, as replaced",
+        quote=(
+            "Chapter III, Sections 1, 2, and 3, with the exception of Article 6(5), shall apply from: "
+            "(i) 2 December 2027 as regards AI systems classified as high-risk pursuant to Article 6(2) "
+            "and Annex III; and (ii) 2 August 2028 as regards AI systems classified as high-risk pursuant "
+            "to Article 6(1) and Annex I"
+        ),
+        note=(
+            "Regulation (EU) 2026/1744 was published in the Official Journal on 24 July 2026 "
+            "and entered into force on 27 July 2026. It deferred these Chapter III dates. "
+            "The citation tells you when to read the high-risk duties. It does not classify the system."
+        ),
+        source_url=_AMENDMENT_URL,
+    ),
+}
+
+DOCUMENTATION_CITATION_IDS = ("art-11-annex-iv", "art-113-application")
+
+CHANGELOG: tuple[dict[str, str], ...] = (
+    {
+        "version": "2026.07.27",
+        "summary": (
+            "Initial pack. Regulation (EU) 2024/1689 as amended by Regulation (EU) 2026/1744, "
+            "in force 27 July 2026. Records the deferred Chapter III dates in Article 113."
+        ),
+    },
+)
+
+
+def pack_meta() -> dict[str, str]:
+    return {"version": PACK_VERSION, "as_of": AS_OF}
+
+
+def citation_payload(citation_id: str) -> dict[str, str]:
+    citation = CITATIONS[citation_id]
+    return {
+        "id": citation.id,
+        "instrument": citation.instrument,
+        "celex": citation.celex,
+        "pinpoint": citation.pinpoint,
+        "quote": citation.quote,
+        "note": citation.note,
+        "source_url": citation.source_url,
+        "status": citation.status,
+    }
+
+
+def payloads_for(citation_ids: set[str]) -> dict[str, dict[str, str]]:
+    return {citation_id: citation_payload(citation_id) for citation_id in sorted(citation_ids)}

flyleaf/cli.py

@@ -0,0 +1,236 @@
+# Copyright 2026 Krishna Dahale
+# SPDX-License-Identifier: Apache-2.0
+"""Command line interface."""
+
+import json
+from pathlib import Path
+
+import typer
+
+from flyleaf import __version__
+from flyleaf.baseline import BASELINE_FILE, BaselineError, write_baseline
+from flyleaf.brief import GitError, build_brief, highest_severity
+from flyleaf.card import write_cards
+from flyleaf.report import render, render_citations
+from flyleaf.scan import scan_path
+from flyleaf.severity import ORDER, at_least
+
+app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=True,
+    help=(
+        "Inventory AI components in a repository and list areas to review, with citations. "
+        "Not a legal risk classifier."
+    ),
+)
+
+
+def main() -> None:
+    app()
+
+
+@app.callback(invoke_without_command=True)
+def _root(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        help="Print the version and exit.",
+        is_eager=True,
+    ),
+) -> None:
+    if version:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+@app.command()
+def scan(
+    path: Path = typer.Argument(Path("."), exists=False, help="Repository, directory, or file to scan."),
+    output_format: str = typer.Option("json", "--format", "-f", help="json or markdown."),
+    output: Path | None = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Write the report to this file. Prints to stdout when omitted.",
+    ),
+) -> None:
+    """Scan a tree and print an AI component inventory.
+
+    The command exits 0 when the scan finishes, including when it finds AI
+    libraries. It does not fail a build for using an AI library.
+    """
+    _check_format(output_format, {"json", "markdown"})
+    try:
+        document = scan_path(path)
+    except FileNotFoundError:
+        typer.echo(f"Path not found: {path}", err=True)
+        raise typer.Exit(code=2) from None
+    _emit(render(document, output_format), output)
+
+
+@app.command()
+def brief(
+    base: str | None = typer.Argument(None, help="Git ref to compare from. Omit with --baseline."),
+    head: str | None = typer.Argument(None, help="Git ref to compare to. Defaults to the working tree."),
+    path: Path = typer.Option(Path("."), "--path", "-p", help="Repository to read."),
+    use_baseline: bool = typer.Option(
+        False,
+        "--baseline",
+        help=f"Compare against the approved state in {BASELINE_FILE.as_posix()} instead of a git ref.",
+    ),
+    fail_on: str = typer.Option(
+        "none",
+        "--fail-on",
+        help="Exit 1 when an active finding reaches this severity: none, low, medium, or high.",
+    ),
+    blame: bool = typer.Option(
+        True,
+        "--blame/--no-blame",
+        help="Name who last changed the evidence, read from local git blame.",
+    ),
+    output_format: str = typer.Option("json", "--format", "-f", help="json, markdown, or sarif."),
+    output: Path | None = typer.Option(None, "--output", "-o", help="Write the brief to this file."),
+) -> None:
+    """Compare two states and list documentation changes with citations.
+
+    Status values are missing and needs_review. Severity ranks engineering
+    attention, not legal risk. The brief does not declare a legal breach.
+    """
+    _check_format(output_format, {"json", "markdown", "sarif"})
+    if fail_on not in {"none", *ORDER}:
+        typer.echo("Fail-on must be none, low, medium, or high.", err=True)
+        raise typer.Exit(code=2)
+    if base is None and not use_baseline:
+        typer.echo("Give a base ref, or pass --baseline.", err=True)
+        raise typer.Exit(code=2)
+
+    try:
+        document = build_brief(path, base, head, use_baseline=use_baseline, blame=blame)
+    except FileNotFoundError:
+        typer.echo(f"Path not found: {path}", err=True)
+        raise typer.Exit(code=2) from None
+    except (GitError, BaselineError) as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=2) from None
+
+    _emit(render(document, output_format), output)
+    for warning in document["warnings"]:
+        typer.echo(warning, err=True)
+
+    if fail_on == "none":
+        return
+    worst = highest_severity(document)
+    if worst is not None and at_least(worst, fail_on):
+        typer.echo(
+            f"Highest severity is {worst}, at or above the --fail-on threshold of {fail_on}.",
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+
+@app.command(name="render")
+def render_command(
+    document: Path = typer.Argument(..., help="A brief or inventory saved with --format json."),
+    output_format: str = typer.Option("markdown", "--format", "-f", help="json, markdown, or sarif."),
+    output: Path | None = typer.Option(None, "--output", "-o", help="Write the report to this file."),
+) -> None:
+    """Re-render a saved report in another format.
+
+    No scan and no git, so one scan can produce every format a pipeline wants,
+    and an archived report can be read back without the repository.
+    """
+    _check_format(output_format, {"json", "markdown", "sarif"})
+    try:
+        loaded = json.loads(document.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        typer.echo(f"Could not read {document}: {exc}", err=True)
+        raise typer.Exit(code=2) from None
+    if not isinstance(loaded, dict) or loaded.get("kind") not in {"brief", "inventory"}:
+        typer.echo(f"{document} is not a flyleaf brief or inventory.", err=True)
+        raise typer.Exit(code=2)
+    try:
+        text = render(loaded, output_format)
+    except (ValueError, KeyError) as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=2) from None
+    _emit(text, output)
+
+
+@app.command(name="baseline")
+def baseline_command(
+    path: Path = typer.Option(Path("."), "--path", "-p", help="Repository to read."),
+    approved_by: str | None = typer.Option(
+        None, "--approved-by", help="Who signed off on this state."
+    ),
+    rev: str | None = typer.Option(None, "--rev", help="Revision this snapshot represents."),
+) -> None:
+    """Record the current inventory as the approved state.
+
+    Later runs of 'flyleaf brief --baseline' report what changed since this sign-off.
+    """
+    try:
+        destination = write_baseline(path, rev, approved_by)
+    except FileNotFoundError:
+        typer.echo(f"Path not found: {path}", err=True)
+        raise typer.Exit(code=2) from None
+    typer.echo(destination)
+
+
+@app.command()
+def card(
+    path: Path = typer.Argument(Path("."), exists=False, help="Repository, directory, or file to scan."),
+    output: Path = typer.Option(
+        Path("flyleaf-cards"),
+        "--output",
+        "-o",
+        help="Directory for the scaffolds. Existing files are kept unless --force is set.",
+    ),
+    force: bool = typer.Option(False, "--force", help="Overwrite scaffolds that already exist."),
+) -> None:
+    """Write a model-card scaffold per declared system, then per loose component.
+
+    Scaffolds land under --output, never at a declared card path, so an
+    unfinished draft never counts as documentation.
+    """
+    try:
+        written = write_cards(path, output, force=force)
+    except FileNotFoundError:
+        typer.echo(f"Path not found: {path}", err=True)
+        raise typer.Exit(code=2) from None
+    if not written:
+        typer.echo(f"No new scaffolds written under {output}.")
+        return
+    for destination in written:
+        typer.echo(destination)
+
+
+@app.command(name="cite")
+def cite_command(
+    citation_id: str | None = typer.Argument(None, help="Citation id. Omit to list the pack."),
+    changelog: bool = typer.Option(False, "--changelog", help="Print the pack changelog."),
+    output_format: str = typer.Option("markdown", "--format", "-f", help="markdown or json."),
+    output: Path | None = typer.Option(None, "--output", "-o", help="Write the citation text to this file."),
+) -> None:
+    """Print the citation pack, or one entry, with the source URL and pack version."""
+    _check_format(output_format, {"json", "markdown"})
+    try:
+        text = render_citations(citation_id, changelog, output_format)
+    except KeyError:
+        typer.echo(f"Unknown citation: {citation_id}", err=True)
+        raise typer.Exit(code=2) from None
+    _emit(text, output)
+
+
+def _check_format(output_format: str, allowed: set[str]) -> None:
+    if output_format not in allowed:
+        typer.echo(f"Format must be {' or '.join(sorted(allowed))}.", err=True)
+        raise typer.Exit(code=2)
+
+
+def _emit(text: str, output: Path | None) -> None:
+    if output is None:
+        typer.echo(text, nl=False)
+        return
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(text, encoding="utf-8")