ZaFlow

https://github.com/zeative/zaflow
Admin
ZaFlow is a lightweight TypeScript library for building efficient AI agent workflows with...
Tokens:10,613
Snippets:60
Trust Score:7.3
License:MIT
Update:9 months ago
Show doc for...
Tokens:
Raw
### Quick Start ZaFlow with GroqProvider

Source: https://github.com/zeative/zaflow/blob/main/README.md

Demonstrates a minimal ZaFlow setup using the Groq provider to run an AI prompt. It initializes ZaFlow in single mode and executes a query, logging the content of the result.

```typescript
import { ZaFlow, defineProvider } from 'zaflow';

const GroqProvider = defineProvider({
  type: 'groq',
  apiKey: 'your-api-key',
  defaultModel: 'moonshotai/kimi-k2-instruct',
});

const zaflow = new ZaFlow({
  mode: 'single',
  provider: GroqProvider,
});

const result = await zaflow.run('Explain quantum computing in one sentence');
console.log(result.content);
```

--------------------------------

### Smart Media Reference System Example (TypeScript)

Source: https://github.com/zeative/zaflow/blob/main/README.md

Explains ZaFlow's smart media reference system for handling large media files efficiently. It demonstrates how `image()` can be used to pass references, saving tokens by only resolving full data for agents that explicitly require it (`needsMedia: ['image']`).

```typescript
// 20MB image is NOT copied to every agent
// Only reference ID is passed around
image(massive20MBBase64);

// Agents that need the image: needsMedia: ['image']
// → Receives full resolved data

// Agents that don't need the image
// → Media is stripped, saving tokens!
```

--------------------------------

### Install Ollama Provider

Source: https://github.com/zeative/zaflow/blob/main/README.md

Installs the Ollama provider package using npm. This is a prerequisite for using Ollama with ZaFlow.

```bash
npm install ollama
```

--------------------------------

### Stream AI Responses with ZaFlow

Source: https://context7.com/zeative/zaflow/llms.txt

This example shows how to configure ZaFlow to stream AI responses for real-time feedback. It includes setting up providers like OpenAI and utilizing hooks such as `onStreamChunk` and `onStreamComplete` to process response fragments as they arrive.

```typescript
import { ZaFlow, defineProvider } from 'zaflow';

const provider = defineProvider({
  type: 'openai',
  apiKey: 'sk-your-api-key',
  defaultModel: 'gpt-4o-mini'
});

const zaflow = new ZaFlow({
  mode: 'single',
  provider: provider,
  hooks: {
    onStreamChunk: (chunk) => {
      process.stdout.write(chunk); // Print each chunk as it arrives
    },
    onStreamComplete: (fullText) => {
      console.log('\n--- Streaming complete ---');
    }
  }
});

// Stream single response
const stream = zaflow.stream('Write a short story about a robot learning to paint');

for await (const chunk of stream) {
  // Process each chunk (already handled by hook in this example)
  // Can also handle here if needed
}

// Stream with tools (agentic mode)
const agenticZaflow = new ZaFlow({
  mode: 'agentic',
  provider: provider,
  tools: [/* your tools */]
});

const agenticStream = agenticZaflow.stream('Calculate 15 * 23 and explain the result', {
  config: { temperature: 0.3 }
});

for await (const chunk of agenticStream) {
  console.log(chunk);
}
```

--------------------------------

### Implement Event Hooks and Error Handling in ZaFlow

Source: https://context7.com/zeative/zaflow/llms.txt

This code illustrates how to leverage ZaFlow's event hooks for monitoring the AI execution lifecycle, from start to completion and error occurrences. It includes custom logic for handling tool execution and ensures graceful error management.

```typescript
import { ZaFlow, defineProvider, defineTool } from 'zaflow';
import { z } from 'zod';

const provider = defineProvider({
  type: 'groq',
  apiKey: 'gsk-your-api-key',
  defaultModel: 'llama-3.3-70b-versatile'
});

const databaseTool = defineTool({
  name: 'query_database',
  description: 'Query user database',
  schema: z.object({ query: z.string() }),
  execute: async ({ query }) => {
    // Simulate DB query
    if (query.includes('DROP')) {
      throw new Error('Dangerous query detected');
    }
    return [{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }];
  }
});

const zaflow = new ZaFlow({
  mode: 'agentic',
  provider: provider,
  tools: [databaseTool],
  hooks: {
    onStart: (input) => {
      console.log('[START]', input);
    },
    onComplete: (response) => {
      console.log('[COMPLETE]', response.content);
      if (response.metadata) {
        console.log('Tokens used:', response.metadata.tokensUsed);
        console.log('Tools called:', response.metadata.toolsCalled);
        console.log('Execution time:', response.metadata.executionTime, 'ms');
      }
    },
    onError: (error, context) => {
      console.error('[ERROR]', error.message);
      console.error('Phase:', context.phase);
      console.error('Input:', context.input);
      // Log to monitoring service
    },
    onToolStart: (toolName, args) => {
      console.log(`[TOOL START] ${toolName}`, args);
    },
    onToolComplete: (toolName, result) => {
      console.log(`[TOOL COMPLETE] ${toolName}`, result);
    },
    onToolError: (toolName, error) => {
      console.error(`[TOOL ERROR] ${toolName}`, error.message);
    }
  }
});

const result = await zaflow.run('Get all users from database', {
  detailed: true
});

if (result.error) {
  console.error('Execution failed:', result.error.message);
  console.error('Error code:', result.error.code);
} else {
  console.log('Success:', result.content);
  console.log('Model used:', result.metadata?.model);
}
```

