@astrive-ai/core 1.0.1

package/dist/validator.d.ts

@@ -0,0 +1,11 @@
+import { ChatRequest, JsonSchema } from '@astrive-ai/types';
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+export declare class RequestValidator {
+    validateChatRequest(request: ChatRequest): ValidationResult;
+    validateToolArgs(schema: JsonSchema, args: Record<string, unknown>): ValidationResult;
+    private validateValue;
+}
+//# sourceMappingURL=validator.d.ts.map

package/dist/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../src/validator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE5D,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,qBAAa,gBAAgB;IACpB,mBAAmB,CAAC,OAAO,EAAE,WAAW,GAAG,gBAAgB;IAa3D,gBAAgB,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,gBAAgB;IAQ5F,OAAO,CAAC,aAAa;CA8DtB"}

package/dist/validator.js

@@ -0,0 +1,85 @@
+export class RequestValidator {
+    validateChatRequest(request) {
+        const errors = [];
+        if (!request) {
+            return { valid: false, errors: ['Request is missing'] };
+        }
+        if (!Array.isArray(request.messages)) {
+            errors.push('request.messages must be an array');
+        }
+        else if (request.messages.length === 0) {
+            errors.push('request.messages cannot be empty');
+        }
+        return { valid: errors.length === 0, errors };
+    }
+    validateToolArgs(schema, args) {
+        const errors = [];
+        this.validateValue(args, schema, '', errors);
+        return { valid: errors.length === 0, errors };
+    }
+    validateValue(value, schema, path, errors) {
+        if (value === undefined || value === null) {
+            return;
+        }
+        if (schema.type === 'object') {
+            if (typeof value !== 'object' || Array.isArray(value)) {
+                errors.push(`'${path}' must be an object`);
+                return;
+            }
+            if (schema.required) {
+                for (const req of schema.required) {
+                    if (value[req] === undefined) {
+                        errors.push(`'${path ? path + '.' : ''}${req}' is required`);
+                    }
+                }
+            }
+            if (schema.properties) {
+                for (const [key, propSchema] of Object.entries(schema.properties)) {
+                    if (value[key] !== undefined) {
+                        this.validateValue(value[key], propSchema, path ? `${path}.${key}` : key, errors);
+                    }
+                }
+            }
+        }
+        else if (schema.type === 'array') {
+            if (!Array.isArray(value)) {
+                errors.push(`'${path}' must be an array`);
+                return;
+            }
+            if (schema.items) {
+                for (let i = 0; i < value.length; i++) {
+                    this.validateValue(value[i], schema.items, `${path}[${i}]`, errors);
+                }
+            }
+        }
+        else if (schema.type === 'string') {
+            if (typeof value !== 'string') {
+                errors.push(`'${path}' must be a string`);
+                return;
+            }
+            if (schema.enum && !schema.enum.includes(value)) {
+                errors.push(`'${path}' must be one of: ${schema.enum.join(', ')}`);
+            }
+            if (schema.pattern) {
+                const regex = new RegExp(schema.pattern);
+                if (!regex.test(value)) {
+                    errors.push(`'${path}' must match pattern ${schema.pattern}`);
+                }
+            }
+        }
+        else if (schema.type === 'number' || schema.type === 'integer') {
+            if (typeof value !== 'number') {
+                errors.push(`'${path}' must be a number`);
+            }
+            else if (schema.type === 'integer' && !Number.isInteger(value)) {
+                errors.push(`'${path}' must be an integer`);
+            }
+        }
+        else if (schema.type === 'boolean') {
+            if (typeof value !== 'boolean') {
+                errors.push(`'${path}' must be a boolean`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=validator.js.map

package/dist/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../src/validator.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@astrive-ai/core",
+  "version": "1.0.1",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@astrive-ai/types": "*",
+    "@astrive-ai/logger": "*",
+    "@astrive-ai/events": "*"
+  },
+  "devDependencies": {
+    "typescript": "5.4.5",
+    "@types/node": "^20.0.0"
+  }
+}

package/src/context.ts

@@ -0,0 +1,64 @@
+import * as crypto from 'crypto';
+
+export interface Message {
+  role: 'user' | 'assistant' | 'system' | 'tool';
+  content: string;
+  name?: string;
+  tool_calls?: any[];
+  tool_call_id?: string;
+}
+
+export interface ConversationContext {
+  id: string;
+  messages: Message[];
+  systemPrompt: string;
+  metadata: Record<string, unknown>;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export class ContextManager {
+  private conversations: Map<string, ConversationContext> = new Map();
+
+  public createConversation(systemPrompt: string = ''): string {
+    const id = crypto.randomUUID();
+    this.conversations.set(id, {
+      id,
+      messages: [],
+      systemPrompt,
+      metadata: {},
+      createdAt: Date.now(),
+      updatedAt: Date.now()
+    });
+    return id;
+  }
+
+  public addMessage(conversationId: string, message: Message): void {
+    const conv = this.conversations.get(conversationId);
+    if (!conv) {
+      throw new Error(`Conversation not found: ${conversationId}`);
+    }
+    conv.messages.push(message);
+    conv.updatedAt = Date.now();
+  }
+
+  public getMessages(conversationId: string): Message[] {
+    return this.conversations.get(conversationId)?.messages || [];
+  }
+
+  public getConversation(conversationId: string): ConversationContext {
+    const conv = this.conversations.get(conversationId);
+    if (!conv) {
+      throw new Error(`Conversation not found: ${conversationId}`);
+    }
+    return conv;
+  }
+
+  public deleteConversation(conversationId: string): void {
+    this.conversations.delete(conversationId);
+  }
+
+  public clear(): void {
+    this.conversations.clear();
+  }
+}

package/src/executor.ts

@@ -0,0 +1,146 @@
+import { ToolRegistry } from './tool-registry.js';
+import { RequestValidator } from './validator.js';
+import { RetryHandler } from './retry.js';
+import { ILogger, IEventEmitter, ToolCall, ToolResult } from '@astrive-ai/types';
+
+export interface ExecutorToolResult {
+  toolCallId: string;
+  result?: ToolResult;
+  error?: string;
+  status: 'success' | 'error';
+}
+
+export interface ExecutorContext {
+  [key: string]: any;
+}
+
+export interface ExecutionStep {
+  id: string;
+  toolCall: ToolCall;
+  dependencies?: string[];
+  status?: 'pending' | 'running' | 'completed' | 'failed';
+  result?: ExecutorToolResult;
+}
+
+export interface ExecutionPlan {
+  steps: ExecutionStep[];
+}
+
+export class ToolExecutor {
+  private registry: ToolRegistry;
+  private events: IEventEmitter;
+  private logger: ILogger;
+  private validator: RequestValidator;
+  private retryHandler: RetryHandler;
+
+  constructor(registry: ToolRegistry, events: IEventEmitter, logger: ILogger) {
+    this.registry = registry;
+    this.events = events;
+    this.logger = logger;
+    this.validator = new RequestValidator();
+    this.retryHandler = new RetryHandler();
+  }
+
+  public async execute(toolCall: ToolCall, context: ExecutorContext = {}): Promise<ExecutorToolResult> {
+    await this.events.emit('tool:start', { toolCall });
+    this.logger.debug(`Starting tool: ${toolCall.name}`);
+
+    const tool = this.registry.get(toolCall.name);
+    if (!tool) {
+      const errorMsg = `Tool not found: ${toolCall.name}`;
+      this.logger.error(errorMsg);
+      await this.events.emit('tool:end', { toolCall, status: 'error', error: errorMsg });
+      return { toolCallId: toolCall.id, error: errorMsg, status: 'error' };
+    }
+
+    const validation = tool.validate(toolCall.arguments as Record<string, unknown>);
+    if (!validation.valid) {
+      const errorMsg = `Validation failed for tool ${toolCall.name}: ${validation.errors?.map(e => e.message).join(', ')}`;
+      this.logger.error(errorMsg);
+      await this.events.emit('tool:end', { toolCall, status: 'error', error: errorMsg });
+      return { toolCallId: toolCall.id, error: errorMsg, status: 'error' };
+    }
+
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 30000);
+
+    try {
+      const executeFn = async () => {
+        if (controller.signal.aborted) throw new Error('Timeout');
+        return await tool.execute(toolCall.arguments as Record<string, unknown>, { ...context, signal: controller.signal } as any);
+      };
+
+      const result = await this.retryHandler.execute(executeFn, {
+        maxRetries: 3,
+        baseDelay: 1000,
+        maxDelay: 10000,
+        backoffMultiplier: 2
+      });
+
+      clearTimeout(timeout);
+      await this.events.emit('tool:end', { toolCall, status: 'success', result });
+      return { toolCallId: toolCall.id, result, status: 'success' };
+    } catch (error: any) {
+      clearTimeout(timeout);
+      this.logger.error(`Error executing tool ${toolCall.name}:`, error);
+      await this.events.emit('tool:end', { toolCall, status: 'error', error: error.message });
+      return { toolCallId: toolCall.id, error: error.message, status: 'error' };
+    }
+  }
+
+  public async executeParallel(toolCalls: ToolCall[], context: ExecutorContext = {}): Promise<ExecutorToolResult[]> {
+    const promises = toolCalls.map(tc => this.execute(tc, context));
+    return await Promise.all(promises);
+  }
+
+  public async executePlan(plan: ExecutionPlan, context: ExecutorContext = {}): Promise<ExecutorToolResult[]> {
+    const results: ExecutorToolResult[] = [];
+    
+    for (const step of plan.steps) {
+      step.status = 'pending';
+    }
+
+    const executeReadySteps = async (): Promise<void> => {
+      const readySteps = plan.steps.filter(step => 
+        step.status === 'pending' && 
+        (!step.dependencies || step.dependencies.every(depId => 
+          plan.steps.find(s => s.id === depId)?.status === 'completed'
+        ))
+      );
+
+      if (readySteps.length === 0) {
+        return;
+      }
+
+      for (const step of readySteps) {
+        step.status = 'running';
+      }
+
+      const promises = readySteps.map(async step => {
+        const result = await this.execute(step.toolCall, context);
+        step.result = result;
+        step.status = result.status === 'success' ? 'completed' : 'failed';
+        results.push(result);
+        if (step.status === 'completed') {
+          await executeReadySteps();
+        }
+      });
+
+      await Promise.all(promises);
+    };
+
+    await executeReadySteps();
+
+    const failedSteps = plan.steps.filter(s => s.status === 'failed');
+    if (failedSteps.length > 0) {
+      this.logger.warn(`Plan execution completed with ${failedSteps.length} failed steps.`);
+    }
+
+    const pendingSteps = plan.steps.filter(s => s.status === 'pending');
+    if (pendingSteps.length > 0) {
+      this.logger.error(`Plan execution deadlocked, ${pendingSteps.length} steps remaining pending.`);
+    }
+
+    return results;
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from './context.js';
+export * from './validator.js';
+export * from './middleware-pipeline.js';
+export * from './tool-registry.js';
+export * from './executor.js';
+export * from './retry.js';
+export * from './utils.js';
+export * from './structured-output.js';

package/src/middleware-pipeline.ts

@@ -0,0 +1,33 @@
+import { IMiddleware, MiddlewareContext } from '@astrive-ai/types';
+
+export class MiddlewarePipeline {
+  private middlewares: IMiddleware[] = [];
+
+  public use(middleware: IMiddleware): void {
+    this.middlewares.push(middleware);
+    this.middlewares.sort((a, b) => a.order - b.order);
+  }
+
+  public async execute(context: MiddlewareContext): Promise<void> {
+    let index = -1;
+    
+    const dispatch = async (i: number): Promise<void> => {
+      if (i <= index) {
+        throw new Error('next() called multiple times');
+      }
+      index = i;
+      
+      if (i < this.middlewares.length) {
+        const middleware = this.middlewares[i];
+        try {
+          await middleware.execute(context, () => dispatch(i + 1));
+        } catch (error) {
+          context.metadata.error = error;
+          throw error;
+        }
+      }
+    };
+    
+    await dispatch(0);
+  }
+}

package/src/retry.ts

@@ -0,0 +1,62 @@
+export class AstriveError extends Error {
+  public retryable: boolean;
+  constructor(message: string, retryable: boolean = false) {
+    super(message);
+    this.name = 'AstriveError';
+    this.retryable = retryable;
+  }
+}
+
+export interface RetryOptions {
+  maxRetries: number;
+  baseDelay: number;
+  maxDelay: number;
+  backoffMultiplier: number;
+  retryOn?: (error: Error) => boolean;
+}
+
+export class RetryHandler {
+  public async execute<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T> {
+    const opts = {
+      maxRetries: 3,
+      baseDelay: 1000,
+      maxDelay: 10000,
+      backoffMultiplier: 2,
+      ...options
+    };
+
+    let attempt = 0;
+    while (true) {
+      try {
+        return await fn();
+      } catch (error: any) {
+        if (attempt >= opts.maxRetries) {
+          throw error;
+        }
+
+        let retryable = false;
+        if (opts.retryOn) {
+          retryable = opts.retryOn(error);
+        } else if (error instanceof AstriveError) {
+          retryable = error.retryable;
+        } else {
+          retryable = true;
+        }
+
+        if (!retryable) {
+          throw error;
+        }
+
+        const delay = Math.min(
+          opts.baseDelay * Math.pow(opts.backoffMultiplier, attempt),
+          opts.maxDelay
+        );
+        const jitter = Math.random() * delay * 0.2;
+        const sleepTime = delay + jitter;
+
+        await new Promise(resolve => setTimeout(resolve, sleepTime));
+        attempt++;
+      }
+    }
+  }
+}

package/src/structured-output.ts

@@ -0,0 +1,80 @@
+import { IProvider, JsonSchema } from '@astrive-ai/types';
+import { RequestValidator } from './validator.js';
+import { AstriveError } from './retry.js';
+
+export interface StructuredOutputOptions {
+  schema: JsonSchema;
+  maxRetries?: number;
+  model?: string;
+}
+
+export class StructuredOutputGenerator {
+  private provider: IProvider;
+  private validator: RequestValidator;
+
+  constructor(provider: IProvider) {
+    this.provider = provider;
+    this.validator = new RequestValidator();
+  }
+
+  public async generate<T>(prompt: string, options: StructuredOutputOptions): Promise<T> {
+    const maxRetries = options.maxRetries || 3;
+    let currentAttempt = 0;
+    
+    // Convert schema to string
+    const schemaString = JSON.stringify(options.schema, null, 2);
+    
+    let currentPrompt = `${prompt}\n\nYou must return a valid JSON object that strictly adheres to the following JSON schema:\n${schemaString}\n\nReturn ONLY the JSON object, with no markdown formatting like \`\`\`json.`;
+
+    while (currentAttempt < maxRetries) {
+      try {
+        const response = await this.provider.chat({
+          messages: [{ role: 'user', content: currentPrompt }],
+          model: options.model,
+          responseFormat: { type: 'json_object' }
+        });
+        
+        const rawOutput = response.content.trim();
+        let parsed: unknown;
+        
+        try {
+          // Attempt to parse raw output as JSON
+          // Strip markdown code blocks if the model ignored instructions
+          let cleanOutput = rawOutput;
+          if (cleanOutput.startsWith('```json')) {
+             cleanOutput = cleanOutput.substring(7);
+          }
+          if (cleanOutput.startsWith('```')) {
+             cleanOutput = cleanOutput.substring(3);
+          }
+          if (cleanOutput.endsWith('```')) {
+             cleanOutput = cleanOutput.substring(0, cleanOutput.length - 3);
+          }
+          cleanOutput = cleanOutput.trim();
+          
+          parsed = JSON.parse(cleanOutput);
+        } catch (e: any) {
+          throw new AstriveError(`Failed to parse JSON: ${e.message}\nRaw output: ${rawOutput}`, true);
+        }
+        
+        // Validate against schema
+        const validation = this.validator.validateToolArgs(options.schema, parsed as Record<string, unknown>);
+        if (!validation.valid) {
+          throw new AstriveError(`JSON does not match schema. Errors: ${validation.errors.join(', ')}`, true);
+        }
+        
+        return parsed as T;
+      } catch (error: any) {
+        currentAttempt++;
+        if (currentAttempt >= maxRetries || !(error instanceof AstriveError) || !error.retryable) {
+          throw error;
+        }
+        
+        // Repair output by telling the model about the error
+        currentPrompt = `The previous attempt failed with the following error:\n${error.message}\n\nPlease try again and fix the errors. Remember, you must return a valid JSON object adhering to this schema:\n${schemaString}`;
+      }
+    }
+    
+    throw new Error('Failed to generate structured output after maximum retries');
+  }
+}

package/src/tool-registry.ts

@@ -0,0 +1,56 @@
+import { ITool, ToolCategory, ToolDefinition, IEventEmitter } from '@astrive-ai/types';
+
+export class ToolRegistry {
+  private tools: Map<string, ITool> = new Map();
+  private events?: IEventEmitter;
+
+  constructor(events?: IEventEmitter) {
+    this.events = events;
+  }
+
+  public register(tool: ITool): void {
+    if (!tool.name || !tool.execute) {
+      throw new Error(`Invalid tool definition for ${tool.name}`);
+    }
+    this.tools.set(tool.name, tool);
+    if (this.events) {
+      this.events.emit('tool:registered', { name: tool.name });
+    }
+  }
+
+  public unregister(name: string): void {
+    if (this.tools.has(name)) {
+      this.tools.delete(name);
+      if (this.events) {
+        this.events.emit('tool:unregistered', { name });
+      }
+    }
+  }
+
+  public get(name: string): ITool | undefined {
+    return this.tools.get(name);
+  }
+
+  public getAll(): ITool[] {
+    return Array.from(this.tools.values());
+  }
+
+  public getByCategory(category: ToolCategory): ITool[] {
+    return this.getAll().filter(tool => tool.category === category);
+  }
+
+  public has(name: string): boolean {
+    return this.tools.has(name);
+  }
+
+  public getDefinitions(): ToolDefinition[] {
+    return this.getAll().map(tool => tool.getSchema());
+  }
+
+  public clear(): void {
+    this.tools.clear();
+    if (this.events) {
+      this.events.emit('tool:cleared');
+    }
+  }
+}

package/src/utils.ts

@@ -0,0 +1,79 @@
+import * as crypto from 'crypto';
+import { Buffer } from 'buffer';
+
+export function generateId(): string {
+  return crypto.randomUUID();
+}
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+export function createAbortController(timeoutMs: number): { controller: AbortController; cleanup: () => void } {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => {
+    controller.abort();
+  }, timeoutMs);
+
+  return {
+    controller,
+    cleanup: () => clearTimeout(timeoutId)
+  };
+}
+
+export function formatBytes(bytes: number): string {
+  if (bytes === 0) return '0 Bytes';
+  const k = 1024;
+  const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
+}
+
+export function isUrl(str: string): boolean {
+  try {
+    new URL(str);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function resolveImageInput(input: string | Buffer): Promise<Buffer> {
+  if (Buffer.isBuffer(input)) {
+    return input;
+  }
+  
+  if (isUrl(input as string)) {
+    const response = await fetch(input as string);
+    if (!response.ok) {
+      throw new Error(`Failed to fetch image from ${input}: ${response.statusText}`);
+    }
+    const arrayBuffer = await response.arrayBuffer();
+    return Buffer.from(arrayBuffer);
+  }
+  
+  if (typeof input === 'string' && input.startsWith('data:image')) {
+    const match = input.match(/^data:image\/[^;]+;base64,(.+)$/);
+    if (match) {
+      return Buffer.from(match[1], 'base64');
+    }
+  }
+
+  try {
+    const buf = Buffer.from(input as string, 'base64');
+    if (buf.toString('base64') === input || buf.toString('base64') === (input as string).replace(/=/g, '')) {
+       return buf;
+    }
+  } catch (e) {
+  }
+
+  throw new Error('Unsupported image input format');
+}
+
+export function toBase64(buffer: Buffer): string {
+  return buffer.toString('base64');
+}
+
+export function fromBase64(str: string): Buffer {
+  return Buffer.from(str, 'base64');
+}