langtrain 0.1.26 → 0.2.0

package/src/lib/agent.ts

@@ -1,4 +1,6 @@
-import axios, { AxiosInstance } from 'axios';
+import { BaseClient, ClientConfig } from './base';
+
+// ── Types ──────────────────────────────────────────────────────────────────
 
 export interface Agent {
     id: string;
@@ -6,12 +8,28 @@ export interface Agent {
     name: string;
     description?: string;
     model_id?: string;
-    config: Record<string, unknown>;
+    config: AgentConfig;
     is_active: boolean;
     created_at: string;
     updated_at: string;
 }
 
+export interface AgentConfig {
+    system_prompt?: string;
+    temperature?: number;
+    max_tokens?: number;
+    tools?: string[];
+    [key: string]: unknown;
+}
+
+export interface AgentCreate {
+    workspace_id: string;
+    name: string;
+    description?: string;
+    model_id?: string;
+    config?: AgentConfig;
+}
+
 export interface AgentRun {
     id: string;
     conversation_id: string;
@@ -22,70 +40,75 @@ export interface AgentRun {
     tokens_used: number;
 }
 
-export class AgentClient {
-    private client: AxiosInstance;
+// ── Client ─────────────────────────────────────────────────────────────────
 
-    constructor(private config: { apiKey: string, baseUrl?: string }) {
-        this.client = axios.create({
-            baseURL: config.baseUrl || 'https://api.langtrain.ai/api/v1',
-            headers: {
-                'X-API-Key': config.apiKey,
-                'Content-Type': 'application/json'
-            }
-        });
+/**
+ * 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!');
+ * ```
+ */
+export class AgentClient extends BaseClient {
+    constructor(config: ClientConfig) {
+        super(config);
     }
 
+    /** List all agents, optionally filtered by workspace. */
     async list(workspaceId?: string): Promise<Agent[]> {
-        const params: any = {};
-        if (workspaceId) params.workspace_id = workspaceId;
-
-        const response = await this.client.get<{ agents: Agent[] }>('/agents', { params });
-        return response.data.agents;
+        return this.request(async () => {
+            const params: Record<string, string> = {};
+            if (workspaceId) params.workspace_id = workspaceId;
+            const res = await this.http.get<{ agents: Agent[] }>('/agents', { params });
+            return res.data.agents;
+        });
     }
 
+    /** Get a single agent by ID. */
     async get(agentId: string): Promise<Agent> {
-        const response = await this.client.get<Agent>(`/agents/${agentId}`);
-        return response.data;
+        return this.request(async () => {
+            const res = await this.http.get<Agent>(`/agents/${agentId}`);
+            return res.data;
+        });
     }
 
+    /** Create a new agent. */
     async create(agent: AgentCreate): Promise<Agent> {
-        const response = await this.client.post<Agent>('/agents/', agent);
-        return response.data;
+        return this.request(async () => {
+            const res = await this.http.post<Agent>('/agents/', agent);
+            return res.data;
+        });
     }
 
+    /** Delete an agent by ID. */
     async delete(agentId: string): Promise<void> {
-        await this.client.delete(`/agents/${agentId}`);
+        return this.request(async () => {
+            await this.http.delete(`/agents/${agentId}`);
+        });
     }
 
-    async execute(agentId: string, input: any, messages: any[] = [], conversationId?: string): Promise<AgentRun> {
-        const response = await this.client.post<AgentRun>(`/agents/${agentId}/execute`, {
-            input,
-            messages,
-            conversation_id: conversationId
+    /** Execute an agent with input and optional conversation context. */
+    async execute(agentId: string, input: string, messages: Array<{ role: string; content: string }> = [], conversationId?: string): Promise<AgentRun> {
+        return this.request(async () => {
+            const res = await this.http.post<AgentRun>(`/agents/${agentId}/execute`, {
+                input,
+                messages,
+                conversation_id: conversationId,
+            });
+            return res.data;
         });
-        return response.data;
     }
 
-    async logs(agentId: string, limit: number = 100): Promise<{ logs: string[] }> {
-        const response = await this.client.get<{ logs: string[] }>(`/agents/${agentId}/logs`, {
-            params: { limit }
+    /** Fetch recent logs for an agent. */
+    async logs(agentId: string, limit: number = 100): Promise<string[]> {
+        return this.request(async () => {
+            const res = await this.http.get<{ logs: string[] }>(`/agents/${agentId}/logs`, {
+                params: { limit },
+            });
+            return res.data.logs;
         });
-        return response.data;
     }
 }
-
-export interface AgentConfig {
-    system_prompt?: string;
-    temperature?: number;
-    max_tokens?: number;
-    tools?: string[];
-    [key: string]: any;
-}
-
-export interface AgentCreate {
-    workspace_id: string; // UUID
-    name: string;
-    description?: string;
-    model_id?: string; // UUID
-    config?: AgentConfig;
-}

package/src/lib/base.ts

@@ -0,0 +1,152 @@
+import axios, { AxiosInstance, AxiosError, AxiosRequestConfig } from 'axios';
+
+// ── Shared Configuration ───────────────────────────────────────────────────
+
+/** Configuration for all Langtrain SDK clients. */
+export 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;
+}
+
+const DEFAULT_BASE_URL = 'https://api.langtrain.ai/api/v1';
+const DEFAULT_TIMEOUT = 30_000;
+const DEFAULT_MAX_RETRIES = 2;
+const RETRYABLE_STATUS_CODES = [408, 429, 500, 502, 503, 504];
+
+// ── Custom Error ───────────────────────────────────────────────────────────
+
+export 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 }) {
+        super(message);
+        this.name = 'LangtrainError';
+        this.status = options?.status;
+        this.code = options?.code;
+        this.cause = options?.cause;
+    }
+
+    /** True if the error was a network/timeout issue (retryable). */
+    get isTransient(): boolean {
+        return this.code === 'ECONNABORTED' || this.code === 'NETWORK_ERROR' ||
+            (this.status !== undefined && RETRYABLE_STATUS_CODES.includes(this.status));
+    }
+
+    /** True if the API key was invalid or expired. */
+    get isAuthError(): boolean {
+        return this.status === 401 || this.status === 403;
+    }
+
+    /** True if a resource was not found. */
+    get isNotFound(): boolean {
+        return this.status === 404;
+    }
+
+    /** True if rate-limited. */
+    get isRateLimited(): boolean {
+        return this.status === 429;
+    }
+}
+
+// ── Base Client ────────────────────────────────────────────────────────────
+
+/**
+ * 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)
+ */
+export abstract class BaseClient {
+    protected readonly http: AxiosInstance;
+    protected readonly maxRetries: number;
+
+    constructor(config: ClientConfig) {
+        this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+
+        this.http = axios.create({
+            baseURL: config.baseUrl || DEFAULT_BASE_URL,
+            timeout: config.timeout ?? DEFAULT_TIMEOUT,
+            headers: {
+                'X-API-Key': config.apiKey,
+                'Content-Type': 'application/json',
+            },
+        });
+    }
+
+    /**
+     * Execute a request with automatic retry and error wrapping.
+     */
+    protected async request<T>(fn: () => Promise<T>): Promise<T> {
+        let lastError: LangtrainError | undefined;
+
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            try {
+                return await fn();
+            } catch (error) {
+                lastError = this.wrapError(error);
+
+                // Only retry on transient errors, and not on the last attempt
+                if (!lastError.isTransient || attempt === this.maxRetries) {
+                    throw lastError;
+                }
+
+                // Exponential backoff: 500ms, 1000ms, 2000ms...
+                const delay = Math.min(500 * Math.pow(2, attempt), 5000);
+                await this.sleep(delay);
+            }
+        }
+
+        throw lastError!;
+    }
+
+    /**
+     * Wrap any thrown error into a structured LangtrainError.
+     */
+    private wrapError(error: unknown): LangtrainError {
+        if (error instanceof LangtrainError) return error;
+
+        if (error instanceof AxiosError) {
+            const status = error.response?.status;
+            const data = error.response?.data as Record<string, unknown> | undefined;
+            const serverMessage = data?.detail ?? data?.message ?? data?.error;
+
+            const message = serverMessage
+                ? String(serverMessage)
+                : error.code === 'ECONNABORTED'
+                    ? `Request timed out`
+                    : status
+                        ? `API request failed with status ${status}`
+                        : `Network error: ${error.message}`;
+
+            return new LangtrainError(message, {
+                status,
+                code: error.code,
+                cause: error,
+            });
+        }
+
+        if (error instanceof Error) {
+            return new LangtrainError(error.message, { cause: error });
+        }
+
+        return new LangtrainError(String(error));
+    }
+
+    private sleep(ms: number): Promise<void> {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}

package/src/lib/files.ts

@@ -1,53 +1,68 @@
-import axios, { AxiosInstance } from 'axios';
+import { BaseClient, ClientConfig } from './base';
 import FormData from 'form-data';
 import fs from 'fs';
 
-export class FileClient {
-    private client: AxiosInstance;
+// ── Types ──────────────────────────────────────────────────────────────────
 
-    constructor(config: { apiKey: string, baseUrl?: string }) {
-        this.client = axios.create({
-            baseURL: config.baseUrl || 'https://api.langtrain.ai/api/v1',
-            headers: {
-                'X-API-Key': config.apiKey,
-            }
-        });
+export interface FileResponse {
+    id: string;
+    filename: string;
+    purpose: string;
+    bytes: number;
+    created_at: string;
+}
+
+// ── Client ─────────────────────────────────────────────────────────────────
+
+/**
+ * Client for managing file uploads (datasets for fine-tuning).
+ *
+ * @example
+ * ```ts
+ * const files = new FileClient({ apiKey: 'lt_...' });
+ * const uploaded = await files.upload('./data.jsonl');
+ * ```
+ */
+export class FileClient extends BaseClient {
+    constructor(config: ClientConfig) {
+        super(config);
     }
 
-    async upload(file: any, workspaceId?: string, purpose: string = 'fine-tune'): Promise<FileResponse> {
-        const form = new FormData();
-        // Check if file is a path or buffer. Assuming path for CLI
-        if (typeof file === 'string') {
-            if (!fs.existsSync(file)) throw new Error(`File not found: ${file}`);
-            form.append('file', fs.createReadStream(file));
-        } else {
-            // Handle buffer or other types if needed, but for now strict to path
-            throw new Error('File path required');
+    /** Upload a file from a local path. */
+    async upload(filePath: string, workspaceId?: string, purpose: string = 'fine-tune'): Promise<FileResponse> {
+        if (!fs.existsSync(filePath)) {
+            throw new Error(`File not found: ${filePath}`);
         }
 
-        if (workspaceId) form.append('workspace_id', workspaceId);
-        form.append('purpose', purpose);
+        return this.request(async () => {
+            const form = new FormData();
+            form.append('file', fs.createReadStream(filePath));
+            if (workspaceId) form.append('workspace_id', workspaceId);
+            form.append('purpose', purpose);
 
-        const response = await this.client.post('/files', form, {
-            headers: {
-                ...form.getHeaders()
-            }
+            const res = await this.http.post<FileResponse>('/files', form, {
+                headers: form.getHeaders(),
+                maxContentLength: Infinity,
+                maxBodyLength: Infinity,
+            });
+            return res.data;
         });
-        return response.data;
     }
 
+    /** List files in a workspace, optionally filtered by purpose. */
     async list(workspaceId: string, purpose?: string): Promise<FileResponse[]> {
-        const params: any = { workspace_id: workspaceId };
-        if (purpose) params.purpose = purpose;
-        const response = await this.client.get('/files', { params });
-        return response.data.data;
+        return this.request(async () => {
+            const params: Record<string, string> = { workspace_id: workspaceId };
+            if (purpose) params.purpose = purpose;
+            const res = await this.http.get<{ data: FileResponse[] }>('/files', { params });
+            return res.data.data;
+        });
     }
-}
 
-export interface FileResponse {
-    id: string;
-    filename: string;
-    purpose: string;
-    bytes: number;
-    created_at: string;
+    /** Delete a file by ID. */
+    async delete(fileId: string): Promise<void> {
+        return this.request(async () => {
+            await this.http.delete(`/files/${fileId}`);
+        });
+    }
 }

package/src/lib/guardrails.ts

@@ -1,4 +1,6 @@
-import axios, { AxiosInstance } from 'axios';
+import { BaseClient, ClientConfig } from './base';
+
+// ── Types ──────────────────────────────────────────────────────────────────
 
 export interface GuardrailConfig {
     pii_enabled: boolean;
@@ -28,45 +30,73 @@ export interface GuardrailCreate {
     config: GuardrailConfig;
 }
 
-export class GuardrailClient {
-    private client: AxiosInstance;
+export interface GuardrailApplyResult {
+    total_rows: number;
+    passed: number;
+    failed: number;
+    violations: Array<{ row: number; rule: string; message: string }>;
+}
+
+// ── Client ─────────────────────────────────────────────────────────────────
 
-    constructor(private config: { apiKey: string, baseUrl?: string }) {
-        this.client = axios.create({
-            baseURL: config.baseUrl || 'https://api.langtrain.ai/api/v1',
-            headers: {
-                'X-API-Key': config.apiKey,
-                'Content-Type': 'application/json'
-            }
-        });
+/**
+ * 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 },
+ * });
+ * ```
+ */
+export class GuardrailClient extends BaseClient {
+    constructor(config: ClientConfig) {
+        super(config);
     }
 
+    /** List guardrails, optionally filtered by workspace. */
     async list(workspaceId?: string): Promise<Guardrail[]> {
-        const params: any = {};
-        if (workspaceId) params.workspace_id = workspaceId;
-        const response = await this.client.get<Guardrail[]>('/guardrails/', { params });
-        return response.data;
+        return this.request(async () => {
+            const params: Record<string, string> = {};
+            if (workspaceId) params.workspace_id = workspaceId;
+            const res = await this.http.get<Guardrail[]>('/guardrails/', { params });
+            return res.data;
+        });
     }
 
+    /** Get a guardrail by ID. */
     async get(guardrailId: string): Promise<Guardrail> {
-        const response = await this.client.get<Guardrail>(`/guardrails/${guardrailId}`);
-        return response.data;
+        return this.request(async () => {
+            const res = await this.http.get<Guardrail>(`/guardrails/${guardrailId}`);
+            return res.data;
+        });
     }
 
+    /** Create a new guardrail. */
     async create(data: GuardrailCreate): Promise<Guardrail> {
-        const response = await this.client.post<Guardrail>('/guardrails/', data);
-        return response.data;
+        return this.request(async () => {
+            const res = await this.http.post<Guardrail>('/guardrails/', data);
+            return res.data;
+        });
     }
 
+    /** Delete a guardrail by ID. */
     async delete(guardrailId: string): Promise<void> {
-        await this.client.delete(`/guardrails/${guardrailId}`);
+        return this.request(async () => {
+            await this.http.delete(`/guardrails/${guardrailId}`);
+        });
     }
 
-    async apply(datasetId: string, guardrailId: string): Promise<any> {
-        const response = await this.client.post('/guardrails/apply', {
-            dataset_id: datasetId,
-            guardrail_id: guardrailId
+    /** Apply a guardrail to a dataset for validation. */
+    async apply(datasetId: string, guardrailId: string): Promise<GuardrailApplyResult> {
+        return this.request(async () => {
+            const res = await this.http.post<GuardrailApplyResult>('/guardrails/apply', {
+                dataset_id: datasetId,
+                guardrail_id: guardrailId,
+            });
+            return res.data;
         });
-        return response.data;
     }
 }

package/src/lib/models.ts

@@ -1,4 +1,6 @@
-import axios, { AxiosInstance } from 'axios';
+import { BaseClient, ClientConfig } from './base';
+
+// ── Types ──────────────────────────────────────────────────────────────────
 
 export interface Permission {
     id: string;
@@ -11,13 +13,13 @@ export interface Permission {
     allow_view: boolean;
     allow_fine_tuning: boolean;
     organization: string;
-    group: any;
+    group: string | null;
     is_blocking: boolean;
 }
 
 export interface Model {
     id: string;
-    object: string; // 'model'
+    object: string;
     created: number;
     owned_by: string;
     permission: Permission[];
@@ -26,36 +28,38 @@ export interface Model {
     task?: 'text' | 'vision' | 'agent';
 }
 
-export class ModelClient {
-    private client: AxiosInstance;
+// ── Client ─────────────────────────────────────────────────────────────────
 
-    constructor(config: { apiKey: string, baseUrl?: string }) {
-        this.client = axios.create({
-            baseURL: config.baseUrl || 'https://api.langtrain.ai/api/v1',
-            headers: {
-                'X-API-Key': config.apiKey,
-                'Content-Type': 'application/json'
-            }
-        });
+/**
+ * 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');
+ * ```
+ */
+export class ModelClient extends BaseClient {
+    constructor(config: ClientConfig) {
+        super(config);
     }
 
-    async list(task?: string): Promise<Model[]> {
-        const params: any = {};
-        if (task) params.task = task;
-
-        try {
-            const response = await this.client.get<{ data: Model[] }>('/models', { params });
-            return response.data.data;
-        } catch (error) {
-            // Fallback if endpoint doesn't support filtering or fails
-            // Verify if /models exists, otherwise return empty or throw
-            // customized error handling could go here
-            throw error;
-        }
+    /** List available models, optionally filtered by task type. */
+    async list(task?: 'text' | 'vision' | 'agent'): Promise<Model[]> {
+        return this.request(async () => {
+            const params: Record<string, string> = {};
+            if (task) params.task = task;
+            const res = await this.http.get<{ data: Model[] }>('/models', { params });
+            return res.data.data;
+        });
     }
 
+    /** Get a specific model by ID. */
     async get(modelId: string): Promise<Model> {
-        const response = await this.client.get<Model>(`/models/${modelId}`);
-        return response.data;
+        return this.request(async () => {
+            const res = await this.http.get<Model>(`/models/${modelId}`);
+            return res.data;
+        });
     }
 }