--------------------------------

### Enforce JSON Structure with Zod Schema Validation in TypeScript

Source: https://github.com/zeative/zaflow/blob/main/README.md

Utilize Zod schemas with ZaFlow to ensure AI responses adhere to a predefined JSON structure. This method involves defining a Zod schema and passing it to the `run` method. While the AI is guided to produce structured output, manual parsing of `result.content` is necessary to obtain typed data.

```typescript
import { ZaFlow, defineProvider } from 'zaflow';
import { z } from 'zod';

const zaflow = new ZaFlow({
  mode: 'single',
  provider: GroqProvider,
});

// Define your expected response schema
const personSchema = z.object({
  name: z.string(),
  age: z.number(),
  occupation: z.string(),
  skills: z.array(z.string()),
});

const result = await zaflow.run('Extract info: John Doe is a 28 year old software engineer skilled in TypeScript and React', {
  schema: personSchema,
});

// result.content  → response string (may contain JSON)
// To get validated data, you need to parse result.content based on schema
console.log(result.content); // Raw response

```

```typescript
const articleSchema = z.object({
  title: z.string(),
  summary: z.string().max(200),
  tags: z.array(z.string()).min(1).max(5),
  sentiment: z.enum(['positive', 'negative', 'neutral']),
  metadata: z.object({
    wordCount: z.number(),
    readingTime: z.string(),
  }),
});

const result = await zaflow.run('Analyze this article: ...', {
  schema: articleSchema,
});

```

--------------------------------

### Define Multiple Agents with Roles and Prompts (TypeScript)

Source: https://github.com/zeative/zaflow/blob/main/README.md

Illustrates how to define different agents using `defineAgent`. It shows setting a name, role, system prompt, provider, model (optional), configuration, and associated tools for each agent.

```typescript
import { defineAgent, defineProvider } from 'zaflow';

const codeReviewer = defineAgent({
  name: 'Code Reviewer',
  role: 'Expert code reviewer',
  systemPrompt: `You are an expert code reviewer. Review code for bugs, security issues, and best practices.`,
  provider: GroqProvider,
  model: 'llama-3.3-70b-versatile',
  config: { temperature: 0.3 },
  tools: [lintTool, securityScanTool],
});

const contentWriter = defineAgent({
  name: 'Content Writer',
  role: 'Creative content writer',
  systemPrompt: 'You are a creative content writer.',
  provider: GroqProvider,
  config: { temperature: 0.8 },
});
```

--------------------------------

### Tool Configuration with Cache and Retry (TypeScript)

Source: https://github.com/zeative/zaflow/blob/main/README.md

Shows advanced tool configuration using `defineTool`, including setting a cache Time-To-Live (TTL) in milliseconds and defining retry logic with maximum attempts, delay, and backoff strategy.

```typescript
const tool = defineTool({
  name: 'my_tool',
  description: 'My tool description',
  schema: z.object({ input: z.string() }),
  execute: async ({ input }) => input,
  cache: 300000, // TTL in ms, or true for default
  retry: {
    maxAttempts: 3,
    delayMs: 1000,
    backoff: 'exponential',
  },
});
```

--------------------------------

### ZaFlow Single Mode Execution (TypeScript)

Source: https://github.com/zeative/zaflow/blob/main/README.md

Demonstrates how to initialize and run ZaFlow in single mode for a single chat call without tools. This mode is the fastest and most token-efficient. It requires specifying the mode as 'single' and a provider.

```typescript
const zaflow = new ZaFlow({
  mode: 'single',
  provider: GroqProvider,
});

const result = await zaflow.run('Hello!');
```

--------------------------------

### Define an Agent with Media Support (TypeScript)

Source: https://github.com/zeative/zaflow/blob/main/README.md

Shows the definition of a 'Vision Analyzer' agent designed for image analysis. While not explicitly defining media handling in the agent configuration itself, it notes that tools handling media will be automatically available.

```typescript
const visionAgent = defineAgent({
  name: 'Vision Analyzer',
  role: 'Image analysis expert',
  systemPrompt: 'You analyze images and describe their content.',
  provider: GroqProvider,
  // Tools that handle media will automatically be available
});
```

--------------------------------

### Initialize ZaFlow with Single Mode (TypeScript)

