langtrain 0.1.25 → 0.2.0

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+import { AxiosInstance } from 'axios';
 import * as langvision from 'langvision';
 export { langvision as Vision };
 export { Langvision } from 'langvision';
@@ -5,17 +6,87 @@ import * as langtune from 'langtune';
 export { langtune as Text };
 export { Langtune } from 'langtune';
 
+/** Configuration for all Langtrain SDK clients. */
+interface ClientConfig {
+    /** Your Langtrain API key. */
+    apiKey: string;
+    /** Override the default API base URL. */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000). */
+    timeout?: number;
+    /** Maximum number of retries on transient errors (default: 2). */
+    maxRetries?: number;
+}
+declare class LangtrainError extends Error {
+    /** HTTP status code, if available. */
+    readonly status?: number;
+    /** Raw error code from the API. */
+    readonly code?: string;
+    /** The original error, if any. */
+    readonly cause?: Error;
+    constructor(message: string, options?: {
+        status?: number;
+        code?: string;
+        cause?: Error;
+    });
+    /** True if the error was a network/timeout issue (retryable). */
+    get isTransient(): boolean;
+    /** True if the API key was invalid or expired. */
+    get isAuthError(): boolean;
+    /** True if a resource was not found. */
+    get isNotFound(): boolean;
+    /** True if rate-limited. */
+    get isRateLimited(): boolean;
+}
+/**
+ * BaseClient — abstract foundation for all Langtrain SDK clients.
+ *
+ * Provides:
+ * - Shared axios instance with API key auth
+ * - Configurable timeouts
+ * - Automatic retry with exponential backoff on transient errors
+ * - Structured error wrapping (LangtrainError)
+ */
+declare abstract class BaseClient {
+    protected readonly http: AxiosInstance;
+    protected readonly maxRetries: number;
+    constructor(config: ClientConfig);
+    /**
+     * Execute a request with automatic retry and error wrapping.
+     */
+    protected request<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Wrap any thrown error into a structured LangtrainError.
+     */
+    private wrapError;
+    private sleep;
+}
+
 interface Agent {
     id: string;
     workspace_id: string;
     name: string;
     description?: string;
     model_id?: string;
-    config: Record<string, unknown>;
+    config: AgentConfig;
     is_active: boolean;
     created_at: string;
     updated_at: string;
 }
