@labelbox/rl-sdk 0.0.0

package/dist/generated/types.gen.js

@@ -0,0 +1,2 @@
+// This file is auto-generated by @hey-api/openapi-ts
+export {};

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import { type RecursionClientOptions } from './client-options.js';
+import { Recursion } from './generated/sdk.gen.js';
+export { DEFAULT_BASE_URL, type RecursionClientOptions } from './client-options.js';
+export * from './generated/index.js';
+/**
+ * Server-sent events are the one managed-agents response shape the generated
+ * client cannot carry, so the session event stream is hand-written. See
+ * `session-events.ts` for why it is not generated.
+ */
+export { ManagedAgentSessionStreamError, type ManagedAgentSessionStreamEvent, type ManagedAgentSessionStreamParams, streamManagedAgentSessionEvents, } from './session-events.js';
+/**
+ * Construct an authenticated `Recursion` client.
+ *
+ * @example
+ * const rl = createRecursionClient({ apiKey: process.env.LABELBOX_API_KEY! });
+ * const job = await rl.synthesizers.create({
+ *   environmentId: 'env_abc',
+ *   body: { name: 'Variant generator', systemPrompt: '…', runConfigVersionId: 'rcv_…' },
+ * });
+ */
+export declare function createRecursionClient(options: RecursionClientOptions): Recursion;

package/dist/index.js

@@ -0,0 +1,39 @@
+// Public entry point for the rl-gym TypeScript SDK.
+//
+// The `Recursion` class and every namespace/method on it, plus the request/response
+// types, are generated from the backend OpenAPI spec by `@hey-api/openapi-ts`
+// (see `openapi-ts.config.ts`). This file is the only hand-written surface: it
+// re-exports the generated client and adds a small constructor that wires auth +
+// base URL. It does not grow as operations are added.
+import { DEFAULT_BASE_URL } from './client-options.js';
+import { createClient, createConfig } from './generated/client/index.js';
+import { Recursion } from './generated/sdk.gen.js';
+export { DEFAULT_BASE_URL } from './client-options.js';
+export * from './generated/index.js';
+/**
+ * Server-sent events are the one managed-agents response shape the generated
+ * client cannot carry, so the session event stream is hand-written. See
+ * `session-events.ts` for why it is not generated.
+ */
+export { ManagedAgentSessionStreamError, streamManagedAgentSessionEvents, } from './session-events.js';
+/**
+ * Construct an authenticated `Recursion` client.
+ *
+ * @example
+ * const rl = createRecursionClient({ apiKey: process.env.LABELBOX_API_KEY! });
+ * const job = await rl.synthesizers.create({
+ *   environmentId: 'env_abc',
+ *   body: { name: 'Variant generator', systemPrompt: '…', runConfigVersionId: 'rcv_…' },
+ * });
+ */
+export function createRecursionClient(options) {
+    const client = createClient(createConfig({
+        baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+        // Surface non-2xx responses as thrown errors so callers can use plain
+        // `await` + try/catch instead of inspecting an error field.
+        throwOnError: true,
+        // biome-ignore lint/style/useNamingConvention: HTTP header names are not camelCase.
+        headers: { ...options.headers, Authorization: `Bearer ${options.apiKey}` },
+    }));
+    return new Recursion({ client });
+}

package/dist/nesting.d.ts

@@ -0,0 +1,18 @@
+/**
+ * camelCase → kebab-case. Shared by the CLI (command + flag names) and the
+ * reference-doc generator (CLI example flags) so both spell names identically.
+ */
+export declare function kebab(value: string): string;
+/**
+ * Validate the declared SDK paths: every segment must be a camelCase identifier
+ * and no two operations may share the same path. Throws on the first problem —
+ * a codegen-time guard against malformed or shadowing routes.
+ */
+export declare function validateSdkPaths(pathsByOperationId: Map<string, string[]>): void;
+/**
+ * Scan a parsed OpenAPI spec for opted-in operations and return their declared
+ * SDK call paths keyed by operationId. An operation is opted in iff it carries
+ * an `x-sdk-path` array (emitted by the backend `@SdkRoute(...)` decorator). The
+ * collected paths are validated (unique, valid segments) before returning.
+ */
+export declare function collectSdkPaths(spec: unknown): Map<string, string[]>;

