@intella/sdk 0.0.1

package/examples/claude-code/advanced-config.ts

@@ -0,0 +1,55 @@
+/**
+ * Advanced Claude Code Agent Configuration
+ * 
+ * This example demonstrates advanced configuration options for the Claude Code agent,
+ * including tool permissions, MCP servers, and custom settings.
+ * 
+ * Prerequisites:
+ * 1. Install dependencies: npm install @intella/sdk ai ai-sdk-provider-claude-code
+ * 2. Install Claude Code CLI: npm install -g @anthropic-ai/claude-code
+ * 3. Authenticate: claude login
+ */
+
+import { IntellaSDK } from '../../src/index';
+
+async function main() {
+  const sdk = new IntellaSDK();
+
+  // Select and configure Claude agent with advanced options
+  sdk.selectAgent('claude', {
+    model: 'opus', // Most capable model
+    
+    // Tool permissions
+    allowedTools: ['Read', 'Write', 'Edit'], // Only allow these tools
+    disallowedTools: ['Bash'], // Explicitly disallow Bash
+    
+    // Permission mode
+    permissionMode: 'default', // Options: 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan'
+    
+    // MCP server configuration (optional)
+    // mcpServers: {
+    //   'my-server': {
+    //     command: 'node',
+    //     args: ['server.js'],
+    //   },
+    // },
+    
+    // Other options
+    maxTurns: 10, // Maximum conversation turns
+    cwd: process.cwd(), // Working directory
+    verbose: true, // Enable debug logging
+  });
+
+  console.log('Claude agent configured with advanced settings\n');
+
+  // Execute a task that might use tools
+  const response = await sdk.executeTask({
+    prompt: 'Read the package.json file and summarize the dependencies.',
+    systemPrompt: 'You are a helpful coding assistant.',
+  });
+
+  console.log('Response:', response.text);
+}
+
+main().catch(console.error);
+

package/examples/claude-code/basic-usage.ts

@@ -0,0 +1,56 @@
+/**
+ * Basic Claude Code Agent Usage
+ * 
+ * This example demonstrates basic usage of the Claude Code agent
+ * through the Intella SDK.
+ * 
+ * Prerequisites:
+ * 1. Install dependencies: npm install @intella/sdk ai ai-sdk-provider-claude-code
+ * 2. Install Claude Code CLI: npm install -g @anthropic-ai/claude-code
+ * 3. Authenticate: claude login
+ */
+
+import { IntellaSDK } from '../../src/index';
+
+async function main() {
+  const sdk = new IntellaSDK();
+
+  // Verify default agent before selection
+  console.log('Default agent before selection:', sdk.getDefaultAgentType());
+  console.log('Available agents:', sdk.listAgents());
+  console.log('');
+
+  // Select and configure Claude agent as default
+  // Claude Code uses CLI authentication (claude login)
+  sdk.selectAgent('claude', {
+    model: 'sonnet', // Options: 'opus', 'sonnet', 'haiku'
+    verbose: true, // Enable verbose logging to see Claude Code in action
+  });
+
+  // Verify agent selection
+  console.log('Default agent after selection:', sdk.getDefaultAgentType());
+  console.log('Claude agent config:', sdk.getAgentConfig('claude'));
+  console.log('');
+
+  // Execute a simple task (will use Claude as it's now the default)
+  console.log('Executing task with Claude Code agent...\n');
+  const response = await sdk.executeTask(
+    'Write a brief explanation of quantum computing in 2-3 sentences.'
+  );
+
+  console.log('\n=== Response ===');
+  console.log('Agent Type:', response.agentType);
+  console.log('Response:', response.text);
+  console.log('\n=== Metadata ===');
+  console.log(JSON.stringify(response.metadata, null, 2));
+  
+  // Final verification
+  if (response.agentType === 'claude') {
+    console.log('\n✅ SUCCESS: Claude Code agent was used!');
+  } else {
+    console.log(`\n❌ WARNING: Expected 'claude' but got '${response.agentType}'`);
+  }
+}
+
+main().catch(console.error);
+

