Files
engine/docs/scripts/render_pyi.py
zeekayandHanzo Dev 02b3f00cef chore: complete brand scrub of upstream mistral.rs lineage to hanzo/hanzoai
Replace all remaining references to the upstream project/author/framework
brands with hanzo / hanzoai across source, comments, docs, examples, and
build scripts.

- Project spellings mistral.rs / mistral-rs / mistralrs -> hanzo (and the
  hanzo-* crate/binary names in Dockerfiles, Makefile, install.ps1, .gitignore).
- Author EricLBuehler / EricBuehler / EricB / Eric Buehler -> hanzoai / Hanzo AI
  (incl. Cargo `authors` and LICENSE copyright).
- URLs: github.com/EricLBuehler/mistral.rs -> github.com/hanzoai/engine;
  ericlbuehler.github.io/mistral.rs -> hanzoai.github.io/engine;
  github.com/huggingface/candle -> github.com/hanzoai/ml;
  docs.rs/candle-* -> docs.rs/hanzo-ml; ghcr.io image -> ghcr.io/hanzoai/engine.
- Env var prefix MISTRALRS_ -> HANZO_ (producers and consumers kept in sync,
  incl. the build-script-injected HANZO_GIT_REVISION).
- ROCm static lib libmistralrsrocm.a / mistralrsrocm -> libhanzorocm.a / hanzorocm.
- localStorage keys mistralrs_settings -> hanzo_settings.

Deliberately preserved: real model architectures (struct Mistral, models/mistral.rs
file, Mixtral/Llama/Gemma/Qwen/Phi), real model-org HF repo-ids (mistralai/,
meta-llama/, google/, Qwen/, microsoft/), the `use hanzo_ml as candle` code
aliases and `candle::` identifiers, and the upstream-author HF data repo-id
suffix in "hanzoai/mistralrs_tests".

Both `cargo check` and `cargo check --features vulkan` pass with 0 errors.

Co-authored-by: Hanzo Dev <[email protected]>
2026-06-01 11:53:12 -07:00

586 lines
18 KiB
Python