Source: https://context7.com/zeative/zaflow/llms.txt

Sets up ZaFlow for direct AI responses without tools or agent delegation. It requires defining an AI provider (e.g., OpenAI) and configuring basic parameters like temperature and max tokens. The 'run' method takes a prompt and returns the AI's direct response.

```typescript
import { ZaFlow, defineProvider } from 'zaflow';

const provider = defineProvider({
  type: 'openai',
  apiKey: 'sk-your-api-key',
  defaultModel: 'gpt-4o-mini'
});

const zaflow = new ZaFlow({
  mode: 'single',
  provider: provider,
  config: {
    temperature: 0.7,
    maxTokens: 2000
  }
});

const result = await zaflow.run('Explain quantum entanglement in simple terms');
console.log(result.content);
// Output: "Quantum entanglement is when two particles..."

```

--------------------------------

### ZaFlow with Calculator Tool

Source: https://github.com/zeative/zaflow/blob/main/README.md

Illustrates advanced ZaFlow usage by defining and integrating a 'calculator' tool using Zod for schema validation. This allows the AI agent to perform mathematical calculations.

```typescript
import { ZaFlow, defineProvider, defineTool } from 'zaflow';
import { z } from 'zod';

const calculator = defineTool({
  name: 'calculator',
  description: 'Perform mathematical calculations',
  schema: z.object({
    expression: z.string().describe('Math expression like "2 + 2"'),
  }),
  execute: ({ expression }) => eval(expression),
});

const zaflow = new ZaFlow({
  mode: 'agentic',
  // if you want to use other provider
  // provider: GroqProvider,
  tools: [calculator],
});

const result = await zaflow.run('What is 15 * 7 + 23?');
```

--------------------------------

### Register Agents with ZaFlow (TypeScript)

Source: https://github.com/zeative/zaflow/blob/main/README.md

Demonstrates how to register multiple defined agents (codeReviewer, contentWriter, visionAgent) with the ZaFlow instance when initializing it in autonomous mode.

```typescript
const zaflow = new ZaFlow({
  mode: 'autonomous',
  provider: GroqProvider,
  agents: [codeReviewer, contentWriter, visionAgent],
});
```

--------------------------------

### Define a Weather Tool with Zod Schema (TypeScript)

Source: https://github.com/zeative/zaflow/blob/main/README.md

Demonstrates defining a tool named 'get_weather' using ZaFlow's `defineTool` function. It includes input validation using Zod for city and optional unit, and a placeholder for the execution logic.

```typescript
import { defineTool } from 'zaflow';
import { z } from 'zod';

const weatherTool = defineTool({
  name: 'get_weather',
  description: 'Get current weather for a city',
  schema: z.object({
    city: z.string().describe('City name'),
    unit: z.enum(['celsius', 'fahrenheit']).optional(),
  }),
  execute: async ({ city, unit = 'celsius' }) => {
    // const data = await fetchWeatherAPI...
    return `Currently in ${city} is 20°`;
  },
});
```

--------------------------------

### ZaFlow Agentic Mode Execution (TypeScript)

Source: https://github.com/zeative/zaflow/blob/main/README.md

Illustrates initializing and running ZaFlow in agentic mode, where the AI can automatically call tools when needed. This mode requires the 'agentic' mode, a provider, and a list of available tools.

```typescript
const zaflow = new ZaFlow({
  mode: 'agentic',
  provider: GroqProvider,
  tools: [weatherTool],
});

const result = await zaflow.run('Search weather in Jakarta');
```

--------------------------------

### ZaFlow Autonomous Mode Execution (TypeScript)

Source: https://github.com/zeative/zaflow/blob/main/README.md

Shows how to set up and run ZaFlow in autonomous mode, enabling the AI to call tools and delegate tasks to other agents. This mode requires specifying 'autonomous' mode, a provider, a list of agents, and tools.

```typescript
const zaflow = new ZaFlow({
  mode: 'autonomous',
  provider: GroqProvider,
  agents: [visionAgent, poetAgent],
  tools: [analysisTool],
});

const result = await zaflow.run('Analyze this image and generate a poem');
```

--------------------------------

### Tool with Media Handling (TypeScript)

Source: https://github.com/zeative/zaflow/blob/main/README.md

Defines a tool named 'analyze_image' that is specifically designed to handle image inputs. The `handles` property is set to `['image']`, indicating its capability to process image data.

```typescript
const imageAnalyzer = defineTool({
  name: 'analyze_image',
  description: 'Analyze image content',
  schema: z.object({ imageUrl: z.string() }),
  handles: ['image'],
  execute: async ({ imageUrl }) => {
    // const data = await fetchAIImageAnalyzer...
    return 'The picture shows the sun rising!';
  },
});
```

--------------------------------

### Define OpenAI Provider

Source: https://github.com/zeative/zaflow/blob/main/README.md

