Skip to content

armgit / laya

Public Imported from GitHub
0

Non-autoregressive System 1 decision engine. Typed choice, score and yes/no decisions over any text in a single forward pass, in 100+ languages, with a router that picks the right checkpoint per request.

docs: fail the docs build on docstring warnings

Maxfield Allison441414c95cd6
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index c185edfc..266ebfb2 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -35,7 +35,16 @@ jobs:
# --strict fails on every warning, including links the site cannot resolve.
# Use absolute GitHub URLs for files outside docs/ so links work when pages in docs/
# are read on GitHub or on the site.
- - run: zensical build --strict
+ # Griffe's docstring warnings (a parameter the signature does not have, a missing type)
+ # are printed but pass --strict, and the API reference is built from those docstrings.
+ # --clean because a cached build skips unchanged modules and prints no warnings for them.
+ - run: |
+ set -o pipefail
+ zensical build --strict --clean 2>&1 | tee "$RUNNER_TEMP/docs-build.log"
+ if grep '^griffe:' "$RUNNER_TEMP/docs-build.log"; then
+ echo "::error::Fix the docstring warnings above; the API reference is built from them."
+ exit 1
+ fi
- uses: actions/upload-pages-artifact@v5
if: github.event_name != 'pull_request'
diff --git a/AGENTS.md b/AGENTS.md
index cbc8a237..4ebc2a10 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -28,7 +28,7 @@ Context for AI coding assistants (Claude Code, Codex, Cursor, Copilot, Gemini CL
| server path | `tests/test_serve.py` | `python -m pytest tests/test_serve.py` (skips when the `serve` extra is missing) |
| ONNX path | `tests/test_onnx.py` | `python -m pytest tests/test_onnx.py` (skips when the `onnx` extra is missing) |
| fast/local paths | `tests/test_fast.py`, `tests/test_local_e2e.py`, `tests/test_mcp_local_e2e.py` | need CUDA or checkpoints under `~/laya_models`; skipped otherwise |
-| docs | `docs/` | — |
+| docs, docstrings in `laya/` | `docs/`, `docs/.nav.yml` for page order | `pip install -r requirements-docs.txt`, then `zensical build --strict --clean` with no `griffe:` lines in the output |
Optional extras are declared in `pyproject.toml` (`serve`, `fast`, `onnx`, `langchain`, `langgraph`); install only what the change needs.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 91b8ef86..e3055414 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -61,6 +61,22 @@ ruff check laya/ --select=E9,F63,F7,F82,F401,F811 --line-length=120
python -m compileall -q laya/ tests/
```
+## Documentation
+
+The site at [nandhakishorm.github.io/laya](https://nandhakishorm.github.io/laya/) builds from
+`docs/` with Zensical, and its API reference builds from the docstrings in `laya/`. A new page
+appears under Guides without a config change; to put it somewhere else, add it to
+[`docs/.nav.yml`](docs/.nav.yml). For a docs or docstring change, build the site the way the CI
+does:
+
+```bash
+pip install -r requirements-docs.txt
+zensical build --strict --clean
+```
+
+The output must have no `griffe:` lines. Those are docstring problems, such as a parameter the
+signature does not have, and the CI fails on them.
+
## Style
- Keep the public API stable. If a change must move it, update `tests/test_hooks_api.py` in the same
diff --git a/laya/agent.py b/laya/agent.py
index b0fb78a7..e80044fe 100644
--- a/laya/agent.py
+++ b/laya/agent.py
@@ -729,13 +729,16 @@ class Agent(HookRegistry):
questions: Question definitions, exactly as accepted by `system_one`.
batch_size: Optional cap on states per forward pass. `None` sends them all in one pass;
set it to bound peak memory when batching many or long states.
- hooks, on_predict_start, on_predict_end: Per-call hooks, appended after any installed on
- the Agent. `on_predict_start` may rewrite the state/questions or call
- `ctx.skip(...)` to short-circuit inference; `on_predict_end` may rewrite the
- results. See `laya.hooks`.
+ hooks (HookArg): Per-call hooks, appended after any installed on the Agent.
+ See `laya.hooks`.
+ on_predict_start (PredictHookArg): A per-call start hook. It may rewrite the
+ state/questions or call `ctx.skip(...)` to short-circuit inference.
+ on_predict_end (PredictHookArg): A per-call end hook. It may rewrite the results.
hooks_raise: Override the Agent's `hooks_raise` for this call.
- max_len, head_max_len: Override the agent config for this call. A start hook may also
- set `ctx.max_len` / `ctx.head_max_len` to shape the token budget.
+ max_len: Override the agent config's `max_len` for this call. A start hook may also
+ set `ctx.max_len` to shape the token budget.
+ head_max_len: Override the agent config's `head_max_len` for this call. A start hook
+ may also set `ctx.head_max_len`.
sort_by_length: Group similarly sized encoded states within windows of eight batches
to reduce padding. Requires an explicit `batch_size` greater than one and
smaller than the number of states; otherwise it has no effect. Results retain
diff --git a/laya/onnx_agent.py b/laya/onnx_agent.py
index b7f2e2d6..ecfcfb7e 100644
--- a/laya/onnx_agent.py
+++ b/laya/onnx_agent.py
@@ -49,7 +49,9 @@ class ONNXAgent(HookRegistry):
(used to load the tokenizer and config).
onnx_path: Path to the exported .onnx file.
subfolder: Optional subfolder if downloading from a repo bundle.
- hooks, on_predict_start, on_predict_end: Opt-in prediction hooks; see `laya.hooks`.
+ hooks (HookArg): Opt-in prediction hooks; see `laya.hooks`.
+ on_predict_start (PredictHookArg): An opt-in start hook, run before inference.
+ on_predict_end (PredictHookArg): An opt-in end hook, run after inference.
hooks_raise: When False, a failing hook warns and inference continues.
hooks_concurrent: When False, hooks are serialised with a lock.
"""