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

package/src/core/schema/shared.ts

@@ -0,0 +1,102 @@
+/**
+ * Shared Zod schemas for reuse across definitions
+ * These schemas represent common patterns used in multiple models/actions/skills
+ */
+
+import { z } from "zod";
+
+// Video aspect ratios
+export const aspectRatioSchema = z.enum(["16:9", "9:16", "1:1"]);
+export type AspectRatio = z.infer<typeof aspectRatioSchema>;
+
+// Video duration in seconds (number version)
+export const videoDurationSchema = z.union([z.literal(5), z.literal(10)]);
+export type VideoDuration = z.infer<typeof videoDurationSchema>;
+
+// Video duration as string (for models that expect string)
+export const videoDurationStringSchema = z.enum(["5", "10"]);
+export type VideoDurationString = z.infer<typeof videoDurationStringSchema>;
+
+// Video resolution
+export const resolutionSchema = z.enum(["480p", "720p", "1080p"]);
+export type Resolution = z.infer<typeof resolutionSchema>;
+
+// ElevenLabs preset voices
+export const voiceNameSchema = z.enum([
+  "rachel",
+  "domi",
+  "bella",
+  "antoni",
+  "josh",
+  "adam",
+  "sam",
+]);
+export type VoiceName = z.infer<typeof voiceNameSchema>;
+
+// Simplified voice set (commonly used in skills)
+export const simpleVoiceSchema = z.enum(["rachel", "sam", "adam", "josh"]);
+export type SimpleVoice = z.infer<typeof simpleVoiceSchema>;
+
+// Caption styles
+export const captionStyleSchema = z.enum(["default", "tiktok", "youtube"]);
+export type CaptionStyle = z.infer<typeof captionStyleSchema>;
+
+// Audio output formats
+export const audioFormatSchema = z.enum(["mp3", "wav", "flac", "ogg", "m4a"]);
+export type AudioFormat = z.infer<typeof audioFormatSchema>;
+
+// Flux image sizes
+export const imageSizeSchema = z.enum([
+  "square_hd",
+  "square",
+  "portrait_4_3",
+  "portrait_16_9",
+  "landscape_4_3",
+  "landscape_16_9",
+]);
+export type ImageSize = z.infer<typeof imageSizeSchema>;
+
+// Soul character quality
+export const soulQualitySchema = z.enum(["SD", "HD", "UHD"]);
+export type SoulQuality = z.infer<typeof soulQualitySchema>;
+
+// ElevenLabs TTS model IDs
+export const elevenLabsModelSchema = z.enum([
+  "eleven_multilingual_v2",
+  "eleven_monolingual_v1",
+  "eleven_turbo_v2",
+]);
+export type ElevenLabsModel = z.infer<typeof elevenLabsModelSchema>;
+
+// Transcription providers
+export const transcriptionProviderSchema = z.enum(["groq", "fireworks"]);
+export type TranscriptionProvider = z.infer<typeof transcriptionProviderSchema>;
+
+// Provider name choices
+export const providerNameSchema = z.enum([
+  "fal",
+  "replicate",
+  "elevenlabs",
+  "higgsfield",
+  "groq",
+  "fireworks",
+]);
+export type ProviderName = z.infer<typeof providerNameSchema>;
+
+// Common format validators
+export const filePathSchema = z.string().min(1, "File path cannot be empty");
+export const urlSchema = z.string().url("Must be a valid URL");
+export const uriSchema = z
+  .string()
+  .refine(
+    (val) =>
+      val.startsWith("http://") ||
+      val.startsWith("https://") ||
+      val.startsWith("file://") ||
+      val.startsWith("/"),
+    "Must be a URL or absolute path",
+  );
+
+// Number range helpers
+export const percentSchema = z.number().min(0).max(1);
+export const positiveIntSchema = z.number().int().positive();

package/src/core/schema/types.ts