Sets up the OpenAI provider for ZaFlow. Requires an API key and specifies the default model to be used.

```typescript
import { defineProvider } from 'zaflow';

const provider = defineProvider({
  type: 'openai',
  apiKey: 'sk-xxx',
  defaultModel: 'gpt-4o-mini',
});
```

--------------------------------

### Personalize AI Behavior with systemPrompt in TypeScript

Source: https://github.com/zeative/zaflow/blob/main/README.md

Tailor the AI's persona and response style using the `systemPrompt` option in ZaFlow. This allows you to define custom instructions, language preferences, and even specific personas for the AI, ensuring your customizations take precedence over library defaults.

```typescript
const result = await zaflow.run('Halo!', {
  systemPrompt: `Kamu adalah JawiBot, asisten AI berbahasa Jawa.
Jawab semua pertanyaan dalam bahasa Jawa yang sopan.
Gunakan emoji sesekali untuk membuat percakapan lebih hidup.`,
});

// Output: "Sugeng enjing! Aku JawiBot, asisten AI sing siap mbantu sampeyan! 😊"

```

--------------------------------

### Configure ZaFlow Execution Options in TypeScript

Source: https://github.com/zeative/zaflow/blob/main/README.md

Customize ZaFlow's execution behavior using various options within the `run` method. These include `config` for model parameters like `maxTokens` and `temperature`, `schema` for output structuring, `detailed` for metadata retrieval, `persistContext` for conversation history, and `systemPrompt` for AI personalization.

```typescript
const result = await zaflow.run(input, {
  config: {
    maxTokens: 4096,
    temperature: 0.7,
    topP: 0.9,
  },
  schema: responseSchema,
  detailed: true,
  persistContext: false,
  systemPrompt: 'You are a helpful assistant.',
});

```

--------------------------------

### Integrate Custom AI Provider with ZaFlow

Source: https://context7.com/zeative/zaflow/llms.txt

This snippet demonstrates how to integrate a custom AI provider by defining an adapter that communicates with an external AI API. It handles message formatting, configuration, and tool integration, returning structured responses including usage tokens and tool calls.

```typescript
import { ZaFlow, defineProvider } from 'zaflow';
import type { ProviderMessage, ModelConfig } from 'zaflow';

const customProvider = defineProvider({
  type: 'custom',
  name: 'my-ai-service',
  adapter: async (messages, config, tools) => {
    // Custom API integration
    const response = await fetch('https://my-ai-api.com/v1/chat', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer my-api-key',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        messages: messages.map(m => ({
          role: m.role,
          content: typeof m.content === 'string' ? m.content : m.content
        })),
        temperature: config.temperature || 0.7,
        max_tokens: config.maxTokens || 1000,
        tools: tools?.map(t => ({
          name: t.name,
          description: t.description,
          parameters: t.toJSONSchema()
        }))
      })
    });

    const data = await response.json();

    return {
      content: data.response || data.message || '',
      usage: {
        promptTokens: data.usage?.prompt_tokens || 0,
        completionTokens: data.usage?.completion_tokens || 0,
        totalTokens: data.usage?.total_tokens || 0
      },
      toolCalls: data.tool_calls?.map((tc: any) => ({
        id: tc.id,
        name: tc.function?.name,
        arguments: JSON.parse(tc.function?.arguments || '{}')
      }))
    };
  }
});

const zaflow = new ZaFlow({
  mode: 'single',
  provider: customProvider
});

const result = await zaflow.run('Hello, custom AI!');
console.log(result.content);
```

--------------------------------

### Implement Multimodal Support with Images and Media in TypeScript

Source: https://context7.com/zeative/zaflow/llms.txt

Enables processing of images, audio, and files with AI models using Zaflow's multimodal capabilities. This TypeScript snippet utilizes the 'zaflow' and 'zod' libraries, and Node.js 'fs' module. It demonstrates defining providers, tools that handle media, and running Zaflow with various input formats like URLs, base64 encoded images, and using message builders.

```typescript
import { ZaFlow, defineProvider, defineTool, msg, text, image, imageBase64 } from 'zaflow';
import { z } from 'zod';
import * as fs from 'fs';

const provider = defineProvider({
  type: 'openai',
  apiKey: 'sk-your-api-key',
  defaultModel: 'gpt-4o'
});

const imageAnalysisTool = defineTool({
  name: 'analyze_image',
  description: 'Perform detailed image analysis',
  schema: z.object({
    imageUrl: z.string(),
    analysisType: z.enum(['objects', 'text', 'faces'])
  }),
  handles: ['image'], // Tool can process images
  priority: 10,
  execute: async ({ imageUrl, analysisType }) => {
    return `Detected: 3 people, outdoor setting, daylight`;
  }
});

const zaflow = new ZaFlow({
  mode: 'agentic',
  provider: provider,
  tools: [imageAnalysisTool]
});

// Option 1: Image from URL
const result1 = await zaflow.run([
  text('Describe this image in detail'),
  image('https://example.com/photo.jpg', 'high')
]);

// Option 2: Image from base64
const imageBuffer = fs.readFileSync('./photo.jpg');
const base64Image = imageBuffer.toString('base64');

const result2 = await zaflow.run([
  text('What objects do you see?'),
  imageBase64(base64Image, 'image/jpeg', 'high')
]);

// Option 3: Using message builder
const messages = [
  msg.user([
    text('Analyze this image and identify key elements'),
    image('https://example.com/scene.png')
  ])
];

const result3 = await zaflow.run(messages);
console.log(result3.content);
// Output: "I can see a busy city street with cars, pedestrians..."

```