package/examples/claude-code/model-comparison.ts

@@ -0,0 +1,50 @@
+/**
+ * Claude Code Model Comparison
+ * 
+ * This example demonstrates using different Claude models (Opus, Sonnet, Haiku)
+ * to compare their responses to the same prompt.
+ * 
+ * Prerequisites:
+ * 1. Install dependencies: npm install @intella/sdk ai ai-sdk-provider-claude-code
+ * 2. Install Claude Code CLI: npm install -g @anthropic-ai/claude-code
+ * 3. Authenticate: claude login
+ */
+
+import { IntellaSDK } from '../../src/index';
+
+async function main() {
+  const sdk = new IntellaSDK();
+
+  const prompt = 'Explain the concept of recursion in programming with a simple example.';
+  const models = ['haiku', 'sonnet', 'opus'] as const;
+
+  console.log('Comparing Claude models on the same prompt...\n');
+  console.log('Prompt:', prompt);
+  console.log('='.repeat(80) + '\n');
+
+  for (const model of models) {
+    console.log(`\n${model.toUpperCase()} Model:`);
+    console.log('-'.repeat(80));
+
+    // Select agent with specific model
+    sdk.selectAgent('claude', { model });
+
+    const startTime = Date.now();
+    const response = await sdk.executeTask(prompt);
+    const duration = Date.now() - startTime;
+
+    console.log(response.text);
+    console.log(`\nResponse time: ${duration}ms`);
+    console.log(`Tokens: ${response.metadata?.usage?.totalTokens || 'N/A'}`);
+    console.log('='.repeat(80));
+  }
+
+  console.log('\nComparison complete!');
+  console.log('\nModel characteristics:');
+  console.log('- Haiku: Fastest, good for simple tasks');
+  console.log('- Sonnet: Balanced performance and capability');
+  console.log('- Opus: Most capable, best for complex reasoning');
+}
+
+main().catch(console.error);
+

package/examples/claude-code/orchestration.ts

@@ -0,0 +1,70 @@
+/**
+ * Multi-Agent Orchestration with Claude Code
+ * 
+ * This example demonstrates orchestrating multiple agents including Claude Code
+ * for complex tasks that benefit from multiple AI perspectives.
+ * 
+ * Prerequisites:
+ * 1. Install dependencies: npm install @intella/sdk ai ai-sdk-provider-claude-code
+ * 2. Install Claude Code CLI: npm install -g @anthropic-ai/claude-code
+ * 3. Authenticate: claude login
+ */
+
+import { IntellaSDK } from '../../src/index';
+
+async function main() {
+  const sdk = new IntellaSDK();
+
+  // Configure multiple agents
+  sdk.configureAgent('claude', {
+    model: 'sonnet',
+  });
+
+  sdk.configureAgent('intella-lite', {
+    apiKey: process.env.OPENAI_API_KEY,
+    model: 'gpt-4o-mini',
+  });
+
+  console.log('Orchestrating task across multiple agents...\n');
+
+  // Sequential orchestration: Claude analyzes, then Intella Lite refines
+  const sequentialResult = await sdk.orchestrateTask(
+    {
+      prompt: 'Analyze the pros and cons of microservices architecture, then create a summary.',
+      systemPrompt: 'You are a software architecture expert.',
+    },
+    ['claude', 'intella-lite'],
+    'sequential',
+    {
+      passResults: true, // Pass Claude's analysis to Intella Lite for summarization
+    }
+  );
+
+  console.log('Sequential Orchestration Result:');
+  console.log('='.repeat(50));
+  console.log(sequentialResult.result);
+  console.log('\nAgent Responses:');
+  sequentialResult.agentResponses.forEach((agentResponse, index) => {
+    console.log(`\n${index + 1}. ${agentResponse.agentType}:`);
+    console.log(agentResponse.response.substring(0, 200) + '...');
+  });
+
+  console.log('\n\n' + '='.repeat(50) + '\n');
+
+  // Parallel orchestration: Get multiple perspectives simultaneously
+  const parallelResult = await sdk.orchestrateTask(
+    'What are the key considerations when choosing a database for a new project?',
+    ['claude', 'intella-lite'],
+    'parallel',
+    {
+      combineStrategy: 'merge', // Combine all responses
+    }
+  );
+
+  console.log('Parallel Orchestration Result:');
+  console.log('='.repeat(50));
+  console.log(parallelResult.result);
+}
+
+main().catch(console.error);
+

