@just-every/task

Intelligent orchestration layer for @just-every/ensemble agents with meta-cognition and adaptive model selection.

Overview

Task adds meta-cognition, adaptive model rotation and cost tracking to your @just-every/ensemble agents in a single call. It automatically selects the best model for each step, monitors performance, and adjusts strategy when needed - all while tracking costs across providers.

Task is designed to make AI agents more reliable and cost-effective by adding a layer of intelligence on top of ensemble's multi-provider capabilities.

Features

• 🎯 Automatic Model Rotation - Performance-based selection across providers
• 🧠 Meta-cognition - Agents periodically reflect and self-correct
• 🔄 Adaptive Strategy - Detects loops and adjusts approach automatically
• 💰 Cost Tracking - Real-time cost monitoring across all providers
• 🛠️ Zero Configuration - Works with any ensemble agent and tools
• 📊 Model Scoring - Dynamic scoring based on task performance

Installation

npm install @just-every/task

Prerequisites

• Node.js 20.x or higher
• At least one LLM provider API key
• @just-every/ensemble (installed as peer dependency)

Environment Setup

Set your LLM provider API keys (any combination works):

export OPENAI_API_KEY="your-openai-key"export ANTHROPIC_API_KEY="your-anthropic-key"export GOOGLE_API_KEY="your-google-key"export XAI_API_KEY="your-xai-key"export DEEPSEEK_API_KEY="your-deepseek-key"

Quick Start

import{runTask}from"@just-every/task";import{Agent}from"@just-every/ensemble";// Create an agent with a model classconstagent=newAgent({name: "MyAssistant",modelClass: "reasoning",instructions: "You are a helpful coding assistant"});// Run a task - Task handles everything elseconststream=runTask(agent,"Analyze this code and suggest improvements: ...");// Process the streaming responseforawait(consteventofstream){if(event.type==='message_delta'){process.stdout.write(event.content);}}

Usage Examples

1. Basic Task Execution

import{runTask}from"@just-every/task";import{Agent}from"@just-every/ensemble";// Create a simple agentconstagent=newAgent({modelClass: "standard"});// Execute a taskconststream=runTask(agent,"Write a haiku about programming");// Handle the responseforawait(consteventofstream){if(event.type==='message_delta'){process.stdout.write(event.content);}}

2. Code Analysis with Instructions

constcodeAgent=newAgent({name: "CodeAnalyzer",modelClass: "code",instructions: `You are an expert code reviewer. Focus on: - Performance improvements - Security vulnerabilities - Code maintainability - Best practices`});constcodeToAnalyze=`function processData(users) { let result = []; for (let i = 0; i < users.length; i++) { if (users[i].age > 18) { result.push(users[i].name); } } return result;}`;conststream=runTask(codeAgent,`Review this code and suggest improvements:\n${codeToAnalyze}`);

3. Multi-Step Problem Solving

constproblemSolver=newAgent({modelClass: "reasoning",instructions: "Break down complex problems into steps and solve systematically"});// Task handles meta-cognition and self-correction automaticallyconststream=runTask(problemSolver,` I have a dataset of 10,000 customer transactions. I need to: 1. Identify suspicious patterns 2. Calculate risk scores 3. Generate a report with visualizations Design a solution architecture for this.`);

4. Custom Tools Integration

import{createToolFunction}from"@just-every/ensemble";// Create custom toolsconstdatabaseTool=createToolFunction(async({ query }: {query: string})=>{// Simulate database queryreturn`Query executed: ${query}. Found 42 records.`;},'Execute database queries',{query: {type: 'string',description: 'SQL query to execute'}},undefined,'query_database');constapiTool=createToolFunction(async({ endpoint, method }: {endpoint: string;method: string})=>{// Simulate API callreturn`API ${method}${endpoint} returned: {"status": "success", "data": [...]}`;},'Make API calls',{endpoint: {type: 'string',description: 'API endpoint'},method: {type: 'string',description: 'HTTP method',enum: ['GET','POST','PUT','DELETE']}},['endpoint','method'],'call_api');// Create agent with toolsconstagent=newAgent({modelClass: "code",tools: [databaseTool,apiTool],instructions: "Use the available tools to gather data and complete tasks"});// Run task that uses toolsconststream=runTask(agent,"Check the database for users created today and call the analytics API");// Process events including tool callsforawait(consteventofstream){if(event.type==='message_delta'){process.stdout.write(event.content);}elseif(event.type==='tool_start'){console.log(`\n🔧 Using tool: ${event.tool_call?.function?.name}`);}}