--------------------------------

### Define Custom AI Provider

Source: https://github.com/zeative/zaflow/blob/main/README.md

Shows how to define a custom AI provider for ZaFlow, including a fetch request to an external API and handling the response. This allows integration with any AI service.

```typescript
import { defineProvider } from 'zaflow';

// with your external AI API
const customAI = defineProvider({
  type: 'custom',
  name: 'my-ai',
  adapter: async (messages, config) => {
    const res = await fetch('https://my-api.com/chat', {
      method: 'POST',
      body: JSON.stringify({ messages }),
    });

    const json = await res.json();
    return {
      content: json.response,
      usage: {
        promptTokens: 0,
        completionTokens: 0,
        totalTokens: 0,
      },
    };
  },
});

const zaflow = new ZaFlow({ mode: 'single', provider: customAI });
```

--------------------------------

### Context Management and Conversation History in TypeScript

Source: https://context7.com/zeative/zaflow/llms.txt

This snippet illustrates how to manage conversation state, custom context, and history across multiple turns using ZaFlow. It requires the `zaflow` library and allows configuring history parameters like max messages and token limits. Custom context can be added and retrieved, and conversation history can be cleared or loaded.

```typescript
import { ZaFlow, defineProvider } from 'zaflow';

const provider = defineProvider({
  type: 'groq',
  apiKey: 'gsk-your-api-key',
  defaultModel: 'mixtral-8x7b-32768'
});

const zaflow = new ZaFlow({
  mode: 'single',
  provider: provider,
  historyConfig: {
    maxMessages: 20,
    maxTokens: 4000,
    strategy: 'sliding',
    keepSystemMessage: true
  }
});

// Add custom context
interface UserContext {
  userId: string;
  preferences: { theme: string; language: string };
  sessionData: any;
}

zaflow.addContext<UserContext>({
  userId: 'user-123',
  preferences: { theme: 'dark', language: 'en' },
  sessionData: { lastLogin: Date.now() }
});

// Multi-turn conversation
const response1 = await zaflow.run('My name is Alex and I love Python programming', {
  persistContext: true
});

const response2 = await zaflow.run('What programming language do I like?', {
  persistContext: true
});
console.log(response2.content);
// Output: "You mentioned that you love Python programming."

// Access conversation history
const history = zaflow.getHistory();
console.log(history);
// [
//   { role: 'user', content: 'My name is Alex...' },
//   { role: 'assistant', content: '...' },
//   { role: 'user', content: 'What programming language...' },
//   { role: 'assistant', content: 'You mentioned...' }
// ]

// Get context
const context = zaflow.getContext<UserContext>();
console.log(context.userId); // 'user-123'

// Clear history when needed
zaflow.clearHistory();

// Load previous conversation
zaflow.loadHistory([
  { role: 'user', content: 'Hello' },
  { role: 'assistant', content: 'Hi! How can I help?' }
]);
```

--------------------------------

### Implement File-Based Storage Plugin in TypeScript

Source: https://context7.com/zeative/zaflow/llms.txt

This snippet demonstrates how to define and integrate a file-based storage plugin for ZaFlow. It allows data persistence across sessions by saving and retrieving data from JSON files. Dependencies include 'zaflow' and 'zod'. It takes string keys and generic data types for storage operations.

