#!/usr/bin/env python

"""Generate EXAMPLES.md and examples/registry.py from example file frontmatter.

Usage:

uv run python scripts/generate_examples_md.py # Generate files

uv run python scripts/generate_examples_md.py --check # Check if files are up to date

"""

from __future__ import annotations

import re

import sys

import argparse

from typing import Any

from pathlib import Path

import frontmatter # type: ignore[import-untyped]

ROOT = Path(__file__).parent.parent

EXAMPLES_DIR = ROOT / "examples"

OUTPUT_FILE = ROOT / "EXAMPLES.md"

OUTPUT_REGISTRY_FILE = EXAMPLES_DIR / "registry.py"

LLMS_FILE = ROOT / "llms.txt"

REQUIRED_FIELDS = ["title", "slug", "use_case", "workflow", "tags", "prerequisites", "run", "test"]

EXCLUDED_FILES = {"_harness.py", "example_types.py", "registry.py", "__init__.py"}

def parse_example(path: Path) -> dict[str, Any]:

"""Parse frontmatter from a Python file's docstring."""

content = path.read_text()

match = re.search(r'^(?:#!.*\n)?(?:\s*\n)*"""([\s\S]*?)"""', content)

if not match:

raise ValueError(f"{path}: missing docstring")

docstring = match.group(1).strip()

if not docstring.startswith("---"):

raise ValueError(f"{path}: docstring must start with frontmatter (---)")

try:

post = frontmatter.loads(docstring)

return dict(post.metadata)

except Exception as e:

raise ValueError(f"{path}: invalid frontmatter: {e}") from e

def validate_example(metadata: dict[str, Any], file_name: str, seen_slugs: set[str]) -> None:

"""Validate all example metadata in one pass."""

path = f"examples/{file_name}"

missing = [f for f in REQUIRED_FIELDS if f not in metadata]

if missing:

raise ValueError(f"{path}: missing fields: {', '.join(missing)}")

for field in ("workflow", "tags", "prerequisites"):

if not isinstance(metadata[field], list) or not metadata[field]:

raise ValueError(f"{path}: '{field}' must be a non-empty list")

slug = metadata["slug"]

expected_slug = file_name.replace(".py", "").replace("_", "-")

if slug != expected_slug:

raise ValueError(f"{path}: slug '{slug}' must match '{expected_slug}'")

if slug in seen_slugs:

raise ValueError(f"{path}: duplicate slug")

seen_slugs.add(slug)

module_name = file_name.replace(".py", "")

if f"examples.{module_name}" not in metadata["run"]:

raise ValueError(f"{path}: run command must reference 'examples.{module_name}'")

def ensure_llms_references(examples: list[dict[str, Any]]) -> None:

"""Ensure llms.txt references at least one example file."""

if not LLMS_FILE.exists():

raise ValueError(f"Missing llms file: {LLMS_FILE.relative_to(ROOT)}")

llms_text = LLMS_FILE.read_text()

referenced = set(re.findall(r"examples/([a-z0-9_]+\.py)", llms_text))

if not referenced:

raise ValueError(f"{LLMS_FILE.relative_to(ROOT)}: expected at least one reference to examples/*.py")

generated = {e["file_name"] for e in examples}

for file_name in referenced:

if file_name not in generated:

raise ValueError(f"{LLMS_FILE.relative_to(ROOT)}: references unknown example file 'examples/{file_name}'")

def normalize_env_var(prerequisite: str) -> str | None:

"""Extract environment variable name from prerequisite string."""

match = re.match(r"^[A-Z0-9_]+", prerequisite)

return match.group(0) if match else None

def markdown_for_example(example: dict[str, Any]) -> str:

"""Generate markdown section for a single example."""

lines = [

f'<a id="{example["slug"]}"></a>',

f"## {example['title']}",

"",

f"**Use case:** {example['use_case']}",

"",

f"**Tags:** {', '.join(f'`{tag}`' for tag in example['tags'])}",

"",

"### Workflow",

*[f"- {step}" for step in example["workflow"]],

"",

"### Prerequisites",

*[f"- `{item}`" for item in example["prerequisites"]],

"",

"### Run",

"```sh",

example["run"],

"```",

"",

"### Test",

"```sh",

example["test"],

"```",

"",

f"**Source:** [`examples/{example['file_name']}`](./examples/{example['file_name']})",

"",

]

return "\n".join(lines)

def generate_markdown(examples: list[dict[str, Any]]) -> str:

