helios-ai-sdk 1.0.0

package/dist/sdk.d.ts

@@ -0,0 +1,399 @@
+/**
+ * Helios Embedded SDK — Comprehensive API
+ *
+ * A full-featured TypeScript SDK for embedding the Helios AI-native
+ * runtime into JavaScript/TypeScript applications.
+ *
+ * @module helios-sdk
+ */
+/** Supported AI providers */
+type HeliosProvider = 'gemini' | 'openai' | 'anthropic' | 'webllm' | 'custom';
+/** Event types emitted by the Helios runtime */
+type HeliosEventType = 'print' | 'error' | 'trace' | 'tool_call' | 'agent_delegate' | 'prompt_start' | 'prompt_end';
+/** A structured print payload from UI primitives */
+interface HeliosPrintPayload {
+    type?: string;
+    title?: string;
+    content?: string;
+    value?: number;
+    max?: number;
+    label?: string;
+    [key: string]: unknown;
+}
+/** Trace entry from the execution engine */
+interface HeliosTraceEntry {
+    type: string;
+    name?: string;
+    model?: string;
+    input?: string;
+    output?: string;
+    duration?: number;
+    timestamp?: number;
+    tokens?: {
+        input?: number;
+        output?: number;
+    };
+    [key: string]: unknown;
+}
+/** Tool call event */
+interface HeliosToolCallEvent {
+    name: string;
+    args: unknown[];
+    result?: unknown;
+}
+/** Agent delegation event */
+interface HeliosAgentDelegateEvent {
+    from: string;
+    to: string;
+    task: string;
+    result?: string;
+}
+/** Prompt lifecycle events */
+interface HeliosPromptEvent {
+    prompt: string;
+    model?: string;
+    provider?: string;
+}
+/** Event map for typed event listeners */
+interface HeliosEventMap {
+    print: string | HeliosPrintPayload;
+    error: Error;
+    trace: HeliosTraceEntry;
+    tool_call: HeliosToolCallEvent;
+    agent_delegate: HeliosAgentDelegateEvent;
+    prompt_start: HeliosPromptEvent;
+    prompt_end: HeliosPromptEvent & {
+        response?: string;
+        duration?: number;
+    };
+}
+/** Typed event handler */
+type HeliosEventHandler<T extends HeliosEventType> = (data: HeliosEventMap[T]) => void;
+/** Tool metadata for registration */
+interface HeliosToolMetadata {
+    name: string;
+    description?: string;
+    params?: Array<{
+        name: string;
+        type: string;
+        description?: string;
+    }>;
+    returnType?: string;
+}
+/** Configuration for Helios runtime */
+interface HeliosConfig {
+    /** AI provider API key */
+    apiKey?: string;
+    /** AI provider to use */
+    provider?: HeliosProvider;
+    /** Default model ID */
+    model?: string;
+    /** Base URL for custom API providers */
+    baseUrl?: string;
+    /** Sampling temperature (0-2) */
+    temperature?: number;
+    /** Top-K sampling */
+    topK?: number;
+    /** Top-P (nucleus) sampling */
+    topP?: number;
+    /** Maximum conversation history entries to retain */
+    memoryLimit?: number;
+    /** Auto-summarize when history exceeds limit */
+    summarizeHistory?: boolean;
+    /** Default system prompt for all AI calls */
+    systemPrompt?: string;
+    /** Maximum loop iterations before kill (default: 1,000,000) */
+    maxLoopIterations?: number;
+    /** Skip actual AI API calls (return placeholder) */
+    dryRun?: boolean;
+    /** Middleware stack */
+    middleware?: HeliosMiddleware[];
+    /** Handler for user input requests from the runtime */
+    onInputRequest?: (prompt: string) => Promise<string>;
+}
+/** Middleware hook interface */
+interface HeliosMiddleware {
+    /** Unique name for this middleware */
+    name: string;
+    /** Called before each AI prompt call */
+    beforePrompt?: (context: MiddlewarePromptContext) => Promise<MiddlewarePromptContext | void>;
+    /** Called after each AI prompt call */
+    afterPrompt?: (context: MiddlewarePromptContext, response: MiddlewarePromptResponse) => Promise<MiddlewarePromptResponse | void>;
+    /** Called when a tool is invoked */
+    onToolCall?: (name: string, args: unknown[]) => Promise<void>;
+    /** Called on any runtime error */
+    onError?: (error: Error) => Promise<void>;
+}
+/** Context passed through prompt middleware */
+interface MiddlewarePromptContext {
+    prompt: string;
+    model: string;
+    provider: string;
+    history: HeliosMessage[];
+    systemPrompt?: string;
+    metadata: Record<string, unknown>;
+}
+/** Response from prompt middleware */
+interface MiddlewarePromptResponse {
+    text: string;
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+    };
+    metadata: Record<string, unknown>;
+}
+/** Conversation message */
+interface HeliosMessage {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+    timestamp: number;
+}
+/** Session configuration */
+interface HeliosSessionConfig {
+    /** Session-specific system prompt (overrides global) */
+    systemPrompt?: string;
+    /** Maximum history length for this session */
+    historyLimit?: number;
+    /** Initial context data */
+    context?: Record<string, unknown>;
+}
+/** Agent configuration */
+interface HeliosAgentConfig {
+    /** Agent system prompt / persona description */
+    prompt: string;
+    /** Model override for this agent */
+    model?: string;
+    /** Tool names available to this agent */
+    tools?: string[];
+    /** Whether the agent has persistent memory */
+    memory?: boolean;
+}
+/** Memory store entry */
+interface HeliosMemoryEntry {
+    key: string;
+    text: string;
+    metadata?: Record<string, unknown>;
+    embedding?: number[];
+    timestamp: number;
+}
+/** Memory search result */
+interface HeliosMemorySearchResult {
+    key: string;
+    text: string;
+    score: number;
+    metadata?: Record<string, unknown>;
+}
+declare class HeliosSDKError extends Error {
+    code: string;
+    constructor(message: string, code: string);
+}
+declare class HeliosConfigError extends HeliosSDKError {
+    constructor(message: string);
+}
+declare class HeliosExecutionError extends HeliosSDKError {
+    line?: number;
+    col?: number;
+    sourceHint?: string;
+    constructor(message: string, line?: number, col?: number, sourceHint?: string);
+}
+declare class HeliosCancelledError extends HeliosSDKError {
+    constructor();
+}
+declare class HeliosMemory {
+    private _store;
+    /** Store a text entry with optional metadata */
+    store(key: string, text: string, metadata?: Record<string, unknown>): Promise<void>;
+    /** Search entries by text similarity (basic substring search without embeddings) */
+    search(query: string, limit?: number): Promise<HeliosMemorySearchResult[]>;
+    /** Get a specific entry by key */
+    get(key: string): HeliosMemoryEntry | undefined;
+    /** Check if a key exists */
+    has(key: string): boolean;
+    /** Remove an entry */
+    delete(key: string): boolean;
+    /** Clear all entries */
+    clear(): void;
+    /** Get total entry count */
+    get size(): number;
+    /** Export all entries as a portable array */
+    export(): HeliosMemoryEntry[];
+    /** Import entries from a previously exported array */
+    import(data: HeliosMemoryEntry[]): void;
+}
+declare class HeliosSession {
+    readonly id: string;
+    private helios;
+    private history;
+    private context;
+    private systemPrompt;
+    private historyLimit;
+    private abortController;
+    constructor(helios: Helios, config?: HeliosSessionConfig);
+    /** Run a Helios prompt within this session's context and history */
+    prompt(text: string, options?: {
+        model?: string;
+        schema?: string;
+    }): Promise<string>;
+    /** Run arbitrary Helios code within session context */
+    run(source: string): Promise<unknown>;
+    /** Get the conversation history */
+    getHistory(): HeliosMessage[];
+    /** Clear the conversation history */
+    clearHistory(): void;
+    /** Set the system prompt */
+    setSystemPrompt(prompt: string): void;
+    /** Add contextual data available to all prompts */
+    addContext(key: string, value: unknown): void;
+    /** Remove a context key */
+    removeContext(key: string): boolean;
+    /** Clear all context */
+    clearContext(): void;
+    /** Get current context as a plain object */
+    getContext(): Record<string, unknown>;
+    /** Cancel any running operation */
+    abort(): void;
+    private trimHistory;
+}
+declare class HeliosAgent {
+    readonly name: string;
+    private helios;
+    private config;
+    private tools;
+    private history;
+    private isRegistered;
+    constructor(helios: Helios, name: string, config: HeliosAgentConfig);
+    /** Register agent in the Helios runtime and make it available for delegation */
+    register(): Promise<void>;
+    /** Delegate a task to this agent */
+    delegate(task: string): Promise<string>;
+    /** Add a tool to this agent */
+    addTool(name: string, fn: Function, metadata?: Partial<HeliosToolMetadata>): void;
+    /** Remove a tool from this agent */
+    removeTool(name: string): boolean;
+    /** List tool names on this agent */
+    listTools(): string[];
+    /** Switch the agent's model */
+    setModel(model: string): void;
+    /** Get agent's conversation history */
+    getHistory(): HeliosMessage[];
+    /** Clear agent's history */
+    clearHistory(): void;
+    /** Get the agent's config */
+    getConfig(): Readonly<HeliosAgentConfig>;
+}
+declare class Helios {
+    private config;
+    private tools;
+    private toolMetadata;
+    private modules;
+    private listeners;
+    private middleware;
+    private sessions;
+    private agents;
+    private memory;
+    private evaluator;
+    constructor(config?: HeliosConfig);
+    /** Get the current configuration (read-only copy) */
+    getConfig(): Readonly<HeliosConfig>;
+    /** Update configuration (merges with existing) */
+    updateConfig(updates: Partial<HeliosConfig>): void;
+    /** Register an event listener */
+    on<T extends HeliosEventType>(event: T, handler: HeliosEventHandler<T>): this;
+    /** Remove an event listener */
+    off<T extends HeliosEventType>(event: T, handler: HeliosEventHandler<T>): this;
+    /** Remove all listeners for an event, or all events if no type given */
+    removeAllListeners(event?: HeliosEventType): this;
+    /** Emit an event (internal + public) */
+    emit<T extends HeliosEventType>(event: T, data: HeliosEventMap[T]): void;
+    /** Add a middleware to the stack */
+    use(middleware: HeliosMiddleware): this;
+    /** Remove a middleware by name */
+    removeMiddleware(name: string): boolean;
+    /** Run prompt through middleware beforePrompt hooks */
+    runBeforePromptMiddleware(context: MiddlewarePromptContext): Promise<MiddlewarePromptContext>;
+    /** Run response through middleware afterPrompt hooks */
+    runAfterPromptMiddleware(context: MiddlewarePromptContext, response: MiddlewarePromptResponse): Promise<MiddlewarePromptResponse>;
+    /** Notify middleware of tool calls */
+    notifyToolCallMiddleware(name: string, args: unknown[]): Promise<void>;
+    /** Notify middleware of errors */
+    notifyErrorMiddleware(error: Error): Promise<void>;
+    /** Register a JavaScript function as a Helios tool */
+    registerTool(name: string, fn: Function, metadata?: Partial<HeliosToolMetadata>): this;
+    /** Unregister a tool */
+    unregisterTool(name: string): boolean;
+    /** List registered tools */
+    listTools(): HeliosToolMetadata[];
+    /** Register a module of functions */
+    registerModule(name: string, exports: Record<string, Function>): this;
+    /** Unregister a module */
+    unregisterModule(name: string): boolean;
+    /** Execute Helios source code */
+    run(source: string, context?: Record<string, unknown>): Promise<unknown>;
+    /** Create a new conversation session */
+    createSession(config?: HeliosSessionConfig): HeliosSession;
+    /** Get a session by ID */
+    getSession(id: string): HeliosSession | undefined;
+    /** List active session IDs */
+    listSessions(): string[];
+    /** Destroy a session */
+    destroySession(id: string): boolean;
+    /** Create a new agent with declarative config */
+    createAgent(name: string, config: HeliosAgentConfig): HeliosAgent;
+    /** Get an existing agent */
+    getAgent(name: string): HeliosAgent | undefined;
+    /** List all agent names */
+    listAgents(): string[];
+    /** Destroy an agent */
+    destroyAgent(name: string): boolean;
+    /** Access the vector memory store */
+    getMemory(): HeliosMemory;
+    /** Reset all state (evaluator, sessions, agents, memory) */
+    reset(): void;
+    /** Reset only the evaluator (keeps sessions, agents, memory) */
+    resetRuntime(): void;
+    private ensureEvaluator;
+}
+/** Fluent builder for creating a Helios instance */
+declare class HeliosBuilder {
+    private config;
+    private toolRegistrations;
+    private moduleRegistrations;
+    private middlewareStack;
+    private eventHandlers;
+    /** Set the AI provider */
+    provider(provider: HeliosProvider): this;
+    /** Set the API key */
+    apiKey(key: string): this;
+    /** Set the default model */
+    model(model: string): this;
+    /** Set a custom base URL */
+    baseUrl(url: string): this;
+    /** Set the system prompt */
+    systemPrompt(prompt: string): this;
+    /** Set sampling temperature */
+    temperature(temp: number): this;
+    /** Set memory limit */
+    memoryLimit(limit: number): this;
+    /** Set max loop iterations */
+    maxLoopIterations(limit: number): this;
+    /** Enable dry-run mode (no real AI calls) */
+    dryRun(enabled?: boolean): this;
+    /** Set input request handler */
+    onInputRequest(handler: (prompt: string) => Promise<string>): this;
+    /** Register a tool */
+    tool(name: string, fn: Function, metadata?: Partial<HeliosToolMetadata>): this;
+    /** Register a module */
+    module(name: string, exports: Record<string, Function>): this;
+    /** Add middleware */
+    use(middleware: HeliosMiddleware): this;
+    /** Add an event handler */
+    on<T extends HeliosEventType>(event: T, handler: HeliosEventHandler<T>): this;
+    /** Build the Helios instance */
+    build(): Helios;
+}
+/** Create a HeliosBuilder for fluent configuration */
+declare function createHelios(): HeliosBuilder;
+/** Quick-start: Create a Helios instance with minimal config */
+declare function helios(config?: HeliosConfig): Helios;
+
+export { Helios, HeliosAgent, type HeliosAgentConfig, type HeliosAgentDelegateEvent, HeliosBuilder, HeliosCancelledError, type HeliosConfig, HeliosConfigError, type HeliosEventHandler, type HeliosEventMap, type HeliosEventType, HeliosExecutionError, HeliosMemory, type HeliosMemoryEntry, type HeliosMemorySearchResult, type HeliosMessage, type HeliosMiddleware, type HeliosPrintPayload, type HeliosPromptEvent, type HeliosProvider, HeliosSDKError, HeliosSession, type HeliosSessionConfig, type HeliosToolCallEvent, type HeliosToolMetadata, type HeliosTraceEntry, type MiddlewarePromptContext, type MiddlewarePromptResponse, createHelios, helios };