varg.ai-sdk 0.1.0 → 0.4.0-alpha.1

package/src/core/executor/executor.ts

@@ -0,0 +1,201 @@
+/**
+ * Main Execution Orchestrator
+ * Routes execution to appropriate handlers based on definition type
+ */
+
+import { registry } from "../registry/registry";
+import { resolve } from "../registry/resolver";
+import type {
+  ActionDefinition,
+  Definition,
+  ExecutionResult,
+  ModelDefinition,
+  RunOptions,
+  SkillDefinition,
+} from "../schema/types";
+import { validateAndPrepare } from "../schema/validator";
+import { jobRunner } from "./job";
+import { pipelineRunner } from "./pipeline";
+
+export class Executor {
+  /**
+   * Run a definition by name
+   */
+  async run(
+    name: string,
+    inputs: Record<string, unknown>,
+    options?: RunOptions,
+  ): Promise<ExecutionResult> {
+    // Resolve name to definition
+    const result = resolve(name, { required: true });
+    const definition = result.definition;
+    if (!definition) {
+      throw new Error(`Definition not found: ${name}`);
+    }
+
+    // Validate and prepare inputs using Zod schema
+    const validation = validateAndPrepare(inputs, definition.schema.input);
+    if (!validation.valid) {
+      const errorMessages = validation.errors
+        .map((e) => (e.path ? `${e.path}: ${e.message}` : e.message))
+        .join(", ");
+      throw new Error(`Validation failed: ${errorMessages}`);
+    }
+
+    // Use validated and transformed data (Zod applies defaults)
+    const validatedInputs = validation.data as Record<string, unknown>;
+
+    // Route to appropriate handler
+    switch (definition.type) {
+      case "model":
+        return this.runModel(definition, validatedInputs, options);
+      case "action":
+        return this.runAction(definition, validatedInputs, options);
+      case "skill":
+        return this.runSkill(definition, validatedInputs, options);
+      default:
+        throw new Error(
+          `Unknown definition type: ${(definition as Definition).type}`,
+        );
+    }
+  }
+
+  /**
+   * Run a model directly
+   */
+  async runModel(
+    model: ModelDefinition,
+    inputs: Record<string, unknown>,
+    options?: RunOptions,
+  ): Promise<ExecutionResult> {
+    // Determine provider
+    const providerName = options?.provider ?? model.defaultProvider;
+    const provider = registry.getProvider(providerName);
+
+    if (!provider) {
+      throw new Error(
+        `Provider not found: ${providerName}. Available: ${registry
+          .listProviders()
+          .map((p) => p.name)
+          .join(", ")}`,
+      );
+    }
+
+    // Get provider-specific model ID
+    const providerModelId = model.providerModels?.[providerName] ?? model.name;
+
+    // Run via job runner
+    return jobRunner.run({
+      provider,
+      model: providerModelId,
+      inputs,
+      options,
+    });
+  }
+
+  /**
+   * Run an action
+   * Actions can route to models or have direct execution
+   */
+  async runAction(
+    action: ActionDefinition,
+    inputs: Record<string, unknown>,
+    options?: RunOptions,
+  ): Promise<ExecutionResult> {
+    // If action has direct execute function, use it
+    if (action.execute) {
+      const startTime = Date.now();
+      const output = await action.execute(inputs);
+
+      return {
+        output: output as string | Record<string, unknown>,
+        duration: Date.now() - startTime,
+        provider: "local",
+        model: action.name,
+      };
+    }
+
+    // Otherwise, route to a model
+    const route = this.selectRoute(action, inputs, options);
+
+    if (!route) {
+      throw new Error(`No valid route found for action: ${action.name}`);
+    }
+
+    // Transform inputs if needed
+    const transformedInputs = route.transform
+      ? route.transform(inputs)
+      : inputs;
+
+    // Recursive call to run the target
+    return this.run(route.target, transformedInputs, options);
+  }
+
+  /**
+   * Run a skill (multi-step pipeline)
+   */
+  async runSkill(
+    skill: SkillDefinition,
+    inputs: Record<string, unknown>,
+    options?: RunOptions,
+  ): Promise<ExecutionResult> {
+    return pipelineRunner.run(
+      skill,
+      inputs,
+      (name, stepInputs, stepOptions) =>
+        this.run(name, stepInputs, stepOptions),
+      options,
+    );
+  }
+
+  /**
+   * Select the best route for an action based on inputs and conditions
+   */
+  private selectRoute(
+    action: ActionDefinition,
+    inputs: Record<string, unknown>,
+    _options?: RunOptions,
+  ) {
+    // Filter routes by conditions
+    const validRoutes = action.routes.filter((route) => {
+      if (!route.when) return true;
+
+      // Check each condition
+      for (const [key, expected] of Object.entries(route.when)) {
+        const actual = inputs[key];
+
+        // Handle special condition operators
+        if (typeof expected === "object" && expected !== null) {
+          const cond = expected as Record<string, unknown>;
+
+          if ("$lt" in cond && !(Number(actual) < Number(cond.$lt)))
+            return false;
+          if ("$lte" in cond && !(Number(actual) <= Number(cond.$lte)))
+            return false;
+          if ("$gt" in cond && !(Number(actual) > Number(cond.$gt)))
+            return false;
+          if ("$gte" in cond && !(Number(actual) >= Number(cond.$gte)))
+            return false;
+          if ("$eq" in cond && actual !== cond.$eq) return false;
+          if ("$ne" in cond && actual === cond.$ne) return false;
+          if ("$in" in cond && !Array.isArray(cond.$in)) return false;
+          if ("$in" in cond && !(cond.$in as unknown[]).includes(actual))
+            return false;
+        } else if (actual !== expected) {
+          return false;
+        }
+      }
+
+      return true;
+    });
+
+    // Sort by priority (higher = preferred)
+    validRoutes.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+
+    // Return the highest priority route
+    return validRoutes[0];
+  }
+}
+
+// Global executor instance
+export const executor = new Executor();

