Chat-Flow

A production-ready conversation orchestration library with intent detection and workflow integration.

Features

• 🎯 Intent Detection - AI-powered intent classification with confidence scoring
• 💬 Session Management - Persistent conversation sessions with Redis or in-memory storage
• 🔄 Workflow Integration - Seamless integration with workflow engines (Zapier, N8N, etc.)
• 🤖 LLM Adapters - Support for multiple LLM providers (Gemini, OpenAI, etc.)
• 🏗️ Clean Architecture - Ports & Adapters pattern for maximum flexibility
• 📊 Type-Safe - Full TypeScript support with comprehensive type definitions
• ✅ Well-Tested - Comprehensive test coverage
• 🔧 Configurable - Flexible configuration system

Installation

npm install @your-org/chat-flow

Quick Start

import {
    Orchestrator,
    GeminiLLMAdapter,
    RedisRepository,
    IntentService,
    IntentRepository,
    IntentMatcher,
    MockWorkflowAdapter
} from '@your-org/chat-flow';

// Initialize adapters
const llm = new GeminiLLMAdapter(process.env.GOOGLE_AI_API_KEY!);
const repository = new RedisRepository('redis://localhost:6379');
const intentRepo = new IntentRepository(repository);
const intentMatcher = new IntentMatcher(llm);
const intentService = new IntentService(intentRepo, intentMatcher);
const workflow = new MockWorkflowAdapter();

// Create orchestrator with custom config
const orchestrator = new Orchestrator(
    repository,
    llm,
    intentService,
    workflow,
    {
        intent: {
            confidenceThreshold: 0.7,
            maxIntents: 5,
            cacheTTL: 300
        }
    }
);

// Create a session
const session = await orchestrator.createSession(
    'session-123',
    'TEXT',
    'You are a helpful travel assistant'
);

// Handle user messages
const { messages, metadata } = await orchestrator.handleMessage(
    session.sessionId,
    'I want to book a flight to Paris'
);

console.log('Assistant:', messages[0].content);
console.log('Intent detected:', metadata.intent);
console.log('Confidence:', metadata.confidence);

Core Concepts

Session Management

Sessions maintain conversation state and history:

const session = await orchestrator.createSession(
    'unique-session-id',
    'TEXT', // or 'VOICE'
    'Your agent prompt here'
);

Intent Detection

Automatically detect user intents with confidence scoring:

// Define intents
const intents = [
    {
        name: 'BOOK_FLIGHT',
        description: 'User wants to book a flight',
        required_fields: [
            { name: 'destination', type: 'string' },
            { name: 'date', type: 'string' }
        ]
    }
];

await intentRepo.upsertIntents(intents);

Workflow Integration

Execute workflows when intents are detected:

class CustomWorkflowAdapter implements IWorkflowAdapter {
    async executeWorkflow(workflowId: string, context: any): Promise<WorkflowResult> {
        // Your workflow execution logic
        return {
            success: true,
            data: { /* workflow results */ }
        };
    }
}

Configuration

Customize behavior with configuration options:

const config = {
    session: {
        ttl: 3600,              // Session TTL in seconds
        maxHistoryLength: 100   // Max messages to keep
    },
    intent: {
        confidenceThreshold: 0.6,  // Minimum confidence (0-1)
        maxIntents: 5,             // Max intents to return
        cacheTTL: 300              // Cache TTL in seconds
    },
    llm: {
        model: 'gemini-2.0-flash-lite',
        temperature: 0.7,
        maxTokens: 1000,
        timeout: 30000
    },
    workflow: {
        timeout: 60000,
        retries: 3,
        retryDelay: 1000
    },
    logging: {
        enabled: true,
        level: 'info',
        timestamps: true
    }
};

const orchestrator = new Orchestrator(repo, llm, intent, workflow, config);

Error Handling

Chat-Flow provides typed errors for better error handling:

import {
    SessionNotFoundError,
    IntentDetectionError,
    WorkflowExecutionError,
    LLMError
} from '@your-org/chat-flow';

try {
    await orchestrator.handleMessage(sessionId, message);
} catch (error) {
    if (error instanceof SessionNotFoundError) {
        console.error('Session not found:', error.details.sessionId);
    } else if (error instanceof IntentDetectionError) {
        console.error('Intent detection failed:', error.message);
    }
}

Architecture

Chat-Flow follows Clean Architecture principles:

┌─────────────────────────────────────────┐
│         Application Layer               │
│  (Orchestrator, ConversationSession)    │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│           Ports (Interfaces)            │
│  (IRepository, ILLMAdapter, etc.)       │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│        Adapters (Implementations)       │
│  (RedisRepository, GeminiLLMAdapter)    │
└─────────────────────────────────────────┘

Testing

Note: We prioritize Unit and Integration tests over ad-hoc scripts. Please check CONTRIBUTING.md for our testing policy.

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

Development

# Install dependencies
npm install

# Build
npm run build

# Run linter
npm run lint

# Format code
npm run format

# Run demo
npm run demo

Examples

See the /examples directory for more usage examples:

• Basic chat implementation
• Custom intent detection
• Workflow integration
• Custom adapters

API Documentation

For detailed API documentation, see API.md.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details.

License

MIT © [Your Organization]

Support

• 📧 Email: [email protected]
• 💬 Discord: Join our community
• 🐛 Issues: GitHub Issues