scorecard-ai 1.0.0-alpha.6 → 1.0.0-alpha.7

package/resources/testsets.mjs

@@ -6,6 +6,28 @@ export class Testsets extends APIResource {
     /**
      * Create a new Testset for a Project. The Testset will be created in the Project
      * specified in the path.
+     *
+     * @example
+     * ```ts
+     * const testset = await client.testsets.create('314', {
+     *   description: 'Testset for long context Q&A chatbot.',
+     *   fieldMapping: {
+     *     inputs: ['question'],
+     *     labels: ['idealAnswer'],
+     *     metadata: [],
+     *   },
+     *   jsonSchema: {
+     *     type: 'object',
+     *     properties: {
+     *       question: { type: 'string' },
+     *       idealAnswer: { type: 'string' },
+     *       provenance: { type: 'string' },
+     *       geo: { type: 'string' },
+     *     },
+     *   },
+     *   name: 'Long Context Q&A',
+     * });
+     * ```
      */
     create(projectID, body, options) {
         return this._client.post(path `/projects/${projectID}/testsets`, { body, ...options });
@@ -23,12 +45,28 @@ export class Testsets extends APIResource {
      *   updated schema
      * - For complete control, provide both schema and fieldMapping when updating the
      *   schema
+     *
+     * @example
+     * ```ts
+     * const testset = await client.testsets.update('246', {
+     *   description: 'Updated description for the Q&A Testset.',
+     *   name: 'Updated Q&A Testset',
+     * });
+     * ```
      */
     update(testsetID, body = {}, options) {
         return this._client.patch(path `/testsets/${testsetID}`, { body, ...options });
     }
     /**
      * Retrieve a paginated list of Testsets belonging to a Project.
+     *
+     * @example
+     * ```ts
+     * // Automatically fetches more pages as needed.
+     * for await (const testset of client.testsets.list('314')) {
+     *   // ...
+     * }
+     * ```
      */
     list(projectID, query = {}, options) {
         return this._client.getAPIList(path `/projects/${projectID}/testsets`, (PaginatedResponse), {
@@ -38,12 +76,22 @@ export class Testsets extends APIResource {
     }
     /**
      * Delete Testset
+     *
+     * @example
+     * ```ts
+     * const testset = await client.testsets.delete('246');
+     * ```
      */
     delete(testsetID, options) {
         return this._client.delete(path `/testsets/${testsetID}`, options);
     }
     /**
      * Get Testset by ID
+     *
+     * @example
+     * ```ts
+     * const testset = await client.testsets.get('246');
+     * ```
      */
     get(testsetID, options) {
         return this._client.get(path `/testsets/${testsetID}`, options);

package/resources/testsets.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"testsets.mjs","sourceRoot":"","sources":["../src/resources/testsets.ts"],"names":[],"mappings":"AAAA,sFAAsF;OAE/E,EAAE,WAAW,EAAE;OAEf,EAAe,iBAAiB,EAAgC;OAEhE,EAAE,IAAI,EAAE;AAEf,MAAM,OAAO,QAAS,SAAQ,WAAW;IACvC;;;OAGG;IACH,MAAM,CAAC,SAAiB,EAAE,IAAyB,EAAE,OAAwB;QAC3E,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAA,aAAa,SAAS,WAAW,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACxF,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,MAAM,CACJ,SAAiB,EACjB,OAA+C,EAAE,EACjD,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAA,aAAa,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAChF,CAAC;IAED;;OAEG;IACH,IAAI,CACF,SAAiB,EACjB,QAA8C,EAAE,EAChD,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAA,aAAa,SAAS,WAAW,EAAE,CAAA,iBAA0B,CAAA,EAAE;YAChG,KAAK;YACL,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,SAAiB,EAAE,OAAwB;QAChD,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAA,aAAa,SAAS,EAAE,EAAE,OAAO,CAAC,CAAC;IACpE,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,SAAiB,EAAE,OAAwB;QAC7C,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,aAAa,SAAS,EAAE,EAAE,OAAO,CAAC,CAAC;IACjE,CAAC;CACF"}
+{"version":3,"file":"testsets.mjs","sourceRoot":"","sources":["../src/resources/testsets.ts"],"names":[],"mappings":"AAAA,sFAAsF;OAE/E,EAAE,WAAW,EAAE;OAEf,EAAe,iBAAiB,EAAgC;OAEhE,EAAE,IAAI,EAAE;AAEf,MAAM,OAAO,QAAS,SAAQ,WAAW;IACvC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,MAAM,CAAC,SAAiB,EAAE,IAAyB,EAAE,OAAwB;QAC3E,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAA,aAAa,SAAS,WAAW,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACxF,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,MAAM,CACJ,SAAiB,EACjB,OAA+C,EAAE,EACjD,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAA,aAAa,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAChF,CAAC;IAED;;;;;;;;;;OAUG;IACH,IAAI,CACF,SAAiB,EACjB,QAA8C,EAAE,EAChD,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAA,aAAa,SAAS,WAAW,EAAE,CAAA,iBAA0B,CAAA,EAAE;YAChG,KAAK;YACL,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,SAAiB,EAAE,OAAwB;QAChD,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAA,aAAa,SAAS,EAAE,EAAE,OAAO,CAAC,CAAC;IACpE,CAAC;IAED;;;;;;;OAOG;IACH,GAAG,CAAC,SAAiB,EAAE,OAAwB;QAC7C,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,aAAa,SAAS,EAAE,EAAE,OAAO,CAAC,CAAC;IACjE,CAAC;CACF"}

package/src/client.ts

@@ -23,13 +23,15 @@ import { type Fetch } from './internal/builtin-types';
 import { HeadersLike, NullableHeaders, buildHeaders } from './internal/headers';
 import { FinalRequestOptions, RequestOptions } from './internal/request-options';
 import {
+  Project,
+  ProjectCreateParams,
   ProjectListParams,
-  ProjectListResponse,
-  ProjectListResponsesPaginatedResponse,
   Projects,
+  ProjectsPaginatedResponse,
 } from './resources/projects';
 import { Record as RecordsAPIRecord, RecordCreateParams, Records } from './resources/records';
 import { Run, RunCreateParams, RunUpdateParams, RunUpdateResponse, Runs } from './resources/runs';
+import { Score, ScoreUpsertParams, Scores } from './resources/scores';
 import {
   SystemConfig,
   SystemConfigCreateParams,
@@ -236,6 +238,24 @@ export class Scorecard {
     this.apiKey = apiKey;
   }
 
+  /**
+   * Create a new client instance re-using the same options given to the current client with optional overriding.
+   */
+  withOptions(options: Partial<ClientOptions>): this {
+    return new (this.constructor as any as new (props: ClientOptions) => typeof this)({
+      ...this._options,
+      environment: options.environment ? options.environment : undefined,
+      baseURL: options.environment ? undefined : this.baseURL,
+      maxRetries: this.maxRetries,
+      timeout: this.timeout,
+      logger: this.logger,
+      logLevel: this.logLevel,
+      fetchOptions: this.fetchOptions,
+      apiKey: this.apiKey,
+      ...options,
+    });
+  }
+
   protected defaultQuery(): Record<string, string | undefined> | undefined {
     return this._options.defaultQuery;
   }
@@ -769,6 +789,7 @@ export class Scorecard {
   testcases: API.Testcases = new API.Testcases(this);
   runs: API.Runs = new API.Runs(this);
   records: API.Records = new API.Records(this);
+  scores: API.Scores = new API.Scores(this);
   systems: API.Systems = new API.Systems(this);
   systemConfigs: API.SystemConfigs = new API.SystemConfigs(this);
 }
@@ -777,6 +798,7 @@ Scorecard.Testsets = Testsets;
 Scorecard.Testcases = Testcases;
 Scorecard.Runs = Runs;
 Scorecard.Records = Records;
+Scorecard.Scores = Scores;
 Scorecard.Systems = Systems;
 Scorecard.SystemConfigs = SystemConfigs;
 export declare namespace Scorecard {
@@ -790,8 +812,9 @@ export declare namespace Scorecard {
 
   export {
     Projects as Projects,
-    type ProjectListResponse as ProjectListResponse,
-    type ProjectListResponsesPaginatedResponse as ProjectListResponsesPaginatedResponse,
+    type Project as Project,
+    type ProjectsPaginatedResponse as ProjectsPaginatedResponse,
+    type ProjectCreateParams as ProjectCreateParams,
     type ProjectListParams as ProjectListParams,
   };
 
@@ -831,6 +854,8 @@ export declare namespace Scorecard {
     type RecordCreateParams as RecordCreateParams,
   };
 
+  export { Scores as Scores, type Score as Score, type ScoreUpsertParams as ScoreUpsertParams };
+
   export {
     Systems as Systems,
     type System as System,

package/src/internal/headers.ts

@@ -71,8 +71,8 @@ function* iterateHeaders(headers: HeadersLike): IterableIterator<readonly [strin
 export const buildHeaders = (newHeaders: HeadersLike[]): NullableHeaders => {
   const targetHeaders = new Headers();
   const nullHeaders = new Set<string>();
-  const seenHeaders = new Set<string>();
   for (const headers of newHeaders) {
+    const seenHeaders = new Set<string>();
     for (const [name, value] of iterateHeaders(headers)) {
       const lowerName = name.toLowerCase();
       if (!seenHeaders.has(lowerName)) {

package/src/internal/to-file.ts

@@ -1,6 +1,6 @@
-import { type File, getFile } from './shims/file';
 import { BlobPart, getName, makeFile, isAsyncIterable } from './uploads';
 import type { FilePropertyBag } from './builtin-types';
+import { checkFileSupport } from './uploads';
 
 type BlobLikePart = string | ArrayBuffer | ArrayBufferView | BlobLike | DataView;
 
@@ -85,12 +85,14 @@ export async function toFile(
   name?: string | null | undefined,
   options?: FilePropertyBag | undefined,
 ): Promise<File> {
+  checkFileSupport();
+
   // If it's a promise, resolve it.
   value = await value;
 
   // If we've been given a `File` we don't need to do anything
   if (isFileLike(value)) {
-    if (value instanceof getFile()) {
+    if (value instanceof File) {
       return value;
     }
     return makeFile([await value.arrayBuffer()], value.name);

package/src/internal/uploads.ts

@@ -1,7 +1,6 @@
 import { type RequestOptions } from './request-options';
 import type { FilePropertyBag, Fetch } from './builtin-types';
 import type { Scorecard } from '../client';
-import { type File, getFile } from './shims/file';
 import { ReadableStreamFrom } from './shims';
 
 export type BlobPart = string | ArrayBuffer | ArrayBufferView | Blob | DataView;
@@ -12,6 +11,20 @@ interface BunFile extends Blob {
   readonly name?: string | undefined;
 }
 
+export const checkFileSupport = () => {
+  if (typeof File === 'undefined') {
+    const { process } = globalThis as any;
+    const isOldNode =
+      typeof process?.versions?.node === 'string' && parseInt(process.versions.node.split('.')) < 20;
+    throw new Error(
+      '`File` is not defined as a global, which is required for file uploads.' +
+        (isOldNode ?
+          " Update to Node 20 LTS or newer, or set `globalThis.File` to `import('node:buffer').File`."
+        : ''),
+    );
+  }
+};
+
 /**
  * Typically, this is a native "File" class.
  *
@@ -32,7 +45,7 @@ export function makeFile(
   fileName: string | undefined,
   options?: FilePropertyBag,
 ): File {
-  const File = getFile();
+  checkFileSupport();
   return new File(fileBits as any, fileName ?? 'unknown_file', options);
 }
 
@@ -125,8 +138,7 @@ export const createForm = async <T = Record<string, unknown>>(
 
 // We check for Blob not File because Bun.File doesn't inherit from File,
 // but they both inherit from Blob and have a `name` property at runtime.
-const isNamedBlob = (value: object) =>
-  value instanceof getFile() || (value instanceof Blob && 'name' in value);
+const isNamedBlob = (value: object) => value instanceof Blob && 'name' in value;
 
 const isUploadable = (value: unknown) =>
   typeof value === 'object' &&

package/src/internal/utils/uuid.ts

@@ -1,12 +1,10 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { getCrypto } from '../shims/crypto';
-
 /**
  * https://stackoverflow.com/a/2117523
  */
 export let uuid4 = function () {
-  const crypto = getCrypto();
+  const { crypto } = globalThis as any;
   if (crypto?.randomUUID) {
     uuid4 = crypto.randomUUID.bind(crypto);
     return crypto.randomUUID();

package/src/resources/index.ts

@@ -3,12 +3,14 @@
 export * from './shared';
 export {
   Projects,
-  type ProjectListResponse,
+  type Project,
+  type ProjectCreateParams,
   type ProjectListParams,
-  type ProjectListResponsesPaginatedResponse,
+  type ProjectsPaginatedResponse,
 } from './projects';
 export { Records, type Record, type RecordCreateParams } from './records';
 export { Runs, type Run, type RunUpdateResponse, type RunCreateParams, type RunUpdateParams } from './runs';
+export { Scores, type Score, type ScoreUpsertParams } from './scores';
 export {
   SystemConfigs,
   type SystemConfig,

package/src/resources/projects.ts

@@ -1,48 +1,87 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
 import { PagePromise, PaginatedResponse, type PaginatedResponseParams } from '../core/pagination';
 import { RequestOptions } from '../internal/request-options';
 
 export class Projects extends APIResource {
+  /**
+   * Create a new Project.
+   *
+   * @example
+   * ```ts
+   * const project = await client.projects.create({
+   *   description: 'This is a test project',
+   *   name: 'My Project',
+   * });
+   * ```
+   */
+  create(body: ProjectCreateParams, options?: RequestOptions): APIPromise<Project> {
+    return this._client.post('/projects', { body, ...options });
+  }
+
   /**
    * Retrieve a paginated list of all Projects. Projects are ordered by creation
    * date, with oldest Projects first.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const project of client.projects.list()) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     query: ProjectListParams | null | undefined = {},
     options?: RequestOptions,
-  ): PagePromise<ProjectListResponsesPaginatedResponse, ProjectListResponse> {
-    return this._client.getAPIList('/projects', PaginatedResponse<ProjectListResponse>, {
-      query,
-      ...options,
-    });
+  ): PagePromise<ProjectsPaginatedResponse, Project> {
+    return this._client.getAPIList('/projects', PaginatedResponse<Project>, { query, ...options });
   }
 }
 
-export type ProjectListResponsesPaginatedResponse = PaginatedResponse<ProjectListResponse>;
+export type ProjectsPaginatedResponse = PaginatedResponse<Project>;
 
 /**
  * A Project in the Scorecard system.
  */
-export interface ProjectListResponse {
+export interface Project {
   /**
    * The ID of the Project.
    */
   id: string;
 
+  /**
+   * The description of the Project.
+   */
+  description: string | null;
+
   /**
    * The name of the Project.
    */
   name: string | null;
 }
 
+export interface ProjectCreateParams {
+  /**
+   * The description of the Project.
+   */
+  description: string;
+
+  /**
+   * The name of the Project.
+   */
+  name: string;
+}
+
 export interface ProjectListParams extends PaginatedResponseParams {}
 
 export declare namespace Projects {
   export {
-    type ProjectListResponse as ProjectListResponse,
-    type ProjectListResponsesPaginatedResponse as ProjectListResponsesPaginatedResponse,
+    type Project as Project,
+    type ProjectsPaginatedResponse as ProjectsPaginatedResponse,
+    type ProjectCreateParams as ProjectCreateParams,
     type ProjectListParams as ProjectListParams,
   };
 }

package/src/resources/records.ts

@@ -9,6 +9,16 @@ import { path } from '../internal/utils/path';
 export class Records extends APIResource {
   /**
    * Create a new Record in a Run.
+   *
+   * @example
+   * ```ts
+   * const record = await client.records.create('135', {
+   *   inputs: { question: 'What is the capital of France?' },
+   *   labels: { idealAnswer: 'Paris is the capital of France' },
+   *   outputs: { response: 'The capital of France is Paris.' },
+   *   testcaseId: '248',
+   * });
+   * ```
    */
   create(runID: string, body: RecordCreateParams, options?: RequestOptions): APIPromise<Record> {
     return this._client.post(path`/runs/${runID}/records`, { body, ...options });

package/src/resources/runs.ts

@@ -8,6 +8,15 @@ import { path } from '../internal/utils/path';
 export class Runs extends APIResource {
   /**
    * Create a new Run.
+   *
+   * @example
+   * ```ts
+   * const run = await client.runs.create('314', {
+   *   metricIds: ['789', '101'],
+   *   testsetId: '246',
+   *   systemConfigId: '87654321-4d3b-4ae4-8c7a-4b6e2a19ccf0',
+   * });
+   * ```
    */
   create(projectID: string, body: RunCreateParams, options?: RequestOptions): APIPromise<Run> {
     return this._client.post(path`/projects/${projectID}/runs`, { body, ...options });
@@ -15,6 +24,13 @@ export class Runs extends APIResource {
 
   /**
    * Update the status of a Run.
+   *
+   * @example
+   * ```ts
+   * const run = await client.runs.update('135', {
+   *   status: 'awaiting_scoring',
+   * });
+   * ```
    */
   update(runID: string, body: RunUpdateParams, options?: RequestOptions): APIPromise<RunUpdateResponse> {
     return this._client.patch(path`/runs/${runID}`, { body, ...options });

package/src/resources/scores.ts

@@ -0,0 +1,98 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+export class Scores extends APIResource {
+  /**
+   * Create or update a Score for a given Record and MetricConfig. If a Score with
+   * the specified Record ID and MetricConfig ID already exists, it will be updated.
+   * Otherwise, a new Score will be created. The score provided should conform to the
+   * schema defined by the MetricConfig; otherwise, validation errors will be
+   * reported.
+   *
+   * @example
+   * ```ts
+   * const score = await client.scores.upsert(
+   *   'a1b2c3d4-e5f6-7890-1234-567890abcdef',
+   *   {
+   *     recordId: '777',
+   *     score: {
+   *       value: true,
+   *       reasoning: 'The response is correct',
+   *     },
+   *   },
+   * );
+   * ```
+   */
+  upsert(metricConfigID: string, params: ScoreUpsertParams, options?: RequestOptions): APIPromise<Score> {
+    const { recordId, ...body } = params;
+    return this._client.put(path`/records/${recordId}/scores/${metricConfigID}`, { body, ...options });
+  }
+}
+
+/**
+ * A Score represents the evaluation of a Record against a specific MetricConfig.
+ * The actual `score` is stored as flexible JSON. While any JSON is accepted, it is
+ * expected to conform to the output schema defined by the MetricConfig. Any
+ * discrepancies will be noted in the `validationErrors` field, but the Score will
+ * still be stored.
+ */
+export interface Score {
+  /**
+   * The ID of the MetricConfig this Score is for.
+   */
+  metricConfigId: string;
+
+  /**
+   * The ID of the Record this Score is for.
+   */
+  recordId: string;
+
+  /**
+   * The score of the Record, as arbitrary JSON. This data should ideally conform to
+   * the output schema defined by the associated MetricConfig. If it doesn't,
+   * validation errors will be captured in the `validationErrors` field.
+   */
+  score: Record<string, unknown>;
+
+  /**
+   * Validation errors found in the Score data. If present, the Score doesn't fully
+   * conform to its MetricConfig's schema.
+   */
+  validationErrors?: Array<Score.ValidationError>;
+}
+
+export namespace Score {
+  export interface ValidationError {
+    /**
+     * Human-readable error description.
+     */
+    message: string;
+
+    /**
+     * JSON Pointer to the field with the validation error.
+     */
+    path: string;
+  }
+}
+
+export interface ScoreUpsertParams {
+  /**
+   * Path param: The ID of the Record.
+   */
+  recordId: string;
+
+  /**
+   * Body param: The score of the Record, as arbitrary JSON. This data should ideally
+   * conform to the output schema defined by the associated MetricConfig. If it
+   * doesn't, validation errors will be captured in the `validationErrors` field.
+   */
+  score: Record<string, unknown>;
+}
+
+export declare namespace Scores {
+  export { type Score as Score, type ScoreUpsertParams as ScoreUpsertParams };
+}

package/src/resources/system-configs.ts

@@ -23,6 +23,21 @@ export class SystemConfigs extends APIResource {
    * - Validation errors indicate fields that don't match the schema but don't
    *   prevent creation
    * - Having validation errors may affect how some evaluation metrics are calculated
+   *
+   * @example
+   * ```ts
+   * const systemConfig = await client.systemConfigs.create(
+   *   '12345678-0a8b-4f66-b6f3-2ddcfa097257',
+   *   {
+   *     config: {
+   *       temperature: 0.1,
+   *       maxTokens: 1024,
+   *       model: 'gpt-4-turbo',
+   *     },
+   *     name: 'Production (Low Temperature)',
+   *   },
+   * );
+   * ```
    */
   create(
     systemID: string,
@@ -37,6 +52,16 @@ export class SystemConfigs extends APIResource {
    *
    * System configurations provide concrete parameter values for a System Under Test,
    * defining exactly how the system should be configured during an evaluation run.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const systemConfig of client.systemConfigs.list(
+   *   '12345678-0a8b-4f66-b6f3-2ddcfa097257',
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     systemID: string,
@@ -51,6 +76,14 @@ export class SystemConfigs extends APIResource {
 
   /**
    * Retrieve a specific system configuration by ID.
+   *
+   * @example
+   * ```ts
+   * const systemConfig = await client.systemConfigs.get(
+   *   '87654321-4d3b-4ae4-8c7a-4b6e2a19ccf0',
+   *   { systemId: '12345678-0a8b-4f66-b6f3-2ddcfa097257' },
+   * );
+   * ```
    */
   get(
     systemConfigID: string,

package/src/resources/systems.ts

@@ -23,6 +23,45 @@ export class Systems extends APIResource {
    *
    * This separation lets you evaluate any system as a black box, focusing on its
    * interface rather than implementation details.
+   *
+   * @example
+   * ```ts
+   * const system = await client.systems.create('314', {
+   *   configSchema: {
+   *     type: 'object',
+   *     properties: {
+   *       temperature: { type: 'number' },
+   *       maxTokens: { type: 'integer' },
+   *       model: { type: 'string', enum: ['gpt-4', 'gpt-4-turbo'] },
+   *     },
+   *     required: ['model'],
+   *   },
+   *   description: 'Production chatbot powered by GPT-4',
+   *   inputSchema: {
+   *     type: 'object',
+   *     properties: {
+   *       messages: {
+   *         type: 'array',
+   *         items: {
+   *           type: 'object',
+   *           properties: {
+   *             role: { type: 'string', enum: ['system', 'user', 'assistant'] },
+   *             content: { type: 'string' },
+   *           },
+   *           required: ['role', 'content'],
+   *         },
+   *       },
+   *     },
+   *     required: ['messages'],
+   *   },
+   *   name: 'GPT-4 Chatbot',
+   *   outputSchema: {
+   *     type: 'object',
+   *     properties: { response: { type: 'string' } },
+   *     required: ['response'],
+   *   },
+   * });
+   * ```
    */
   create(projectID: string, body: SystemCreateParams, options?: RequestOptions): APIPromise<System> {
     return this._client.post(path`/projects/${projectID}/systems`, { body, ...options });
@@ -41,6 +80,18 @@ export class Systems extends APIResource {
    * - Schema updates won't invalidate existing evaluations or configurations
    * - For significant redesigns, creating a new system definition provides a cleaner
    *   separation
+   *
+   * @example
+   * ```ts
+   * const system = await client.systems.update(
+   *   '12345678-0a8b-4f66-b6f3-2ddcfa097257',
+   *   {
+   *     description:
+   *       'Updated production chatbot powered by GPT-4 Turbo',
+   *     name: 'GPT-4 Turbo Chatbot',
+   *   },
+   * );
+   * ```
    */
   update(
     systemID: string,
@@ -52,6 +103,14 @@ export class Systems extends APIResource {
 
   /**
    * Retrieve a paginated list of all systems. Systems are ordered by creation date.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const system of client.systems.list('314')) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     projectID: string,
@@ -67,6 +126,13 @@ export class Systems extends APIResource {
   /**
    * Delete a system definition by ID. This will not delete associated system
    * configurations.
+   *
+   * @example
+   * ```ts
+   * const system = await client.systems.delete(
+   *   '12345678-0a8b-4f66-b6f3-2ddcfa097257',
+   * );
+   * ```
    */
   delete(systemID: string, options?: RequestOptions): APIPromise<SystemDeleteResponse> {
     return this._client.delete(path`/systems/${systemID}`, options);
@@ -74,6 +140,13 @@ export class Systems extends APIResource {
 
   /**
    * Retrieve a specific system by ID.
+   *
+   * @example
+   * ```ts
+   * const system = await client.systems.get(
+   *   '12345678-0a8b-4f66-b6f3-2ddcfa097257',
+   * );
+   * ```
    */
   get(systemID: string, options?: RequestOptions): APIPromise<System> {
     return this._client.get(path`/systems/${systemID}`, options);