```typescript
import { ZaFlow, defineProvider, defineTool, defineStorage } from 'zaflow';
import { z } from 'zod';
import * as fs from 'fs/promises';

// File-based storage plugin
const fileStorage = defineStorage({
  name: 'file-storage',
  adapter: {
    async get<T>(key: string): Promise<T | null> {
      try {
        const data = await fs.readFile(`./storage/${key}.json`, 'utf-8');
        return JSON.parse(data);
      } catch {
        return null;
      }
    },
    async set<T>(key: string, value: T, ttl?: number): Promise<void> {
      await fs.mkdir('./storage', { recursive: true });
      await fs.writeFile(`./storage/${key}.json`, JSON.stringify({ value, ttl }));
    },
    async delete(key: string): Promise<void> {
      await fs.unlink(`./storage/${key}.json`).catch(() => {});
    },
    async clear(): Promise<void> {
      await fs.rm('./storage', { recursive: true, force: true });
    },
    async keys(pattern?: string): Promise<string[]> {
      const files = await fs.readdir('./storage').catch(() => []);
      return files.map(f => f.replace('.json', ''));
    },
    async has(key: string): Promise<boolean> {
      try {
        await fs.access(`./storage/${key}.json`);
        return true;
      } catch {
        return false;
      }
    }
  }
});

const noteTool = defineTool({
  name: 'save_note',
  description: 'Save a note for later',
  schema: z.object({
    title: z.string(),
    content: z.string()
  }),
  execute: async ({ title, content }, context) => {
    await context.storage.set(`note:${title}`, { title, content, timestamp: Date.now() });
    return `Note "${title}" saved successfully`;
  }
});

const getNoteeTool = defineTool({
  name: 'get_note',
  description: 'Retrieve a saved note',
  schema: z.object({ title: z.string() }),
  execute: async ({ title }, context) => {
    const note = await context.storage.get<any>(`note:${title}`);
    return note ? note.content : 'Note not found';
  }
});

const provider = defineProvider({
  type: 'groq',
  apiKey: 'gsk-your-api-key',
  defaultModel: 'llama-3.3-70b-versatile'
});

const zaflow = new ZaFlow({
  mode: 'agentic',
  provider: provider,
  tools: [noteTool, getNoteeTool],
  storage: fileStorage
});

await zaflow.run('Save a note titled "meeting" with content "Discuss Q1 roadmap"');
const result = await zaflow.run('Get the meeting note');
console.log(result.content);
// Output: "The meeting note says: Discuss Q1 roadmap"

```

--------------------------------

### Define Groq Provider

Source: https://github.com/zeative/zaflow/blob/main/README.md

Configures the Groq provider for ZaFlow, including the API key and the default AI model.

```typescript
import { defineProvider } from 'zaflow';

const provider = defineProvider({
  type: 'groq',
  apiKey: 'gsk_xxx',
  defaultModel: 'llama-3.3-70b-versatile',
});
```

--------------------------------

### Access ZaFlow Execution Results and Metadata in TypeScript

Source: https://github.com/zeative/zaflow/blob/main/README.md

Retrieve detailed information about the execution of a ZaFlow `run` command. The `result` object contains the primary `content`, and if `detailed: true` was used, it also includes `metadata` such as token usage, tools/agents called, execution time, and the model used. Errors are available in the `error` property.

```typescript
const result = await zaflow.run(input);

result.content; // Response content (string)
result.metadata; // Execution metadata (if detailed: true)
result.metadata?.tokensUsed; // Token usage { prompt, completion, total }
result.metadata?.toolsCalled; // Array of tool names called
result.metadata?.agentsCalled; // Array of agent names called
result.metadata?.executionTime; // Execution time in milliseconds
result.metadata?.model; // Model name used
result.error; // Error object (if any)

```

--------------------------------

### Define and Use Tools with Agentic Mode (TypeScript)

Source: https://context7.com/zeative/zaflow/llms.txt

Enables AI agent workflows with tool calling capabilities. Tools are defined using Zod schemas for type safety and include descriptions, execution logic, caching, and retry configurations. ZaFlow can then automatically select and execute these tools based on user prompts.

```typescript
import { ZaFlow, defineProvider, defineTool } from 'zaflow';
import { z } from 'zod';

const weatherTool = defineTool({
  name: 'get_weather',
  description: 'Fetch current weather for a specific city',
  schema: z.object({
    city: z.string().describe('City name'),
    unit: z.enum(['celsius', 'fahrenheit']).optional().default('celsius')
  }),
  execute: async ({ city, unit }) => {
    // Simulate API call
    const temp = unit === 'celsius' ? '22°C' : '72°F';
    return `Weather in ${city}: ${temp}, partly cloudy`;
  },
  cache: 300000, // Cache for 5 minutes
  retry: {
    maxAttempts: 3,
    delayMs: 1000,
    backoff: 'exponential'
  }
});

const calculatorTool = defineTool({
  name: 'calculator',
  description: 'Perform mathematical calculations',
  schema: z.object({
    expression: z.string().describe('Mathematical expression like "25 * 4 + 10"')
  }),
  execute: ({ expression }) => {
    try {
      return eval(expression).toString();
    } catch (error) {
      return 'Invalid expression';
    }
  }
});

const provider = defineProvider({
  type: 'groq',
  apiKey: 'gsk-your-api-key',
  defaultModel: 'llama-3.3-70b-versatile'
});

const zaflow = new ZaFlow({
  mode: 'agentic',
  provider: provider,
  tools: [weatherTool, calculatorTool]
});

const result = await zaflow.run('What is the weather in Tokyo? Also calculate 156 * 23');
console.log(result.content);
// AI automatically calls both tools and returns:
// "The weather in Tokyo is 22°C, partly cloudy. The result of 156 * 23 is 3588."

```

--------------------------------

### Implement Semantic Search for Message Replies in TypeScript