package/dist/nesting.js

@@ -0,0 +1,75 @@
+// The SDK/CLI surface is declared at the source: each backend handler that
+// should be generated carries `@SdkRoute(...segments)`, which emits an
+// `x-sdk-path` OpenAPI extension. This module reads those declared paths from
+// the spec and is the single source of truth shared by the hey-api codegen
+// config (`openapi-ts.config.ts`) and the SDK reference-doc generator
+// (`dx sdk:generate`), so the generated client and its docs can never disagree.
+//
+// There is no heuristic and no per-operation table here — the path comes
+// straight from the decorator. Operations WITHOUT an `x-sdk-path` are not
+// generated at all (that is also how an endpoint is excluded).
+/**
+ * camelCase → kebab-case. Shared by the CLI (command + flag names) and the
+ * reference-doc generator (CLI example flags) so both spell names identically.
+ */
+export function kebab(value) {
+    return value.replace(/([a-z0-9])([A-Z])/gu, '$1-$2').toLowerCase();
+}
+const SEGMENT = /^[a-z][A-Za-z0-9]*$/u;
+const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete'];
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Validate the declared SDK paths: every segment must be a camelCase identifier
+ * and no two operations may share the same path. Throws on the first problem —
+ * a codegen-time guard against malformed or shadowing routes.
+ */
+export function validateSdkPaths(pathsByOperationId) {
+    const seen = new Map();
+    for (const [operationId, path] of pathsByOperationId) {
+        if (path.length === 0) {
+            throw new Error(`sdk-ts: operation "${operationId}" has an empty x-sdk-path.`);
+        }
+        for (const segment of path) {
+            if (!SEGMENT.test(segment)) {
+                throw new Error(`sdk-ts: operation "${operationId}" has invalid x-sdk-path segment "${segment}" ` +
+                    '(each segment must be a camelCase identifier).');
+            }
+        }
+        const key = path.join('.');
+        const prior = seen.get(key);
+        if (prior !== undefined) {
+            throw new Error(`sdk-ts: "${operationId}" and "${prior}" both declare rl.${key}(). Change one @SdkRoute.`);
+        }
+        seen.set(key, operationId);
+    }
+}
+/**
+ * Scan a parsed OpenAPI spec for opted-in operations and return their declared
+ * SDK call paths keyed by operationId. An operation is opted in iff it carries
+ * an `x-sdk-path` array (emitted by the backend `@SdkRoute(...)` decorator). The
+ * collected paths are validated (unique, valid segments) before returning.
+ */
+export function collectSdkPaths(spec) {
+    // biome-ignore lint/complexity/useLiteralKeys: spec is Record<string, unknown>; noPropertyAccessFromIndexSignature requires bracket access
+    const paths = isRecord(spec) && isRecord(spec['paths']) ? spec['paths'] : {};
+    const result = new Map();
+    for (const methods of Object.values(paths)) {
+        if (!isRecord(methods))
+            continue;
+        for (const method of HTTP_METHODS) {
+            const op = methods[method];
+            if (!isRecord(op))
+                continue;
+            const sdkPath = op['x-sdk-path'];
+            // biome-ignore lint/complexity/useLiteralKeys: op is Record<string, unknown>; noPropertyAccessFromIndexSignature requires bracket access
+            const operationId = op['operationId'];
+            if (!Array.isArray(sdkPath) || typeof operationId !== 'string')
+                continue;
+            result.set(operationId, sdkPath.filter((segment) => typeof segment === 'string'));
+        }
+    }
+    validateSdkPaths(result);
+    return result;
+}

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

