From 1f0e2060113944fd12e19cc2948c72f2a251a6eb Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 24 Sep 2026 12:19:02 +0000 Subject: [PATCH] docs: sync documentation with recent changes Review window: everything merged into main after PR #167 (the prior sync), i.e. #168-#179 (the hosted Hugging Face Space, its per-step model selection, the Pipeline page, the database switcher, the ordinal-field removal, and the global-planner-into-decomposer refactor). Each of those PRs already updated most of its own docs; this covers what survived that self-documentation, verified against the current code on main rather than the diffs. - docs/architecture/invariants.md: dropped the "Relation Schemas Have Unique Column Names" section and its "State" category listing. RelationSchema and ColumnSpec were deleted by #177; nothing in packages/ references them any more. - docs/architecture/failure_recovery.md (two spots) and docs/architecture/graph_state.md: dropped "global planner" from the retry and no-local-recovery node lists, and "DAG hashes" from what GraphState carries. #177 deleted the standalone global_planner node (folded into decomposer/dag.py) and ExecutionDAG's dag_id/content_hash fields. - docs/deployment/hosted-demo.md and deploy/huggingface/README.md: the query timeout was documented as 60s, but the demo project's .env.demo template (cli/generators/env/templates.py) overrides GLOBAL_TIMEOUT_SEC to 300, and the Dockerfile never overrides it back down, so 300s is the actual hosted default. Also noted that a push to the workflow file itself (.github/workflows/publish_space.yml) redeploys, per its own path trigger. - web/playground/README.md: added the missing /api/pipeline route to the dev route list, added src/pipeline.js, src/hostedKey.js and src/hostedModels.js (each with its own test file) to the npm test description, and fixed router.js's stale line count (110 -> 119). - docs/getting_started/demo.md: the Pipeline page section said nine non-model steps; pipeline/steps.py lists 13 steps total and llm/providers.py's LLM_AGENTS names 5 as model-decided, leaving eight. - docs/configuration/llm.md: "Settings panel" -> "Settings page", matching the rest of the same file (Settings has been a routed page since #154). Not touched: CHANGELOG.md and version numbers (release-please owns those). Everything else in the window's own doc edits was checked and found consistent with the current code. Verification: pip install -r requirements-docs.txt && python -m mkdocs build --strict fails with exactly one warning -- mkdocs-mermaid2-plugin cannot reach unpkg.com to verify the mermaid.js CDN URL, rejected by this sandbox's outbound network policy. This is the identical sandbox-only failure documented by every prior sync PR (#60, #77, #103, #135, #167). With no other warnings, every content and nav validation passes. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01SAJucHo2Qx4qVUgiyNVLwy --- deploy/huggingface/README.md | 2 +- docs/architecture/failure_recovery.md | 4 ++-- docs/architecture/graph_state.md | 2 +- docs/architecture/invariants.md | 18 +----------------- docs/configuration/llm.md | 4 ++-- docs/deployment/hosted-demo.md | 9 +++++---- docs/getting_started/demo.md | 2 +- web/playground/README.md | 12 +++++++----- 8 files changed, 20 insertions(+), 33 deletions(-) diff --git a/deploy/huggingface/README.md b/deploy/huggingface/README.md index 808800da..de43001a 100644 --- a/deploy/huggingface/README.md +++ b/deploy/huggingface/README.md @@ -133,7 +133,7 @@ Variables** can override any of them: | `PORT` | `7860` | the port the Space routes to (`app_port` above must match) | | `NL2SQL_DEMO_QUESTIONS_PER_MINUTE` | `6` | rate limit per visitor | | `NL2SQL_DEMO_QUESTIONS_PER_SESSION` | `30` | cap per browser session | -| `GLOBAL_TIMEOUT_SEC` | `60` | how long one question may run | +| `GLOBAL_TIMEOUT_SEC` | `300` (from `.env.demo`) | how long one question may run | | `TRACE_MODE` | `always` (from `.env.demo`) | what the playground's **Debug** drill-down reads. Every question writes a trace file to the container's own disk, which is wiped whenever the Space restarts; set it to `on_failure` to keep only the runs that went wrong | **Never add an API key as a Space secret.** The whole point of hosted mode is diff --git a/docs/architecture/failure_recovery.md b/docs/architecture/failure_recovery.md index 8b6909d8..92f5e7d5 100644 --- a/docs/architecture/failure_recovery.md +++ b/docs/architecture/failure_recovery.md @@ -108,7 +108,7 @@ Failure in this system is represented as structured `PipelineError` objects accu ### Retry scope - Only the SQL agent subgraph retries (planner and validation loop). -- Other nodes (resolver, decomposer, global planner, generator, executor, aggregator, answer synthesizer) do not retry. +- Other nodes (resolver, decomposer, generator, executor, aggregator, answer synthesizer) do not retry. ### Backoff - Exponential backoff with jitter in `retry_handler` using: @@ -144,7 +144,7 @@ Failure in this system is represented as structured `PipelineError` objects accu ### What must restart - Any graph-level failure (timeout, cancellation, unknown exception) requires a new run. -- Resolver failures, decomposer failures, global planner failures, generator failures, executor failures, and aggregator failures have no local recovery and require a new run. +- Resolver failures, decomposer failures, generator failures, executor failures, and aggregator failures have no local recovery and require a new run. ### What is unrecoverable - `FATAL_ERRORS` or `CRITICAL` severity errors (security violations, missing datasource ID, missing LLM, invalid state) terminate the subgraph or graph without retry. diff --git a/docs/architecture/graph_state.md b/docs/architecture/graph_state.md index bb52ac32..4e5113ca 100644 --- a/docs/architecture/graph_state.md +++ b/docs/architecture/graph_state.md @@ -231,7 +231,7 @@ GraphState carries identifiers and artifact references that could support replay --- ## Determinism Impact -Determinism guarantees and non-determinism sources are documented in `determinism.md`. GraphState only carries the artifacts produced by those nodes (IDs, DAG hashes, errors, and diagnostics). +Determinism guarantees and non-determinism sources are documented in `determinism.md`. GraphState only carries the artifacts produced by those nodes (IDs, errors, and diagnostics). --- diff --git a/docs/architecture/invariants.md b/docs/architecture/invariants.md index d031221b..a61c27ff 100644 --- a/docs/architecture/invariants.md +++ b/docs/architecture/invariants.md @@ -235,22 +235,6 @@ Ensures deterministic and well-ordered aggregation execution. --- -## Relation Schemas Have Unique Column Names - -### Definition -Each relation schema’s column names must be unique. - -### Enforcement Points -- `RelationSchema.validate_unique_columns()` in `nl2sql.execution.dag` - -### Failure Behavior -Raises `ValueError` during schema validation. - -### Why It Exists -Prevents ambiguous column outputs in execution DAG nodes. - ---- - ## Aggregation Requires Scan Artifacts and Single-Input Post Nodes ### Definition @@ -389,7 +373,7 @@ The validator resolves columns against a throw-away query in which every table i ## Categories -- **State**: Plan Model Is Strict and Read-Only; Relation Schemas Have Unique Column Names; Context Requires Vector Store and Schema Store Configuration +- **State**: Plan Model Is Strict and Read-Only; Context Requires Vector Store and Schema Store Configuration - **Execution**: SQL Execution Requires SQL, Datasource, and Capability; Execution DAG Must Be Valid and Acyclic; Aggregation Requires Scan Artifacts and Single-Input Post Nodes; Pipeline Execution Is Time-Bounded - **Security**: Policy Enforcement Is Namespaced and Fail-Closed; Datasource Access Is RBAC-Gated; Plan Model Is Strict and Read-Only - **Determinism**: Expected Schema Must Match Select List; Joins Must Be Valid and Schema-Backed diff --git a/docs/configuration/llm.md b/docs/configuration/llm.md index 16e23fa5..c8c8086e 100644 --- a/docs/configuration/llm.md +++ b/docs/configuration/llm.md @@ -336,7 +336,7 @@ cache-marked for Anthropic, the others are sent unmarked to OpenAI. The model each call actually used is recorded per node in `QueryResult.usage.calls` and in a run trace's `llm.by_node` (see [Debugging](../observability/debugging.md)). -In the demo, the playground's **Settings** panel writes exactly these entries +In the demo, the playground's **Settings** page writes exactly these entries into `configs/llm.demo.yaml`. Choosing a provider and a model for a step adds an `agents:` entry with `provider`, `model` and the temperature that model takes: `0.0`, or `null` for `gpt-5.5`, `gpt-5-mini`, `claude-opus-5` and @@ -344,7 +344,7 @@ takes: `0.0`, or `null` for `gpt-5.5`, `gpt-5-mini`, `claude-opus-5` and `base_url` and `api_key` reference; a step on another provider gets that provider's own `${env:...}` reference and no `base_url`. Choosing "Default" removes the entry. The running engine reloads the file, so the change applies -to the next question. The panel offers the providers and models in +to the next question. The page offers the providers and models in `VERIFIED_MODELS` (`nl2sql/llm/providers.py`), OpenAI and Anthropic for now, and a provider only once its key is saved. See [the Settings page](../getting_started/demo.md#the-settings-page). diff --git a/docs/deployment/hosted-demo.md b/docs/deployment/hosted-demo.md index 19734377..ca11bb2a 100644 --- a/docs/deployment/hosted-demo.md +++ b/docs/deployment/hosted-demo.md @@ -133,7 +133,7 @@ no storage. | --- | --- | --- | --- | | Questions per minute | 6 | `NL2SQL_DEMO_QUESTIONS_PER_MINUTE` | client address (a token bucket) | | Questions per session | 30 | `NL2SQL_DEMO_QUESTIONS_PER_SESSION` | a random session cookie | -| Query timeout | 60s | `GLOBAL_TIMEOUT_SEC` | the run | +| Query timeout | 300s | `GLOBAL_TIMEOUT_SEC` | the run | | Rows returned | 1000 | the datasource's `row_limit` option | the query | Hitting one is a `429` with a sentence, never a stack trace: the rate limit says @@ -286,9 +286,10 @@ command rather than saved into `.git/config`. **When it runs.** On every push to `main` that touches something the Space is built from -- `deploy/huggingface/**` (its root), `packages/nl2sql/**` (the engine the image installs) or `web/playground/**` (the page the engine serves) --- and on demand. A docs-only merge changes none of those and does not -redeploy. One deploy runs at a time; a run overtaken by a newer push is -cancelled. +-- or the workflow file itself, `.github/workflows/publish_space.yml`, so a +change to the deploy logic redeploys too -- and on demand. A docs-only merge +changes none of those and does not redeploy. One deploy runs at a time; a run +overtaken by a newer push is cancelled. **What it reports.** The job never calls a build that did not happen a success. If the push produced a commit, the workflow checks the Space's head is that diff --git a/docs/getting_started/demo.md b/docs/getting_started/demo.md index 542e5005..16359a95 100644 --- a/docs/getting_started/demo.md +++ b/docs/getting_started/demo.md @@ -244,7 +244,7 @@ Debug choice: they belong to the visit, not to the page. **Pipeline** lists every step a question passes through, in the order a run takes them, and marks which of them a model decides. Five do: the answerability check, the question splitter, the query planner, the plan repair and the answer -writer. The other nine are ordinary code -- the schema search, the execution +writer. The other eight are ordinary code -- the schema search, the execution plan, the layer router, the plan checks, the SQL writer, the executor and the result combiner among them -- which is the point: the model plans, and deterministic code writes the SQL, checks it against the real schema and this diff --git a/web/playground/README.md b/web/playground/README.md index ca9056df..da67e50a 100644 --- a/web/playground/README.md +++ b/web/playground/README.md @@ -257,8 +257,10 @@ rows, and the router over `hashchange`), `src/questions.js` (the guided questions grouped by datasource), `src/firstRun.js` (when the hosted demo has to ask for a key before it takes a question, and what the mode line then says), `src/datasources.js` (the -databases the switcher offers, and which one a run was answered from) and -`src/retrieval.js` (the MMR summary line, picks +databases the switcher offers, and which one a run was answered from), +`src/pipeline.js` (the run/model join for the Pipeline page), `src/hostedKey.js` +(per-provider key parsing and masking), `src/hostedModels.js` (per-step model +choice storage), `src/retrieval.js` (the MMR summary line, picks in order, entries passed over, the copyable text form) and `src/feedback.js` (when a run can be rated, the request body, the saved line) with Node's built-in test runner; there is no test dependency. @@ -281,8 +283,8 @@ npm run dev Vite serves the page on its own port. Run `nl2sql demo --no-browser` alongside it and proxy or point `fetch` at `http://127.0.0.1:8765` to exercise the real -API; the app calls `/api/meta`, `/api/schema`, `/api/ask`, `/api/trace/{id}` -the settings routes (`GET /api/settings`, `POST /api/settings/key`, +API; the app calls `/api/meta`, `/api/schema`, `/api/ask`, `/api/trace/{id}`, +`/api/pipeline`, the settings routes (`GET /api/settings`, `POST /api/settings/key`, `POST /api/settings/models`) and the index routes (`GET /api/index`, `POST /api/index/rebuild`), the inspector's (`GET /api/retrieval`, `POST /api/retrieval`) and feedback's (`GET /api/feedback`, `POST /api/feedback`). @@ -292,7 +294,7 @@ serves, not from the Vite dev server. ## Scope -React and Vite only -- no router library (`src/router.js` is 110 lines over the +React and Vite only -- no router library (`src/router.js` is 119 lines over the hash), no state library, no component kit, no CSS framework, no TypeScript. Plain JSX and plain CSS, kept small enough to read in one sitting. Light and dark follow `prefers-color-scheme`; motion is limited to the run arriving in order and is off under `prefers-reduced-motion`. The only