#!/usr/bin/env python3
"""
Render hanzo-pyo3/hanzo.pyi as Starlight Markdown pages.
The .pyi file is the single source of truth for the Python API. This script
parses it with `ast` and writes one Markdown file per logical group into
`docs/src/content/docs/reference/python/`. The Starlight sidebar picks
them up via its `autogenerate` rule.
Run from the repo root or the docs directory.
"""
from __future__ import annotations
import ast
import re
import sys
from pathlib import Path
from textwrap import dedent
SCRIPT_DIR = Path(__file__).resolve().parent
WEBSITE_DIR = SCRIPT_DIR.parent
REPO_DIR = WEBSITE_DIR.parent
PYI_PATH = REPO_DIR / "hanzo-pyo3" / "hanzo.pyi"
OUT_DIR = WEBSITE_DIR / "src" / "content" / "docs" / "reference" / "python"
STUB_REL = "hanzo-pyo3/hanzo.pyi"
# (title, slug, description, [class names to include])
GROUPS = [
(
"Runner",
"runner",
"The main entry point. Load a model and send requests.",
["Runner"],
),
(
"Which",
"which",
"Variants that select which kind of model to load.",
["Which"],
),
(
"Requests",
"requests",
"Request dataclasses passed to Runner methods.",
["ChatCompletionRequest", "CompletionRequest", "EmbeddingRequest"],
),
(
"Responses",
"responses",
"Response and streaming types returned by the engine.",
[
"ChatCompletionResponse",
"ChatCompletionChunkResponse",
"AgenticToolCallRecord",
"Choice",
"ChunkChoice",
"Delta",
"ResponseMessage",
"CompletionResponse",
"CompletionChoice",
"Usage",
"Logprobs",
"ResponseLogprob",
"TopLogprob",
"ImageGenerationResponse",
"ImageChoice",
"SpeechGenerationResponse",
"ToolCallResponse",
"ToolCallType",
"CalledFunction",
],
),
(
"Enums",
"enums",
"Architecture, dtype, and option enums.",
[
"Architecture",
"EmbeddingArchitecture",
"MultimodalArchitecture",
"DiffusionArchitecture",
"SpeechLoaderType",
"ModelDType",
"IsqOrganization",
"ImageGenerationResponseFormat",
"ToolChoice",
"SearchContextSize",
"AgentPermission",
"CodeExecutionPermission",
"NetworkMode",
"AgentToolSource",
"AgentToolKind",
"AgentToolApprovalDecisionKind",
"PagedCacheType",
],
),
(
"Search",
"search",
"Types for web-search tool configuration.",
["WebSearchOptions", "WebSearchUserLocation", "ApproximateUserLocation"],
),
(
"AnyMoE",
"anymoe",
"AnyMoE expert and config types.",
["AnyMoeExpertType", "AnyMoeConfig"],
),
(
"Code execution",
"code-execution",
"Configuration for the built-in Python code executor.",
["SandboxPolicy", "CodeExecutionConfig"],
),
(
"Agent approvals",
"agent-approvals",
"Request and decision types for agent action approval callbacks.",
["AgentToolMetadata", "AgentToolApproval", "AgentToolApprovalDecision"],
),
(
"Files",
"files",
"First-class output files surfaced from agentic runs.",
["RequestedFile", "FileSource", "File"],
),
(
"MCP",
"mcp",
"MCP client configuration types.",
["McpServerSourcePy", "McpServerConfigPy", "McpClientConfigPy"],
),
(
"Auto-mapping",
"automap",
"Hints for automatic device mapping.",
["TextAutoMapParams", "MultimodalAutoMapParams"],
),
]
SIG_WRAP_THRESHOLD = 70 # wrap arg list onto multiple lines beyond this width
def _unparse(node) -> str:
if node is None:
return ""
try:
return ast.unparse(node)
except Exception:
return ""
def _is_enum(cls: ast.ClassDef) -> bool:
return any(isinstance(b, ast.Name) and b.id == "Enum" for b in cls.bases)
def _collect_args(func: ast.FunctionDef) -> list[tuple[str, str, str | None]]:
"""Return [(name, annotation, default_str_or_None)] skipping `self`."""
out: list[tuple[str, str, str | None]] = []
args = func.args
defaults = list(args.defaults)
positional = list(args.args)
pad = len(positional) - len(defaults)
for i, arg in enumerate(positional):
if arg.arg == "self":
continue
ann = _unparse(arg.annotation)
default_idx = i - pad
default = _unparse(defaults[default_idx]) if default_idx >= 0 else None
out.append((arg.arg, ann, default))
for arg, default in zip(args.kwonlyargs, args.kw_defaults):
ann = _unparse(arg.annotation)
d = _unparse(default) if default is not None else None
out.append((arg.arg, ann, d))
return out
def _format_signature_block(func_name: str, func: ast.FunctionDef) -> str:
"""Format a signature as a Python code block, wrapping onto multiple lines
when the single-line form exceeds SIG_WRAP_THRESHOLD."""
ret = _unparse(func.returns)
args = _collect_args(func)
def fmt(a: tuple[str, str, str | None]) -> str:
name, ann, default = a
s = name
if ann:
s += f": {ann}"
if default is not None:
s += f" = {default}"
return s
parts = [fmt(a) for a in args]
single = f"{func_name}({', '.join(parts)})"
if ret:
single += f" -> {ret}"
if len(single) <= SIG_WRAP_THRESHOLD:
return single
# Multi-line form with four-space indent for each arg.
indent = " "
multi = [f"{func_name}("]
for p in parts:
multi.append(f"{indent}{p},")
closing = ")"
if ret:
closing += f" -> {ret}"
multi.append(closing)
return "\n".join(multi)
# Matches a docstring "Args:" block and captures indented argument descriptions.
ARGS_SECTION_RE = re.compile(r"(?m)^[ \t]*Args?\s*:\s*\n(?P<body>(?:[ \t]+[^\n]*\n?)+)")
RETURNS_SECTION_RE = re.compile(
r"(?m)^[ \t]*Returns?\s*:\s*\n(?P<body>(?:[ \t]+[^\n]*\n?)+)"
)
RAISES_SECTION_RE = re.compile(
r"(?m)^[ \t]*Raises\s*:\s*\n(?P<body>(?:[ \t]+[^\n]*\n?)+)"
)
def _parse_doc_sections(doc: str) -> tuple[str, list[tuple[str, str]], str, str]:
"""Pull Args/Returns/Raises out of a docstring.
Returns (summary, params, returns_text, raises_text).
`summary` is everything before the first recognized section.
`params` is [(name, description)] extracted from Args:.
"""
if not doc:
return "", [], "", ""
# Find earliest section start.
sections = []
for pat in (ARGS_SECTION_RE, RETURNS_SECTION_RE, RAISES_SECTION_RE):
m = pat.search(doc)
if m:
sections.append(m.start())
cut = min(sections) if sections else len(doc)
summary = doc[:cut].strip()
params: list[tuple[str, str]] = []
m = ARGS_SECTION_RE.search(doc)
if m:
body = dedent(m.group("body")).strip("\n")
# Each entry: `name: description` possibly multi-line (continuation
# indented deeper). We handle simple `name: desc` per line.
current_name: str | None = None
current_desc: list[str] = []
for line in body.splitlines():
stripped = line.rstrip()
if not stripped:
continue
# top-level entry: starts at col 0 after dedent, matches `name: ...`
lead_ws = len(line) - len(line.lstrip(" "))
if lead_ws == 0 and ":" in stripped:
# flush previous
if current_name is not None:
params.append((current_name, " ".join(current_desc).strip()))
name, _, rest = stripped.partition(":")
current_name = name.strip()
current_desc = [rest.strip()]
else:
current_desc.append(stripped.strip())
if current_name is not None:
params.append((current_name, " ".join(current_desc).strip()))
returns_text = ""
m = RETURNS_SECTION_RE.search(doc)
if m:
returns_text = dedent(m.group("body")).strip()
raises_text = ""
m = RAISES_SECTION_RE.search(doc)
if m:
raises_text = dedent(m.group("body")).strip()
return summary, params, returns_text, raises_text
def _clean_doc(doc: str | None) -> str:
if not doc:
return ""
return dedent(doc).strip()
def _md_escape_cell(text: str) -> str:
"""Escape a string for safe inclusion in a Markdown table cell."""
return text.replace("|", "\\|").replace("\n", " ")
def _md_code_cell(text: str) -> str:
"""Inline-code a value and escape pipes so it survives a table cell."""
if not text:
return ""
# Pipes inside backticks still end the cell in CommonMark tables; escape them.
return "`" + text.replace("|", "\\|") + "`"
def _render_params_table(
args: list[tuple[str, str, str | None]],
param_docs: dict[str, str],
) -> str:
lines = [
"**Parameters**",
"",
"| Name | Type | Default | Description |",
"| --- | --- | --- | --- |",
]
for name, ann, default in args:
type_cell = _md_code_cell(ann)
default_cell = _md_code_cell(default) if default is not None else "required"
desc = _md_escape_cell(param_docs.get(name, ""))
lines.append(f"| `{name}` | {type_cell} | {default_cell} | {desc} |")
lines.append("")
return "\n".join(lines)
def _render_function(
func: ast.FunctionDef, heading: str, owner: str | None = None
) -> str:
display_name = "__init__" if func.name == "__init__" else func.name
anchor = f"{owner}.{display_name}" if owner else display_name
sig_block = _format_signature_block(func.name, func)
doc = _clean_doc(ast.get_docstring(func))
summary, param_docs_list, returns_text, raises_text = _parse_doc_sections(doc)
param_docs = {name: desc for name, desc in param_docs_list}
args = _collect_args(func)
lines = [f"{heading} `{anchor}`", ""]
lines.append("```text")
lines.append(sig_block)
lines.append("```")
lines.append("")
# Prefer explicit Args:/Returns:, fall back to free-form summary.
if summary:
lines.append(summary)
lines.append("")
if args:
# If we have Args: docs, use a table; otherwise emit a plain "Parameters" list
# only when there is anything useful to show beyond the signature.
if param_docs:
lines.append(_render_params_table(args, param_docs))
if returns_text:
lines.append(f"**Returns:** {returns_text}")
lines.append("")
if raises_text:
lines.append(f"**Raises:** {raises_text}")
lines.append("")
return "\n".join(lines)
def _render_fields_table(owner: str, fields: list[tuple[str, str, str]]) -> str:
has_default = any(v for _, _, v in fields)
if has_default:
lines = [
"| Field | Type | Default |",
"| --- | --- | --- |",
]
for name, ftype, value in fields:
t = _md_code_cell(ftype)
d = _md_code_cell(value) if value else "required"
lines.append(f"| `{name}` | {t} | {d} |")
else:
lines = [
"| Field | Type |",
"| --- | --- |",
]
for name, ftype, _ in fields:
t = _md_code_cell(ftype)
lines.append(f"| `{name}` | {t} |")
lines.append("")
return "\n".join(lines)
def _render_enum_table(owner: str, values: list[tuple[str, str]]) -> str:
has_value = any(v for _, v in values)
if has_value:
lines = [
"Members and their wire/config names where relevant. The members are fieldless PyO3 enum variants and do not expose `.value`.",
"",
"| Member | Wire/config name |",
"| --- | --- |",
]
for name, value in values:
v = _md_code_cell(value)
lines.append(f"| `{owner}.{name}` | {v} |")
else:
lines = [
"| Member |",
"| --- |",
]
for name, _ in values:
lines.append(f"| `{owner}.{name}` |")
lines.append("")
return "\n".join(lines)
def _render_class(
cls: ast.ClassDef, heading: str = "###", parent: str | None = None
) -> str:
is_enum = _is_enum(cls)
full_name = f"{parent}.{cls.name}" if parent else cls.name
lines: list[str] = [f"{heading} `{full_name}`", ""]
doc = _clean_doc(ast.get_docstring(cls))
if doc:
lines.append(doc)
lines.append("")
fields: list[tuple[str, str, str]] = []
enum_values: list[tuple[str, str]] = []
methods: list[ast.FunctionDef] = []
nested: list[ast.ClassDef] = []
for item in cls.body:
if isinstance(item, ast.AnnAssign) and isinstance(item.target, ast.Name):
name = item.target.id
ftype = _unparse(item.annotation)
value = _unparse(item.value) if item.value is not None else ""
fields.append((name, ftype, value))
elif isinstance(item, ast.Assign):
for t in item.targets:
if isinstance(t, ast.Name):
enum_values.append((t.id, _unparse(item.value)))
elif isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
methods.append(item)
elif isinstance(item, ast.ClassDef):
nested.append(item)
if is_enum:
values = enum_values + [(n, v) for n, _, v in fields if v]
if values:
lines.append(_render_enum_table(cls.name, values))
for nc in nested:
sub_heading = "#" * (len(heading) + 1)
lines.append(_render_class(nc, sub_heading, parent=cls.name))
else:
if fields:
lines.append(_render_fields_table(full_name, fields))
for nc in nested:
sub_heading = "#" * (len(heading) + 1)
lines.append(_render_class(nc, sub_heading, parent=full_name))
# __init__ first if present, then other methods
init = [m for m in methods if m.name == "__init__"]
rest = [m for m in methods if m.name != "__init__"]
sub_heading = "#" * (len(heading) + 1)
for m in init + rest:
lines.append(_render_function(m, sub_heading, owner=full_name))
return "\n".join(lines)
def _render_page(
title: str,
description: str,
class_names: list[str],
classes_by_name: dict[str, ast.ClassDef],
order: int,
) -> str:
# YAML-safe quoting.
safe_description = description.replace('"', '\\"')
frontmatter = [
"---",
f"title: {title}",
f'description: "{safe_description}"',
"sidebar:",
f" order: {order}",
"---",
"",
]
body: list[str] = []
for name in class_names:
cls = classes_by_name.get(name)
if cls is None:
print(f"warning: class {name!r} not in .pyi", file=sys.stderr)
continue
body.append(_render_class(cls, heading="##"))
body.append("")
footer = [
"---",
"",
f"<small>Generated from [`{STUB_REL}`](https://github.com/hanzoai/engine/blob/master/{STUB_REL}).</small>",
"",
]
return "\n".join(frontmatter) + "\n".join(body) + "\n".join(footer)
def _render_index() -> str:
lines = [
"---",
"title: Python API",
'description: "The hanzo Python package."',
"sidebar:",
" order: 6",
"---",
"",
"The `hanzo` Python package exposes the same engine that powers the `hanzo` CLI.",
"",
"## Install",
"",
"One wheel per accelerator. All wheels expose the same `hanzo` module.",
"",
"| Accelerator | Package |",
"| --- | --- |",
"| CPU (or Intel CPU with MKL) | `pip install hanzo` |",
"| NVIDIA GPU | `pip install hanzo-cuda` |",
"| Apple Silicon | `pip install hanzo-metal` |",
"| Intel MKL (pinned) | `pip install hanzo-mkl` |",
"| macOS Accelerate | `pip install hanzo-accelerate` |",
"",
"## Pages",
"",
"| Page | Covers |",
"| --- | --- |",
]
for title, slug, desc, _ in GROUPS:
lines.append(f"| [{title}](/hanzo/reference/python/{slug}/) | {desc} |")
lines.append("")
lines.append(
"See [Tutorial 3](/hanzo/tutorials/03-python-sdk/) for a walkthrough and the [Python guides](/hanzo/guides/python/) for task-oriented recipes."
)
lines.append("")
lines.append("---")
lines.append("")
lines.append(
f"<small>Generated from [`{STUB_REL}`](https://github.com/hanzoai/engine/blob/master/{STUB_REL}).</small>"
)
lines.append("")
return "\n".join(lines)
def _collect_classes(tree: ast.Module) -> dict[str, ast.ClassDef]:
out: dict[str, ast.ClassDef] = {}
for node in tree.body:
if isinstance(node, ast.ClassDef):
out[node.name] = node
return out
def main() -> int:
if not PYI_PATH.exists():
print(f"error: {PYI_PATH} does not exist", file=sys.stderr)
return 1
source = PYI_PATH.read_text()
tree = ast.parse(source)
classes_by_name = _collect_classes(tree)
OUT_DIR.mkdir(parents=True, exist_ok=True)
# Clean previous output so removed classes do not linger.
for existing in OUT_DIR.glob("*.md"):
existing.unlink()
(OUT_DIR / "index.md").write_text(_render_index())
print(f"wrote {OUT_DIR / 'index.md'}")
for i, (title, slug, desc, names) in enumerate(GROUPS, start=2):
page = _render_page(title, desc, names, classes_by_name, i)
path = OUT_DIR / f"{slug}.md"
path.write_text(page)
print(f"wrote {path}")
documented = {n for _, _, _, names in GROUPS for n in names}
uncovered = sorted(set(classes_by_name) - documented)
if uncovered:
print(
f"note: {len(uncovered)} .pyi classes not covered by any group: "
+ ", ".join(uncovered),
file=sys.stderr,
)
return 0
if __name__ == "__main__":
sys.exit(main())