package/examples/claude-code/streaming.ts

@@ -0,0 +1,69 @@
+/**
+ * Streaming with Claude Code Agent
+ * 
+ * This example demonstrates how to stream responses from the Claude Code agent.
+ * 
+ * Prerequisites:
+ * 1. Install dependencies: npm install @intella/sdk ai ai-sdk-provider-claude-code
+ * 2. Install Claude Code CLI: npm install -g @anthropic-ai/claude-code
+ * 3. Authenticate: claude login
+ */
+
+import { IntellaSDK, extractCodeBlock } from '../../src/index';
+
+async function main() {
+  const sdk = new IntellaSDK();
+
+  // Select and configure Claude agent
+  sdk.selectAgent('intella-lite', {
+    model: 'gpt-4o-mini',
+  });
+
+  console.log('Streaming response from Claude Code agent...\n');
+
+  let code = ''
+
+  let chunks = []
+
+  // Stream the response
+  for await (const chunk of sdk.streamTask(
+    'Write a python script to generate ascii art of a cat'
+  )) {
+    // Write each chunk as it arrives
+    process.stdout.write(chunk.text);
+    chunks.push(chunk.text);
+    
+    if (chunk.isDone) {
+      console.log('\n\nStreaming complete!');
+      console.log('Agent Type:', chunk.agentType);
+    }
+  }
+
+  let response = chunks.join('');
+
+  console.log('Response:', response);
+
+  // Extract the code from the response
+
+  const codeBlock = extractCodeBlock(response, 'python');
+  if (!codeBlock) {
+    throw new Error('No python code block found');
+  }
+  code = codeBlock.code;
+
+  // Execute the code
+
+  console.log('Code:', code);
+
+  const sandbox = await sdk.initializeSandbox('e2b', {
+    templateId: 'base',
+  });
+  const result = await sandbox.runCode(code, {
+    language: 'python',
+  });
+  console.log('Result:', result);
+
+}
+
+main().catch(console.error);
+

