@labelbox/rl-sdk 0.0.0

package/dist/reference/recipes-schema.js

@@ -0,0 +1,406 @@
+import { z } from 'zod';
+// Types for declarative **recipes** — medium-grained user goals composed of an
+// ordered sequence of SDK operations, with values threaded from one step's
+// response into the next step's inputs. Authored under
+// `tests/smoke/recipes/<category>/<id>/` (a `manifest.ts` + an `api.ts`),
+// statically validated and composed into SDK/CLI/cURL examples by
+// `yarn dx recipes:generate`, and rendered in the in-app "Recipes" docs.
+//
+// Two layers live here:
+//   1. Authoring types (`RecipeManifest`, `RecipeApi`) — what an author writes.
+//   2. The generated reference entry (`RecipeReferenceEntry`) — what the
+//      generator emits and the frontend renders.
+// ---------------------------------------------------------------------------
+// Authoring types — `manifest.ts` + `api.ts`
+// ---------------------------------------------------------------------------
+// Kebab-case (lowercase words joined by single hyphens). Shared by recipe ids
+// and category slugs: the docs nav groups by category and renders it via a
+// kebab→sentence-case transform, so a free-form category (trailing space,
+// spaces vs hyphens) could collapse two distinct categories into one nav group.
+const KEBAB_CASE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/**
+ * How often a recipe is validated — an **internal CI cadence**, never surfaced
+ * in the docs (deliberately not on `RecipeReferenceEntry`):
+ *   - `'per-merge'` — rides the post-deploy smoke on every merge.
+ *   - `{ everyDays: N }` — pulled out of the per-merge smoke; validated by the
+ *     daily workflow only on the days it's "due" (date-modulo schedule).
+ * A future weekly tier is just `{ everyDays: 7 }` — no schema change.
+ */
+export const RecipeCadenceSchema = z.union([
+    z.literal('per-merge'),
+    z.object({ everyDays: z.number().int().positive() }).strict(),
+]);
+// ---------------------------------------------------------------------------
+// Related links — the relationship graph between recipes and doc elements
+// ---------------------------------------------------------------------------
+//
+// A recipe is no longer a floating island: its optional `related` block names
+// what it **requires** (a prerequisite recipe or a precondition state), the
+// **canonical** recipe it's a `variationOf` (one knob changed), and the concept
+// / tutorial / resource pages worth reading to **learn more**. These are pure
+// *metadata*, never execution — no recipe runs another; each still provisions
+// and tears down its own world. They are a map read by the CLI (`rl recipes
+// <id>`), the in-app recipe page, the agent (the recursion skill traverses
+// them), and — later — the course generator. `recipes:check` validates that
+// every target resolves and that the `requires` graph is acyclic.
+/** A link to another **recipe** (traversable — the agent can follow it). */
+export const RecipeRecipeTargetSchema = z
+    .object({ type: z.literal('recipe'), id: z.string().regex(KEBAB_CASE, 'id must be kebab-case') })
+    .strict();
+/** A link to a **concept** (Explanation) page declared in `CONCEPT_REFERENCE`. */
+export const RecipeConceptTargetSchema = z
+    .object({ type: z.literal('concept'), id: z.string().min(1) })
+    .strict();
+/** A link to a **tutorial** page. */
+export const RecipeTutorialTargetSchema = z
+    .object({ type: z.literal('tutorial'), id: z.string().min(1) })
+    .strict();
+/** A link to a **resource** page. */
+export const RecipeResourceTargetSchema = z
+    .object({ type: z.literal('resource'), id: z.string().min(1) })
+    .strict();
+/**
+ * Any typed link target (`recipe | concept | tutorial | resource`). One typed
+ * model lets a recipe reference *any* doc element — relationships aren't only
+ * between recipes — instead of a separate field per kind.
+ */
+export const RecipeLinkTargetSchema = z.discriminatedUnion('type', [
+    RecipeRecipeTargetSchema,
+    RecipeConceptTargetSchema,
+    RecipeTutorialTargetSchema,
+    RecipeResourceTargetSchema,
+]);
+/**
+ * A `learnMore` target — the "why" behind the how-to: a concept / tutorial /
+ * resource. NOT a recipe (a recipe demonstrates; a concept explains — pairing
+ * them is what teaches the reader). The concept page lists its recipes via the
+ * inverse, so there's no second "taught by" field.
+ */
+export const RecipeLearnMoreTargetSchema = z.discriminatedUnion('type', [
+    RecipeConceptTargetSchema,
+    RecipeTutorialTargetSchema,
+    RecipeResourceTargetSchema,
+]);
+/**
+ * A `requires` entry that is a **state precondition** rather than a recipe — the
+ * common "the version must be locked" case that has no recipe of its own. It
+ * carries a human `explanation`, an optional machine-checkable `predicate`
+ * (e.g. `version.locked === true` — in L0 only *stored* and required to be a
+ * non-empty string; *evaluated* in a later layer), and an optional `via` link to
+ * whatever reaches the state (a recipe / concept / tutorial / resource).
+ */
+export const RecipeStateRequirementSchema = z
+    .object({
+    type: z.literal('state'),
+    explanation: z.string().min(1),
+    predicate: z.string().min(1).optional(),
+    via: RecipeLinkTargetSchema.optional(),
+})
+    .strict();
+/**
+ * A typed prerequisite: another **recipe** (a real, followable edge — "author a
+ * problem before grading it") or a **state** precondition (the explanation +
+ * optional predicate above). The backbone an agent traverses off the `now what?`
+ * cliff.
+ */
+export const RecipeRequiresEntrySchema = z.discriminatedUnion('type', [
+    RecipeRecipeTargetSchema,
+    RecipeStateRequirementSchema,
+]);
+/**
+ * The optional `related` block on a recipe — its place in the graph. All fields
+ * optional; an absent block means "no declared relationships" (an island, which
+ * `recipes:check` permits but the docs nudge away from).
+ */
+export const RecipeRelatedSchema = z
+    .object({
+    // Typed prerequisites (recipes and/or states) to satisfy before this recipe.
+    requires: z.array(RecipeRequiresEntrySchema).min(1).optional(),
+    // The canonical recipe this is a one-knob variation of (its id).
+    variationOf: z
+        .string()
+        .regex(KEBAB_CASE, 'variationOf must be a kebab-case recipe id')
+        .optional(),
+    // Related reading — the "why" behind the how-to.
+    learnMore: z.array(RecipeLearnMoreTargetSchema).min(1).optional(),
+})
+    .strict();
+/** A recipe's identity + docs metadata (`manifest.ts`). */
+export const RecipeManifestSchema = z
+    .object({
+    // Stable kebab-case id; must match the recipe's folder name.
+    id: z.string().regex(KEBAB_CASE, 'id must be kebab-case'),
+    title: z.string().min(1),
+    // One-sentence statement of the user goal this recipe accomplishes.
+    goal: z.string().min(1),
+    // The canonical product domain this recipe lives under in the docs How-to nav
+    // (one of the eight `DOMAINS`). Kebab here; membership in `DOMAINS` is enforced
+    // fail-fast by `recipes:generate` (it can't import the domains module — schema
+    // files are loaded as source at codegen time, so they may only import npm deps).
+    category: z.string().regex(KEBAB_CASE, 'category must be kebab-case'),
+    // Internal CI validation cadence (required, no default — every recipe makes
+    // a deliberate tier choice). Read only by dx for smoke selection; NOT
+    // projected into the generated reference, so it never reaches the frontend.
+    cadence: RecipeCadenceSchema,
+    // Optional editorial one-liners for the walkthrough steps, keyed by the
+    // step's caption. Authored here (not captured), so editing copy is a fast
+    // `recipes:generate` — never a staging re-capture. Merged into the
+    // reference's walkthrough by `recipes:generate`.
+    stepDescriptions: z.record(z.string(), z.string()).optional(),
+    // The documented opt-out from the terminal GET-or-poll gate (`recipes:check`):
+    // every recipe must end its `main` phase by observing the user-meaningful
+    // outcome (a read or a `poll`). The ONLY exception is a last-mile step that
+    // genuinely has no API — e.g. the Intelligence reviewer's approval in
+    // `submit-and-review` — whose outcome is instead proven in `ui.spec`. Set this
+    // (with a non-empty reason naming the step) to satisfy the gate in that case.
+    outcomeInUiOnly: z
+        .object({ reason: z.string().min(1) })
+        .strict()
+        .optional(),
+    // The recipe's place in the relationship graph (prerequisites / canonical /
+    // related reading). Optional + additive; projected verbatim into the
+    // generated reference and validated by `recipes:check`.
+    related: RecipeRelatedSchema.optional(),
+})
+    .strict();
+/** A reference to a value captured by an earlier step (threading). */
+export const RecipeRefSchema = z.object({ $ref: z.string().min(1) }).strict();
+/**
+ * An input supplied to one of a step's params:
+ *   - `{ $ref: '<captureName>' }` — threaded from an earlier step's capture.
+ *   - `{ value: <json> }`         — a literal rendered verbatim in the examples.
+ * Params not listed in a step's `inputs` render as placeholders (user-supplied).
+ */
+export const RecipeInputSchema = z.union([
+    RecipeRefSchema,
+    z.object({ value: z.unknown() }).strict(),
+]);
+/**
+ * A response-field condition: the value at `path` is one of `in`, OR (with
+ * `present: true`) is simply non-null. `present` gates on a field that only
+ * appears once the real outcome lands — e.g. `gradedAt`/`finalScore`, where the
+ * `status` string alone is ambiguous (a graded run passes through `completed`
+ * transiently before grading finalizes). Exactly one of `in` / `present`.
+ */
+// A union of two CLOSED variants rather than one flat object with an `.refine`
+// exclusivity check, so every consumer reads `cond.in` / `cond.present` with no
+// `?? []` defence. Note the static guarantee is partial: authoring NEITHER field
+// (`{ path }`) is a `satisfies RecipeApiInput` compile error (both variants
+// require their discriminating field), but authoring BOTH (`{ path, in, present }`)
+// still compiles — TypeScript's excess-property check treats a property as
+// "known" if it appears in ANY union constituent — and is only rejected at
+// runtime by the `.strict()` variants inside `recipes:generate`/`recipes:check`.
+// (Root CLAUDE.md: "Leverage discriminated unions" / "Encode as much invariant
+// information in the type system as possible".)
+const RecipePollConditionSchema = z.union([
+    z
+        .object({
+        // A field path on the operation's response, in the same grammar `captures`
+        // uses (e.g. `status`, `result.grade`). Read each poll iteration.
+        path: z.string().min(1),
+        // The values that satisfy the condition (≥1). For `until`, these are the
+        // terminal-success states; for `failOn`, the terminal-failure states.
+        in: z.array(z.string()).min(1),
+    })
+        .strict(),
+    z
+        .object({
+        path: z.string().min(1),
+        // Satisfied as soon as the field is present (non-null) — e.g. a numeric
+        // `finalScore` (including `0`), where a `status` string alone is ambiguous.
+        present: z.literal(true),
+    })
+        .strict(),
+]);
+/**
+ * A **poll** modifier on an SDK step: re-invoke this operation on an interval
+ * until it reaches a terminal state, *then* read its captures off that terminal
+ * response. This makes "wait for the result, then read it" a first-class,
+ * **documented** part of the recipe (rendered as a real loop in the SDK/CLI/cURL
+ * examples) rather than hidden test scaffolding — a recipe teaches the reader how
+ * to wait, exactly as the UI walkthrough does. The executor (`executeApiPlan`):
+ *   - fails RED when `failOn` is set and its condition holds — `failOn.path`'s
+ *     value is in `failOn.in` (or, with `present`, is non-null). Checked FIRST,
+ *     so a terminal failure is surfaced, never masked by a coincident `until`.
+ *   - stops successfully when `until` holds — `until.path`'s value is in
+ *     `until.in`, or (with `present`) is non-null (e.g. `finalScore` landing).
+ *   - fails RED when `timeoutMs` elapses first.
+ * Poll is SDK-only (an Intelligence step has no `operationId` to re-invoke).
+ */
+export const RecipePollSchema = z
+    .object({
+    until: RecipePollConditionSchema,
+    failOn: RecipePollConditionSchema.optional(),
+    timeoutMs: z.number().int().positive(),
+    intervalMs: z.number().int().positive(),
+})
+    .strict();
+/**
+ * An SDK step — today's `operationId`-based call. `setup` steps render as a
+ * marked preamble (each recipe provisions its own setup); `main` steps are the
+ * goal proper. `kind` defaults to `'sdk'` so existing (kind-less) recipes stay
+ * valid and the common case needs no `kind:` line.
+ */
+export const RecipeSdkStepSchema = z
+    .object({
+    kind: z.literal('sdk').default('sdk'),
+    operationId: z.string().min(1),
+    // Human caption — mirrors the matching `ui.spec` `test.step()` caption and
+    // doubles as the step heading in docs.
+    caption: z.string().optional(),
+    phase: z.enum(['setup', 'main']).default('main'),
+    // Param name → input value (threaded ref or literal).
+    inputs: z.record(z.string(), RecipeInputSchema).default({}),
+    // Optional poll: when set, this step waits for a terminal state (see
+    // RecipePollSchema) before reading its captures — the documented "wait for
+    // the result" step that lets a recipe prove its outcome.
+    poll: RecipePollSchema.optional(),
+    // Capture name → a field path on this operation's response shape.
+    captures: z.record(z.string(), z.string()).default({}),
+})
+    .strict();
+/**
+ * An Intelligence (Labelbox) step — a raw GraphQL command POSTed to
+ * `${LBX_URL}/api/_gql` with the SAME `Authorization: Bearer <LABELBOX_API_KEY>`
+ * the rl SDK/CLI already use. This surfaces the parts of a real flow that have
+ * no rl-gym SDK route (create a project, add a labeler, submit/review) so an
+ * agent reading the recipe gets the *complete* journey, not just the SDK slice.
+ * `caption` is REQUIRED — it is the user-facing instruction ("Create a project
+ * in Intelligence") that the whole feature exists to surface. `{ $ref }` markers
+ * embedded in `gql.variables` thread in earlier captures; `captures` reads
+ * fields off the GraphQL response's `data` object (e.g. `createProject.id`).
+ */
+export const RecipeIntelligenceStepSchema = z
+    .object({
+    kind: z.literal('intelligence'),
+    caption: z.string().min(1),
+    phase: z.enum(['setup', 'main']).default('main'),
+    gql: z
+        .object({
+        query: z.string().min(1),
+        // GraphQL variables; values may embed `{ $ref: '<capture>' }` markers,
+        // resolved against earlier captures at execution + render time.
+        variables: z.record(z.string(), z.unknown()).default({}),
+    })
+        .strict(),
+    // Capture name → a dot/`[]` path on the GraphQL `data` response.
+    captures: z.record(z.string(), z.string()).default({}),
+})
+    .strict();
+/**
+ * One step of a recipe's `api.ts`: an SDK call or an Intelligence GraphQL
+ * command. A plain `z.union` (not `discriminatedUnion`) is deliberate — Zod 4's
+ * `discriminatedUnion` reads the discriminator BEFORE applying defaults, so a
+ * `kind`-less step would fail to match; `z.union` tries the SDK variant first,
+ * whose defaulted `kind` absorbs the omitted discriminator. TypeScript still
+ * narrows on the `kind` literal at the consumer.
+ */
+export const RecipeApiStepSchema = z.union([RecipeSdkStepSchema, RecipeIntelligenceStepSchema]);
+/** The ordered API plan for a recipe (`api.ts`). */
+export const RecipeApiSchema = z
+    .object({
+    steps: z.array(RecipeApiStepSchema).min(1),
+})
+    .strict();
+// ---------------------------------------------------------------------------
+// Generated reference entry — `recipes-reference.generated.ts`
+// ---------------------------------------------------------------------------
+/** A validated SDK step in the generated reference (phase/inputs/captures normalized). */
+export const RecipeSdkReferenceStepSchema = z
+    .object({
+    kind: z.literal('sdk'),
+    operationId: z.string(),
+    caption: z.string().optional(),
+    phase: z.enum(['setup', 'main']),
+    inputs: z.record(z.string(), RecipeInputSchema),
+    // Mirrors the authoring step's `poll` (carried verbatim into the reference so
+    // the renderer can emit the wait-loop in the SDK/CLI/cURL examples).
+    poll: RecipePollSchema.optional(),
+    captures: z.record(z.string(), z.string()),
+})
+    .strict();
+/** A validated Intelligence step in the generated reference (normalized). */
+export const RecipeIntelligenceReferenceStepSchema = z
+    .object({
+    kind: z.literal('intelligence'),
+    caption: z.string().min(1),
+    phase: z.enum(['setup', 'main']),
+    gql: z
+        .object({
+        query: z.string().min(1),
+        variables: z.record(z.string(), z.unknown()),
+    })
+        .strict(),
+    captures: z.record(z.string(), z.string()),
+})
+    .strict();
+/**
+ * A validated step in the generated reference. The reference is the *normalized*
+ * form (defaults already applied, so `kind` is always present) — a
+ * `discriminatedUnion` is safe here and gives precise per-variant errors.
+ */
+export const RecipeReferenceStepSchema = z.discriminatedUnion('kind', [
+    RecipeSdkReferenceStepSchema,
+    RecipeIntelligenceReferenceStepSchema,
+]);
+/**
+ * One step of the UI **walkthrough** — a user-facing caption next to its
+ * screenshot. Captured from the `ui.spec` run by `recipes:capture-media`
+ * (`image` is a filename under `apps/recursion/web/public/docs/recipes/<id>/`) and
+ * rendered as the docs Walkthrough filmstrip. The caption is page text beside
+ * the image, never burned into it.
+ */
+export const RecipeWalkthroughStepSchema = z
+    .object({
+    caption: z.string().min(1),
+    image: z.string().min(1),
+    // Optional editorial one-liner (from the manifest's `stepDescriptions`),
+    // rendered under the caption. Absent in the captured manifest.
+    description: z.string().optional(),
+})
+    .strict();
+/** The committed walkthrough manifest (`walkthrough.json`): an ordered step list. */
+export const RecipeWalkthroughSchema = z.array(RecipeWalkthroughStepSchema);
+/**
+ * A composed example for one surface, split by phase: the `setup` preamble
+ * (provisioning steps — `phase: 'setup'`) and the `main` goal steps. The docs
+ * render `setup` as a collapsed disclosure so the recipe's actual point leads;
+ * concatenating `setup` + `main` is the full runnable script. Either may be the
+ * empty string (a recipe with no setup steps, or none in main).
+ */
+export const RecipeSnippetSchema = z.object({ setup: z.string(), main: z.string() }).strict();
+/**
+ * One recipe in the generated reference, keyed by id. Carries the docs
+ * metadata, the validated step plan, and the composed SDK/CLI/cURL examples
+ * (full runnable snippets with captured values threaded between steps), each
+ * split into a folded `setup` preamble + the `main` goal steps.
+ */
+export const RecipeReferenceEntrySchema = z
+    .object({
+    id: z.string(),
+    title: z.string(),
+    goal: z.string(),
+    // The canonical domain (carried verbatim from the manifest) — keeps the docs
+    // How-to nav grouping 1:1 with the domain taxonomy. Membership validated by
+    // `recipes:generate`.
+    category: z.string().regex(KEBAB_CASE, 'category must be kebab-case'),
+    // Docs video path, derived as `<id>.mp4` by the generator (never authored).
+    // Always present: the generator sets it unconditionally from `id` (it is a
+    // derived path string, not captured content), so every generated entry has
+    // one. The file's existence — and a non-empty walkthrough — are separately
+    // presence-checked by `recipes:check` before a recipe can land.
+    video: z.string().min(1),
+    // Ordered UI walkthrough (caption + screenshot per step), captured from the
+    // ui.spec run. Empty until `recipes:capture-media` has been run.
+    walkthrough: z.array(RecipeWalkthroughStepSchema).default([]),
+    steps: z.array(RecipeReferenceStepSchema).min(1),
+    // Composed, ready-to-render examples per representation (setup + main split).
+    sdk: RecipeSnippetSchema,
+    cli: RecipeSnippetSchema,
+    curl: RecipeSnippetSchema,
+    // The recipe's place in the graph, carried verbatim from the manifest so
+    // every surface (CLI / frontend / agent) reads one source. Absent when the
+    // recipe declares no relationships.
+    related: RecipeRelatedSchema.optional(),
+})
+    .strict();

package/dist/reference/resources-reference.generated.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AUTO-GENERATED by 'yarn dx resources:generate'.
+ * Do not edit manually — changes will be overwritten.
+ *
+ * Explanation-layer resource hubs, keyed by resource id (= the OpenAPI tag
+ * name). One hub per domain-resource tag; the resource tree (`parent`),
+ * object shape, operations, and relationships are all derived from the
+ * backend OpenAPI spec.
+ */
+import type { ResourceReferenceEntry } from './resources-schema.js';
+export declare const RESOURCE_REFERENCE: Record<string, ResourceReferenceEntry>;