workstory-agent

@workstory/agent

Multi-agent system for extracting structured work story data from conversational inputs using LLM-powered property agents.

Installation

npm install @workstory/agent

Quick Start

import { MCPStorageManager, MemoryStorageAdapter, createDefaultAgents } from '@workstory/agent';

// Create storage adapter (or use FirestoreStorageAdapter for production)
const storageAdapter = new MemoryStorageAdapter();

// Initialize manager with OpenAI API key
const manager = new MCPStorageManager({
  storageAdapter,
  agents: createDefaultAgents(),
  autoUpdate: true,
  llmConfig: {
    apiKey: process.env.OPENAI_API_KEY,
    model: 'gpt-4o',
    temperature: 0.7,
    maxTokens: 1000,
  },
});

// Add a chat message
await manager.addChatMessage('user123', {
  id: 'msg1',
  role: 'user',
  content: 'I worked at Google as a Software Engineer from 2020 to 2022',
  timestamp: new Date().toISOString(),
});

// Work story will auto-update (if autoUpdate: true)
// Or manually trigger update
const result = await manager.updateWorkStoryFromChat('user123', 50);

// Get the updated work story
const workStory = await manager.getWorkStory('user123');
console.log(workStory.data.timeline.engagements);

Features

• Multi-Agent Architecture: Specialized agents extract different data types (work experience, skills, education, etc.)
• LLM-Powered Extraction: Uses OpenAI GPT-4o for intelligent data extraction from natural language
• Gold Standard Format: Follows org.workstory.standard v1.0.0 schema
• Flexible Storage: Works with any storage backend via adapters
• Real-time Updates: Auto-updates work story as chat messages arrive
• TypeScript Support: Full TypeScript types included

Storage Adapters

MemoryStorageAdapter (Testing)

import { MemoryStorageAdapter } from '@workstory/agent';

const adapter = new MemoryStorageAdapter();

FirestoreStorageAdapter (Production)

import { FirestoreStorageAdapter } from '@workstory/agent';
import { getFirestore } from 'firebase/firestore';

const db = getFirestore();
const adapter = new FirestoreStorageAdapter(db);

Note: Requires firebase as a peer dependency. Install with:

npm install firebase

Custom Adapter

Implement the MCPStorageAdapter interface:

import { MCPStorageAdapter, GoldStandardWorkStory, ChatMessage } from '@workstory/agent';

class MyCustomAdapter implements MCPStorageAdapter {
  async readWorkStory(userId: string): Promise<GoldStandardWorkStory | null> {
    // Read from your database
  }
  
  async writeWorkStory(userId: string, workStory: GoldStandardWorkStory): Promise<void> {
    // Write to your database
  }
  
  async readChatLog(userId: string, limit?: number): Promise<ChatMessage[]> {
    // Read chat messages
  }
  
  async writeChatMessage(userId: string, message: ChatMessage): Promise<void> {
    // Write chat message
  }
}

Property Agents

The package includes default agents for:

• PersonalInfoAgent: Name, email, phone, location, LinkedIn
• WorkExperienceAgent: Employment history, roles, achievements
• ProfessionalSummaryAgent: Headline, bio, narrative
• SkillsAgent: Technical skills, soft skills, certifications
• EducationAgent: Degrees, institutions, dates
• PreferencesAgent: Role preferences, salary, location
• PortfolioAgent: Projects, URLs, descriptions
• WorkStyleAgent: Collaboration style, management preferences

Custom Agents

Create custom agents by extending BasePropertyAgent:

import { BasePropertyAgent, PropertyAgentResponse, ChatMessage, GoldStandardWorkStory } from '@workstory/agent';

class CustomAgent extends BasePropertyAgent {
  constructor() {
    super({
      propertyPath: 'customProperty',
      description: 'Extract custom data',
      systemPrompt: 'Your extraction instructions',
    });
  }
  
  async extractProperty(chatLog: ChatMessage[], currentWorkStory: GoldStandardWorkStory): Promise<PropertyAgentResponse> {
    // Custom extraction logic
  }
  
  getCurrentValue(workStory: GoldStandardWorkStory): any {
    return workStory.data.customProperty;
  }
  
  updateWorkStory(workStory: GoldStandardWorkStory, value: any): GoldStandardWorkStory {
    return {
      ...workStory,
      data: {
        ...workStory.data,
        customProperty: value,
      },
    };
  }
}

Configuration

LLM Configuration

llmConfig: {
  apiKey: string,              // OpenAI API key (required)
  apiUrl?: string,             // Default: 'https://api.openai.com/v1/chat/completions'
  model?: string,               // Default: 'gpt-4o'
  temperature?: number,         // Default: 0.7
  maxTokens?: number,          // Default: 1000
  maxRetries?: number,         // Default: 10
  retryDelay?: number,         // Default: 1000ms
  timeout?: number,            // Default: 120000ms (2 minutes)
}

Auto-Update

When autoUpdate: true, the work story automatically updates after chat messages are added (with a 1-second debounce).

const manager = new MCPStorageManager({
  storageAdapter,
  autoUpdate: true, // Automatically update on message add
});

API Reference

MCPStorageManager

getWorkStory(userId: string): Promise<GoldStandardWorkStory>

Get the current work story for a user.

updateWorkStoryFromChat(userId: string, chatLogLimit?: number): Promise<WorkstoryUpdateResult>

Manually trigger work story update from chat logs.

addChatMessage(userId: string, message: ChatMessage): Promise<void>

Add a chat message and trigger auto-update if enabled.

WorkstoryUpdateResult

interface WorkstoryUpdateResult {
  updated: boolean;
  updatedProperties: string[];
  agentResponses: Map<string, PropertyAgentResponse>;
  workStory: GoldStandardWorkStory;
}

Gold Standard Format

Work stories follow the org.workstory.standard v1.0.0 schema:

interface GoldStandardWorkStory {
  schema: {
    name: "org.workstory.standard";
    version: "1.0.0";
    document_type: "work_story";
  };
  id: string;
  created_at: string;
  updated_at: string;
  source: WorkStorySource;
  privacy: WorkStoryPrivacy;
  data: {
    person?: PersonData;
    summary?: SummaryData;
    timeline?: { engagements: Engagement[] };
    skills?: SkillsData;
    preferences?: PreferencesData;
    // ... more fields
  };
}

Examples

See the examples/ directory for more examples:

• Basic usage with memory storage
• Firestore integration
• Custom agents
• Serverless function integration

License

MIT