@@ -0,0 +1,279 @@
+/**
+ * Core type definitions for varg SDK
+ * These types form the foundation of the registry, executor, and provider systems
+ */
+
+import type { z } from "zod";
+
+// ============================================================================
+// Zod Schema Types
+// ============================================================================
+
+/**
+ * Schema definition using Zod
+ * TInput: Zod schema for input validation
+ * TOutput: Zod schema for output type definition
+ */
+export interface ZodSchema<
+  TInput extends z.ZodTypeAny = z.ZodTypeAny,
+  TOutput extends z.ZodTypeAny = z.ZodTypeAny,
+> {
+  input: TInput;
+  output: TOutput;
+}
+
+/**
+ * Infer the TypeScript type from a ZodSchema's input
+ */
+export type InferInput<S extends ZodSchema> = z.infer<S["input"]>;
+
+/**
+ * Infer the TypeScript type from a ZodSchema's output
+ */
+export type InferOutput<S extends ZodSchema> = z.infer<S["output"]>;
+
+// ============================================================================
+// Legacy Schema Types (for JSON Schema compatibility)
+// These are used by CLI introspection via Zod v4's native toJSONSchema()
+// ============================================================================
+
+export interface SchemaProperty {
+  type: "string" | "number" | "integer" | "boolean" | "array" | "object";
+  description?: string;
+  enum?: (string | number)[];
+  default?: unknown;
+  format?: string;
+  items?: SchemaProperty;
+  properties?: Record<string, SchemaProperty>;
+  required?: string[];
+}
+
+export interface JsonSchema {
+  type: "object";
+  required?: string[];
+  properties?: Record<string, SchemaProperty>;
+  description?: string;
+}
+
+// ============================================================================
+// Job Types
+// ============================================================================
+
+export type JobStatus =
+  | "pending"
+  | "queued"
+  | "processing"
+  | "completed"
+  | "failed"
+  | "cancelled";
+
+export interface Job {
+  id: string;
+  status: JobStatus;
+  provider: string;
+  model: string;
+  inputs: Record<string, unknown>;
+  output?: unknown;
+  error?: string;
+  createdAt: Date;
+  updatedAt: Date;
+  completedAt?: Date;
+  progress?: number;
+  logs?: string[];
+}
+
+export interface JobStatusUpdate {
+  status: JobStatus;
+  progress?: number;
+  logs?: string[];
+  output?: unknown;
+  error?: string;
+}
+
+// ============================================================================
+// Provider Types
+// ============================================================================
+
+export interface ProviderConfig {
+  apiKey?: string;
+  baseUrl?: string;
+  timeout?: number;
+  retries?: number;
+}
+
+export interface Provider {
+  readonly name: string;
+
+  /**
+   * Submit a job to the provider
+   * @returns Job ID from the provider
+   */
+  submit(
+    model: string,
+    inputs: Record<string, unknown>,
+    config?: ProviderConfig,
+  ): Promise<string>;
+
+  /**
+   * Get the current status of a job
+   */
+  getStatus(jobId: string): Promise<JobStatusUpdate>;
+
+  /**
+   * Get the result of a completed job
+   */
+  getResult(jobId: string): Promise<unknown>;
+
+  /**
+   * Cancel a running job (if supported)
+   */
+  cancel?(jobId: string): Promise<void>;
+
+  /**
+   * Upload a file to the provider's storage (if supported)
+   */
+  uploadFile?(
+    file: File | Blob | ArrayBuffer,
+    filename?: string,
+  ): Promise<string>;
+}
+
+// ============================================================================
+// Definition Types
+// ============================================================================
+
+export interface ModelDefinition<S extends ZodSchema = ZodSchema> {
+  type: "model";
+  name: string;
+  description: string;
+  providers: string[];
+  defaultProvider: string;
+  schema: S;
+  /**
+   * Provider-specific model identifiers
+   * e.g., { fal: "fal-ai/kling-video/v2.5", replicate: "..." }
+   */
+  providerModels?: Record<string, string>;
+}
+
+export interface ActionRoute {
+  /** Target model or action name */
+  target: string;
+  /** Conditions that must be met for this route */
+  when?: Record<string, unknown>;
+  /** Priority (higher = preferred) */
+  priority?: number;
+  /** Transform inputs before passing to target */
+  transform?: (inputs: Record<string, unknown>) => Record<string, unknown>;
+}
+
+export interface ActionDefinition<S extends ZodSchema = ZodSchema> {
+  type: "action";
+  name: string;
+  description: string;
+  schema: S;
+  /** Routes to models or other actions */
+  routes: ActionRoute[];
+  /** Direct execution function (for local actions like ffmpeg) */
+  execute?: (inputs: InferInput<S>) => Promise<InferOutput<S>>;
+}
+
+export interface SkillStep {
+  name: string;
+  /** Action or model to run */
+  run: string;
+  /** Input mapping from previous steps or initial inputs */
+  inputs: Record<string, unknown>;
+  /** Condition to run this step */
+  when?: Record<string, unknown>;
+}
+
+export interface SkillDefinition<S extends ZodSchema = ZodSchema> {
+  type: "skill";
+  name: string;
+  description: string;
+  schema: S;
+  /** Ordered steps to execute */
+  steps: SkillStep[];
+}
+
+export type Definition =
+  | ModelDefinition<ZodSchema>
+  | ActionDefinition<ZodSchema>
+  | SkillDefinition<ZodSchema>;
+
+// ============================================================================
+// Execution Types
+// ============================================================================
+
+export interface RunOptions {
+  /** Override the default provider */
+  provider?: string;
+  /** Timeout in milliseconds */
+  timeout?: number;
+  /** Whether to wait for completion */
+  wait?: boolean;
+  /** Output directory for downloaded files */
+  outputDir?: string;
+  /** Progress callback */
+  onProgress?: (progress: number, logs?: string[]) => void;
+  /** Status change callback */
+  onStatusChange?: (status: JobStatus) => void;
+}
+
+export interface ExecutionResult {
+  /** Primary output (URL or file path) */
+  output: string | Record<string, unknown>;
+  /** Estimated cost in USD */
+  cost?: number;
+  /** Duration in milliseconds */
+  duration: number;
+  /** Provider used */
+  provider: string;
+  /** Model used */
+  model: string;
+  /** Job ID for reference */
+  jobId?: string;
+  /** Additional metadata */
+  metadata?: Record<string, unknown>;
+}
+
+// ============================================================================
+// Registry Types
+// ============================================================================
+
+export interface RegistryOptions {
+  /** Paths to scan for definitions */
+  definitionPaths?: string[];
+  /** Paths to scan for user skills */
+  skillPaths?: string[];
+}
+
+export interface SearchOptions {
+  /** Filter by type */
+  type?: "model" | "action" | "skill";
+  /** Filter by input type */
+  inputType?: string;
+  /** Filter by output type */
+  outputType?: string;
+  /** Filter by provider */
+  provider?: string;
+}
+
+// ============================================================================
+// Config Types
+// ============================================================================
+
+export interface VargConfig {
+  /** Default provider for each capability */
+  defaults?: {
+    imageToVideo?: string;
+    textToVideo?: string;
+    textToImage?: string;
+    textToSpeech?: string;
+  };
+  /** Provider-specific configuration */
+  providers?: Record<string, ProviderConfig>;
+  /** Output directory */
+  outputDir?: string;
+}