package/src/core/executor/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Executor module exports
+ */
+
+export { Executor, executor } from "./executor";
+export type { JobConfig } from "./job";
+export { JobRunner, jobRunner } from "./job";
+export type {
+  PipelineContext,
+  PipelineOptions,
+  StepExecutor,
+} from "./pipeline";
+export { PipelineRunner, pipelineRunner } from "./pipeline";

package/src/core/executor/job.ts

@@ -0,0 +1,214 @@
+/**
+ * Job State Machine
+ * Manages job lifecycle: queued -> processing -> completed/failed
+ */
+
+import type {
+  ExecutionResult,
+  Job,
+  JobStatus,
+  JobStatusUpdate,
+  Provider,
+  RunOptions,
+} from "../schema/types";
+
+export interface JobConfig {
+  provider: Provider;
+  model: string;
+  inputs: Record<string, unknown>;
+  options?: RunOptions;
+}
+
+export class JobRunner {
+  private jobs = new Map<string, Job>();
+  private pollInterval = 2000; // Start with 2s
+  private maxPollInterval = 10000; // Cap at 10s
+
+  /**
+   * Create and run a job
+   */
+  async run(config: JobConfig): Promise<ExecutionResult> {
+    const { provider, model, inputs, options } = config;
+    const startTime = Date.now();
+
+    // Create job record
+    const job: Job = {
+      id: "",
+      status: "pending",
+      provider: provider.name,
+      model,
+      inputs,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+      logs: [],
+    };
+
+    try {
+      // Submit to provider
+      job.status = "queued";
+      job.id = await provider.submit(model, inputs);
+      this.jobs.set(job.id, job);
+
+      if (options?.onStatusChange) {
+        options.onStatusChange("queued");
+      }
+
+      // If not waiting, return immediately
+      if (options?.wait === false) {
+        return {
+          output: { jobId: job.id },
+          duration: Date.now() - startTime,
+          provider: provider.name,
+          model,
+          jobId: job.id,
+        };
+      }
+
+      // Poll for completion
+      const result = await this.waitForCompletion(job, provider, options);
+
+      // Update job record
+      job.status = "completed";
+      job.output = result;
+      job.completedAt = new Date();
+      job.updatedAt = new Date();
+
+      const duration = Date.now() - startTime;
+
+      return {
+        output: result as string | Record<string, unknown>,
+        duration,
+        provider: provider.name,
+        model,
+        jobId: job.id,
+      };
+    } catch (error) {
+      job.status = "failed";
+      job.error = error instanceof Error ? error.message : String(error);
+      job.updatedAt = new Date();
+
+      if (options?.onStatusChange) {
+        options.onStatusChange("failed");
+      }
+
+      throw error;
+    }
+  }
+
+  /**
+   * Wait for a job to complete with polling
+   */
+  private async waitForCompletion(
+    job: Job,
+    provider: Provider,
+    options?: RunOptions,
+  ): Promise<unknown> {
+    const timeout = options?.timeout ?? 300000; // 5 minutes default
+    const startTime = Date.now();
+    let currentInterval = this.pollInterval;
+
+    while (Date.now() - startTime < timeout) {
+      const status = await provider.getStatus(job.id);
+
+      // Update job record
+      job.status = this.mapStatus(status.status);
+      job.updatedAt = new Date();
+
+      if (status.progress !== undefined) {
+        job.progress = status.progress;
+      }
+
+      if (status.logs) {
+        job.logs = [...(job.logs || []), ...status.logs];
+      }
+
+      // Notify progress
+      if (options?.onProgress && status.progress !== undefined) {
+        options.onProgress(status.progress, status.logs);
+      }
+
+      if (options?.onStatusChange) {
+        options.onStatusChange(job.status);
+      }
+
+      // Check terminal states
+      if (status.status === "completed") {
+        return status.output ?? (await provider.getResult(job.id));
+      }
+
+      if (status.status === "failed") {
+        throw new Error(status.error ?? "Job failed");
+      }
+
+      if (status.status === "cancelled") {
+        throw new Error("Job was cancelled");
+      }
+
+      // Wait with exponential backoff
+      await this.sleep(currentInterval);
+      currentInterval = Math.min(currentInterval * 1.5, this.maxPollInterval);
+    }
+
+    throw new Error(`Job ${job.id} timed out after ${timeout}ms`);
+  }
+
+  /**
+   * Map provider status to our status
+   */
+  private mapStatus(status: JobStatusUpdate["status"]): JobStatus {
+    return status;
+  }
+
+  /**
+   * Get a job by ID
+   */
+  get(jobId: string): Job | undefined {
+    return this.jobs.get(jobId);
+  }
+
+  /**
+   * Cancel a job
+   */
+  async cancel(jobId: string, provider: Provider): Promise<void> {
+    const job = this.jobs.get(jobId);
+    if (!job) {
+      throw new Error(`Job not found: ${jobId}`);
+    }
+
+    if (provider.cancel) {
+      await provider.cancel(jobId);
+    }
+
+    job.status = "cancelled";
+    job.updatedAt = new Date();
+  }
+
+  /**
+   * List all jobs
+   */
+  list(): Job[] {
+    return Array.from(this.jobs.values());
+  }
+
+  /**
+   * Clear completed jobs
+   */
+  clearCompleted(): void {
+    for (const [id, job] of this.jobs) {
+      if (
+        job.status === "completed" ||
+        job.status === "failed" ||
+        job.status === "cancelled"
+      ) {
+        this.jobs.delete(id);
+      }
+    }
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+
+// Global job runner instance
+export const jobRunner = new JobRunner();

package/src/core/executor/pipeline.ts

@@ -0,0 +1,222 @@
+/**
+ * Pipeline Runner
+ * Executes multi-step skills/workflows
+ */
+
+import type {
+  ExecutionResult,
+  RunOptions,
+  SkillDefinition,
+  SkillStep,
+} from "../schema/types";
+
+export interface PipelineContext {
+  /** Initial inputs provided to the pipeline */
+  inputs: Record<string, unknown>;
+  /** Results from each completed step, keyed by step name */
+  results: Record<string, unknown>;
+  /** Current step index */
+  stepIndex: number;
+  /** Total number of steps */
+  totalSteps: number;
+}
+
+export interface PipelineOptions extends RunOptions {
+  /** If true, stop on first error */
+  stopOnError?: boolean;
+  /** Step-level callback */
+  onStepStart?: (step: SkillStep, context: PipelineContext) => void;
+  /** Step completion callback */
+  onStepComplete?: (
+    step: SkillStep,
+    result: unknown,
+    context: PipelineContext,
+  ) => void;
+}
+
+export type StepExecutor = (
+  name: string,
+  inputs: Record<string, unknown>,
+  options?: RunOptions,
+) => Promise<ExecutionResult>;
+
+export class PipelineRunner {
+  /**
+   * Execute a skill definition
+   */
+  async run(
+    skill: SkillDefinition,
+    inputs: Record<string, unknown>,
+    executor: StepExecutor,
+    options?: PipelineOptions,
+  ): Promise<ExecutionResult> {
+    const startTime = Date.now();
+    const context: PipelineContext = {
+      inputs,
+      results: {},
+      stepIndex: 0,
+      totalSteps: skill.steps.length,
+    };
+
+    console.log(`[pipeline] starting skill: ${skill.name}`);
+    console.log(`[pipeline] steps: ${skill.steps.length}`);
+
+    let lastResult: ExecutionResult | null = null;
+
+    for (let i = 0; i < skill.steps.length; i++) {
+      const step = skill.steps[i];
+      if (!step) continue;
+
+      context.stepIndex = i;
+
+      // Check step condition
+      if (step.when && !this.evaluateCondition(step.when, context)) {
+        console.log(
+          `[pipeline] skipping step ${i + 1}: ${step.name} (condition not met)`,
+        );
+        continue;
+      }
+
+      console.log(
+        `[pipeline] step ${i + 1}/${skill.steps.length}: ${step.name}`,
+      );
+
+      if (options?.onStepStart) {
+        options.onStepStart(step, context);
+      }
+
+      try {
+        // Resolve inputs for this step
+        const stepInputs = this.resolveInputs(step.inputs, context);
+
+        // Execute the step
+        const result = await executor(step.run, stepInputs, options);
+
+        // Store result
+        context.results[step.name] = result.output;
+        lastResult = result;
+
+        if (options?.onStepComplete) {
+          options.onStepComplete(step, result, context);
+        }
+
+        console.log(`[pipeline] step ${step.name} completed`);
+      } catch (error) {
+        console.error(`[pipeline] step ${step.name} failed:`, error);
+
+        if (options?.stopOnError !== false) {
+          throw error;
+        }
+
+        // Store error as result
+        context.results[step.name] = {
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    }
+
+    const duration = Date.now() - startTime;
+    console.log(`[pipeline] skill ${skill.name} completed in ${duration}ms`);
+
+    return {
+      output: lastResult?.output ?? context.results,
+      duration,
+      provider: lastResult?.provider ?? "pipeline",
+      model: skill.name,
+      metadata: {
+        stepResults: context.results,
+      },
+    };
+  }
+
+  /**
+   * Evaluate a condition against the current context
+   */
+  private evaluateCondition(
+    condition: Record<string, unknown>,
+    context: PipelineContext,
+  ): boolean {
+    for (const [key, expected] of Object.entries(condition)) {
+      const actual = this.resolveValue(key, context);
+
+      // Simple equality check
+      if (actual !== expected) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Resolve inputs for a step, substituting references
+   */
+  private resolveInputs(
+    inputs: Record<string, unknown>,
+    context: PipelineContext,
+  ): Record<string, unknown> {
+    const resolved: Record<string, unknown> = {};
+
+    for (const [key, value] of Object.entries(inputs)) {
+      resolved[key] = this.resolveValue(value, context);
+    }
+
+    return resolved;
+  }
+
+  /**
+   * Resolve a value, handling references like $inputs.foo or $results.step1.output
+   */
+  private resolveValue(value: unknown, context: PipelineContext): unknown {
+    if (typeof value !== "string") {
+      return value;
+    }
+
+    // Check for reference syntax
+    if (!value.startsWith("$")) {
+      return value;
+    }
+
+    const path = value.slice(1).split(".");
+    const source = path[0];
+    const rest = path.slice(1);
+
+    if (!source) {
+      return value;
+    }
+
+    let current: unknown;
+
+    switch (source) {
+      case "inputs":
+        current = context.inputs;
+        break;
+      case "results":
+        current = context.results;
+        break;
+      default:
+        // Check if it's a direct step result reference
+        if (source in context.results) {
+          current = context.results[source];
+        } else {
+          return value; // Return as-is if not a valid reference
+        }
+    }
+
+    // Navigate the path
+    for (const part of rest) {
+      if (current === null || current === undefined) {
+        return undefined;
+      }
+      if (typeof current === "object") {
+        current = (current as Record<string, unknown>)[part];
+      } else {
+        return undefined;
+      }
+    }
+
+    return current;
+  }
+}
+
+// Global pipeline runner instance
+export const pipelineRunner = new PipelineRunner();

package/src/core/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Core module exports
+ */
+
+// Executor
+export * from "./executor";
+
+// Registry
+export * from "./registry";
+// Schema
+export * from "./schema";

package/src/core/registry/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Registry module exports
+ */
+
+export type { LoaderOptions } from "./loader";
+export { loadDefinitions, loadUserSkills, reloadDefinitions } from "./loader";
+export { Registry, registry } from "./registry";
+export type { ResolveOptions, ResolveResult } from "./resolver";
+export { findSimilar, resolve, search, suggest } from "./resolver";