@samrahimi/smol-js 0.6.4 → 0.7.0

package/README.md

@@ -1,24 +1,27 @@
 # smol-js
 
-**A TypeScript port of the [smolagents](https://github.com/huggingface/smolagents) agentic framework.**
+**A TypeScript agentic framework inspired by [smolagents](https://github.com/huggingface/smolagents).**
 
-Build AI agents that solve tasks by writing and executing JavaScript code. The agent reasons about problems, generates code, executes it in a sandbox, observes results, and iterates until it finds the answer.
+Build AI agents that solve tasks autonomously using the ReAct (Reasoning + Acting) pattern. Agents can write and execute JavaScript code, call tools, delegate to other agents, and orchestrate complex workflows via YAML definitions.
 
 [![npm version](https://img.shields.io/npm/v/@samrahimi/smol-js.svg)](https://www.npmjs.com/package/@samrahimi/smol-js)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ## Features
 
-- **ReAct Framework**: Reasoning + Acting loop (Thought → Code → Observation → repeat)
+- **Two Agent Types**:
+  - `CodeAgent` - Writes JavaScript code to solve tasks
+  - `ToolUseAgent` - Uses native LLM function calling (OpenAI-style)
+- **YAML Orchestration**: Define complex agent workflows declaratively
 - **Sandboxed Execution**: JavaScript runs in Node's vm module with state persistence
-- **Tool System**: Extensible tools that agents can call as functions
-- **Nested Agents**: Use agents as tools for hierarchical task delegation
+- **Extensible Tool System**: Built-in tools + easy custom tool creation
+- **Nested Agents**: Manager-worker patterns for hierarchical task delegation
+- **Exa.ai Integration**: Semantic web search, content extraction, and research automation
 - **Dynamic Imports**: Import npm packages on-the-fly via jsdelivr CDN
-- **Built-in fetch()**: Agents can make HTTP requests directly in generated code
 - **OpenAI-Compatible**: Works with OpenRouter, OpenAI, Azure, Anthropic, and local servers
 - **Streaming**: Real-time output streaming from the LLM
+- **Memory Management**: Context-aware with truncate/compact strategies
 - **Color-Coded Logging**: Beautiful terminal output with session logging to disk
-- **Error Recovery**: Agent can recover from errors and try different approaches
 
 ## Installation
 
@@ -28,6 +31,56 @@ npm install @samrahimi/smol-js
 
 ## Quick Start
 
+### Via CLI (YAML Workflows)
+
+The easiest way to get started is using YAML workflows:
+
+```bash
+# Run directly with npx (no installation needed)
+npx @samrahimi/smol-js workflow.yaml --task "Your task here"
+
+# Or install globally and use the CLI
+npm install -g @samrahimi/smol-js
+smol-js workflow.yaml --task "Research quantum computing"
+
+# Validate a workflow
+npx @samrahimi/smol-js validate workflow.yaml
+```
+
+Example workflow (`research-agent.yaml`):
+
+```yaml
+name: "Research Agent"
+description: "An agent that can search the web and write reports"
+
+model:
+  modelId: "anthropic/claude-sonnet-4.5"
+  baseUrl: "https://openrouter.ai/api/v1"
+  maxTokens: 4000
+
+tools:
+  search:
+    type: exa_search
+    config:
+      apiKey: "$EXA_API_KEY"
+
+  write:
+    type: write_file
+
+agents:
+  researcher:
+    type: ToolUseAgent
+    tools:
+      - search
+      - write
+    maxSteps: 10
+    customInstructions: "You are a thorough researcher. Always cite sources."
+
+entrypoint: researcher
+```
+
+### Programmatic Usage
+
 ```typescript
 import 'dotenv/config';
 import { CodeAgent, OpenAIModel } from '@samrahimi/smol-js';
@@ -48,16 +101,59 @@ const result = await agent.run('Calculate the first 10 prime numbers');
 console.log(result.output); // [2, 3, 5, 7, 11, 13, 17, 19, 23, 29]
 ```
 
+## Agent Types
+
+### CodeAgent
+
+Generates and executes JavaScript code to solve tasks. The agent has access to tools as async functions in its execution environment.
+
+```typescript
+import { CodeAgent, OpenAIModel } from '@samrahimi/smol-js';
+
+const agent = new CodeAgent({
+  model,
+  tools: [myTool],
+  maxSteps: 20,
+});
+
+await agent.run('Analyze the file data.csv and create a summary');
+```
+
+**How it works:**
+1. Agent generates thought + JavaScript code
+2. Code executes in sandboxed VM
+3. Results become observations
+4. Repeats until `final_answer()` is called
+
+### ToolUseAgent
+
+Uses native LLM function calling (OpenAI-style tool calling). Better for LLMs with strong tool-calling capabilities.
+
+```typescript
+import { ToolUseAgent, OpenAIModel } from '@samrahimi/smol-js';
+
+const agent = new ToolUseAgent({
+  model,
+  tools: [searchTool, readFileTool],
+  maxSteps: 15,
+  enableParallelToolCalls: true, // Execute independent tools in parallel
+});
+
+await agent.run('Search for recent AI papers and summarize the top 3');
+```
+
 ## Configuration
 
 ### Environment Variables
 
 ```bash
-# API key for LLM provider (OpenRouter by default)
+# API key for LLM provider
 OPENAI_API_KEY=sk-or-v1-your-openrouter-key
+# or
+OPENROUTER_API_KEY=sk-or-v1-your-key
 
-# Or for OpenAI directly
-OPENAI_API_KEY=sk-your-openai-key
+# For Exa.ai tools
+EXA_API_KEY=your-exa-api-key
 ```
 
 ### Model Configuration
@@ -66,7 +162,7 @@ OPENAI_API_KEY=sk-your-openai-key
 const model = new OpenAIModel({
   modelId: 'anthropic/claude-sonnet-4.5', // Model identifier
   apiKey: 'sk-...',                        // API key (or use env var)
-  baseUrl: 'https://openrouter.ai/api/v1', // API endpoint (default: OpenRouter)
+  baseUrl: 'https://openrouter.ai/api/v1', // API endpoint
   maxTokens: 4096,                          // Max tokens to generate
   temperature: 0.7,                         // Generation temperature
   timeout: 120000,                          // Request timeout in ms
@@ -82,16 +178,29 @@ const agent = new CodeAgent({
   maxSteps: 20,                             // Max iterations (default: 20)
   codeExecutionDelay: 5000,                 // Safety delay before execution (default: 5000ms)
   customInstructions: '...',                // Additional system prompt instructions
-  verboseLevel: LogLevel.INFO,              // Logging level (OFF, ERROR, INFO, DEBUG)
+  verboseLevel: LogLevel.INFO,              // Logging level
   streamOutputs: true,                      // Stream LLM output in real-time
-  additionalAuthorizedImports: ['lodash'],  // npm packages the agent can import
-  workingDirectory: '/path/to/dir',         // Working dir for fs operations
+  persistent: false,                        // Retain memory between run() calls
+  maxContextLength: 100000,                 // Token limit for context
+  memoryStrategy: 'truncate',               // 'truncate' or 'compact'
+  additionalAuthorizedImports: ['lodash'], // npm packages (CodeAgent only)
+  workingDirectory: '/path/to/dir',        // Working dir for fs operations
 });
 ```
 
-## Creating Tools
+## Built-in Tools
+
+- **FinalAnswerTool**: Return the final result (always available)
+- **UserInputTool**: Prompt for user input
+- **ReadFileTool**: Read file contents
+- **WriteFileTool**: Write to files
+- **CurlTool**: Make HTTP requests
+- **ExaSearchTool**: Semantic web search via Exa.ai
+- **ExaGetContentsTool**: Fetch and extract webpage content
+- **ExaResearchTool**: Multi-step research workflow
+- **AgentTool**: Wrap agents as tools for nested architectures
 
-Tools extend the agent's capabilities. The agent sees tools as async functions it can call.
+## Creating Custom Tools
 
 ### Class-Based Tools
 
@@ -124,158 +233,310 @@ const agent = new CodeAgent({
 });
 ```
 
-### Functional Tools
+### Registering Tools for YAML Workflows
 
 ```typescript
-import { createTool } from '@samrahimi/smol-js';
-
-const calculator = createTool({
-  name: 'calculate',
-  description: 'Evaluate a math expression',
-  inputs: {
-    expression: { type: 'string', description: 'Math expression to evaluate', required: true },
-  },
-  outputType: 'number',
-  execute: async (args) => {
-    return new Function('Math', `return ${args.expression}`)(Math);
-  },
-});
+import { YAMLLoader, Orchestrator } from '@samrahimi/smol-js';
+import { MyCustomTool } from './tools.js';
+
+const loader = new YAMLLoader();
+
+// Register custom tools by type name
+loader.registerToolType('my_tool', MyCustomTool);
+
+// Now use in YAML:
+// tools:
+//   custom:
+//     type: my_tool
+//     config:
+//       apiKey: "$MY_API_KEY"
+
+const workflow = loader.loadFromFile('./workflow.yaml');
+const orchestrator = new Orchestrator();
+await orchestrator.runWorkflow(workflow, 'Your task here');
 ```
 
-## Nested Agents (Agent as Tool)
+## YAML Workflow System
+
+Define complex agent architectures declaratively:
+
+```yaml
+name: "Multi-Agent Research System"
+description: "Manager-worker pattern with specialized agents"
+
+model:
+  modelId: "anthropic/claude-sonnet-4.5"
+  baseUrl: "https://openrouter.ai/api/v1"
+  apiKey: "$OPENROUTER_API_KEY"
+
+tools:
+  search:
+    type: exa_search
+    config:
+      apiKey: "$EXA_API_KEY"
+
+  read:
+    type: read_file
+
+  write:
+    type: write_file
+
+agents:
+  # Worker agent: specialized in research
+  researcher:
+    type: ToolUseAgent
+    tools:
+      - search
+      - read
+    maxSteps: 8
+    temperature: 0.3
+    customInstructions: "You are a research specialist. Be thorough and cite sources."
+
+  # Worker agent: specialized in writing
+  writer:
+    type: CodeAgent
+    tools:
+      - write
+    maxSteps: 5
+    temperature: 0.7
+    customInstructions: "You are a skilled technical writer. Create clear, engaging content."
+
+  # Manager agent: delegates to workers
+  manager:
+    type: ToolUseAgent
+    agents:
+      - researcher  # Available as a tool
+      - writer      # Available as a tool
+    maxSteps: 10
+    customInstructions: "You coordinate research and writing tasks. Delegate appropriately."
+
+entrypoint: manager
+```
 
-Use agents as tools for hierarchical task delegation. A "manager" agent can delegate specialized tasks to "worker" agents.
+Run it:
+
+```bash
+npx @samrahimi/smol-js research-workflow.yaml --task "Write a report on quantum computing"
+```
+
+## Nested Agents (Manager-Worker Pattern)
+
+Use agents as tools for hierarchical task delegation:
 
 ```typescript
-import { CodeAgent, OpenAIModel, AgentTool, agentAsTool } from '@samrahimi/smol-js';
+import { CodeAgent, ToolUseAgent, OpenAIModel, AgentTool } from '@samrahimi/smol-js';
 
-// Create a specialized worker agent
+// Create specialized worker agents
 const mathAgent = new CodeAgent({
   model,
-  tools: [calculatorTool],
   maxSteps: 5,
-  verboseLevel: LogLevel.OFF, // Quiet - manager reports results
+  verboseLevel: LogLevel.OFF, // Quiet - manager handles output
 });
 
-// Wrap it as a tool
+const researchAgent = new ToolUseAgent({
+  model,
+  tools: [searchTool],
+  maxSteps: 8,
+  verboseLevel: LogLevel.OFF,
+});
+
+// Wrap workers as tools
 const mathExpert = new AgentTool({
   agent: mathAgent,
   name: 'math_expert',
-  description: 'Delegate math problems to a specialized math agent',
+  description: 'Delegate math and calculation tasks to this agent',
 });
 
-// Or use the helper function
-const mathExpert = agentAsTool(mathAgent, {
-  name: 'math_expert',
-  description: 'Delegate math problems to a specialized math agent',
+const researcher = new AgentTool({
+  agent: researchAgent,
+  name: 'researcher',
+  description: 'Delegate research and information gathering to this agent',
 });
 
-// Create manager that uses the worker
-const manager = new CodeAgent({
+// Create manager that uses the workers
+const manager = new ToolUseAgent({
   model,
-  tools: [mathExpert, researchExpert], // Agents as tools!
+  tools: [mathExpert, researcher],
   maxSteps: 10,
 });
 
-await manager.run('Research Tokyo population and calculate water consumption');
+await manager.run('Research Tokyo population and calculate water consumption per capita');
 ```
 
-## Using fetch() Directly
+## Exa.ai Integration
+
+Three tools for web research powered by Exa.ai:
 
-Agents can make HTTP requests directly in their code without needing a tool:
+### ExaSearchTool
+
+Semantic search with advanced filtering:
 
 ```typescript
-const agent = new CodeAgent({
-  model,
-  tools: [], // No tools needed!
-  customInstructions: `You can use fetch() directly to make HTTP requests.
-Example: const data = await fetch('https://api.example.com').then(r => r.json());`,
+import { ExaSearchTool } from '@samrahimi/smol-js';
+
+const searchTool = new ExaSearchTool({
+  apiKey: process.env.EXA_API_KEY,
+  numResults: 10,
+  searchType: 'auto', // 'auto', 'neural', or 'keyword'
 });
+```
+
+### ExaGetContentsTool
+
+Extract clean webpage content:
+
+```typescript
+import { ExaGetContentsTool } from '@samrahimi/smol-js';
 
-await agent.run('Fetch users from https://jsonplaceholder.typicode.com/users');
+const contentTool = new ExaGetContentsTool({
+  apiKey: process.env.EXA_API_KEY,
+  textOnly: true,
+});
 ```
 
-## Dynamic npm Imports
+### ExaResearchTool
 
-The agent can import npm packages dynamically:
+Agentic web research that writes comprehensive reports:
 
 ```typescript
-const agent = new CodeAgent({
-  model,
-  additionalAuthorizedImports: ['lodash', 'dayjs', 'uuid'],
+import { ExaResearchTool } from '@samrahimi/smol-js';
+
+const researchTool = new ExaResearchTool({
+  apiKey: process.env.EXA_API_KEY,
+  model: 'exa-research', // or 'exa-research-fast', 'exa-research-pro'
 });
 
-// The agent can now write:
-// const _ = await importPackage('lodash');
-// const dayjs = await importPackage('dayjs');
-```
+// The Exa Research API is an asynchronous research agent that:
+// 1. Plans the research approach
+// 2. Executes searches across the web
+// 3. Extracts and analyzes facts from sources
+// 4. Synthesizes findings into a markdown report with citations
+// 5. Returns the complete report (typically 20-90 seconds)
 
-Packages are fetched from [jsdelivr CDN](https://www.jsdelivr.com/) and cached locally in `~/.smol-js/packages/`.
+// Usage in agent:
+await agent.run('Use exa_research to write a comprehensive report on quantum computing breakthroughs in 2024');
+```
 
-## Built-in Capabilities
+## Built-in Capabilities (CodeAgent)
 
-The agent's sandbox includes:
+The CodeAgent sandbox includes:
 
 | Category | Available |
 |----------|-----------|
 | **Output** | `console.log()`, `console.error()`, `print()` |
 | **HTTP** | `fetch()`, `URL`, `URLSearchParams` |
-| **File System** | `fs.readFileSync()`, `fs.writeFileSync()`, `fs.existsSync()`, etc. |
-| **Path** | `path.join()`, `path.resolve()`, `path.dirname()`, etc. |
+| **File System** | `fs.*` (readFileSync, writeFileSync, etc.) |
+| **Path** | `path.*` (join, resolve, dirname, etc.) |
 | **Data** | `JSON`, `Buffer`, `TextEncoder`, `TextDecoder` |
 | **Math** | `Math.*`, `parseInt()`, `parseFloat()` |
 | **Types** | `Object`, `Array`, `Map`, `Set`, `Date`, `RegExp`, `Promise` |
 | **Timers** | `setTimeout()`, `setInterval()` |
 | **Final** | `final_answer(value)` - Return the result |
 
+### Dynamic npm Imports
+
+```typescript
+const agent = new CodeAgent({
+  model,
+  additionalAuthorizedImports: ['lodash', 'dayjs', 'uuid'],
+});
+
+// Agent can now write:
+// const _ = await importPackage('lodash');
+// const result = _.uniq([1, 2, 2, 3]);
+```
+
+Packages are fetched from [jsdelivr CDN](https://www.jsdelivr.com/) and cached in `~/.smol-js/packages/`.
+
 ## Examples
 
-The `examples/` folder contains complete, runnable examples:
+See the `examples/js/` directory for complete examples:
 
-| Example | Description |
-|---------|-------------|
-| **01-simple-math.ts** | Basic calculation task |
-| **02-dynamic-imports.ts** | Using npm packages dynamically |
-| **03-variable-persistence.ts** | Multi-step state management |
-| **04-research-with-tools.ts** | Custom tools for research tasks |
-| **05-error-recovery.ts** | Handling and recovering from errors |
-| **06-deep-research.ts** | Real API calls with DuckDuckGo/Wikipedia |
-| **07-npm-package-import.ts** | Importing from the published npm package |
-| **08-fetch-agent.ts** | Agent using fetch() directly (no tools) |
-| **09-nested-agents.ts** | Manager agent delegating to worker agents |
+- **main.ts**: Main demo with custom tools and YAML workflows
+- **custom-tools.ts**: Custom tool implementations (TimestampTool, TextStatsTool, SlugifyTool)
+- **agents/**: YAML workflow definitions
+  - `custom_tools.yaml`: Workflow using custom tools
+  - `bloomberg.yaml`: Bloomberg research workflow
+  - `policy.yaml`: Policy analysis workflow
+  - `simple-test.yaml`: Simple test workflow
 
 Run an example:
 
 ```bash
-npx tsx examples/08-fetch-agent.ts
+cd examples/js
+npm install
+npx tsx main.ts
 ```
 
-## API Reference
+## Memory Management
 
-### CodeAgent
+Agents track all execution steps and manage context automatically:
 
 ```typescript
-class CodeAgent {
-  constructor(config: CodeAgentConfig)
+const agent = new CodeAgent({
+  model,
+  maxContextLength: 100000,    // Token limit
+  memoryStrategy: 'truncate',  // or 'compact'
+  persistent: false,           // Retain memory between run() calls
+});
 
-  // Run a task
-  run(task: string, reset?: boolean): Promise<RunResult>
+// Non-persistent (default): Fresh memory each run
+await agent.run('Task 1');
+await agent.run('Task 2'); // Doesn't remember Task 1
 
-  // Control
+// Persistent: Maintains conversation context
+const persistentAgent = new CodeAgent({ model, persistent: true });
+await persistentAgent.run('Remember this: X = 42');
+await persistentAgent.run('What is X?'); // Remembers X = 42
+```
+
+**Memory Strategies:**
+- **truncate**: Removes oldest steps when over token limit
+- **compact**: Uses LLM to summarize older steps
+
+## Session Logging
+
+All sessions are logged to `~/.smol-js/`:
+- `session-<timestamp>.log` - Full session transcript with color codes
+- `packages/` - Cached npm packages from dynamic imports
+
+## API Reference
+
+### Agent Base Class
+
+```typescript
+abstract class Agent {
+  constructor(config: AgentConfig)
+  run(task: string, reset?: boolean): Promise<RunResult>
   stop(): void
   reset(): void
-
-  // Tools
   addTool(tool: Tool): void
   removeTool(name: string): boolean
-  getTools(): Map<string, Tool>
-
-  // State
   getMemory(): AgentMemory
+}
+```
+
+### CodeAgent
+
+```typescript
+class CodeAgent extends Agent {
+  constructor(config: CodeAgentConfig)
   getExecutor(): LocalExecutor
 }
 ```
 
+### ToolUseAgent
+
+```typescript
+class ToolUseAgent extends Agent {
+  constructor(config: ToolUseAgentConfig)
+}
+
+interface ToolUseAgentConfig extends AgentConfig {
+  enableParallelToolCalls?: boolean; // Execute independent tools in parallel
+}
+```
+
 ### RunResult
 
 ```typescript
@@ -298,68 +559,60 @@ abstract class Tool {
 
   abstract execute(args: Record<string, unknown>): Promise<unknown>;
 
-  setup(): Promise<void>;          // Optional async initialization
+  setup(): Promise<void>;
   call(args: Record<string, unknown>): Promise<unknown>;
-  toCodePrompt(): string;          // Generate function signature for prompt
+  toCodePrompt(): string;          // For CodeAgent
+  toOpenAITool(): OpenAITool;      // For ToolUseAgent
 }
 ```
 
-### AgentTool
+### Orchestrator
 
 ```typescript
-class AgentTool extends Tool {
-  constructor(config: AgentToolConfig)
+class Orchestrator {
+  constructor(config?: { verbose?: boolean })
+
+  loadWorkflow(filePath: string): Workflow
+  loadWorkflowFromString(yaml: string): Workflow
+  runWorkflow(workflow: Workflow, task: string): Promise<void>
+  runAgent(agent: Agent, task: string): Promise<void>
+  getEventLog(): OrchestrationEvent[]
 }
-
-interface AgentToolConfig {
-  agent: Agent;              // The agent to wrap
-  name?: string;             // Tool name (default: 'managed_agent')
-  description?: string;      // Tool description
-  additionalContext?: string; // Extra context for the agent
-  returnFullResult?: boolean; // Return full result vs just output
-}
-
-// Helper function
-function agentAsTool(agent: Agent, options?: Omit<AgentToolConfig, 'agent'>): AgentTool
 ```
 
-### LocalExecutor
+### YAMLLoader
 
 ```typescript
-class LocalExecutor {
-  constructor(config?: ExecutorConfig)
-
-  execute(code: string): Promise<CodeExecutionOutput>
-  sendTools(tools: Record<string, Tool>): void
-  sendVariables(variables: Record<string, unknown>): void
-  reset(): void
-  getState(): Record<string, unknown>
-}
-
-interface ExecutorConfig {
-  timeout?: number;              // Execution timeout (default: 30000ms)
-  authorizedImports?: string[];  // Allowed npm packages
-  allowFs?: boolean;             // Enable fs access (default: true)
-  workingDirectory?: string;     // Working dir for fs operations
+class YAMLLoader {
+  registerToolType(typeName: string, toolClass: typeof Tool): void
+  loadFromFile(filePath: string): Workflow
+  loadFromString(yaml: string): Workflow
 }
 ```
 
-### LogLevel
+## CLI Reference
 
-```typescript
-enum LogLevel {
-  OFF = 0,    // No output
-  ERROR = 1,  // Errors only
-  INFO = 2,   // Normal output (default)
-  DEBUG = 3,  // Detailed debugging
-}
+```bash
+# Run a workflow
+npx @samrahimi/smol-js <workflow.yaml> [options]
+npx @samrahimi/smol-js run <workflow.yaml> [options]
+
+# Validate a workflow
+npx @samrahimi/smol-js validate <workflow.yaml>
+
+# Options
+--task, -t <task>    Task description (prompted if not provided)
+--quiet, -q          Reduce output verbosity
+--help, -h           Show help message
 ```
 
-## Session Logging
+## Security Considerations
 
-All sessions are logged to `~/.smol-js/`:
-- `session-<timestamp>.log` - Full session transcript
-- `packages/` - Cached npm packages
+- **Sandboxed Execution**: Code runs in Node's vm module, isolated from the main process
+- **Authorized Imports**: Only explicitly allowed npm packages can be imported
+- **File System Isolation**: fs operations are restricted to configured working directory
+- **Execution Delay**: Configurable delay before code execution allows user interruption (Ctrl+C)
+- **Timeout Protection**: Code execution has a configurable timeout (default: 30s)
 
 ## Comparison with Python smolagents
 
@@ -371,33 +624,33 @@ All sessions are logged to `~/.smol-js/`:
 | Nested agents | `ManagedAgent` | `AgentTool` |
 | Async support | Optional | All tools are async |
 | HTTP requests | Requires tool | Built-in `fetch()` |
-| Remote executors | E2B, Docker, etc. | Local only (for now) |
-| Agent types | CodeAgent, ToolCallingAgent | CodeAgent only |
-| Multi-agent | Yes | Yes (via AgentTool) |
-
-## Security Considerations
-
-- **Sandboxed Execution**: Code runs in Node's vm module, isolated from the main process
-- **Authorized Imports**: Only explicitly allowed npm packages can be imported
-- **File System Isolation**: fs operations are restricted to the configured working directory
-- **Execution Delay**: Configurable delay before code execution allows user interruption (Ctrl+C)
-- **Timeout Protection**: Code execution has a configurable timeout (default: 30s)
+| Remote executors | E2B, Docker, etc. | Local only |
+| Agent types | CodeAgent, ToolCallingAgent | CodeAgent, ToolUseAgent |
+| YAML workflows | ❌ | ✅ |
+| Exa.ai integration | ❌ | ✅ Built-in |
 
 ## Contributing
 
-Contributions are welcome! Please open an issue or PR on GitHub.
+Contributions are welcome! Please follow OOP principles and open an issue or PR on GitHub.
 
 ```bash
 # Clone and install
-git clone https://github.com/samrahimi/smol-js
-cd smol-js
+git clone https://github.com/samrahimi/smolagents
+cd smolagents/smol-js
 npm install
 
+# Build
+npm run build
+
 # Run tests
 npm test
 
-# Run examples
-npx tsx examples/01-simple-math.ts
+# Lint
+npm run lint
+npm run lint:fix
+
+# Type check
+npm run typecheck
 ```
 
 ## License
@@ -406,4 +659,4 @@ MIT
 
 ## Credits
 
-This is a TypeScript port of [smolagents](https://github.com/huggingface/smolagents) by Hugging Face.
+This is a TypeScript framework inspired by [smolagents](https://github.com/huggingface/smolagents) by Hugging Face, with additional features including YAML orchestration, ToolUseAgent, and Exa.ai integration.