package/examples/claude-code/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "../..",
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "lib": ["ES2020"],
+    "baseUrl": "../..",
+    "paths": {
+      "@intella/sdk": ["./src/index.ts"]
+    }
+  },
+  "include": ["*.ts", "../../src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}
+

package/examples/code-extractor/README.md

@@ -0,0 +1,77 @@
+# Code Extractor Utility Example
+
+This example demonstrates how to use the code extractor utility functions to extract code blocks from LLM responses in markdown format.
+
+## Functions
+
+### `extractCodeBlocks(text, options?)`
+
+Extracts all code blocks from markdown text. Returns an array of `CodeBlock` objects or code strings.
+
+**Options:**
+- `languages?: string[]` - Filter by specific language(s) (case-insensitive)
+- `codeOnly?: boolean` - Return only code strings instead of full objects
+- `includeFullMatch?: boolean` - Include the full match including fences
+- `customWrapper?: { start: string; end: string }` - Use custom wrapper strings instead of default ``` markers
+
+### `extractCodeBlock(text, language?)`
+
+Extracts the first code block from markdown text. Optionally filter by language.
+
+### `extractCode(text, language?)`
+
+Extracts the code content from the first code block as a string. Optionally filter by language.
+
+## Usage Examples
+
+```typescript
+import { extractCodeBlocks, extractCodeBlock, extractCode } from '@intella/sdk';
+
+const markdown = `
+Here's some code:
+\`\`\`typescript
+const x = 1;
+\`\`\`
+
+And a command:
+\`\`\`bash
+npm install
+\`\`\`
+`;
+
+// Extract all code blocks
+const blocks = extractCodeBlocks(markdown);
+// Returns: [
+//   { language: 'typescript', code: 'const x = 1;' },
+//   { language: 'bash', code: 'npm install' }
+// ]
+
+// Extract only TypeScript blocks
+const tsBlocks = extractCodeBlocks(markdown, { languages: ['typescript'] });
+
+// Extract only code strings
+const codeStrings = extractCodeBlocks(markdown, { codeOnly: true });
+// Returns: ['const x = 1;', 'npm install']
+
+// Extract first block
+const firstBlock = extractCodeBlock(markdown);
+// Returns: { language: 'typescript', code: 'const x = 1;' }
+
+// Extract code string only
+const code = extractCode(markdown, 'bash');
+// Returns: 'npm install'
+
+// Using custom wrapper
+const customMarkdown = '<code>typescript\nconst x = 1;\n</code>';
+const customBlocks = extractCodeBlocks(customMarkdown, {
+  customWrapper: { start: '<code>', end: '</code>' }
+});
+// Returns: [{ language: 'typescript', code: 'const x = 1;' }]
+```
+
+## Running the Example
+
+```bash
+# From the SDK root directory
+npx tsx examples/code-extractor/example.ts
+```

package/examples/code-extractor/example.ts

@@ -0,0 +1,145 @@
+/**
+ * Code Extractor Utility Example
+ * 
+ * This example demonstrates how to use the code extractor utility
+ * to extract code blocks from LLM responses in markdown format.
+ */
+
+import {
+  extractCodeBlocks,
+  extractCodeBlock,
+  extractCode,
+  type CodeBlock,
+} from '../../src/index';
+
+async function main() {
+  // Example markdown text with multiple code blocks
+  const markdownText = `
+Here's a TypeScript example:
+
+\`\`\`typescript
+function greet(name: string): string {
+  return \`Hello, \${name}!\`;
+}
+\`\`\`
+
+And here's a bash command:
+
+\`\`\`bash
+npm install @intella/sdk
+\`\`\`
+
+Finally, some Python code:
+
+\`\`\`python
+def calculate_sum(a, b):
+    return a + b
+\`\`\`
+  `;
+
+  console.log('=== Example 1: Extract All Code Blocks ===\n');
+  const allBlocks = extractCodeBlocks(markdownText) as CodeBlock[];
+  console.log(`Found ${allBlocks.length} code blocks:\n`);
+  allBlocks.forEach((block, index) => {
+    console.log(`Block ${index + 1}:`);
+    console.log(`  Language: ${block.language || '(none)'}`);
+    console.log(`  Code:\n${block.code}\n`);
+  });
+
+  console.log('\n=== Example 2: Extract Only TypeScript Blocks ===\n');
+  const tsBlocks = extractCodeBlocks(markdownText, {
+    languages: ['typescript'],
+  }) as CodeBlock[];
+  console.log(`Found ${tsBlocks.length} TypeScript block(s):\n`);
+  tsBlocks.forEach((block) => {
+    console.log(`Language: ${block.language}`);
+    console.log(`Code:\n${block.code}\n`);
+  });
+
+  console.log('\n=== Example 3: Extract Code Strings Only ===\n');
+  const codeStrings = extractCodeBlocks(markdownText, {
+    codeOnly: true,
+  }) as string[];
+  console.log(`Extracted ${codeStrings.length} code strings:\n`);
+  codeStrings.forEach((code, index) => {
+    console.log(`Code ${index + 1}:\n${code}\n`);
+  });
+
+  console.log('\n=== Example 4: Extract Single Code Block ===\n');
+  const bashBlock = extractCodeBlock(markdownText, 'bash');
+  if (bashBlock) {
+    console.log('Found bash block:');
+    console.log(`Language: ${bashBlock.language}`);
+    console.log(`Code: ${bashBlock.code}\n`);
+  }
+
+  console.log('\n=== Example 5: Extract Code String Only ===\n');
+  const pythonCode = extractCode(markdownText, 'python');
+  if (pythonCode) {
+    console.log('Python code:');
+    console.log(pythonCode);
+  }
+
+  console.log('\n=== Example 6: Extract with Full Match ===\n');
+  const blocksWithMatch = extractCodeBlocks(markdownText, {
+    includeFullMatch: true,
+  }) as CodeBlock[];
+  console.log('First block with full match:');
+  if (blocksWithMatch[0]?.fullMatch) {
+    console.log(blocksWithMatch[0].fullMatch);
+  }
+
+  // Example: Using with LLM response
+  console.log('\n=== Example 7: Real-world Usage with LLM Response ===\n');
+  const llmResponse = `
+I'll help you create a function. Here's the code:
+
+\`\`\`typescript
+export function add(a: number, b: number): number {
+  return a + b;
+}
+\`\`\`
+
+You can test it with:
+
+\`\`\`bash
+npm test
+\`\`\`
+  `;
+
+  const extractedCode = extractCode(llmResponse, 'typescript');
+  if (extractedCode) {
+    console.log('Extracted TypeScript code from LLM response:');
+    console.log(extractedCode);
+  }
+
+  // Example: Using custom wrapper
+  console.log('\n=== Example 8: Using Custom Wrapper ===\n');
+  const customMarkdown = `
+Here's some code with custom tags:
+
+<code>typescript
+function hello() {
+  console.log('Hello!');
+}
+</code>
+
+And another one:
+
+<code>bash
+echo "Hello World"
+</code>
+  `;
+
+  const customBlocks = extractCodeBlocks(customMarkdown, {
+    customWrapper: { start: '<code>', end: '</code>' },
+  }) as CodeBlock[];
+  console.log(`Found ${customBlocks.length} code blocks with custom wrapper:\n`);
+  customBlocks.forEach((block, index) => {
+    console.log(`Block ${index + 1}:`);
+    console.log(`  Language: ${block.language || '(none)'}`);
+    console.log(`  Code:\n${block.code}\n`);
+  });
+}
+
+main().catch(console.error);

