@gpt-platform/client 0.10.5 → 0.11.0

package/dist/namespaces/training.d.ts

@@ -0,0 +1,358 @@
+import type { TrainingExample, TrainingSession } from "../_internal/types.gen";
+/** Attributes accepted when creating a new training example. */
+export type CreateTrainingExampleAttributes = {
+    agent_id?: string;
+    input?: string;
+    output?: string;
+    label?: string;
+    [key: string]: unknown;
+};
+/** Attributes accepted when updating a training example (PATCH semantics). */
+export type UpdateTrainingExampleAttributes = {
+    input?: string;
+    output?: string;
+    label?: string;
+    [key: string]: unknown;
+};
+/** Attributes accepted when creating a new training session. */
+export type CreateTrainingSessionAttributes = {
+    agent_id: string;
+    model?: string;
+    epochs?: number;
+    [key: string]: unknown;
+};
+/** Attributes accepted when updating a training session (PATCH semantics). */
+export type UpdateTrainingSessionAttributes = {
+    notes?: string;
+    [key: string]: unknown;
+};
+import type { RequestOptions } from "../base-client";
+import { RequestBuilder } from "../request-builder";
+/**
+ * Creates the `training` namespace, providing methods for managing training
+ * examples and training sessions across the workspace.
+ *
+ * Training examples are labeled input/output pairs used to teach agents how to
+ * respond correctly. Training sessions are batch fine-tuning or in-context
+ * learning runs that consume a set of examples and update an agent's behavior.
+ *
+ * This namespace surfaces workspace-level access to both resources. For
+ * agent-scoped training operations (e.g. examples belonging to a specific agent),
+ * see `client.agents.training` instead.
+ *
+ * @param rb - The `RequestBuilder` instance bound to the authenticated client.
+ * @returns An object containing the `examples` and `sessions` sub-namespaces.
+ *
+ * @example
+ * const client = new GptClient({ apiKey: 'sk_app_...' });
+ * const examples = await client.training.examples.listAll();
+ * console.log(`Workspace training examples: ${examples.length}`);
+ */
+export declare function createTrainingNamespace(rb: RequestBuilder): {
+    /**
+     * Sub-namespace for managing individual training examples.
+     *
+     * Training examples are the raw labeled data that drives agent learning.
+     * Each example pairs an `input` (what the user or document provides) with
+     * an expected `output` (what the agent should produce). High-quality,
+     * diverse examples improve consistency and accuracy.
+     *
+     * @example
+     * const client = new GptClient({ apiKey: 'sk_app_...' });
+     * const example = await client.training.examples.create({
+     *   agent_id: 'agt_01HXYZ...',
+     *   input: 'What is the due date?',
+     *   output: '2026-04-15',
+     * });
+     */
+    examples: {
+        /**
+         * Permanently deletes a training example by its ID.
+         *
+         * This action is irreversible. The example will be removed from the agent's
+         * training dataset and will not be included in any future teach or fine-tune
+         * runs. Examples already incorporated into a completed training session are
+         * not retroactively affected.
+         *
+         * @param id - The UUID of the training example to delete.
+         * @param options - Optional request options.
+         * @returns A promise that resolves to `true` on successful deletion.
+         *
+         * @example
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * await client.training.examples.delete('tex_01HXYZ...');
+         */
+        delete: (id: string, options?: RequestOptions) => Promise<true>;
+        /**
+         * Lists training examples in the workspace with optional pagination controls.
+         *
+         * Returns a single page of examples. Use {@link listAll} to fetch every
+         * example across all pages automatically.
+         *
+         * @param options - Optional pagination and request options.
+         * @param options.page - The page number to fetch (1-based). Defaults to 1.
+         * @param options.pageSize - Number of examples per page. Defaults to the server default.
+         * @returns A promise that resolves to an array of `TrainingExample` objects.
+         *
+         * @example
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const page1 = await client.training.examples.list({ page: 1, pageSize: 25 });
+         */
+        list: (options?: {
+            page?: number;
+            pageSize?: number;
+        } & RequestOptions) => Promise<TrainingExample[]>;
+        /**
+         * Fetches all training examples in the workspace by transparently paginating
+         * through every page until exhausted.
+         *
+         * This is a convenience wrapper that handles cursor/page management
+         * automatically. For large datasets, prefer {@link list} with explicit
+         * pagination to control memory usage.
+         *
+         * @param options - Optional request options.
+         * @returns A promise that resolves to a flat array of all `TrainingExample` objects.
+         *
+         * @example
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const allExamples = await client.training.examples.listAll();
+         * console.log(`Total examples: ${allExamples.length}`);
+         */
+        listAll: (options?: RequestOptions) => Promise<TrainingExample[]>;
+        /**
+         * Fetches a single training example by its ID.
+         *
+         * @param id - The UUID of the training example to retrieve.
+         * @param options - Optional request options.
+         * @returns A promise that resolves to the full `TrainingExample` object.
+         *
+         * @example
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const example = await client.training.examples.get('tex_01HXYZ...');
+         * console.log(`Input: ${example.attributes.input}`);
+         * console.log(`Expected output: ${example.attributes.output}`);
+         */
+        get: (id: string, options?: RequestOptions) => Promise<TrainingExample>;
+        /**
+         * Creates a new training example for an agent.
+         *
+         * Provide at minimum `agent_id`, `input`, and `output`. Additional
+         * metadata fields such as `label`, `weight`, `source_document_id`, or
+         * `notes` may be included in `attributes` to help organize and prioritize
+         * examples.
+         *
+         * @param attributes - The training example attributes. Must include at least
+         *   `agent_id` (string), `input` (string), and `output` (string).
+         * @param options - Optional request options.
+         * @returns A promise that resolves to the newly created `TrainingExample` object.
+         *
+         * @example
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         *
+         * const example = await client.training.examples.create({
+         *   agent_id: 'agt_01HXYZ...',
+         *   input: 'What is the subtotal before tax?',
+         *   output: '$980.00',
+         *   label: 'currency-extraction',
+         * });
+         * console.log(`Created: ${example.id}`);
+         */
+        create: (attributes: CreateTrainingExampleAttributes, options?: RequestOptions) => Promise<TrainingExample>;
+        /**
+         * Updates one or more attributes of an existing training example.
+         *
+         * Only the fields provided in `attributes` are changed; all other fields
+         * remain unchanged (PATCH semantics). Commonly used to correct the expected
+         * `output` of an example after a human review.
+         *
+         * @param id - The UUID of the training example to update.
+         * @param attributes - A partial map of attributes to update
+         *   (e.g. `{ output: 'Corrected answer', label: 'reviewed' }`).
+         * @param options - Optional request options.
+         * @returns A promise that resolves to the updated `TrainingExample` object.
+         *
+         * @example
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         *
+         * const updated = await client.training.examples.update('tex_01HXYZ...', {
+         *   output: '$1,100.00',
+         *   label: 'reviewed',
+         * });
+         */
+        update: (id: string, attributes: UpdateTrainingExampleAttributes, options?: RequestOptions) => Promise<TrainingExample>;
+        /**
+         * Creates multiple training examples in a single request.
+         *
+         * More efficient than issuing individual `create` calls in a loop.
+         * Useful when ingesting a batch of labeled examples from an external
+         * dataset, annotation tool export, or historical conversation log.
+         *
+         * @param options - Optional request options.
+         * @returns A promise that resolves to the created `TrainingExample` records.
+         *
+         * @example
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const result = await client.training.examples.bulkCreate();
+         */
+        bulkCreate: (options?: RequestOptions) => Promise<TrainingExample>;
+        /**
+         * Deletes multiple training examples in a single request.
+         *
+         * More efficient than issuing individual `delete` calls in a loop.
+         * Useful for pruning a large set of outdated or low-quality examples
+         * identified during a training analysis run.
+         *
+         * @param options - Optional request options.
+         * @returns A promise that resolves once all targeted examples are deleted.
+         *
+         * @example
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * await client.training.examples.bulkDestroy();
+         */
+        bulkDestroy: (options?: RequestOptions) => Promise<TrainingExample>;
+        /**
+         * Searches for training examples semantically similar to a query vector.
+         *
+         * Uses vector similarity (pgvector cosine distance) to find examples whose
+         * `input` embeddings are closest to the provided query. Useful for finding
+         * near-duplicate examples before adding new ones, or for discovering which
+         * examples are most relevant to a given input at inference time.
+         *
+         * @param options - Optional request options. Pass the query vector and
+         *   similarity threshold via request body options.
+         * @returns A promise that resolves to an array of semantically similar
+         *   `TrainingExample` objects, ordered by descending similarity.
+         *
+         * @example
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const similar = await client.training.examples.searchByVector();
+         * console.log(`Found ${similar.length} similar examples`);
+         */
+        searchByVector: (options?: RequestOptions) => Promise<TrainingExample>;
+    };
+    /**
+     * Sub-namespace for managing training sessions.
+     *
+     * Training sessions are batch fine-tuning or in-context learning runs
+     * associated with a specific agent. Each session consumes a snapshot of the
+     * agent's training examples and produces an updated model or prompt
+     * configuration. Sessions provide an audit trail of when and how an agent
+     * was trained, along with metrics such as loss, accuracy, and example count.
+     *
+     * @example
+     * const client = new GptClient({ apiKey: 'sk_app_...' });
+     * const sessions = await client.training.sessions.listAllAgentsSessions();
+     * console.log(`Training sessions: ${sessions.length}`);
+     */
+    sessions: {
+        /**
+         * Lists training sessions for a specific agent with optional pagination controls.
+         *
+         * Returns a single page of sessions. Use {@link listAllAgentsSessions} to
+         * fetch every session across all pages automatically.
+         *
+         * @param options - Optional pagination and request options.
+         * @param options.page - The page number to fetch (1-based). Defaults to 1.
+         * @param options.pageSize - Number of sessions per page.
+         * @returns A promise that resolves to an array of `TrainingSession` objects.
+         *
+         * @example
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const sessions = await client.training.sessions.listAgentsSessions({ pageSize: 10 });
+         */
+        listAgentsSessions: (options?: {
+            page?: number;
+            pageSize?: number;
+        } & RequestOptions) => Promise<TrainingSession[]>;
+        /**
+         * Fetches all training sessions for an agent by transparently paginating
+         * through every page until exhausted.
+         *
+         * @param options - Optional request options.
+         * @returns A promise that resolves to a flat array of all `TrainingSession` objects.
+         *
+         * @example
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const allSessions = await client.training.sessions.listAllAgentsSessions();
+         * const latest = allSessions.at(-1);
+         * console.log(`Latest session status: ${latest?.attributes.status}`);
+         */
+        listAllAgentsSessions: (options?: RequestOptions) => Promise<TrainingSession[]>;
+        /**
+         * Fetches a single training session by its ID.
+         *
+         * @param id - The UUID of the training session to retrieve.
+         * @param options - Optional request options.
+         * @returns A promise that resolves to the full `TrainingSession` object,
+         *   including status, metrics, and associated agent ID.
+         *
+         * @example
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const session = await client.training.sessions.get('tsn_01HXYZ...');
+         * console.log(`Status: ${session.attributes.status}`);
+         * console.log(`Examples used: ${session.attributes.example_count}`);
+         */
+        get: (id: string, options?: RequestOptions) => Promise<TrainingSession>;
+        /**
+         * Creates and enqueues a new training session for an agent.
+         *
+         * Initiates a training run that will consume the agent's current set of
+         * training examples. The session is created in a `pending` or `running`
+         * state and transitions to `completed` or `failed` asynchronously. Poll
+         * `sessions.get(id)` to monitor progress.
+         *
+         * @param attributes - Session configuration attributes. Must include at least
+         *   `agent_id` (string). Optional fields include `model`, `epochs`,
+         *   `learning_rate`, and `example_filter`.
+         * @param options - Optional request options.
+         * @returns A promise that resolves to the newly created `TrainingSession` object.
+         *
+         * @example
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         *
+         * const session = await client.training.sessions.create({
+         *   agent_id: 'agt_01HXYZ...',
+         *   epochs: 3,
+         * });
+         * console.log(`Session started: ${session.id} (${session.attributes.status})`);
+         */
+        create: (attributes: CreateTrainingSessionAttributes, options?: RequestOptions) => Promise<TrainingSession>;
+        /**
+         * Permanently deletes a training session by its ID.
+         *
+         * Deleting a completed session removes its metrics and audit record but
+         * does not revert any model changes that the session produced. Running or
+         * pending sessions should be cancelled before deletion.
+         *
+         * @param id - The UUID of the training session to delete.
+         * @param options - Optional request options.
+         * @returns A promise that resolves to `true` on successful deletion.
+         *
+         * @example
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * await client.training.sessions.delete('tsn_01HXYZ...');
+         */
+        delete: (id: string, options?: RequestOptions) => Promise<true>;
+        /**
+         * Updates one or more attributes of an existing training session for an agent.
+         *
+         * Typically used to update session metadata such as `notes` or `label` after
+         * the session completes. Configuration fields (epochs, learning rate) cannot
+         * be changed after a session has started.
+         *
+         * @param agentId - The UUID of the agent the session belongs to.
+         * @param attributes - A partial map of session attributes to update.
+         * @param options - Optional request options.
+         * @returns A promise that resolves to the updated `TrainingSession` object.
+         *
+         * @example
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         *
+         * const updated = await client.training.sessions.update('agt_01HXYZ...', {
+         *   notes: 'Post-review fine-tune — improved currency extraction accuracy',
+         * });
+         */
+        update: (agentId: string, attributes: UpdateTrainingSessionAttributes, options?: RequestOptions) => Promise<TrainingSession>;
+    };
+};
+//# sourceMappingURL=training.d.ts.map

package/dist/namespaces/training.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"training.d.ts","sourceRoot":"","sources":["../../src/namespaces/training.ts"],"names":[],"mappings":"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"}