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

@@ -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:

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.

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

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

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).

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

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

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

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