package/examples/filesystem/basic-usage.ts

@@ -0,0 +1,84 @@
+import { IntellaSDK } from '../../src/index.js';
+
+/**
+ * Basic example demonstrating filesystem usage with Intella SDK
+ */
+async function main() {
+  const sdk = new IntellaSDK();
+
+  // Initialize filesystem with AgentFS provider
+  console.log('Initializing AgentFS filesystem...');
+  await sdk.initializeFilesystem('agentfs', {
+    agentId: 'example-agent',
+  });
+
+  // Filesystem operations
+  console.log('\n=== Filesystem Operations ===');
+  
+  // Write a file
+  await sdk.writeFile('/hello.txt', 'Hello from Intella SDK!');
+  console.log('✓ Wrote /hello.txt');
+
+  // Read the file
+  const content = await sdk.readFile('/hello.txt');
+  console.log(`✓ Read /hello.txt: ${content}`);
+
+  // Create a directory
+  await sdk.createDirectory('/output', true);
+  console.log('✓ Created /output directory');
+
+  // Write a file in the directory
+  await sdk.writeFile('/output/report.txt', 'This is a report');
+  console.log('✓ Wrote /output/report.txt');
+
+  // List directory contents
+  const entries = await sdk.readDirectory('/output');
+  console.log(`✓ Directory /output contains ${entries.length} entries:`);
+  for (const entry of entries) {
+    console.log(`  - ${entry.name} (${entry.stats.isDirectory ? 'dir' : 'file'})`);
+  }
+
+  // Key-value operations
+  console.log('\n=== Key-Value Operations ===');
+  
+  await sdk.setValue('user:preferences', { theme: 'dark', language: 'en' });
+  console.log('✓ Set user preferences');
+
+  const preferences = await sdk.getValue('user:preferences');
+  console.log(`✓ Got user preferences:`, preferences);
+
+  // Tool call tracking
+  console.log('\n=== Tool Call Tracking ===');
+  
+  await sdk.recordToolCall({
+    tool: 'web_search',
+    startedAt: Date.now() / 1000 - 5,
+    endedAt: Date.now() / 1000 - 4,
+    input: { query: 'AI agents' },
+    output: { results: ['result1', 'result2'] },
+    status: 'success',
+  });
+  console.log('✓ Recorded tool call');
+
+  const history = await sdk.getToolCallHistory({ limit: 10 });
+  console.log(`✓ Retrieved ${history.length} tool calls from history`);
+
+  // Using memory provider (ephemeral, in-memory)
+  console.log('\n=== Memory Provider (Ephemeral) ===');
+  
+  await sdk.closeFilesystem();
+  await sdk.initializeFilesystem('memory');
+  
+  await sdk.writeFile('/temp.txt', 'Temporary file');
+  console.log('✓ Wrote temporary file to memory filesystem');
+
+  const tempContent = await sdk.readFile('/temp.txt');
+  console.log(`✓ Read temporary file: ${tempContent}`);
+
+  // Cleanup
+  await sdk.closeFilesystem();
+  console.log('\n✓ Closed filesystem');
+}
+
+main().catch(console.error);
+

