@flatfile/improv/docs/api-overview.md

A powerful TypeScript library for building AI agents with multi-threaded conversations, tool execution, and event handling capabilities

# API Overview

Improv provides three complementary APIs for different AI use cases, plus a comprehensive event system for monitoring and control.

## Core APIs

### Solo - Simple Structured Output
**When to use**: One-off LLM calls with type-safe structured responses

```typescript
import { Solo } from '@flatfile/improv';

const solo = new Solo({
  driver,
  outputSchema: z.object({
    sentiment: z.enum(["positive", "negative", "neutral"]),
    confidence: z.number()
  })
});

const result = await solo.ask("Analyze: 'Great product!'");
// result.output is fully typed
```

**Features**:
- Type-safe structured output with Zod schemas
- Built-in retry logic and fallback drivers
- Streaming support
- Perfect for classification and extraction

### Agent - Advanced Workflows
**When to use**: Complex, multi-step workflows requiring tool usage

```typescript
import { Agent } from '@flatfile/improv';

const agent = new Agent({
  driver,
  tools: [searchTool, calculatorTool],
  instructions: [
    { instruction: "Always search before answering", priority: 1 }
  ]
});

const thread = agent.createThread({ 
  prompt: "Research and calculate ROI for this investment" 
});
await thread.send();
```

**Features**:
- Tool execution with type-safe parameters
- Knowledge base and instruction management
- Multi-threaded conversation support
- Event-driven architecture

### Gig - Workflow Orchestration
**When to use**: Orchestrating multiple AI operations with dependencies

```typescript
import { Gig } from '@flatfile/improv';

const gig = new Gig({ label: "Customer Support", driver });

gig
  .add("classify", groove => 
    `Classify: "${groove.feelVibe("request")}"`, {
    outputSchema: z.enum(["technical", "billing", "general"])
  })
  .add("research", groove => {
    const category = groove.recall("classify");
    return `Research solutions for ${category} issue`;
  }, { tools: [searchTool] })
  .add("respond", groove => {
    const research = groove.recall("research");
    return `Generate response using: ${research}`;
  });

const results = await gig.perform({ 
  request: "My invoice is wrong!" 
});
```

**Features**:
- Sequential and parallel execution
- Auto-detection of Solo vs Agent needs
- Driver overrides per piece
- Type-safe result access

## Event System

All components emit events for monitoring and control:

```typescript
import { MESSAGE_EVENTS, TOOL_EVENTS, GIG_EVENTS } from '@flatfile/improv';

// Monitor message lifecycle
agent.on(MESSAGE_EVENTS.ADDED, ({ thread, message }) => {
  console.log(`Message added: ${message.content}`);
});

// Monitor tool execution
tool.on(TOOL_EVENTS.STARTED, ({ tool, name, args }) => {
  console.log(`Tool ${name} started`);
});

// Monitor workflow progress
gig.on(GIG_EVENTS.PERFORMANCE_COMPLETED, ({ results }) => {
  console.log('Workflow completed:', results);
});
```

## Model Drivers

Support for multiple LLM providers:

```typescript
import { 
  BedrockThreadDriver,
  OpenAIThreadDriver,
  CohereThreadDriver,
  GeminiThreadDriver,
  CerebrasThreadDriver
} from '@flatfile/improv';

// AWS Bedrock (Claude)
const bedrockDriver = new BedrockThreadDriver({
  model: 'anthropic.claude-3-haiku-20240307-v1:0'
});

// OpenAI
const openaiDriver = new OpenAIThreadDriver({
  model: 'gpt-4o',
  apiKey: process.env.OPENAI_API_KEY
});

// Use with any API
const solo = new Solo({ driver: openaiDriver });
const agent = new Agent({ driver: bedrockDriver });
```

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                        Event System                         │
│              (monitoring, debugging, control)               │
└─────────────────────────────────────────────────────────────┘
┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐
│    Solo     │  │   Agent     │  │          Gig            │
│             │  │             │  │                         │
│ ┌─────────┐ │  │ ┌─────────┐ │  │ ┌─────────┐ ┌─────────┐ │
│ │ Schema  │ │  │ │ Tools   │ │  │ │ Pieces  │ │ Groove  │ │
│ └─────────┘ │  │ └─────────┘ │  │ └─────────┘ └─────────┘ │
│ ┌─────────┐ │  │ ┌─────────┐ │  │ ┌─────────┐ ┌─────────┐ │
│ │ Driver  │ │  │ │ Threads │ │  │ │ Flow    │ │ Results │ │
│ └─────────┘ │  │ └─────────┘ │  │ └─────────┘ └─────────┘ │
└─────────────┘  └─────────────┘  └─────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│                    Thread System                            │
│         (message management, conversation state)            │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│                    Model Drivers                            │
│     (Bedrock, OpenAI, Cohere, Gemini, Cerebras, etc.)      │
└─────────────────────────────────────────────────────────────┘
```

## Quick Decision Guide

**Choose Solo when**:
- You need structured output from a single LLM call
- You're doing classification, extraction, or simple Q&A
- You want type safety with minimal setup

**Choose Agent when**:
- You need tool usage and multi-step reasoning
- You want persistent conversation threads
- You need complex decision-making workflows

**Choose Gig when**:
- You're orchestrating multiple AI operations
- You need dependency management between tasks
- You want to optimize costs with different models per task

## TypeScript Support

Full TypeScript support with:
- Type-safe event payloads
- Structured output inference
- Tool parameter validation
- IDE autocomplete and error checking

```typescript
// Fully typed structured output
const result = await solo.ask("...", MySchema);
result.output.myProperty; // Typed!

// Typed event handlers
agent.on(MESSAGE_EVENTS.ADDED, ({ thread, message }) => {
  // thread and message are properly typed
});
```

## Next Steps

- **[Event System Guide](./events-guide.md)** - Learn to use events effectively
- **[Events Reference](./events.md)** - Complete event documentation
- **[Structured Output Guide](./structured-output.md)** - Advanced Solo patterns
- **[Creating Pieces](./creating-pieces.md)** - Build reusable components