From 3a250e3adc094b37542a25e91a00a886de2b036a Mon Sep 17 00:00:00 2001
From: Maxfield Allison <42394355+maxfield-allison@users.noreply.github.com>
Date: Wed, 23 Sep 2026 21:51:58 -0500
Subject: [PATCH] docs: add a Python API reference generated from docstrings
 (#283)

The Python API docstrings now have browsable pages under docs/reference/, rendered with mkdocstrings. Handler options keep signatures and multi-line Returns sections readable and put the constructor on the class page without changing the source. The Docs workflow also runs on laya/** so docstring changes rebuild the site.
---
 .github/workflows/docs.yml  |  4 +--
 docs/index.md               |  1 +
 docs/reference/agent.md     | 11 ++++++++
 docs/reference/helpers.md   | 53 +++++++++++++++++++++++++++++++++++++
 docs/reference/index.md     | 17 ++++++++++++
 docs/reference/langchain.md | 14 ++++++++++
 docs/reference/router.md    | 10 +++++++
 requirements-docs.txt       |  3 +++
 zensical.toml               | 18 +++++++++++++
 9 files changed, 129 insertions(+), 2 deletions(-)
 create mode 100644 docs/reference/agent.md
 create mode 100644 docs/reference/helpers.md
 create mode 100644 docs/reference/index.md
 create mode 100644 docs/reference/langchain.md
 create mode 100644 docs/reference/router.md

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index defb723..c185edf 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -5,10 +5,10 @@ name: Docs
 
 on:
   pull_request:
-    paths: [docs/**, zensical.toml, requirements-docs.txt, .github/workflows/docs.yml]
+    paths: [docs/**, laya/**, zensical.toml, requirements-docs.txt, .github/workflows/docs.yml]
   push:
     branches: [main]
-    paths: [docs/**, zensical.toml, requirements-docs.txt, .github/workflows/docs.yml]
+    paths: [docs/**, laya/**, zensical.toml, requirements-docs.txt, .github/workflows/docs.yml]
   workflow_dispatch:
 
 permissions:
diff --git a/docs/index.md b/docs/index.md
index e2e129f..c41eb0d 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -5,6 +5,7 @@ decisions over any state, in a single forward pass.
 
 The [README](https://github.com/NandhaKishorM/laya#readme) is the main guide. It covers
 installation, the `Router` quickstart, the HTTP server, calibration, benchmarks and known limits.
+The [Python API reference](reference/index.md) is generated from the docstrings.
 These guides cover individual topics:
 
 - [Docker quickstart](docker.md): run the SDK in a container, on CPU or an NVIDIA GPU.
diff --git a/docs/reference/agent.md b/docs/reference/agent.md
new file mode 100644
index 0000000..b235cf9
--- /dev/null
+++ b/docs/reference/agent.md
@@ -0,0 +1,11 @@
+# Agent
+
+`laya.Agent` loads one checkpoint and answers typed questions about a state. `laya.load` is
+a shortcut for `Agent(...)`, and `laya.RLAgent` is an alias of `Agent`. `ONNXAgent` runs an
+exported ONNX model on CPU; import it from `laya.onnx_agent`.
+
+::: laya.agent.Agent
+
+::: laya.agent.load
+
+::: laya.onnx_agent.ONNXAgent
diff --git a/docs/reference/helpers.md b/docs/reference/helpers.md
new file mode 100644
index 0000000..dcedd20
--- /dev/null
+++ b/docs/reference/helpers.md
@@ -0,0 +1,53 @@
+# Helpers
+
+## Language detection
+
+`laya.detect_language` is `laya.lang.analyse`.
+
+::: laya.lang.analyse
+
+::: laya.lang.detect_script
+
+::: laya.lang.is_english
+
+## Email
+
+::: laya.email.clean_email_body
+
+::: laya.email.email_state
+
+## Question presets
+
+::: laya.presets.triage_questions
+
+::: laya.presets.email_questions
+
+::: laya.presets.guard_questions
+
+::: laya.presets.moderation_questions
+
+::: laya.presets.router_questions
+
+## Shortlisting
+
+::: laya.shortlist.shortlist_choice
+
+::: laya.shortlist.predict_shortlist
+
+::: laya.shortlist.embed_fn_from_agent
+
+## Calibration and training
+
+::: laya.common.confidence_from_probs
+
+::: laya.common.ece_score
+
+::: laya.common.render_options
+
+::: laya.common.proper_reward
+
+::: laya.common.td_lambda_targets
+
+::: laya.common.QTYPES
+
+::: laya.common.QTYPE_NAMES
diff --git a/docs/reference/index.md b/docs/reference/index.md
new file mode 100644
index 0000000..34f195a
--- /dev/null
+++ b/docs/reference/index.md
@@ -0,0 +1,17 @@
+# Python API
+
+These pages are generated from the docstrings in `laya/`, so they change with the code. Apart
+from `ONNXAgent`, every name below can be imported from the top-level package, for example
+`from laya import Router`.
+
+- [Agent](agent.md): `Agent` and `load` run one checkpoint; `ONNXAgent` runs an exported ONNX
+  model.
+- [Router](router.md): `Router` picks the checkpoint for each request; `RouteDecision` records
+  the choice.
+- [Helpers](helpers.md): language detection, email cleaning, question presets, shortlisting
+  and calibration utilities.
+- [LangChain components](langchain.md): `LayaRouter`, `LayaGuardrail`, `LayaTriage` and
+  `LayaEvaluator`.
+
+Prediction hooks have a hand-written [API reference](../hooks/api.md) with the rest of the
+[hooks guide](../hooks/index.md).
diff --git a/docs/reference/langchain.md b/docs/reference/langchain.md
new file mode 100644
index 0000000..5b38aae
--- /dev/null
+++ b/docs/reference/langchain.md
@@ -0,0 +1,14 @@
+# LangChain components
+
+Install with `pip install "laya[langchain]"`. The [LangChain & LangGraph guide](../langchain.md)
+shows these components in chains and graphs.
+
+::: laya.integrations.langchain.LayaRouter
+
+::: laya.integrations.langchain.LayaGuardrail
+
+::: laya.integrations.langchain.LayaGuardrailError
+
+::: laya.integrations.langchain.LayaTriage
+
+::: laya.integrations.langchain.LayaEvaluator
diff --git a/docs/reference/router.md b/docs/reference/router.md
new file mode 100644
index 0000000..571d5a8
--- /dev/null
+++ b/docs/reference/router.md
@@ -0,0 +1,10 @@
+# Router
+
+`laya.Router` detects the language of each state and sends the request to the matching
+checkpoint, loading checkpoints on first use.
+
+::: laya.router.Router
+
+::: laya.router.RouteDecision
+
+::: laya.router.DEFAULT_MODELS
diff --git a/requirements-docs.txt b/requirements-docs.txt
index 7edf5a0..903614f 100644
--- a/requirements-docs.txt
+++ b/requirements-docs.txt
@@ -1,2 +1,5 @@
 # Documentation build only; not a runtime dependency of the laya package.
 zensical==0.0.64
+# API reference pages (docs/reference/). Ruff formats the rendered signatures.
+mkdocstrings-python==2.0.9
+ruff==0.16.8
diff --git a/zensical.toml b/zensical.toml
index 33b16d5..e33d718 100644
--- a/zensical.toml
+++ b/zensical.toml
@@ -33,3 +33,21 @@ media = "(prefers-color-scheme: dark)"
 scheme = "slate"
 toggle.icon = "lucide/moon"
 toggle.name = "Switch to light mode"
+
+# API reference pages under docs/reference/ are generated from the docstrings in laya/.
+[project.plugins.mkdocstrings.handlers.python]
+paths = ["."]
+
+[project.plugins.mkdocstrings.handlers.python.options]
+docstring_style = "google"
+docstring_options = { returns_multiple_items = false }
+docstring_section_style = "list"
+filters = ["!^_"]
+members_order = "source"
+merge_init_into_class = true
+line_length = 70
+separate_signature = true
+show_root_full_path = false
+show_root_heading = true
+show_signature_annotations = true
+show_source = false