package/src/core/schema/validator.ts

@@ -0,0 +1,92 @@
+/**
+ * Input validation using Zod
+ * Validates inputs before execution
+ */
+
+import type { z } from "zod";
+
+export interface ValidationError {
+  path: string;
+  message: string;
+  value?: unknown;
+}
+
+export interface ValidationResult<T = unknown> {
+  valid: boolean;
+  errors: ValidationError[];
+  data?: T;
+}
+
+/**
+ * Validate inputs against a Zod schema
+ */
+export function validateInputs<T extends z.ZodTypeAny>(
+  inputs: unknown,
+  schema: T,
+): ValidationResult<z.infer<T>> {
+  const result = schema.safeParse(inputs);
+
+  if (result.success) {
+    return {
+      valid: true,
+      errors: [],
+      data: result.data,
+    };
+  }
+
+  return {
+    valid: false,
+    errors: result.error.issues.map((issue) => ({
+      path: issue.path.join("."),
+      message: issue.message,
+      value: inputs,
+    })),
+  };
+}
+
+/**
+ * Validate and prepare inputs in one step
+ * Zod automatically applies defaults during parsing
+ */
+export function validateAndPrepare<T extends z.ZodTypeAny>(
+  inputs: unknown,
+  schema: T,
+): ValidationResult<z.infer<T>> {
+  return validateInputs(inputs, schema);
+}
+
+/**
+ * Type-safe validation helper that throws on invalid input
+ */
+export function parseOrThrow<T extends z.ZodTypeAny>(
+  inputs: unknown,
+  schema: T,
+): z.infer<T> {
+  return schema.parse(inputs);
+}
+
+/**
+ * Apply defaults to inputs using Zod schema
+ * Zod automatically applies defaults during parsing
+ * Returns the input with defaults applied
+ */
+export function applyDefaults(
+  inputs: unknown,
+  // biome-ignore lint/suspicious/noExplicitAny: Zod v4 type compatibility
+  schema: any,
+): Record<string, unknown> {
+  // If schema has .input property (ZodSchema interface), use that
+  const zodSchema = schema.input || schema;
+
+  // Parse with defaults - if invalid, return inputs as-is
+  try {
+    return zodSchema.parse(inputs);
+  } catch {
+    // If validation fails, try to apply partial defaults
+    const partial = zodSchema.partial().safeParse(inputs);
+    if (partial.success) {
+      return { ...(inputs as Record<string, unknown>), ...partial.data };
+    }
+    return inputs as Record<string, unknown>;
+  }
+}