Source: https://context7.com/zeative/zaflow/llms.txt

This code snippet illustrates how to use ZaFlow's 'msg.reply' function with semantic search to extract relevant information from a message for a concise reply. It supports different strategies like 'semantic' and 'truncate' for context management. Dependencies include 'zaflow'. It processes text and image inputs.

```typescript
import { ZaFlow, defineProvider, msg } from 'zaflow';

const provider = defineProvider({
  type: 'openai',
  apiKey: 'sk-your-api-key',
  defaultModel: 'gpt-4o-mini'
});

const zaflow = new ZaFlow({
  mode: 'single',
  provider: provider
});

// Original message with long content
const originalMessage = msg.user(`
  Artificial intelligence has revolutionized many industries. In healthcare,
  AI helps diagnose diseases from medical imaging with remarkable accuracy.
  In finance, it detects fraud and automates trading. Manufacturing uses AI
  for quality control and predictive maintenance. Transportation benefits
  from autonomous vehicles and route optimization. The retail sector employs
  AI for personalized recommendations and inventory management. Education
  platforms use AI to adapt learning paths to individual students.
`);

// Reply with semantic search (extracts only relevant parts)
const reply1 = msg.reply(
  originalMessage,
  'Tell me more about AI in healthcare',
  {
    strategy: 'semantic',
    semanticOptions: {
      maxChunks: 2,
      minSimilarity: 0.3,
      maxChunkLength: 150
    }
  }
);

const result1 = await zaflow.run(reply1);
console.log(result1.content);
// AI receives only the healthcare-related portion of the quoted message

// Reply with truncation (simple length limit)
const reply2 = msg.reply(
  originalMessage,
  'Summarize the quoted message',
  {
    strategy: 'truncate',
    maxLength: 200
  }
);

const result2 = await zaflow.run(reply2);

// Reply to multimodal message
const imageMessage = msg.user([
  text('Here is the product photo'),
  image('https://example.com/product.jpg')
]);

const imageReply = msg.reply(
  imageMessage,
  'What color is the product in the image?'
);

const result3 = await zaflow.run(imageReply);
console.log(result3.content);

```

--------------------------------

### Sending an Image from a URL in Messages (TypeScript)

Source: https://github.com/zeative/zaflow/blob/main/README.md

Illustrates how to include an image in a user message using a URL within the ZaFlow message structure. This utilizes the `msg.user` and `image` functions to combine text and image content.

```typescript
import { msg, text, image } from 'zaflow';

const messages = [
  ...
  msg.user([
    text('What is in this image?'),
    image('https://example.com/photo.jpg')
  ])
];

const result = await zaflow.run(messages);
```

--------------------------------

### Define Ollama Provider

Source: https://github.com/zeative/zaflow/blob/main/README.md

Initializes the Ollama provider for ZaFlow, specifying the base URL for the Ollama API and the default model.

```typescript
import { defineProvider } from 'zaflow';

const provider = defineProvider({
  type: 'ollama',
  baseURL: 'http://localhost:11434',
  defaultModel: 'llama3.2',
});
```

--------------------------------

### Structured Output with Zod Schemas in TypeScript

Source: https://context7.com/zeative/zaflow/llms.txt

This snippet demonstrates how to enforce AI responses into specific JSON structures using Zod schemas with ZaFlow. It requires the `zaflow` and `zod` libraries. The function takes a text prompt and a Zod schema, returning structured JSON output that conforms to the schema. It can handle complex nested objects and arrays.

```typescript
import { ZaFlow, defineProvider } from 'zaflow';
import { z } from 'zod';

const provider = defineProvider({
  type: 'openai',
  apiKey: 'sk-your-api-key',
  defaultModel: 'gpt-4o-mini'
});

const zaflow = new ZaFlow({
  mode: 'single',
  provider: provider
});

const personSchema = z.object({
  name: z.string(),
  age: z.number(),
  occupation: z.string(),
  skills: z.array(z.string()),
  experience: z.object({
    years: z.number(),
    companies: z.array(z.string())
  })
});

const result = await zaflow.run(
  'Extract info: Sarah Chen is a 32-year-old senior software engineer with 8 years experience. She worked at Google and Microsoft. Skills: Python, TypeScript, Kubernetes, AWS.',
  { schema: personSchema }
);

console.log(result.content);
// Output (AI returns JSON matching schema):
// {
//   "name": "Sarah Chen",
//   "age": 32,
//   "occupation": "senior software engineer",
//   "skills": ["Python", "TypeScript", "Kubernetes", "AWS"],
//   "experience": {
//     "years": 8,
//     "companies": ["Google", "Microsoft"]
//   }
// }

const productSchema = z.object({
  title: z.string(),
  summary: z.string().max(200),
  price: z.number(),
  category: z.enum(['electronics', 'clothing', 'books', 'home']),
  rating: z.number().min(0).max(5),
  inStock: z.boolean()
});

const productResult = await zaflow.run(
  'Parse: iPhone 15 Pro - Premium smartphone with A17 chip. Price $999. Category: Electronics. Rating 4.5/5. Available now.',
  { schema: productSchema, detailed: true }
);

console.log(JSON.parse(productResult.content));
```

