@samrahimi/smol-js 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,793 @@
+import OpenAI from 'openai';
+
+/**
+ * Core types for smol-js
+ */
+type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
+interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+}
+interface Timing {
+    startTime: number;
+    endTime?: number;
+    duration?: number;
+}
+interface ChatMessage {
+    role: MessageRole;
+    content: string | null;
+    name?: string;
+    toolCalls?: ToolCall[];
+    toolCallId?: string;
+    tokenUsage?: TokenUsage;
+}
+interface ToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string | Record<string, unknown>;
+    };
+}
+type ToolInputType = 'string' | 'number' | 'boolean' | 'array' | 'object' | 'any';
+interface ToolInput {
+    type: ToolInputType;
+    description: string;
+    required?: boolean;
+    default?: unknown;
+}
+interface ToolInputs {
+    [key: string]: ToolInput;
+}
+interface CodeExecutionOutput {
+    output: unknown;
+    logs: string;
+    isFinalAnswer: boolean;
+    error?: Error;
+}
+interface ActionOutput {
+    output: unknown;
+    isFinalAnswer: boolean;
+}
+interface AgentConfig$1 {
+    model: Model$1;
+    tools?: Tool$1[];
+    maxSteps?: number;
+    codeExecutionDelay?: number;
+    systemPrompt?: string;
+    additionalAuthorizedImports?: string[];
+    streamOutputs?: boolean;
+    verboseLevel?: LogLevel;
+}
+interface ModelConfig {
+    modelId?: string;
+    apiKey?: string;
+    baseUrl?: string;
+    maxTokens?: number;
+    temperature?: number;
+    timeout?: number;
+}
+declare enum LogLevel {
+    OFF = -1,
+    ERROR = 0,
+    INFO = 1,
+    DEBUG = 2
+}
+type StepType = 'system' | 'task' | 'action' | 'planning' | 'final';
+interface MemoryStep {
+    type: StepType;
+    timestamp: number;
+}
+interface SystemPromptStep extends MemoryStep {
+    type: 'system';
+    content: string;
+}
+interface TaskStep extends MemoryStep {
+    type: 'task';
+    task: string;
+}
+interface ActionStep extends MemoryStep {
+    type: 'action';
+    stepNumber: number;
+    timing: Timing;
+    modelInputMessages: ChatMessage[];
+    modelOutputMessage?: ChatMessage;
+    codeAction?: string;
+    observation?: string;
+    actionOutput?: ActionOutput;
+    tokenUsage?: TokenUsage;
+    error?: Error;
+    isFinalAnswer?: boolean;
+}
+interface FinalAnswerStep extends MemoryStep {
+    type: 'final';
+    answer: unknown;
+}
+interface StreamEvent {
+    type: 'delta' | 'toolCall' | 'observation' | 'step' | 'final' | 'error';
+    data: unknown;
+}
+interface RunResult {
+    output: unknown;
+    steps: MemoryStep[];
+    tokenUsage: TokenUsage;
+    duration: number;
+}
+interface Tool$1 {
+    name: string;
+    description: string;
+    inputs: ToolInputs;
+    outputType: string;
+    execute: (args: Record<string, unknown>) => Promise<unknown>;
+    toCodePrompt: () => string;
+}
+interface Model$1 {
+    modelId: string;
+    generate: (messages: ChatMessage[], options?: GenerateOptions) => Promise<ChatMessage>;
+    generateStream?: (messages: ChatMessage[], options?: GenerateOptions) => AsyncGenerator<string, ChatMessage, undefined>;
+}
+interface GenerateOptions {
+    stopSequences?: string[];
+    maxTokens?: number;
+    temperature?: number;
+    tools?: Tool$1[];
+}
+
+/**
+ * Tool base class for smol-js
+ *
+ * Tools are the primary way for agents to interact with the outside world.
+ * Extend this class and implement the execute() method to create custom tools.
+ */
+
+declare abstract class Tool {
+    /**
+     * Unique identifier for the tool
+     */
+    abstract readonly name: string;
+    /**
+     * Human-readable description of what the tool does
+     */
+    abstract readonly description: string;
+    /**
+     * Input parameter schema
+     */
+    abstract readonly inputs: ToolInputs;
+    /**
+     * Output type description
+     */
+    abstract readonly outputType: string;
+    /**
+     * Whether the tool has been set up
+     */
+    protected isSetup: boolean;
+    /**
+     * Optional setup method called before first use.
+     * Override this for expensive initialization (loading models, etc.)
+     */
+    setup(): Promise<void>;
+    /**
+     * Execute the tool with the given arguments.
+     * Must be implemented by subclasses.
+     */
+    abstract execute(args: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Call the tool, ensuring setup is complete and validating arguments.
+     */
+    call(args: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Validate that provided arguments match the input schema.
+     */
+    protected validateArguments(args: Record<string, unknown>): void;
+    /**
+     * Check if a value matches the expected type.
+     */
+    protected checkType(value: unknown, expectedType: ToolInputType): boolean;
+    /**
+     * Generate a code-friendly prompt representation of this tool.
+     * Used in the CodeAgent system prompt.
+     */
+    toCodePrompt(): string;
+    /**
+     * Convert tool input type to JS/TS type string.
+     */
+    protected typeToJsType(type: ToolInputType | string): string;
+    /**
+     * Serialize the tool to a JSON-compatible object.
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Helper function to create a tool from a function.
+ * This is an alternative to extending the Tool class.
+ */
+declare function createTool(config: {
+    name: string;
+    description: string;
+    inputs: ToolInputs;
+    outputType: string;
+    execute: (args: Record<string, unknown>) => Promise<unknown>;
+}): Tool;
+
+/**
+ * Model base class for smol-js
+ *
+ * Models are responsible for generating text responses from LLMs.
+ * Extend this class to support different LLM providers.
+ */
+
+declare abstract class Model {
+    /**
+     * Model identifier (e.g., "gpt-4", "claude-3-sonnet")
+     */
+    abstract readonly modelId: string;
+    /**
+     * Generate a response from the model.
+     */
+    abstract generate(messages: ChatMessage[], options?: GenerateOptions): Promise<ChatMessage>;
+    /**
+     * Optional streaming generation.
+     * Yields content chunks and returns the final message.
+     */
+    generateStream?(messages: ChatMessage[], options?: GenerateOptions): AsyncGenerator<string, ChatMessage, undefined>;
+    /**
+     * Check if the model supports streaming.
+     */
+    supportsStreaming(): boolean;
+    /**
+     * Extract token usage from a response message.
+     */
+    protected extractTokenUsage(_response: unknown): TokenUsage | undefined;
+    /**
+     * Convert messages to the format expected by the model's API.
+     */
+    protected formatMessages(messages: ChatMessage[]): unknown[];
+}
+
+/**
+ * AgentMemory - Tracks agent execution history
+ *
+ * Stores all steps taken by the agent and converts them to messages
+ * that can be sent to the LLM for context.
+ */
+
+declare class AgentMemory {
+    /**
+     * System prompt step (always first)
+     */
+    systemPrompt: SystemPromptStep;
+    /**
+     * All execution steps
+     */
+    steps: (TaskStep | ActionStep | FinalAnswerStep)[];
+    constructor(systemPrompt: string);
+    /**
+     * Reset memory, keeping only the system prompt.
+     */
+    reset(): void;
+    /**
+     * Add a task step.
+     */
+    addTask(task: string): TaskStep;
+    /**
+     * Create a new action step.
+     */
+    createActionStep(stepNumber: number): ActionStep;
+    /**
+     * Add a final answer step.
+     */
+    addFinalAnswer(answer: unknown): FinalAnswerStep;
+    /**
+     * Get the last step.
+     */
+    getLastStep(): MemoryStep | undefined;
+    /**
+     * Get all action steps.
+     */
+    getActionSteps(): ActionStep[];
+    /**
+     * Convert memory to messages for LLM context.
+     */
+    toMessages(): ChatMessage[];
+    /**
+     * Get total token usage across all steps.
+     */
+    getTotalTokenUsage(): TokenUsage;
+    /**
+     * Get a summary of the memory for logging.
+     */
+    getSummary(): string;
+    /**
+     * Serialize memory to JSON.
+     */
+    toJSON(): Record<string, unknown>;
+}
+
+/**
+ * AgentLogger - Color-coded console logging for agent execution
+ *
+ * Provides formatted output with different colors for:
+ * - Headers (cyan)
+ * - Reasoning/Thoughts (yellow)
+ * - Code blocks (green)
+ * - Output/Results (blue)
+ * - Errors (red)
+ */
+
+declare class AgentLogger {
+    private level;
+    private logFile?;
+    private sessionId;
+    constructor(level?: LogLevel);
+    /**
+     * Generate a unique session ID.
+     */
+    private generateSessionId;
+    /**
+     * Initialize the log file.
+     */
+    private initLogFile;
+    /**
+     * Write to the log file.
+     */
+    private writeToFile;
+    /**
+     * Set the log level.
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Log a header (task start, step start, etc.)
+     */
+    header(message: string, level?: LogLevel): void;
+    /**
+     * Log a subheader.
+     */
+    subheader(message: string, level?: LogLevel): void;
+    /**
+     * Log reasoning/thought from the agent.
+     */
+    reasoning(content: string, level?: LogLevel): void;
+    /**
+     * Log code block.
+     */
+    code(content: string, language?: string, level?: LogLevel): void;
+    /**
+     * Log execution output.
+     */
+    output(content: string, level?: LogLevel): void;
+    /**
+     * Log execution logs (print statements).
+     */
+    logs(content: string, level?: LogLevel): void;
+    /**
+     * Log an error.
+     */
+    error(message: string, error?: Error, level?: LogLevel): void;
+    /**
+     * Log a warning.
+     */
+    warn(message: string, level?: LogLevel): void;
+    /**
+     * Log general info.
+     */
+    info(message: string, level?: LogLevel): void;
+    /**
+     * Log debug info.
+     */
+    debug(message: string): void;
+    /**
+     * Log final answer.
+     */
+    finalAnswer(answer: unknown, level?: LogLevel): void;
+    /**
+     * Log step progress.
+     */
+    stepProgress(current: number, max: number, level?: LogLevel): void;
+    /**
+     * Log waiting message for code execution delay.
+     */
+    waiting(seconds: number, level?: LogLevel): void;
+    /**
+     * Stream content character by character.
+     */
+    streamChar(char: string): void;
+    /**
+     * End streaming (add newline).
+     */
+    streamEnd(): void;
+    /**
+     * Close the log file.
+     */
+    close(): void;
+    /**
+     * Get the log file path.
+     */
+    getLogPath(): string | undefined;
+}
+
+/**
+ * Agent - Abstract base class for all agents
+ *
+ * Provides the foundation for multi-step agents that follow the ReAct framework.
+ * Extend this class to create specific agent implementations.
+ */
+
+interface AgentConfig {
+    /**
+     * The LLM model to use for generation
+     */
+    model: Model;
+    /**
+     * Tools available to the agent
+     */
+    tools?: Tool[];
+    /**
+     * Maximum number of steps before stopping
+     * @default 20
+     */
+    maxSteps?: number;
+    /**
+     * Delay in milliseconds before executing code (for user interruption)
+     * @default 5000
+     */
+    codeExecutionDelay?: number;
+    /**
+     * Custom system prompt (will be merged with generated prompt)
+     */
+    customInstructions?: string;
+    /**
+     * Log level for output
+     * @default LogLevel.INFO
+     */
+    verboseLevel?: LogLevel;
+    /**
+     * Whether to stream model outputs
+     * @default true
+     */
+    streamOutputs?: boolean;
+}
+declare abstract class Agent {
+    /**
+     * The LLM model for generation
+     */
+    protected model: Model;
+    /**
+     * Available tools mapped by name
+     */
+    protected tools: Map<string, Tool>;
+    /**
+     * Agent memory tracking all steps
+     */
+    protected memory: AgentMemory;
+    /**
+     * Logger for formatted output
+     */
+    protected logger: AgentLogger;
+    /**
+     * Configuration options
+     */
+    protected config: Required<Omit<AgentConfig, 'model' | 'tools'>>;
+    /**
+     * Current step number
+     */
+    protected currentStep: number;
+    /**
+     * Whether the agent is currently running
+     */
+    protected isRunning: boolean;
+    constructor(config: AgentConfig);
+    /**
+     * Initialize the system prompt for the agent.
+     * Must be implemented by subclasses.
+     */
+    protected abstract initializeSystemPrompt(): string;
+    /**
+     * Execute a single step in the agent loop.
+     * Must be implemented by subclasses.
+     *
+     * @param memoryStep - The memory step to populate with execution results
+     * @returns The action output from this step
+     */
+    protected abstract executeStep(memoryStep: ActionStep): Promise<ActionOutput>;
+    /**
+     * Run the agent on a task.
+     *
+     * @param task - The task description
+     * @param reset - Whether to reset memory before running
+     * @returns The final result
+     */
+    run(task: string, reset?: boolean): Promise<RunResult>;
+    /**
+     * Generate a final answer when max steps is reached.
+     */
+    protected provideFinalAnswer(task: string): Promise<unknown>;
+    /**
+     * Stop the agent.
+     */
+    stop(): void;
+    /**
+     * Get the current memory.
+     */
+    getMemory(): AgentMemory;
+    /**
+     * Get registered tools.
+     */
+    getTools(): Map<string, Tool>;
+    /**
+     * Add a tool to the agent.
+     */
+    addTool(tool: Tool): void;
+    /**
+     * Remove a tool from the agent.
+     */
+    removeTool(name: string): boolean;
+    /**
+     * Sleep for a specified duration.
+     */
+    protected sleep(ms: number): Promise<void>;
+}
+
+/**
+ * LocalExecutor - JavaScript code execution engine using Node's vm module
+ *
+ * Executes JavaScript code chunks in an isolated context with:
+ * - State persistence between steps (variables carry forward)
+ * - Tool injection (tools available as async functions)
+ * - Dynamic imports via CDN (esm.sh)
+ * - Print capture and logging
+ * - Safety timeouts
+ */
+
+interface ExecutorConfig {
+    /**
+     * Maximum execution time in milliseconds
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * Additional authorized imports (npm packages to allow)
+     */
+    authorizedImports?: string[];
+    /**
+     * Whether to allow fs module access
+     * @default true
+     */
+    allowFs?: boolean;
+    /**
+     * Working directory for fs operations
+     */
+    workingDirectory?: string;
+}
+declare class LocalExecutor {
+    private context;
+    private state;
+    private tools;
+    private config;
+    private capturedLogs;
+    constructor(config?: ExecutorConfig);
+    /**
+     * Create the VM context with available globals.
+     */
+    private createContext;
+    /**
+     * Add tools to the executor context.
+     */
+    sendTools(tools: Record<string, Tool>): void;
+    /**
+     * Send variables to the executor state.
+     */
+    sendVariables(variables: Record<string, unknown>): void;
+    /**
+     * Execute JavaScript code and return the result.
+     */
+    execute(code: string): Promise<CodeExecutionOutput>;
+    /**
+     * Wrap code to handle async execution and final_answer calls.
+     */
+    private wrapCode;
+    /**
+     * Instrument code to capture the last expression value and convert
+     * let/const/var declarations to global assignments for state persistence.
+     */
+    private instrumentCode;
+    /**
+     * Check if this is the last meaningful line of code.
+     */
+    private isLastMeaningfulLine;
+    /**
+     * Update internal state from context after execution.
+     */
+    private updateStateFromContext;
+    /**
+     * Stringify a value for logging.
+     */
+    private stringify;
+    /**
+     * Reset the executor state.
+     */
+    reset(): void;
+    /**
+     * Get the current state.
+     */
+    getState(): Record<string, unknown>;
+}
+
+/**
+ * CodeAgent - Executes tasks by generating and running JavaScript code
+ *
+ * This is the main agent implementation for smol-js. It follows the ReAct pattern:
+ * 1. Receives a task
+ * 2. Generates reasoning and code
+ * 3. Executes the code in a sandboxed environment
+ * 4. Observes the result and continues or returns final answer
+ */
+
+interface CodeAgentConfig extends AgentConfig {
+    /**
+     * Additional npm packages that can be imported dynamically
+     */
+    additionalAuthorizedImports?: string[];
+    /**
+     * Executor configuration
+     */
+    executorConfig?: ExecutorConfig;
+    /**
+     * Working directory for file operations
+     */
+    workingDirectory?: string;
+}
+declare class CodeAgent extends Agent {
+    /**
+     * The JavaScript code executor
+     */
+    private executor;
+    /**
+     * Authorized imports for dynamic npm package loading
+     */
+    private authorizedImports;
+    constructor(config: CodeAgentConfig);
+    /**
+     * Initialize the system prompt with tool definitions.
+     */
+    protected initializeSystemPrompt(): string;
+    /**
+     * Execute a single step: get LLM response, extract code, execute it.
+     */
+    protected executeStep(memoryStep: ActionStep): Promise<ActionOutput>;
+    /**
+     * Generate response from the LLM, optionally streaming.
+     */
+    private generateResponse;
+    /**
+     * Format output for display.
+     */
+    private formatOutput;
+    /**
+     * Format the observation to send back to the LLM.
+     */
+    private formatObservation;
+    /**
+     * Reset the agent and executor state.
+     */
+    reset(): void;
+    /**
+     * Get the executor instance.
+     */
+    getExecutor(): LocalExecutor;
+    /**
+     * Override addTool to also register with executor.
+     */
+    addTool(tool: Tool): void;
+}
+
+/**
+ * OpenAI-compatible Model implementation
+ *
+ * Supports any API that follows the OpenAI chat completions format,
+ * including OpenRouter, Azure OpenAI, local servers, etc.
+ */
+
+interface OpenAIModelConfig {
+    /**
+     * Model identifier (e.g., "gpt-4", "anthropic/claude-sonnet-4.5")
+     */
+    modelId?: string;
+    /**
+     * API key for authentication
+     */
+    apiKey?: string;
+    /**
+     * Base URL for the API endpoint
+     * @default "https://openrouter.ai/api/v1"
+     */
+    baseUrl?: string;
+    /**
+     * Maximum tokens to generate
+     */
+    maxTokens?: number;
+    /**
+     * Temperature for generation (0-2)
+     */
+    temperature?: number;
+    /**
+     * Request timeout in milliseconds
+     */
+    timeout?: number;
+    /**
+     * Default headers to include in requests
+     */
+    defaultHeaders?: Record<string, string>;
+}
+declare class OpenAIModel extends Model {
+    readonly modelId: string;
+    private client;
+    private config;
+    constructor(config?: OpenAIModelConfig);
+    /**
+     * Generate a response from the model.
+     */
+    generate(messages: ChatMessage[], options?: GenerateOptions): Promise<ChatMessage>;
+    /**
+     * Generate a streaming response from the model.
+     */
+    generateStream(messages: ChatMessage[], options?: GenerateOptions): AsyncGenerator<string, ChatMessage, undefined>;
+    /**
+     * Format messages for the OpenAI API.
+     */
+    protected formatMessages(messages: ChatMessage[]): OpenAI.Chat.ChatCompletionMessageParam[];
+}
+
+/**
+ * Default tools provided to all agents
+ */
+
+/**
+ * FinalAnswerTool - Used by the agent to return the final answer.
+ * This is always available to CodeAgent.
+ */
+declare class FinalAnswerTool extends Tool {
+    readonly name = "final_answer";
+    readonly description = "Returns the final answer to the user query. Use this when you have completed the task and have the final result.";
+    readonly inputs: ToolInputs;
+    readonly outputType = "any";
+    execute(args: Record<string, unknown>): Promise<unknown>;
+}
+/**
+ * UserInputTool - Allows the agent to ask the user for input.
+ */
+declare class UserInputTool extends Tool {
+    readonly name = "user_input";
+    readonly description = "Asks the user for additional input or clarification.";
+    readonly inputs: ToolInputs;
+    readonly outputType = "string";
+    private inputHandler?;
+    constructor(inputHandler?: (question: string) => Promise<string>);
+    execute(args: Record<string, unknown>): Promise<string>;
+}
+declare const finalAnswerTool: FinalAnswerTool;
+
+/**
+ * System prompts for CodeAgent
+ *
+ * Adapted from smolagents Python prompts but optimized for JavaScript execution.
+ */
+interface PromptVariables {
+    tools: string;
+    authorizedImports: string;
+    customInstructions?: string;
+}
+/**
+ * Generate the system prompt for CodeAgent.
+ */
+declare function generateSystemPrompt(variables: PromptVariables): string;
+/**
+ * Prompt for generating a final answer when max steps is reached.
+ */
+declare const FINAL_ANSWER_PROMPT = "Based on the steps you've taken so far, provide the best answer you can to the original task.\nIf you couldn't fully complete the task, explain what you accomplished and what remains to be done.\nCall final_answer() with your response.";
+/**
+ * Error recovery prompt.
+ */
+declare function getErrorRecoveryPrompt(error: string): string;
+
+export { type ActionOutput, type ActionStep, Agent, type AgentConfig, type AgentConfig$1 as AgentConfigType, AgentLogger, AgentMemory, type ChatMessage, CodeAgent, type CodeAgentConfig, type CodeExecutionOutput, type ExecutorConfig, FINAL_ANSWER_PROMPT, type FinalAnswerStep, FinalAnswerTool, type GenerateOptions, LocalExecutor, LogLevel, type MemoryStep, type MessageRole, Model, type ModelConfig, OpenAIModel, type OpenAIModelConfig, type PromptVariables, type RunResult, type StreamEvent, type SystemPromptStep, type TaskStep, type Timing, type TokenUsage, Tool, type ToolCall, type ToolInput, type ToolInputType, type ToolInputs, UserInputTool, createTool, finalAnswerTool, generateSystemPrompt, getErrorRecoveryPrompt };