package/examples/integrated-task/README.md

@@ -0,0 +1,68 @@
+# Integrated Task Example
+
+This example demonstrates how to use **Agent**, **FileSystem**, and **Sandbox** together to carry out a complete task.
+
+## Overview
+
+The example shows a complete workflow:
+
+1. **Agent** generates Python code to calculate Fibonacci numbers
+2. **FileSystem** stores the generated code and results
+3. **Sandbox** executes the code in an isolated environment
+4. Results are read back and analyzed by the **Agent**
+
+## Prerequisites
+
+- Node.js 18+ or Bun
+- Environment variables:
+  - `E2B_API_KEY` - For E2B sandbox (or use Daytona)
+  - `ANTHROPIC_API_KEY` - For Claude agent (or use another agent)
+
+## Running the Example
+
+```bash
+# Install dependencies (if not already installed)
+cd packages/intella-sdk
+bun install
+
+# Run the example
+bun run examples/integrated-task/integrated-usage.ts
+```
+
+Or with Node.js:
+
+```bash
+npx tsx examples/integrated-task/integrated-usage.ts
+```
+
+## What It Does
+
+1. **Initializes Filesystem** - Sets up a memory-based filesystem for storing code and results
+2. **Initializes Sandbox** - Creates an E2B sandbox environment for code execution
+3. **Configures Agent** - Sets up Claude Sonnet to generate code
+4. **Generates Code** - Agent creates a Python script for Fibonacci calculation
+5. **Saves Code** - Code is stored in the filesystem
+6. **Executes in Sandbox** - The script runs in the isolated sandbox environment
+7. **Reads Results** - Results are retrieved from the sandbox
+8. **Persists Data** - Results are saved back to filesystem
+9. **Analyzes Results** - Agent analyzes the generated Fibonacci sequence
+10. **Tracks Metadata** - Tool calls are recorded for audit/debugging
+
+## Customization
+
+You can modify this example to:
+
+- Use different agents (intella-lite, codex, opencode)
+- Use different sandbox providers (daytona instead of e2b)
+- Use persistent filesystem (agentfs instead of memory)
+- Change the task to generate different types of code
+- Add more complex workflows with multiple agent interactions
+
+## Key Concepts
+
+- **Agent**: Generates code, analyzes results, provides AI capabilities
+- **FileSystem**: Persistent storage for code, data, and metadata
+- **Sandbox**: Isolated execution environment for running code safely
+
+Together, these three components enable powerful AI-driven development workflows.
+