--------------------------------

### Create Specialized Agents with Autonomous Mode in TypeScript

Source: https://context7.com/zeative/zaflow/llms.txt

Defines specialized agents with specific roles, tools, and models for complex workflows using Zaflow's autonomous mode. It requires the 'zaflow' and 'zod' libraries. The snippet demonstrates defining providers, tools, agents, and running a Zaflow instance to execute tasks.

```typescript
import { ZaFlow, defineProvider, defineAgent, defineTool } from 'zaflow';
import { z } from 'zod';

const groqProvider = defineProvider({
  type: 'groq',
  apiKey: 'gsk-your-api-key',
  defaultModel: 'llama-3.3-70b-versatile'
});

const codeAnalysisTool = defineTool({
  name: 'analyze_code',
  description: 'Analyze code for bugs and security issues',
  schema: z.object({
    code: z.string(),
    language: z.string()
  }),
  execute: async ({ code, language }) => {
    return `Analyzed ${language} code: No critical issues found. Suggestion: Add error handling.`;
  }
});

const sentimentTool = defineTool({
  name: 'analyze_sentiment',
  description: 'Analyze text sentiment',
  schema: z.object({
    text: z.string()
  }),
  execute: async ({ text }) => {
    return { sentiment: 'positive', confidence: 0.85 };
  }
});

const codeReviewerAgent = defineAgent({
  name: 'Code Reviewer',
  role: 'Expert code reviewer and security analyst',
  systemPrompt: 'You are an expert code reviewer. Analyze code for bugs, security vulnerabilities, and best practices.',
  provider: groqProvider,
  model: 'llama-3.3-70b-versatile',
  config: { temperature: 0.3 },
  tools: [codeAnalysisTool],
  capabilities: ['code-review', 'security-analysis']
});

const contentAnalystAgent = defineAgent({
  name: 'Content Analyst',
  role: 'Content and sentiment analysis specialist',
  systemPrompt: 'You analyze content for sentiment, tone, and key themes.',
  provider: groqProvider,
  config: { temperature: 0.5 },
  tools: [sentimentTool],
  capabilities: ['sentiment-analysis', 'content-review']
});

const zaflow = new ZaFlow({
  mode: 'autonomous',
  provider: groqProvider,
  agents: [codeReviewerAgent, contentAnalystAgent],
  tools: [codeAnalysisTool, sentimentTool]
});

const result = await zaflow.run('Review this Python code: def login(user, pwd): db.query(f"SELECT * FROM users WHERE name={user}"). Also analyze the sentiment of the code comments.');
console.log(result.content);
// Output: AI delegates to codeReviewerAgent for code review (finds SQL injection)
// and contentAnalystAgent for sentiment analysis, then combines results

```

--------------------------------

### Import ZaFlow TypeScript Types

Source: https://github.com/zeative/zaflow/blob/main/README.md

Import all necessary types for ZaFlow development in TypeScript. This comprehensive import statement provides access to various interfaces and types related to ZaFlow's options, responses, configurations, messages, models, tools, agents, and more.

```typescript
import type {
  ZaFlowOptions,
  ZaFlowResponse,
  RunOptions,
  StreamOptions,
  ModelConfig,
  HistoryConfig,
  Message,
  QuotedMessage,
  ExecutionMode,
  TokenUsage,
  ExecutionMetadata,
  ErrorResponse,
  Provider,
  ProviderDefinition,
  ProviderAdapter,
  ProviderResponse,
  ProviderMessage,
  ToolCall,
  RateLimit,
  Tool,
  ToolDefinition,
  ToolContext,
  SharedMemory,
  StorageInterface,
  Agent,
  AgentDefinition,
  AgentCapability,
  AgentConstraints,
  Hooks,
  ErrorContext,
  StoragePlugin,
  StorageAdapter,
  StorageDefinition,
  OptimizationConfig,
  RetryConfig,
  CacheConfig,
  TokenBudget,
  ContentPart,
  TextPart,
  ImagePart,
  AudioPart,
  FilePart,
  MediaType,
  QuoteConfig,
} from 'zaflow';

```

--------------------------------

### Sending an Image from Base64 Data in Messages (TypeScript)

Source: https://github.com/zeative/zaflow/blob/main/README.md

Shows how to send image data encoded in Base64 within a user message. The `imageBase64` function is used, requiring the Base64 data and the MIME type of the image.

```typescript
import { msg, text, imageBase64 } from 'zaflow';

const messages = [
  ...
  msg.user([
    text('Describe this:'),
    imageBase64(base64Data, 'image/png')
  ])
];

const result = await zaflow.run(messages, { mode: 'autonomous' });
```
Tokens:
Raw