@inferencesh/sdk 0.1.3 → 0.2.1

package/README.md

@@ -24,11 +24,9 @@ Get your API key from the [inference.sh dashboard](https://app.inference.sh/sett
 ## Quick Start
 
 ```typescript
-import { Inference, TaskStatusCompleted } from '@inferencesh/sdk';
+import { inference } from '@inferencesh/sdk';
 
-const client = new Inference({
-  apiKey: 'your-api-key'
-});
+const client = inference({ apiKey: 'your-api-key' });
 
 // Run a task and wait for the result
 const result = await client.run({
@@ -46,9 +44,9 @@ console.log(result.output);
 ### Basic Usage
 
 ```typescript
-import { Inference } from '@inferencesh/sdk';
+import { inference } from '@inferencesh/sdk';
 
-const client = new Inference({ apiKey: 'your-api-key' });
+const client = inference({ apiKey: 'your-api-key' });
 
 // Wait for result (default behavior)
 const result = await client.run({
@@ -59,6 +57,18 @@ const result = await client.run({
 console.log('Output:', result.output);
 ```
 
+### With Setup Parameters
+
+Setup parameters configure the app instance (e.g., model selection). Workers with matching setup are "warm" and skip setup:
+
+```typescript
+const result = await client.run({
+  app: 'my-app',
+  setup: { model: 'schnell' },  // Setup parameters
+  input: { prompt: 'hello' }
+});
+```
+
 ### Fire and Forget
 
 ```typescript
@@ -135,11 +145,90 @@ const task = await client.run(
 await client.cancel(task.id);
 ```
 
+## Agent Chat
+
+Chat with AI agents using `client.agent()`.
+
+### Using a Template Agent
+
+Use an existing agent from your workspace by its `namespace/name@shortid`:
+
+```typescript
+import { inference } from '@inferencesh/sdk';
+
+const client = inference({ apiKey: 'your-api-key' });
+
+// Create agent from template
+const agent = client.agent('my-org/assistant@abc123');
+
+// Send a message with streaming
+await agent.sendMessage('Hello!', {
+  onMessage: (msg) => {
+    if (msg.content) {
+      for (const c of msg.content) {
+        if (c.type === 'text' && c.text) {
+          process.stdout.write(c.text);
+        }
+      }
+    }
+  }
+});
+
+// Clean up
+agent.disconnect();
+```
+
+### Creating an Ad-Hoc Agent
+
+Create agents on-the-fly without saving to your workspace:
+
+```typescript
+import { inference, tool, string } from '@inferencesh/sdk';
+
+const client = inference({ apiKey: 'your-api-key' });
+
+// Create ad-hoc agent
+const agent = client.agent({
+  coreApp: 'infsh/claude-sonnet-4@abc123',  // LLM to use
+  systemPrompt: 'You are a helpful assistant.',
+  tools: [
+    tool('get_weather')
+      .description('Get current weather')
+      .params({ city: string('City name') })
+      .handler(async (args) => {
+        // Your tool logic here
+        return JSON.stringify({ temp: 72, conditions: 'sunny' });
+      })
+      .build()
+  ]
+});
+
+await agent.sendMessage('What is the weather in Paris?', {
+  onMessage: (msg) => console.log(msg),
+  onToolCall: async (call) => {
+    // Tool handlers are auto-executed if defined
+  }
+});
+```
+
+### Agent Methods
+
+| Method | Description |
+|--------|-------------|
+| `sendMessage(text, options?)` | Send a message to the agent |
+| `getChat(chatId?)` | Get chat history |
+| `stopChat(chatId?)` | Stop current generation |
+| `submitToolResult(toolId, resultOrAction)` | Submit result for a client tool (string or {action, form_data}) |
+| `streamMessages(chatId?, options?)` | Stream message updates |
+| `streamChat(chatId?, options?)` | Stream chat updates |
+| `disconnect()` | Clean up streams |
+| `reset()` | Start a new conversation |
+
 ## API Reference
 
-### `new Inference(config)`
+### `inference(config)`
 
-Creates a new Inference client.
+Creates a new inference client.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -156,6 +245,7 @@ Runs a task on inference.sh.
 |-----------|------|----------|-------------|
 | `params.app` | `string` | Yes | App identifier (e.g., `'username/app-name'`) |
 | `params.input` | `object` | Yes | Input parameters for the app |
+| `params.setup` | `object` | No | Setup parameters (affects worker warmth/scheduling) |
 | `params.infra` | `string` | No | Infrastructure: `'cloud'` or `'private'` |
 | `params.variant` | `string` | No | App variant to use |
 

package/dist/agent.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Headless Agent SDK
+ *
+ * Chat with AI agents without UI dependencies.
+ */
+import { ChatDTO, ChatMessageDTO, AgentRuntimeConfig } from './types';
+export interface AgentConfig {
+    apiKey: string;
+    baseUrl?: string;
+}
+/**
+ * Ad-hoc agent configuration - extends AgentRuntimeConfig with core_app_ref required
+ * Uses Partial to make name/system_prompt optional for ad-hoc usage
+ */
+export type AdHocAgentOptions = Partial<AgentRuntimeConfig> & {
+    /** Core LLM app ref: namespace/name@shortid (required for ad-hoc agents) */
+    core_app_ref: string;
+};
+/** Template agent configuration */
+export interface TemplateAgentOptions {
+    /** Agent reference: namespace/name@version (e.g., "my-org/assistant@abc123") */
+    agent: string;
+}
+export type AgentOptions = AdHocAgentOptions | TemplateAgentOptions;
+export interface SendMessageOptions {
+    /** File attachments (Blob or base64 data URI) */
+    files?: (Blob | string)[];
+    /** Callback for message updates */
+    onMessage?: (message: ChatMessageDTO) => void;
+    /** Callback for chat updates */
+    onChat?: (chat: ChatDTO) => void;
+    /** Callback when a client tool needs execution */
+    onToolCall?: (invocation: {
+        id: string;
+        name: string;
+        args: Record<string, unknown>;
+    }) => void;
+}
+export declare class Agent {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly options;
+    private chatId;
+    private stream;
+    constructor(config: AgentConfig, options: AgentOptions);
+    /** Get current chat ID */
+    get currentChatId(): string | null;
+    /** Send a message to the agent */
+    sendMessage(text: string, options?: SendMessageOptions): Promise<ChatMessageDTO>;
+    /** Get chat by ID */
+    getChat(chatId?: string): Promise<ChatDTO | null>;
+    /** Stop the current chat generation */
+    stopChat(): Promise<void>;
+    /**
+     * Submit a tool result
+     * @param toolInvocationId - The tool invocation ID
+     * @param resultOrAction - Either a raw result string, or an object with action and optional form_data (will be JSON-serialized)
+     */
+    submitToolResult(toolInvocationId: string, resultOrAction: string | {
+        action: {
+            type: string;
+            payload?: Record<string, unknown>;
+        };
+        form_data?: Record<string, unknown>;
+    }): Promise<void>;
+    /** Stop streaming and cleanup */
+    disconnect(): void;
+    /** Reset the agent (start fresh chat) */
+    reset(): void;
+    /** Upload a file and return the file object */
+    uploadFile(data: Blob | string): Promise<{
+        uri: string;
+        content_type?: string;
+    }>;
+    private startStreaming;
+    private createEventSource;
+    private request;
+}

package/dist/agent.js

@@ -0,0 +1,188 @@
+"use strict";
+/**
+ * Headless Agent SDK
+ *
+ * Chat with AI agents without UI dependencies.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Agent = void 0;
+const stream_1 = require("./stream");
+const eventsource_1 = require("eventsource");
+const types_1 = require("./types");
+// =============================================================================
+// Agent Class
+// =============================================================================
+class Agent {
+    constructor(config, options) {
+        this.chatId = null;
+        // Unified stream for both Chat and ChatMessage events (uses TypedEvents)
+        this.stream = null;
+        this.apiKey = config.apiKey;
+        this.baseUrl = config.baseUrl || 'https://api.inference.sh';
+        this.options = options;
+    }
+    /** Get current chat ID */
+    get currentChatId() {
+        return this.chatId;
+    }
+    /** Send a message to the agent */
+    async sendMessage(text, options = {}) {
+        const isAdHoc = 'core_app_ref' in this.options;
+        // Upload files if provided
+        let imageUri;
+        let fileUris;
+        if (options.files && options.files.length > 0) {
+            const uploadedFiles = await Promise.all(options.files.map(f => this.uploadFile(f)));
+            // Separate images from other files
+            const images = uploadedFiles.filter(f => f.content_type?.startsWith('image/'));
+            const others = uploadedFiles.filter(f => !f.content_type?.startsWith('image/'));
+            if (images.length > 0)
+                imageUri = images[0].uri;
+            if (others.length > 0)
+                fileUris = others.map(f => f.uri);
+        }
+        // Both template and ad-hoc use /agents/run
+        const input = { text, image: imageUri, files: fileUris, role: 'user', context: [], system_prompt: '', context_size: 0 };
+        const body = isAdHoc
+            ? { chat_id: this.chatId, agent_config: this.options, input }
+            : { chat_id: this.chatId, agent: this.options.agent, input };
+        const response = await this.request('post', '/agents/run', { data: body });
+        // Update chat ID if new
+        if (!this.chatId && response.assistant_message.chat_id) {
+            this.chatId = response.assistant_message.chat_id;
+            this.startStreaming(options);
+        }
+        return response.assistant_message;
+    }
+    /** Get chat by ID */
+    async getChat(chatId) {
+        const id = chatId || this.chatId;
+        if (!id)
+            return null;
+        return this.request('get', `/chats/${id}`);
+    }
+    /** Stop the current chat generation */
+    async stopChat() {
+        if (!this.chatId)
+            return;
+        await this.request('post', `/chats/${this.chatId}/stop`);
+    }
+    /**
+     * Submit a tool result
+     * @param toolInvocationId - The tool invocation ID
+     * @param resultOrAction - Either a raw result string, or an object with action and optional form_data (will be JSON-serialized)
+     */
+    async submitToolResult(toolInvocationId, resultOrAction) {
+        // Serialize widget actions to JSON string
+        const result = typeof resultOrAction === 'string'
+            ? resultOrAction
+            : JSON.stringify(resultOrAction);
+        await this.request('post', `/tools/${toolInvocationId}`, { data: { result } });
+    }
+    /** Stop streaming and cleanup */
+    disconnect() {
+        this.stream?.stop();
+        this.stream = null;
+    }
+    /** Reset the agent (start fresh chat) */
+    reset() {
+        this.disconnect();
+        this.chatId = null;
+    }
+    /** Upload a file and return the file object */
+    async uploadFile(data) {
+        // Create file record
+        let contentType = 'application/octet-stream';
+        let size;
+        if (data instanceof Blob) {
+            contentType = data.type || 'application/octet-stream';
+            size = data.size;
+        }
+        const files = await this.request('post', '/files', { data: { files: [{ uri: '', content_type: contentType, size }] } });
+        const file = files[0];
+        if (!file.upload_url)
+            throw new Error('No upload URL');
+        // Convert to blob if needed
+        let blob;
+        if (data instanceof Blob) {
+            blob = data;
+        }
+        else if (data.startsWith('data:')) {
+            const matches = data.match(/^data:([^;]+);base64,(.+)$/);
+            if (!matches)
+                throw new Error('Invalid data URI');
+            const bytes = Uint8Array.from(atob(matches[2]), c => c.charCodeAt(0));
+            blob = new Blob([bytes], { type: matches[1] });
+        }
+        else {
+            const bytes = Uint8Array.from(atob(data), c => c.charCodeAt(0));
+            blob = new Blob([bytes], { type: contentType });
+        }
+        // Upload to signed URL
+        const uploadResp = await fetch(file.upload_url, {
+            method: 'PUT',
+            body: blob,
+            headers: { 'Content-Type': blob.type },
+        });
+        if (!uploadResp.ok)
+            throw new Error('Upload failed');
+        return { uri: file.uri, content_type: file.content_type };
+    }
+    // =============================================================================
+    // Private Methods
+    // =============================================================================
+    startStreaming(options) {
+        if (!this.chatId)
+            return;
+        // Unified stream with TypedEvents (single SSE connection for both Chat and ChatMessage)
+        this.stream = new stream_1.StreamManager({
+            createEventSource: async () => this.createEventSource(`/chats/${this.chatId}/stream`),
+            autoReconnect: true,
+        });
+        // Listen for Chat object updates (status changes)
+        this.stream.addEventListener('chats', (chat) => {
+            options.onChat?.(chat);
+        });
+        // Listen for ChatMessage updates
+        this.stream.addEventListener('chat_messages', (message) => {
+            options.onMessage?.(message);
+            // Check for client tool invocations
+            if (message.tool_invocations && options.onToolCall) {
+                for (const inv of message.tool_invocations) {
+                    if (inv.type === types_1.ToolTypeClient && inv.status === types_1.ToolInvocationStatusAwaitingInput) {
+                        options.onToolCall({
+                            id: inv.id,
+                            name: inv.function?.name || '',
+                            args: inv.function?.arguments || {},
+                        });
+                    }
+                }
+            }
+        });
+        this.stream.connect();
+    }
+    createEventSource(endpoint) {
+        return new eventsource_1.EventSource(`${this.baseUrl}${endpoint}`, {
+            fetch: (input, init) => fetch(input, {
+                ...init,
+                headers: { ...init.headers, Authorization: `Bearer ${this.apiKey}` },
+            }),
+        });
+    }
+    async request(method, endpoint, options = {}) {
+        const response = await fetch(`${this.baseUrl}${endpoint}`, {
+            method: method.toUpperCase(),
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${this.apiKey}`,
+            },
+            body: options.data ? JSON.stringify(options.data) : undefined,
+        });
+        const json = await response.json();
+        if (!response.ok || !json.success) {
+            throw new Error(json.error?.message || 'Request failed');
+        }
+        return json.data;
+    }
+}
+exports.Agent = Agent;

package/dist/client.d.ts

@@ -1,4 +1,27 @@
-import { ApiTaskRequest, TaskDTO as Task, File } from './types';
+import { ApiAppRunRequest, TaskDTO as Task, File, ChatDTO, ChatMessageDTO, AgentRuntimeConfig } from './types';
+import { EventSource } from 'eventsource';
+/**
+ * Ad-hoc agent configuration - extends AgentRuntimeConfig with core_app_ref required
+ * Uses Partial to make name/system_prompt optional for ad-hoc usage
+ */
+export type AdHocAgentConfig = Partial<AgentRuntimeConfig> & {
+    /** Core LLM app ref: namespace/name@shortid (required for ad-hoc agents) */
+    core_app_ref: string;
+};
+export interface SendMessageOptions {
+    /** File attachments (Blob or base64 data URI) */
+    files?: (Blob | string)[];
+    /** Callback for message updates */
+    onMessage?: (message: ChatMessageDTO) => void;
+    /** Callback for chat updates */
+    onChat?: (chat: ChatDTO) => void;
+    /** Callback when a client tool needs execution */
+    onToolCall?: (invocation: {
+        id: string;
+        name: string;
+        args: Record<string, unknown>;
+    }) => void;
+}
 export interface UploadFileOptions {
     filename?: string;
     contentType?: string;
@@ -38,8 +61,13 @@ export declare class Inference {
     private readonly apiKey;
     private readonly baseUrl;
     constructor(config: InferenceConfig);
-    private request;
-    private createEventSource;
+    /** @internal */
+    _request<T>(method: "get" | "post" | "put" | "delete", endpoint: string, options?: {
+        params?: Record<string, any>;
+        data?: Record<string, any>;
+    }): Promise<T>;
+    /** @internal */
+    _createEventSource(endpoint: string): EventSource;
     private _stripTask;
     private processInputData;
     /**
@@ -49,22 +77,33 @@ export declare class Inference {
      * @param options - Run options for waiting, updates, and reconnection
      * @returns The completed task result
      *
+     * App reference format: `namespace/name@shortid` (version is required)
+     *
+     * The short ID ensures your code always runs the same version,
+     * protecting against breaking changes from app updates.
+     *
      * @example
      * ```typescript
-     * // Simple usage - wait for result
-     * const result = await client.run({ app: 'my-app', input: { prompt: 'hello' } });
+     * // Run a specific version (required)
+     * const result = await client.run({
+     *   app: 'okaris/flux@abc1',  // version @abc1 is pinned
+     *   input: { prompt: 'hello' }
+     * });
      *
      * // With status updates
      * const result = await client.run(
-     *   { app: 'my-app', input: { prompt: 'hello' } },
+     *   { app: 'okaris/flux@abc1', input: { prompt: 'hello' } },
      *   { onUpdate: (update) => console.log(update.status) }
      * );
      *
      * // Fire and forget
-     * const task = await client.run({ app: 'my-app', input: {} }, { wait: false });
+     * const task = await client.run(
+     *   { app: 'okaris/flux@abc1', input: {} },
+     *   { wait: false }
+     * );
      * ```
      */
-    run(params: ApiTaskRequest, options?: RunOptions): Promise<Task>;
+    run(params: ApiAppRunRequest, options?: RunOptions): Promise<Task>;
     uploadFile(data: string | Blob, options?: UploadFileOptions): Promise<File>;
     /**
        * Cancel a running task
@@ -72,8 +111,75 @@ export declare class Inference {
        * @param taskId - The ID of the task to cancel
        */
     cancel(taskId: string): Promise<void>;
+    /**
+     * Create an agent for chat interactions
+     *
+     * @param config - Either a template reference string (namespace/name@version) or ad-hoc config
+     * @returns An Agent instance for chat operations
+     *
+     * @example
+     * ```typescript
+     * // Template agent
+     * const agent = client.agent('okaris/assistant@abc123')
+     *
+     * // Ad-hoc agent
+     * const agent = client.agent({
+     *   core_app_ref: 'infsh/claude-sonnet-4@xyz789',
+     *   system_prompt: 'You are a helpful assistant',
+     *   tools: [...]
+     * })
+     *
+     * // Send messages
+     * const response = await agent.sendMessage('Hello!')
+     * ```
+     */
+    agent(config: string | AdHocAgentConfig): Agent;
+}
+/**
+ * Agent for chat interactions
+ *
+ * Created via `client.agent()` - do not instantiate directly.
+ */
+export declare class Agent {
+    private readonly client;
+    private readonly config;
+    private chatId;
+    private stream;
+    private dispatchedToolCalls;
+    /** @internal */
+    constructor(client: Inference, config: string | AdHocAgentConfig);
+    /** Get current chat ID */
+    get currentChatId(): string | null;
+    /** Send a message to the agent */
+    sendMessage(text: string, options?: SendMessageOptions): Promise<ChatMessageDTO>;
+    /** Get chat by ID */
+    getChat(chatId?: string): Promise<ChatDTO | null>;
+    /** Stop the current chat generation */
+    stopChat(): Promise<void>;
+    /**
+     * Submit a tool result
+     * @param toolInvocationId - The tool invocation ID
+     * @param resultOrAction - Either a raw result string, or an object with action and optional form_data (will be JSON-serialized)
+     */
+    submitToolResult(toolInvocationId: string, resultOrAction: string | {
+        action: {
+            type: string;
+            payload?: Record<string, unknown>;
+        };
+        form_data?: Record<string, unknown>;
+    }): Promise<void>;
+    /** Stop streaming and cleanup */
+    disconnect(): void;
+    /** Reset the agent (start fresh chat) */
+    reset(): void;
+    /** Stream events until chat becomes idle */
+    private streamUntilIdle;
 }
 /**
- * @deprecated Use `Inference` instead. Will be removed in v1.0.0
+ * Factory function for creating an Inference client (lowercase for branding)
+ * @example
+ * ```typescript
+ * const client = inference({ apiKey: 'your-api-key' });
+ * ```
  */
-export declare const inference: typeof Inference;
+export declare function inference(config: InferenceConfig): Inference;