@@ -0,0 +1,9 @@
+/**
+ * AUTO-GENERATED by 'yarn dx concepts:generate'.
+ * Do not edit manually — changes will be overwritten.
+ *
+ * Explanation-layer concept pages, keyed by id (= the markdown filename stem).
+ * Source of truth: the frontmatter of `frontend/public/docs/concepts/*.md`.
+ */
+import type { ConceptReferenceEntry } from './concepts-schema.js';
+export declare const CONCEPT_REFERENCE: Record<string, ConceptReferenceEntry>;

package/dist/reference/concepts-reference.generated.js

@@ -0,0 +1,356 @@
+/**
+ * AUTO-GENERATED by 'yarn dx concepts:generate'.
+ * Do not edit manually — changes will be overwritten.
+ *
+ * Explanation-layer concept pages, keyed by id (= the markdown filename stem).
+ * Source of truth: the frontmatter of `frontend/public/docs/concepts/*.md`.
+ */
+export const CONCEPT_REFERENCE = {
+    'anatomy-of-a-problem-version': {
+        id: 'anatomy-of-a-problem-version',
+        title: 'Anatomy of a problem version',
+        domain: 'problems',
+        related: [
+            'concept:problem-lifecycle',
+            'concept:run-config-roles',
+            'resource:problem-versions',
+            'resource:problems',
+        ],
+    },
+    'authentication-and-access': {
+        id: 'authentication-and-access',
+        title: 'Authentication and access',
+        domain: 'platform',
+        related: ['concept:the-permission-model', 'concept:organizations-and-users'],
+    },
+    computes: {
+        id: 'computes',
+        title: 'Computes',
+        domain: 'run-configs',
+        related: [
+            'concept:run-config-anatomy',
+            'concept:snapshot-solvers-on-compute',
+            'resource:computes',
+        ],
+    },
+    'container-images-and-the-marketplace': {
+        id: 'container-images-and-the-marketplace',
+        title: 'Container images and the marketplace',
+        domain: 'run-configs',
+        related: [
+            'concept:computes',
+            'recipe:browse-images-and-models',
+            'resource:images',
+            'resource:marketplace',
+            'resource:models',
+        ],
+    },
+    'cost-accounting': {
+        id: 'cost-accounting',
+        title: 'How cost is accounted',
+        domain: 'cost',
+        related: [
+            'resource:cost-limits',
+            'resource:problem-runs',
+            'resource:evaluations',
+            'concept:cost-limits-and-budgets',
+            'concept:the-cost-explorer',
+        ],
+    },
+    'cost-limits-and-budgets': {
+        id: 'cost-limits-and-budgets',
+        title: 'Cost limits and budgets',
+        domain: 'cost',
+        related: [
+            'recipe:set-a-per-problem-cost-limit',
+            'recipe:set-an-environment-cost-limit',
+            'recipe:remove-a-cost-limit',
+            'resource:cost-limits',
+            'concept:cost-accounting',
+        ],
+    },
+    'designing-an-evaluation': {
+        id: 'designing-an-evaluation',
+        title: 'Designing an evaluation',
+        domain: 'evaluations',
+        related: [
+            'concept:evaluation-vs-problem-run',
+            'recipe:run-an-evaluation',
+            'recipe:export-evaluation-results',
+            'resource:evaluations',
+        ],
+    },
+    'environment-files': {
+        id: 'environment-files',
+        title: 'Environment files',
+        domain: 'environments',
+        related: ['resource:environment-files', 'concept:problem-files', 'resource:environments'],
+    },
+    'environment-snapshots-and-duplication': {
+        id: 'environment-snapshots-and-duplication',
+        title: 'Environment duplication',
+        domain: 'integrations',
+        related: [
+            'concept:exporting-and-reusing-an-environment',
+            'recipe:export-an-environment',
+            'resource:environments',
+        ],
+    },
+    'environment-templates-and-defaults': {
+        id: 'environment-templates-and-defaults',
+        title: 'Environment templates and defaults',
+        domain: 'environments',
+        related: ['resource:environments', 'resource:run-configs', 'resource:forms'],
+    },
+    'evaluation-vs-problem-run': {
+        id: 'evaluation-vs-problem-run',
+        title: 'Evaluations vs. problem runs',
+        domain: 'evaluations',
+        related: ['resource:evaluations', 'resource:problem-runs', 'recipe:run-an-evaluation'],
+    },
+    'exporting-and-reusing-an-environment': {
+        id: 'exporting-and-reusing-an-environment',
+        title: 'Exporting and reusing an environment',
+        domain: 'environments',
+        related: [
+            'recipe:export-an-environment',
+            'concept:environment-templates-and-defaults',
+            'concept:environment-snapshots-and-duplication',
+            'resource:exports',
+            'resource:environments',
+        ],
+    },
+    'forms-and-structured-capture': {
+        id: 'forms-and-structured-capture',
+        title: 'Forms and structured capture',
+        domain: 'problems',
+        related: ['resource:forms', 'resource:form-answers'],
+    },
+    'grading-strategies': {
+        id: 'grading-strategies',
+        title: 'Grading strategies',
+        domain: 'review-qa',
+        related: [
+            'resource:rubrics',
+            'resource:problem-versions',
+            'recipe:create-and-grade-a-problem',
+            'recipe:grade-with-a-rubric-grader',
+            'recipe:grade-with-an-agentic-grader',
+            'recipe:grade-with-a-programmatic-grader',
+            'recipe:grade-with-a-composite-grader',
+        ],
+    },
+    'guided-tours': {
+        id: 'guided-tours',
+        title: 'Guided tours',
+        domain: 'authoring-aids',
+        related: ['recipe:set-up-a-guided-tour', 'concept:anatomy-of-a-problem-version'],
+    },
+    'how-async-work-runs': {
+        id: 'how-async-work-runs',
+        title: 'How async work runs',
+        domain: 'jobs-observability',
+        related: [
+            'recipe:run-a-job-and-read-results',
+            'recipe:cancel-a-job',
+            'resource:jobs',
+            'resource:problem-runs',
+            'concept:runs-transcripts-and-results',
+        ],
+    },
+    'how-grading-works': {
+        id: 'how-grading-works',
+        title: 'How grading works',
+        domain: 'review-qa',
+        related: [
+            'concept:grading-strategies',
+            'concept:run-config-roles',
+            'recipe:add-and-refine-a-rubric',
+            'recipe:create-and-grade-a-problem',
+            'resource:rubrics',
+            'resource:rubric-scores',
+        ],
+    },
+    'human-review-and-issues': {
+        id: 'human-review-and-issues',
+        title: 'Human review and issues',
+        domain: 'review-qa',
+        related: ['recipe:submit-and-review-a-problem', 'resource:issues', 'resource:issue-comments'],
+    },
+    'importing-problems-and-claiming': {
+        id: 'importing-problems-and-claiming',
+        title: 'Importing problems and claiming',
+        domain: 'problems',
+        related: ['recipe:import-problems', 'resource:imports', 'resource:problems'],
+    },
+    'interfaces-ui-cli-sdk-api': {
+        id: 'interfaces-ui-cli-sdk-api',
+        title: 'Interfaces: UI, CLI, SDK, and API',
+        domain: 'platform',
+        related: ['resource:problems', 'resource:environments'],
+    },
+    'monitoring-and-health': {
+        id: 'monitoring-and-health',
+        title: 'Monitoring and health',
+        domain: 'jobs-observability',
+        related: ['concept:how-async-work-runs'],
+    },
+    'organizations-and-users': {
+        id: 'organizations-and-users',
+        title: 'Organizations and users',
+        domain: 'administration',
+        related: [
+            'concept:the-permission-model',
+            'concept:platform-architecture',
+            'concept:cost-accounting',
+            'resource:environments',
+        ],
+    },
+    'platform-architecture': {
+        id: 'platform-architecture',
+        title: 'Platform architecture',
+        domain: 'platform',
+        related: [
+            'concept:problem-lifecycle',
+            'concept:run-config-roles',
+            'concept:how-async-work-runs',
+            'resource:environments',
+            'resource:problems',
+        ],
+    },
+    'problem-files': {
+        id: 'problem-files',
+        title: 'Problem files',
+        domain: 'problems',
+        related: [
+            'recipe:attach-a-file',
+            'recipe:detach-and-download-a-file',
+            'recipe:set-gold-standard-and-tags',
+            'resource:files',
+            'concept:environment-files',
+        ],
+    },
+    'problem-lifecycle': {
+        id: 'problem-lifecycle',
+        title: 'The problem lifecycle',
+        domain: 'problems',
+        related: ['resource:problems', 'resource:problem-versions', 'resource:problem-runs'],
+    },
+    'public-environments': {
+        id: 'public-environments',
+        title: 'Public environments',
+        domain: 'integrations',
+        related: ['concept:organizations-and-users', 'resource:environments'],
+    },
+    'quality-gates-and-qa': {
+        id: 'quality-gates-and-qa',
+        title: 'Quality gates and QA',
+        domain: 'review-qa',
+        related: ['recipe:gate-a-stage-on-qa', 'resource:qa', 'resource:qa-gates'],
+    },
+    'run-config-anatomy': {
+        id: 'run-config-anatomy',
+        title: 'Anatomy of a run config',
+        domain: 'run-configs',
+        related: [
+            'concept:run-config-roles',
+            'concept:verifying-with-the-probe',
+            'concept:secrets-and-credentials',
+            'recipe:configure-a-run-config',
+            'recipe:create-a-claude-code-run-config',
+            'resource:run-configs',
+        ],
+    },
+    'run-config-roles': {
+        id: 'run-config-roles',
+        title: 'Run config roles and scopes',
+        domain: 'run-configs',
+        related: [
+            'concept:snapshot-solvers-on-compute',
+            'resource:run-configs',
+            'recipe:configure-a-run-config',
+            'recipe:bind-a-run-config-to-an-environment',
+        ],
+    },
+    'runs-transcripts-and-results': {
+        id: 'runs-transcripts-and-results',
+        title: 'Runs, transcripts, and results',
+        domain: 'jobs-observability',
+        related: [
+            'recipe:inspect-run-history-and-transcript',
+            'resource:transcripts',
+            'resource:problem-runs',
+            'concept:how-async-work-runs',
+        ],
+    },
+    'secrets-and-credentials': {
+        id: 'secrets-and-credentials',
+        title: 'Secrets and credentials',
+        domain: 'administration',
+        related: [
+            'recipe:attach-a-customer-secret',
+            'concept:run-config-anatomy',
+            'resource:run-configs',
+        ],
+    },
+    'snapshot-solvers-on-compute': {
+        id: 'snapshot-solvers-on-compute',
+        title: 'Snapshot solvers and compute runs',
+        domain: 'run-configs',
+        related: [
+            'concept:run-config-roles',
+            'concept:computes',
+            'concept:grading-strategies',
+            'resource:run-configs',
+            'recipe:create-and-grade-a-problem',
+            'recipe:run-a-job-and-read-results',
+        ],
+    },
+    tags: {
+        id: 'tags',
+        title: 'Tags',
+        domain: 'problems',
+        related: ['recipe:set-gold-standard-and-tags', 'resource:problems'],
+    },
+    'the-cost-explorer': {
+        id: 'the-cost-explorer',
+        title: 'The cost explorer',
+        domain: 'cost',
+        related: ['concept:cost-accounting', 'resource:cost-limits'],
+    },
+    'the-permission-model': {
+        id: 'the-permission-model',
+        title: 'The permission model',
+        domain: 'administration',
+        related: ['concept:organizations-and-users', 'concept:authentication-and-access'],
+    },
+    'the-synthesizer': {
+        id: 'the-synthesizer',
+        title: 'The synthesizer',
+        domain: 'synthesizer',
+        related: [
+            'resource:synthesizer',
+            'recipe:improve-a-problem-with-the-synthesizer',
+            'recipe:cancel-a-synthesizer-run',
+            'concept:run-config-roles',
+        ],
+    },
+    'the-taiga-integration': {
+        id: 'the-taiga-integration',
+        title: 'The Taiga integration',
+        domain: 'integrations',
+        related: ['resource:environments', 'resource:jobs'],
+    },
+    'verifying-with-the-probe': {
+        id: 'verifying-with-the-probe',
+        title: 'Verifying a run config with the probe',
+        domain: 'run-configs',
+        related: ['concept:run-config-roles', 'concept:run-config-anatomy', 'resource:run-configs'],
+    },
+    'worldsim-authoring': {
+        id: 'worldsim-authoring',
+        title: 'Worldsim authoring',
+        domain: 'authoring-aids',
+        related: ['concept:run-config-anatomy'],
+    },
+};