5. Advanced Configuration with MindState

import{runTask,MindState}from"@just-every/task";// Create custom state configurationconststate=newMindState();// Configure meta-cognition frequency (5, 10, 20, or 40 requests)state.setMetaFrequency(10);// Set thought delays (in seconds: 0, 2, 4, 8, 16, 32, 64, 128)state.setThoughtDelay(4);// Adjust model scores based on your needsstate.setModelScore('claude-3-5-sonnet-20241022',95);state.setModelScore('gpt-4',85);state.setModelScore('gemini-1.5-pro',80);// Disable specific models if neededstate.disableModel('gpt-3.5-turbo');constagent=newAgent({modelClass: "reasoning",instructions: "Think step by step and verify your work"});// Run with custom stateconststream=runTask(agent,"Design a distributed system for real-time data processing",state);// Monitor executionforawait(consteventofstream){if(event.type==='message_delta'){process.stdout.write(event.content);}elseif(event.type==='tool_done'&&event.tool_call?.function?.name==='meta_cognition'){console.log('\n🧠 Meta-cognition triggered - agent is self-reflecting...');}}

6. Error Handling and Recovery

constresilientAgent=newAgent({modelClass: "code",instructions: "If you encounter errors, analyze them and try alternative approaches"});try{conststream=runTask(resilientAgent,"Parse this JSON and handle errors gracefully");forawait(consteventofstream){if(event.type==='message_delta'){process.stdout.write(event.content);}elseif(event.type==='tool_done'){consttoolName=event.tool_call?.function?.name;if(toolName==='task_fatal_error'){console.error('\n❌ Fatal error encountered:',event.result);// Handle fatal errors appropriatelybreak;}elseif(toolName==='task_complete'){console.log('\n✅ Task completed successfully');break;}}}}catch(error){console.error('Unexpected error:',error);}

7. Real-World Example: Data Processing Pipeline

import{Agent,createToolFunction}from"@just-every/ensemble";import{runTask,MindState}from"@just-every/task";// Create data processing toolsconsttools=[createToolFunction(async({ filename }: {filename: string})=>{// Simulate reading CSVreturn`Read 1000 rows from ${filename}`;},'Read CSV file',{filename: {type: 'string'}},undefined,'read_csv'),createToolFunction(async({ data, operation }: {data: string;operation: string})=>{return`Transformed data using ${operation}`;},'Transform data',{data: {type: 'string'},operation: {type: 'string',enum: ['normalize','aggregate','filter']}},['data','operation'],'transform_data'),createToolFunction(async({ data, format }: {data: string;format: string})=>{return`Exported data to ${format} format`;},'Export processed data',{data: {type: 'string'},format: {type: 'string',enum: ['json','csv','parquet']}},['data','format'],'export_data')];// Configure agentconstdataAgent=newAgent({name: "DataProcessor",modelClass: "code",
tools,instructions: `You are a data processing expert. When given a data task: 1. Read the input data 2. Apply appropriate transformations 3. Export in the requested format 4. Provide a summary of what was done`});// Configure state for longer tasksconststate=newMindState();state.setMetaFrequency(20);// Less frequent meta-cognition for focused workstate.setThoughtDelay(2);// Quick thinking for data tasks// Execute complex data pipelineconststream=runTask(dataAgent,` Process the sales_data.csv file: - Normalize the revenue columns - Aggregate by region and product category - Export as both JSON and Parquet formats - Include data quality metrics in your summary`,state);// Track progresslettoolCalls=0;forawait(consteventofstream){if(event.type==='message_delta'){process.stdout.write(event.content);}elseif(event.type==='tool_start'){toolCalls++;console.log(`\n[Step ${toolCalls}] ${event.tool_call?.function?.name}`);}}

Model Classes

Class	Use Cases	Example Models
reasoning	Complex logic, multi-step problems	o1, claude-3-opus
code	Code generation, review, debugging	gpt-4, claude-3-sonnet
standard	General tasks, writing, Q&A	gpt-3.5, claude-3-haiku

Common Patterns

Streaming Output with Progress

conststream=runTask(agent,task);lettotalTokens=0;forawait(consteventofstream){switch(event.type){case'message_delta':
process.stdout.write(event.content);break;case'tool_start':
console.log(`\n🔧 ${event.tool_call?.function?.name} started`);break;case'tool_done':
if(event.tool_call?.function?.name==='task_complete'){console.log(`\n✅ Complete! Total tokens: ${totalTokens}`);}break;case'usage':
totalTokens+=event.usage?.total_tokens||0;break;}}

Handling Different Task Types

// For analysis tasks - use reasoning model with meta-cognitionconstanalysisAgent=newAgent({modelClass: "reasoning"});constanalysisState=newMindState();analysisState.setMetaFrequency(5);// Frequent self-checking// For creative tasks - use standard model with thought delaysconstcreativeAgent=newAgent({modelClass: "standard"});constcreativeState=newMindState();creativeState.setThoughtDelay(8);// Slower, more deliberate// For coding tasks - use code model with minimal delaysconstcodingAgent=newAgent({modelClass: "code"});constcodingState=newMindState();codingState.setThoughtDelay(0);// Fast execution

Building Reusable Agents

// Create a reusable agent factoryfunctioncreateSpecializedAgent(specialty: string){constconfigs={researcher: {modelClass: "reasoning"asconst,instructions: "Research thoroughly and cite sources",metaFrequency: 10,thoughtDelay: 4},developer: {modelClass: "code"asconst,instructions: "Write clean, tested, documented code",metaFrequency: 20,thoughtDelay: 2},writer: {modelClass: "standard"asconst,instructions: "Write engaging, clear content",metaFrequency: 40,thoughtDelay: 8}};constconfig=configs[specialtyaskeyoftypeofconfigs];constagent=newAgent({modelClass: config.modelClass,instructions: config.instructions});conststate=newMindState();state.setMetaFrequency(config.metaFrequency);state.setThoughtDelay(config.thoughtDelay);return{ agent, state };}// Use the factoryconst{ agent, state }=createSpecializedAgent('researcher');conststream=runTask(agent,"Research quantum computing applications",state);

API Reference

runTask(agent, task, state?)

Main function to execute tasks with intelligent orchestration.

• agent: An ensemble Agent instance with tools and model class
• task: String description of the task to complete
• state: Optional MindState instance for custom configuration
• Returns: AsyncIterable stream of events

MindState

Configuration and state management class.

• metaFrequency: How often meta-cognition runs (5, 10, 20, or 40)
• thoughtDelay: Milliseconds between thoughts (0-128000)
• disabledModels: Set of model IDs to exclude
• modelScores: Map of model ID to performance score

Architecture

Task builds on top of ensemble to provide:

1. Model Selection - Weighted random selection based on scores
2. Meta-cognition - Periodic self-reflection and strategy adjustment
3. State Management - Tracks performance and adjusts parameters
4. Tool Integration - Seamlessly works with ensemble tools

Development

# Install dependencies
npm install
# Run tests
npm test# Build
npm run build
# Run examples
npm run example:simple
npm run example:meta
npm run example:tools

More Examples

The examples/ directory contains complete, runnable examples:

• simple-mind.ts - Basic usage with minimal setup
• meta-cognition.ts - See meta-cognition in action with self-reflection
• custom-tools.ts - Create and use custom tools for specific tasks
• thought-management.ts - Control pacing with thought delays
• pause-control.ts - Pause and resume task execution

Run any example:

npm run build && node dist/examples/simple-mind.js

Contributing

Contributions are welcome! Please read our contributing guidelines and submit PRs to the main repository.

Troubleshooting

Models not rotating

• Ensure multiple provider API keys are set
• Check that models aren't disabled in state
• Verify model class has multiple options

High costs

• Adjust metaFrequency to reduce meta-cognition
• Use smaller model classes when appropriate
• Monitor state.usageSummary for cost breakdown

Slow responses

• Reduce thoughtDelay for faster thinking
• Check network latency to providers
• Consider using faster model classes

License

MIT