+interface AgentConfig {
+    system_prompt?: string;
+    temperature?: number;
+    max_tokens?: number;
+    tools?: string[];
+    [key: string]: unknown;
+}
+interface AgentCreate {
+    workspace_id: string;
+    name: string;
+    description?: string;
+    model_id?: string;
+    config?: AgentConfig;
+}
 interface AgentRun {
     id: string;
     conversation_id: string;
@@ -25,35 +96,33 @@ interface AgentRun {
     latency_ms: number;
     tokens_used: number;
 }
-declare class AgentClient {
-    private config;
-    private client;
-    constructor(config: {
-        apiKey: string;
-        baseUrl?: string;
-    });
+/**
+ * Client for managing AI agents — create, execute, and monitor.
+ *
+ * @example
+ * ```ts
+ * const agents = new AgentClient({ apiKey: 'lt_...' });
+ * const list = await agents.list();
+ * const result = await agents.execute(list[0].id, 'Hello!');
+ * ```
+ */
+declare class AgentClient extends BaseClient {
+    constructor(config: ClientConfig);
+    /** List all agents, optionally filtered by workspace. */
     list(workspaceId?: string): Promise<Agent[]>;
+    /** Get a single agent by ID. */
     get(agentId: string): Promise<Agent>;
+    /** Create a new agent. */
     create(agent: AgentCreate): Promise<Agent>;
+    /** Delete an agent by ID. */
     delete(agentId: string): Promise<void>;
-    execute(agentId: string, input: any, messages?: any[], conversationId?: string): Promise<AgentRun>;
-    logs(agentId: string, limit?: number): Promise<{
-        logs: string[];
-    }>;
-}
-interface AgentConfig {
-    system_prompt?: string;
-    temperature?: number;
-    max_tokens?: number;
-    tools?: string[];
-    [key: string]: any;
-}
-interface AgentCreate {
-    workspace_id: string;
-    name: string;
-    description?: string;
-    model_id?: string;
-    config?: AgentConfig;
+    /** Execute an agent with input and optional conversation context. */
+    execute(agentId: string, input: string, messages?: Array<{
+        role: string;
+        content: string;
+    }>, conversationId?: string): Promise<AgentRun>;
+    /** Fetch recent logs for an agent. */
+    logs(agentId: string, limit?: number): Promise<string[]>;
 }
 
 type agent_Agent = Agent;
@@ -66,15 +135,6 @@ declare namespace agent {
   export { type agent_Agent as Agent, agent_AgentClient as AgentClient, type agent_AgentConfig as AgentConfig, type agent_AgentCreate as AgentCreate, type agent_AgentRun as AgentRun };
 }
 
-declare class FileClient {
-    private client;
-    constructor(config: {
-        apiKey: string;
-        baseUrl?: string;
-    });
-    upload(file: any, workspaceId?: string, purpose?: string): Promise<FileResponse>;
-    list(workspaceId: string, purpose?: string): Promise<FileResponse[]>;
-}
 interface FileResponse {
     id: string;
     filename: string;
@@ -82,17 +142,33 @@ interface FileResponse {
     bytes: number;
     created_at: string;
 }
+/**
+ * Client for managing file uploads (datasets for fine-tuning).
+ *
+ * @example
+ * ```ts
+ * const files = new FileClient({ apiKey: 'lt_...' });
+ * const uploaded = await files.upload('./data.jsonl');
+ * ```
+ */
+declare class FileClient extends BaseClient {
+    constructor(config: ClientConfig);
+    /** Upload a file from a local path. */
+    upload(filePath: string, workspaceId?: string, purpose?: string): Promise<FileResponse>;
+    /** List files in a workspace, optionally filtered by purpose. */
+    list(workspaceId: string, purpose?: string): Promise<FileResponse[]>;
+    /** Delete a file by ID. */
+    delete(fileId: string): Promise<void>;
+}
 
-declare class TrainingClient {
-    private client;
-    constructor(config: {
-        apiKey: string;
-        baseUrl?: string;
-    });
-    createJob(job: FineTuneJobCreate): Promise<FineTuneJobResponse>;
-    listJobs(workspaceId: string, limit?: number): Promise<FineTuneJobList>;
-    getJob(jobId: string): Promise<FineTuneJobResponse>;
-    cancelJob(jobId: string): Promise<FineTuneJobResponse>;
+interface FineTuneHyperparameters {
+    epochs?: number;
+    learning_rate?: number;
+    batch_size?: number;
+    warmup_steps?: number;
+    lora_rank?: number;
+    lora_alpha?: number;
+    weight_decay?: number;
 }
 interface FineTuneJobCreate {
     name?: string;
@@ -102,40 +178,61 @@ interface FineTuneJobCreate {
     guardrail_id?: string;
     task?: 'text' | 'vision';
     training_method?: 'sft' | 'dpo' | 'rlhf' | 'lora' | 'qlora';
-    hyperparameters?: any;
-    [key: string]: any;
+    hyperparameters?: FineTuneHyperparameters;
 }
 interface FineTuneJobResponse {
     id: string;
     name: string;
-    status: string;
+    status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
     progress: number;
     error_message?: string;
+    base_model?: string;
+    training_method?: string;
     created_at: string;
-    [key: string]: any;
+    started_at?: string;
+    completed_at?: string;
 }
 interface FineTuneJobList {
     data: FineTuneJobResponse[];
     has_more: boolean;
 }
-
-declare class SubscriptionClient {
-    private client;
-    constructor(config: {
-        apiKey: string;
-        baseUrl?: string;
-    });
-    getStatus(): Promise<SubscriptionInfo>;
-    checkFeature(feature: string): Promise<FeatureCheck>;
-    getLimits(): Promise<any>;
+/**
+ * Client for managing fine-tuning training jobs.
+ *
+ * @example
+ * ```ts
+ * const training = new TrainingClient({ apiKey: 'lt_...' });
+ * const job = await training.createJob({
+ *     base_model: 'meta-llama/Llama-3.1-8B',
+ *     dataset_id: 'file_abc123',
+ *     training_method: 'lora',
+ * });
+ * ```
+ */
+declare class TrainingClient extends BaseClient {
+    constructor(config: ClientConfig);
+    /** Create a new fine-tuning job. */
+    createJob(job: FineTuneJobCreate): Promise<FineTuneJobResponse>;
+    /** List fine-tuning jobs for a workspace. */
+    listJobs(workspaceId: string, limit?: number): Promise<FineTuneJobList>;
+    /** Get a specific job by ID. */
+    getJob(jobId: string): Promise<FineTuneJobResponse>;
+    /** Cancel a running job. */
+    cancelJob(jobId: string): Promise<FineTuneJobResponse>;
 }
+
 interface SubscriptionInfo {
     is_active: boolean;
     plan: string;
     plan_name: string;
     expires_at?: string;
     features: string[];
-    limits: any;
+    limits: Record<string, number>;
+    usage?: {
+        tokensUsedThisMonth?: number;
+        tokenLimit?: number;
+        apiCalls?: number;
+    };
 }
 interface FeatureCheck {
     feature: string;
@@ -143,6 +240,25 @@ interface FeatureCheck {
     limit?: number;
     used?: number;
 }
+/**
+ * Client for checking subscription status and feature access.
+ *
+ * @example
+ * ```ts
+ * const sub = new SubscriptionClient({ apiKey: 'lt_...' });
+ * const status = await sub.getStatus();
+ * console.log(status.plan); // 'pro'
+ * ```
+ */
+declare class SubscriptionClient extends BaseClient {
+    constructor(config: ClientConfig);
+    /** Get current subscription status. */
+    getStatus(): Promise<SubscriptionInfo>;
+    /** Check if a specific feature is available on the current plan. */
+    checkFeature(feature: string): Promise<FeatureCheck>;
+    /** Get usage analytics for the current subscription. */
+    getLimits(): Promise<Record<string, unknown>>;
+}
 
 interface Permission {
     id: string;
@@ -155,7 +271,7 @@ interface Permission {
     allow_view: boolean;
     allow_fine_tuning: boolean;
     organization: string;
-    group: any;
+    group: string | null;
     is_blocking: boolean;
 }
 interface Model {
@@ -168,13 +284,21 @@ interface Model {
     parent: string | null;
     task?: 'text' | 'vision' | 'agent';
 }
-declare class ModelClient {
-    private client;
-    constructor(config: {
-        apiKey: string;
-        baseUrl?: string;
-    });
-    list(task?: string): Promise<Model[]>;
+/**
+ * Client for browsing available base models.
+ *
+ * @example
+ * ```ts
+ * const models = new ModelClient({ apiKey: 'lt_...' });
+ * const all = await models.list();
+ * const textModels = await models.list('text');
+ * ```
+ */
+declare class ModelClient extends BaseClient {
+    constructor(config: ClientConfig);
+    /** List available models, optionally filtered by task type. */
+    list(task?: 'text' | 'vision' | 'agent'): Promise<Model[]>;
+    /** Get a specific model by ID. */
     get(modelId: string): Promise<Model>;
 }
 
@@ -191,15 +315,23 @@ interface Secret {
     created_at: string;
     updated_at: string;
 }
-declare class SecretClient {
-    private config;
-    private client;
-    constructor(config: {
-        apiKey: string;
-        baseUrl?: string;
-    });
+/**
+ * Client for managing workspace secrets and environment variables.
+ *
+ * @example
+ * ```ts
+ * const secrets = new SecretClient({ apiKey: 'lt_...' });
+ * await secrets.set('OPENAI_KEY', 'sk-...');
+ * const all = await secrets.list();
+ * ```
+ */
+declare class SecretClient extends BaseClient {
+    constructor(config: ClientConfig);
+    /** List all secrets in a workspace. Values are redacted. */
     list(workspaceId?: string): Promise<Secret[]>;
+    /** Set (create or update) a secret. */
     set(key: string, value: string, workspaceId?: string): Promise<Secret>;
+    /** Delete a secret by key. */
     delete(key: string, workspaceId?: string): Promise<void>;
 }
 
@@ -235,18 +367,75 @@ interface GuardrailCreate {
     description?: string;
     config: GuardrailConfig;
 }
-declare class GuardrailClient {
-    private config;
-    private client;
-    constructor(config: {
-        apiKey: string;
-        baseUrl?: string;
-    });
+interface GuardrailApplyResult {
+    total_rows: number;
+    passed: number;
+    failed: number;
+    violations: Array<{
+        row: number;
+        rule: string;
+        message: string;
+    }>;
+}
+/**
+ * Client for managing data guardrails (PII, profanity, length, regex).
+ *
+ * @example
+ * ```ts
+ * const guardrails = new GuardrailClient({ apiKey: 'lt_...' });
+ * const rule = await guardrails.create({
+ *     name: 'PII Filter',
+ *     config: { pii_enabled: true, profanity_enabled: false },
+ * });
+ * ```
+ */
+declare class GuardrailClient extends BaseClient {
+    constructor(config: ClientConfig);
+    /** List guardrails, optionally filtered by workspace. */
     list(workspaceId?: string): Promise<Guardrail[]>;
+    /** Get a guardrail by ID. */
     get(guardrailId: string): Promise<Guardrail>;
+    /** Create a new guardrail. */
     create(data: GuardrailCreate): Promise<Guardrail>;
+    /** Delete a guardrail by ID. */
     delete(guardrailId: string): Promise<void>;
-    apply(datasetId: string, guardrailId: string): Promise<any>;
+    /** Apply a guardrail to a dataset for validation. */
+    apply(datasetId: string, guardrailId: string): Promise<GuardrailApplyResult>;
+}
+
+interface UsageSummary {
+    workspace_id: string;
+    plan: string;
+    quotas: Record<string, number>;
+    billing?: {
+        plan_id: string;
+        tokens_used: number;
+        tokens_limit: number;
+        period_end: string;
+    };
+}
+interface UsageHistoryPoint {
+    date: string;
+    tokens: number;
+    agent_runs: number;
+    cost: number;
+}
+/**
+ * Client for querying usage metrics and billing data.
+ *
+ * @example
+ * ```ts
+ * const usage = new UsageClient({ apiKey: 'lt_...' });
+ * const summary = await usage.getSummary('ws_abc123');
+ * console.log(summary.billing?.tokens_used);
+ * ```
+ */
+declare class UsageClient extends BaseClient {
+    constructor(config: ClientConfig);
+    /** Get current usage summary for a workspace. */
+    getSummary(workspaceId: string): Promise<UsageSummary>;
+    /** Get historical usage data for charts. */
+    getHistory(workspaceId: string, days?: number): Promise<UsageHistoryPoint[]>;
 }
 
-export { type Agent, AgentClient, type AgentCreate, type AgentRun, agent as AgentTypes, type FeatureCheck, FileClient, type FileResponse, type FineTuneJobCreate, type FineTuneJobResponse, type Guardrail, GuardrailClient, type GuardrailConfig, type GuardrailCreate, type Model, ModelClient, models as ModelTypes, type Secret, SecretClient, secrets as SecretTypes, SubscriptionClient, type SubscriptionInfo, TrainingClient };
+export { type Agent, AgentClient, type AgentConfig, type AgentCreate, type AgentRun, agent as AgentTypes, BaseClient, type ClientConfig, type FeatureCheck, FileClient, type FileResponse, type FineTuneHyperparameters, type FineTuneJobCreate, type FineTuneJobList, type FineTuneJobResponse, type Guardrail, type GuardrailApplyResult, GuardrailClient, type GuardrailConfig, type GuardrailCreate, LangtrainError, type Model, ModelClient, models as ModelTypes, type Permission, type Secret, SecretClient, secrets as SecretTypes, SubscriptionClient, type SubscriptionInfo, TrainingClient, UsageClient, type UsageHistoryPoint, type UsageSummary };