package/dist/reference/concepts-schema.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+/** The leading `---`…`---` YAML block of a concept page. */
+export declare const ConceptFrontmatterSchema: z.ZodObject<{
+    title: z.ZodString;
+    domain: z.ZodString;
+    related: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type ConceptFrontmatter = z.infer<typeof ConceptFrontmatterSchema>;
+/** One concept in the generated reference, keyed by id (= the markdown filename stem). */
+export declare const ConceptReferenceEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    domain: z.ZodString;
+    related: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type ConceptReferenceEntry = z.infer<typeof ConceptReferenceEntrySchema>;

package/dist/reference/concepts-schema.js

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+// Types for **concept pages** — the cross-cutting Explanation quadrant of the
+// docs. A concept explains an idea that spans more than one resource (e.g. the
+// problem lifecycle, how grading fits together), as opposed to a per-noun resource
+// intro (which stays spec-embedded). Each is authored as a frontmatter markdown
+// file under `frontend/public/docs/concepts/<id>.md`; `yarn dx concepts:generate`
+// reads the frontmatter into `CONCEPT_REFERENCE` (the nav index). The prose is the
+// single source — the frontend fetches the `.md` directly to render the body.
+//
+// Two layers (mirrors recipes-schema):
+//   1. Authoring frontmatter (`ConceptFrontmatter`) — what an author writes.
+//   2. The generated reference entry (`ConceptReferenceEntry`) — what the
+//      generator emits and the frontend nav + P2 search index consume.
+/** The leading `---`…`---` YAML block of a concept page. */
+export const ConceptFrontmatterSchema = z
+    .object({
+    // Sentence-case nav + page title.
+    title: z.string().min(1),
+    // Canonical product domain (a `DomainId`) grouping the page in the Explanation
+    // nav. Kept a plain string here; membership in `DOMAINS` is enforced fail-fast
+    // by `concepts:generate` (this schema is loaded as source at codegen time, so
+    // it can only import npm deps — not the domains module).
+    domain: z.string().min(1),
+    // Slugs of related docs entries (resource hubs, recipes, other concepts).
+    // Collected + referential-integrity-checked by `dx docs:check` now; it will
+    // surface as a "Related" section in the P2 discovery layer (not yet rendered).
+    related: z.array(z.string()).default([]),
+})
+    .strict();
+/** One concept in the generated reference, keyed by id (= the markdown filename stem). */
+export const ConceptReferenceEntrySchema = z
+    .object({
+    // Stable id = the `.md` filename stem; the docs nav slug is `concept:<id>`.
+    id: z.string(),
+    title: z.string(),
+    domain: z.string(),
+    related: z.array(z.string()),
+})
+    .strict();

package/dist/reference/concepts.d.ts

@@ -0,0 +1,15 @@
+import type { DomainId } from './domains.js';
+export type RelatedReference = `concept:${string}` | `recipe:${string}` | `resource:${string}` | `tutorial:${string}`;
+/** Typed metadata for one Explanation page. Markdown supplies optional prose only. */
+export interface ConceptReferenceEntry {
+    readonly id: string;
+    readonly title: string;
+    readonly domain: DomainId;
+    readonly related: readonly RelatedReference[];
+}
+/**
+ * Authoritative concept registry. A concept exists because it is declared here;
+ * an optional `apps/recursion/web/public/docs/concepts/<id>.md` file enriches its rendered
+ * body and search text but never controls membership or metadata.
+ */
+export declare const CONCEPT_REFERENCE: Readonly<Record<string, ConceptReferenceEntry>>;