"""Generate the full EXAMPLES.md content."""

toc = "\n".join(f"- [{e['title']}](#{e['slug']})" for e in examples)

sections = "\n".join(markdown_for_example(e) for e in examples)

return "\n".join(

[

"# Examples",

"",

"> This file is auto-generated from metadata in `examples/*.py`.",

"> Do not edit this file manually. Run `uv run python scripts/generate_examples_md.py` instead.",

"",

"Runnable examples live in [`examples/`](./examples).",

"",

"## Table of Contents",

"",

toc,

"",

sections.rstrip(),

"",

]

)

def generate_registry(examples: list[dict[str, Any]]) -> str:

"""Generate the registry.py content."""

imports: list[tuple[str, str]] = [("example_types", "ExampleResult")]

for example in examples:

module = example["file_name"].replace(".py", "")

runner = f"run_{module}_example"

imports.append((module, runner))

imports.sort(key=lambda x: (len(x[0]), x[0]))

import_lines = [f"from .{mod} import {name}" for mod, name in imports]

entries: list[str] = []

for example in examples:

module = example["file_name"].replace(".py", "")

runner = f"run_{module}_example"

env_vars = [normalize_env_var(p) for p in example["prerequisites"]]

env_list = ", ".join(f'"{e}"' for e in env_vars if e)

title = example["title"].replace('"', '\\"')

entries.append(f''' {{

"slug": "{example["slug"]}",

"title": "{title}",

"file_name": "{example["file_name"]}",

"required_env": [{env_list}],

"run": {runner},

}},''')

return f'''"""

This file is auto-generated by scripts/generate_examples_md.py.

Do not edit manually.

"""

from __future__ import annotations

from typing import Any, Callable, cast

{chr(10).join(import_lines)}

ExampleRegistryEntry = dict[str, Any]

example_registry: list[ExampleRegistryEntry] = [

{chr(10).join(entries)}

]

def get_example_runner(slug: str) -> Callable[[], ExampleResult] | None:

"""Get the runner function for an example by slug."""

for entry in example_registry:

if entry["slug"] == slug:

return cast(Callable[[], ExampleResult], entry["run"])

return None

'''

def main() -> int:

"""Main entry point."""

parser = argparse.ArgumentParser(description="Generate EXAMPLES.md and registry.py")

parser.add_argument("--check", action="store_true", help="Check if files are up to date")

args = parser.parse_args()

seen_slugs: set[str] = set()

examples: list[dict[str, Any]] = []

for path in sorted(EXAMPLES_DIR.glob("*.py")):

if path.name in EXCLUDED_FILES or path.name.startswith("_"):

continue

try:

metadata = parse_example(path)

validate_example(metadata, path.name, seen_slugs)

examples.append({**metadata, "file_name": path.name})

except ValueError as e:

print(f"Error: {e}", file=sys.stderr)

return 1

examples.sort(key=lambda e: e["title"])

try:

ensure_llms_references(examples)

except ValueError as e:

print(f"Error: {e}", file=sys.stderr)

return 1

markdown = generate_markdown(examples)

registry_source = generate_registry(examples)

if args.check:

errors: list[str] = []

if not OUTPUT_FILE.exists():

errors.append(f"{OUTPUT_FILE.relative_to(ROOT)} does not exist")

elif OUTPUT_FILE.read_text() != markdown:

errors.append(f"{OUTPUT_FILE.relative_to(ROOT)} is out of date")

if not OUTPUT_REGISTRY_FILE.exists():

errors.append(f"{OUTPUT_REGISTRY_FILE.relative_to(ROOT)} does not exist")

elif OUTPUT_REGISTRY_FILE.read_text() != registry_source:

errors.append(f"{OUTPUT_REGISTRY_FILE.relative_to(ROOT)} is out of date")

if errors:

for err in errors:

print(f"Error: {err}", file=sys.stderr)

print("\nRun `uv run python scripts/generate_examples_md.py` to regenerate.", file=sys.stderr)

return 1

print("All generated files are up to date.")

return 0

OUTPUT_FILE.write_text(markdown)

OUTPUT_REGISTRY_FILE.write_text(registry_source)

print(f"Wrote {OUTPUT_FILE.relative_to(ROOT)} from {len(examples)} example(s)")

print(f"Wrote {OUTPUT_REGISTRY_FILE.relative_to(ROOT)} from {len(examples)} example(s)")

return 0

if __name__ == "__main__":

sys.exit(main())