From ba8fa2ad2e65307e8127cbaad23a0d71c52e102f Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 31 May 2026 07:41:06 +0000 Subject: [PATCH] police sweep 2026-05-31: pagination cursor + synthesize lifecycle MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - api-reference/introduction.mdx: `next` → `next_cursor` (the actual wire field name on paginated responses; `next` would silently return undefined to callers iterating pages) - concepts/model-lifecycle.mdx: add `synthesize` as a third draft→busy transition in the state diagram, States table, and Mechanism prose; synthesize_samples is a lifecycle-entering operation on par with train and discover https://claude.ai/code/session_01BMNmbn4Rb8JLUbWQu5j8mY --- api-reference/introduction.mdx | 2 +- concepts/model-lifecycle.mdx | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx index d9ddf26..19e0f26 100644 --- a/api-reference/introduction.mdx +++ b/api-reference/introduction.mdx @@ -71,7 +71,7 @@ A URL in `content` is fetched and its extracted text is scored. Set `Accept: tex | Base URL | `https://u22a8.ai/v1` | | Auth | `Authorization: Bearer ` on every endpoint | | Format | JSON request and response; `score` also accepts a raw-text body, and `score`/`compare` can return a `text/plain` view | -| Pagination | Cursor-based; list responses return a `next` cursor | +| Pagination | Cursor-based; list responses return a `next_cursor` field | | Errors | One error envelope; every response carries a request id | ## Failure modes diff --git a/concepts/model-lifecycle.mdx b/concepts/model-lifecycle.mdx index aff94ba..28dbe85 100644 --- a/concepts/model-lifecycle.mdx +++ b/concepts/model-lifecycle.mdx @@ -10,7 +10,7 @@ A model has a **lifecycle**: a small set of states it moves through from first d stateDiagram-v2 direction LR [*] --> draft: create - draft --> busy: train / discover + draft --> busy: train / discover / synthesize busy --> draft: discovery completes busy --> ready: training completes busy --> failed: run fails @@ -25,7 +25,7 @@ stateDiagram-v2 | State | Meaning | |-------|---------| | `draft` | Created and accepting trait and sample edits. Not yet scorable. | -| `busy` | An asynchronous operation is running — training, discovery, or a background retrain. The model reports which one. | +| `busy` | An asynchronous operation is running — training, discovery, synthesis, or a background retrain. The model reports which one. | | `ready` | Trained and serving scores against an active [version](/concepts/versions). | | `failed` | The last run did not complete. Correct the supervision and train again. | | `archived` | Stopped serving. Samples and version history are retained — archiving is not permanent deletion. | @@ -38,6 +38,7 @@ One pattern drives the states: **create → supervise → train → score**, wit - **Trait and sample edits are draft-only.** Adding, changing, or removing traits and explicit samples applies only while the model is a `draft`. Once trained, those edits are no longer accepted — a different standard means a new model, not an edit to a serving one. ([Feedback](/concepts/supervision) still appends samples to a serving model; it adds to the next retrain rather than editing the trained definition.) - **Train** moves a draft to `busy`, then to `ready` on success or `failed` on error. This first run is a [cold start](/concepts/training): the model becomes scorable from whatever supervision it has. - **[Discovery](/concepts/discovery)** runs on a draft, attaches intrinsic traits, and returns the model to `draft` — ready to train. +- **[Synthesis](/concepts/samples)** runs on a draft, generates samples, and returns the model to `draft`. - **Score** serves the active version of a `ready` model. Scoring stays available throughout a background retrain: the model keeps serving its current version until the new one swaps in atomically, so a request never waits on a run and never sees a half-trained snapshot. - **[Feedback](/concepts/supervision)** on a score request records labels for the scored content as new samples, accumulating for the next retrain — **online learning** that does not interrupt scoring.