LLMChat Documentation

LLMChat uses a modular, step-by-step workflow orchestration system to create agentic capabilities (like research agents). The process follows a specific lifecycle:

1. Define Event and Context Types: Establish the data structure for events emitted by tasks and the shared context passed between them.
2. Initialize Core Components: Set up a TypedEventEmitter for events, a Context object for shared state, and a WorkflowBuilder to manage the orchestration.
3. Define Research Tasks: Create individual tasks using createTask. Each task defines an execute function (containing the logic, e.g., LLM calls) and a route function (determining which task comes next).
4. Build and Execute: Register tasks with the WorkflowBuilder, call .build(), and start the workflow using .start(initialTaskName, initialData).

This architecture allows for real-time UI updates as each step emits events during the research process.

To build a research agent, you must define the event/context types, initialize the builder, define the tasks, and then assemble them.

1. Define Types

type AgentEvents = {
    taskPlanner: { tasks: string[]; query: string; };
    informationGatherer: { searchResults: string[]; };
    informationAnalyzer: { analysis: string; insights: string[]; };
    reportGenerator: { report: string; };
};

type AgentContext = {
    query: string;
    tasks: string[];
    searchResults: string[];
    analysis: string;
    insights: string[];
    report: string;
};

2. Initialize Components

import { OpenAI } from 'openai';
import { createTask } from 'task';
import { WorkflowBuilder } from './builder';
import { Context } from './context';
import { TypedEventEmitter } from './events';

const events = new TypedEventEmitter<AgentEvents>();
const builder = new WorkflowBuilder<AgentEvents, AgentContext>('research-agent', {
    events,
    context: new Context<AgentContext>({
        query: '',
        tasks: [],
        searchResults: [],
        analysis: '',
        insights: [],
        report: '',
    }),
});

const llm = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

3. Define and Build Tasks

Each task uses createTask with an execute function and a route function. Tasks can also declare dependencies.

// Example Task Planner
const taskPlanner = createTask({
    name: 'taskPlanner',
    execute: async ({ context, data }) => {
        // ... LLM logic to generate tasks ...
        context?.set('query', userQuery);
        context?.set('tasks', tasks);
        return { tasks, query: userQuery };
    },
    route: () => 'informationGatherer',
});

// Assemble
builder.addTask(taskPlanner);
// ... add other tasks ...
const workflow = builder.build();
workflow.start('taskPlanner', { query: 'Research the impact of AI on healthcare' });

// Full assembly pattern
builder.addTask(taskPlanner);
builder.addTask(informationGatherer);
builder.addTask(informationAnalyzer);
builder.addTask(reportGenerator);

const workflow = builder.build();
workflow.start('taskPlanner', { query: 'Research the impact of AI on healthcare' });

The llmchat service is designed with a privacy-first architecture where data is primarily stored on the client side.

Data Storage

• Local Storage & IndexedDB: All user data, including API keys, chat history, and messages, is stored locally in your browser.
• No Backend Storage: The service does not have a backend server to collect or store your personal data.
• Data Deletion: You can delete all data (API keys, configurations, and chat histories) at any time directly from your browser.

Data Transmission

• Direct Communication: When sending messages, your browser communicates directly with the API server via HTTPS. There is no middle server intercepting your data.
• Proxy Requests: For specific models, requests are routed through a proxy server that acts as a pass-through; the proxy does not log or store any request data.
• No External JavaScript: The service does not execute external JavaScript to maintain high security.

Third-Party Services

While the core service is local, the following third-party tools are used for service optimization:

• PostHog: Used for analytics and understanding user interactions.
• Sentry: Used for error logging and performance monitoring.
• Authentication: Google or GitHub login is required for limited access to the GPT-4o mini model (limited to 10 messages per day).

Workflows progress based on the output of tasks. There are three ways to determine the next task:

1. Explicit Redirection: Inside the execute function, call the redirectTo callback provided in the TaskParams.
2. Return Value: Return an object from the execute function containing { result, next }.
3. Router Function: The route function defined in the TaskConfig is called with the task result and execution context.

To end the workflow, return the special string 'end' from the router or redirection logic.

// Example 1: Using redirectTo
engine.task({
    name: 'decide',
    execute: async ({ redirectTo }) => {
        if (condition) redirectTo('task-a');
        else redirectTo(['task-b', 'task-c']); // Parallel execution
    }
});

// Example 2: Returning next in result
engine.task({
    name: 'process',
    execute: async () => {
        return { result: 'data', next: 'final-step' };
    }
});

// Example 3: Using the route function
engine.task({
    name: 'router-task',
    execute: async () => 'some-result',
    route: (result) => (result === 'success' ? 'end' : 'retry-task')
});