@originals/sdk 1.4.2 → 1.4.3

package/src/kinds/types.ts

@@ -1,470 +0,0 @@
-/**
- * Originals Kind System Types
- * 
- * Defines the typed "Kinds" for Originals - a classification system that
- * enables kind-specific validation, metadata schemas, and behaviors.
- */
-
-import type { AssetResource } from '../types/common';
-
-/**
- * The supported Original kinds
- * Each kind represents a category of digital asset with specific requirements
- */
-export enum OriginalKind {
-  /** Executable application with runtime and entrypoint */
-  App = 'originals:kind:app',
-  
-  /** AI agent or autonomous system with capabilities and model info */
-  Agent = 'originals:kind:agent',
-  
-  /** Reusable code module with exports and dependencies */
-  Module = 'originals:kind:module',
-  
-  /** Structured data collection with schema definition */
-  Dataset = 'originals:kind:dataset',
-  
-  /** Media content (image, audio, video) with format metadata */
-  Media = 'originals:kind:media',
-  
-  /** Text document with formatting and sections */
-  Document = 'originals:kind:document',
-}
-
-/**
- * Reference to a dependency Original
- */
-export interface DependencyRef {
-  /** DID of the dependency Original */
-  did: string;
-  
-  /** Semantic version constraint (e.g., "^1.0.0", ">=2.0.0") */
-  version?: string;
-  
-  /** Human-readable name of the dependency */
-  name?: string;
-  
-  /** Whether this dependency is required (default: true) */
-  optional?: boolean;
-}
-
-/**
- * Base manifest fields shared by all kinds
- */
-export interface BaseManifest {
-  /** Human-readable name */
-  name: string;
-  
-  /** Semantic version string (e.g., "1.0.0") */
-  version: string;
-  
-  /** Optional description */
-  description?: string;
-  
-  /** Resources associated with this Original */
-  resources: AssetResource[];
-  
-  /** Dependencies on other Originals */
-  dependencies?: DependencyRef[];
-  
-  /** Free-form tags for categorization */
-  tags?: string[];
-  
-  /** Author information */
-  author?: {
-    name?: string;
-    did?: string;
-    email?: string;
-    url?: string;
-  };
-  
-  /** License identifier (SPDX) */
-  license?: string;
-  
-  /** URL for more information */
-  homepage?: string;
-  
-  /** Repository URL */
-  repository?: string;
-}
-
-/**
- * App-specific metadata
- */
-export interface AppMetadata {
-  /** Runtime environment (e.g., "node", "browser", "deno", "bun") */
-  runtime: string;
-  
-  /** Entrypoint resource ID or path */
-  entrypoint: string;
-  
-  /** Required runtime version */
-  runtimeVersion?: string;
-  
-  /** Minimum required runtime version */
-  minRuntimeVersion?: string;
-  
-  /** App permissions required */
-  permissions?: string[];
-  
-  /** Environment variables expected */
-  env?: Record<string, {
-    description?: string;
-    required?: boolean;
-    default?: string;
-  }>;
-  
-  /** Supported platforms */
-  platforms?: ('linux' | 'darwin' | 'windows' | 'web')[];
-  
-  /** App icons by size */
-  icons?: Record<string, string>;
-  
-  /** CLI commands exposed */
-  commands?: Record<string, {
-    description: string;
-    args?: string[];
-  }>;
-}
-
-/**
- * Agent-specific metadata
- */
-export interface AgentMetadata {
-  /** Agent capabilities/skills */
-  capabilities: string[];
-  
-  /** Model information if AI-based */
-  model?: {
-    provider?: string;
-    name: string;
-    version?: string;
-    parameters?: Record<string, unknown>;
-  };
-  
-  /** Input types the agent accepts */
-  inputTypes?: string[];
-  
-  /** Output types the agent produces */
-  outputTypes?: string[];
-  
-  /** Memory/state configuration */
-  memory?: {
-    type: 'stateless' | 'session' | 'persistent';
-    maxSize?: number;
-  };
-  
-  /** System prompt or instructions */
-  systemPrompt?: string;
-  
-  /** Tools/functions the agent can use */
-  tools?: Array<{
-    name: string;
-    description: string;
-    parameters?: Record<string, unknown>;
-  }>;
-  
-  /** Rate limiting configuration */
-  rateLimit?: {
-    requestsPerMinute?: number;
-    tokensPerMinute?: number;
-  };
-}
-
-/**
- * Module-specific metadata
- */
-export interface ModuleMetadata {
-  /** Module format (esm, commonjs, umd, etc.) */
-  format: 'esm' | 'commonjs' | 'umd' | 'amd' | 'iife';
-  
-  /** Main entrypoint file (resource ID) */
-  main: string;
-  
-  /** Types definition file (resource ID) */
-  types?: string;
-  
-  /** Exported symbols/functions */
-  exports?: Record<string, string | { import?: string; require?: string; types?: string }>;
-  
-  /** Peer dependencies (expected to be provided by consumer) */
-  peerDependencies?: Record<string, string>;
-  
-  /** Browser-specific entrypoint */
-  browser?: string;
-  
-  /** Files included in the module */
-  files?: string[];
-  
-  /** Side effects declaration */
-  sideEffects?: boolean | string[];
-  
-  /** TypeScript configuration */
-  typescript?: {
-    strict?: boolean;
-    target?: string;
-    moduleResolution?: string;
-  };
-}
-
-/**
- * Dataset-specific metadata
- */
-export interface DatasetMetadata {
-  /** Schema definition (JSON Schema, or URL to schema) */
-  schema: Record<string, unknown> | string;
-  
-  /** Data format (csv, json, parquet, etc.) */
-  format: string;
-  
-  /** Number of records/rows */
-  recordCount?: number;
-  
-  /** Data columns/fields */
-  columns?: Array<{
-    name: string;
-    type: string;
-    description?: string;
-    nullable?: boolean;
-  }>;
-  
-  /** Data source information */
-  source?: {
-    origin?: string;
-    collectedAt?: string;
-    methodology?: string;
-  };
-  
-  /** Dataset statistics */
-  statistics?: {
-    sizeBytes?: number;
-    compression?: string;
-    checksums?: Record<string, string>;
-  };
-  
-  /** License specific to the data */
-  dataLicense?: string;
-  
-  /** Privacy classification */
-  privacy?: 'public' | 'internal' | 'confidential' | 'restricted';
-  
-  /** Update frequency */
-  updateFrequency?: 'realtime' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'static';
-}
-
-/**
- * Media-specific metadata
- */
-export interface MediaMetadata {
-  /** Media type (image, audio, video, 3d) */
-  mediaType: 'image' | 'audio' | 'video' | '3d' | 'animation';
-  
-  /** MIME type of the primary media resource */
-  mimeType: string;
-  
-  /** Dimensions (for images and video) */
-  dimensions?: {
-    width: number;
-    height: number;
-    aspectRatio?: string;
-  };
-  
-  /** Duration in seconds (for audio/video) */
-  duration?: number;
-  
-  /** Frame rate (for video/animation) */
-  frameRate?: number;
-  
-  /** Audio channels (for audio/video) */
-  audioChannels?: number;
-  
-  /** Sample rate (for audio) */
-  sampleRate?: number;
-  
-  /** Codec information */
-  codec?: string;
-  
-  /** Bitrate in kbps */
-  bitrate?: number;
-  
-  /** Color space */
-  colorSpace?: string;
-  
-  /** Thumbnail resource ID */
-  thumbnail?: string;
-  
-  /** Preview/low-res version resource ID */
-  preview?: string;
-  
-  /** Alt text for accessibility */
-  altText?: string;
-  
-  /** Caption or transcript */
-  caption?: string;
-  
-  /** EXIF or similar metadata */
-  exif?: Record<string, unknown>;
-}
-
-/**
- * Document-specific metadata
- */
-export interface DocumentMetadata {
-  /** Document format (markdown, html, pdf, docx, etc.) */
-  format: 'markdown' | 'html' | 'pdf' | 'docx' | 'txt' | 'asciidoc' | 'rst' | 'latex';
-  
-  /** Document language (ISO 639-1) */
-  language?: string;
-  
-  /** Main content resource ID */
-  content: string;
-  
-  /** Table of contents */
-  toc?: Array<{
-    title: string;
-    level: number;
-    anchor?: string;
-  }>;
-  
-  /** Page count */
-  pageCount?: number;
-  
-  /** Word count */
-  wordCount?: number;
-  
-  /** Reading time in minutes */
-  readingTime?: number;
-  
-  /** Keywords */
-  keywords?: string[];
-  
-  /** Abstract or summary */
-  abstract?: string;
-  
-  /** Bibliography/references */
-  references?: Array<{
-    id: string;
-    title: string;
-    authors?: string[];
-    year?: number;
-    url?: string;
-    doi?: string;
-  }>;
-  
-  /** Document status */
-  status?: 'draft' | 'review' | 'published' | 'archived';
-  
-  /** Revision number */
-  revision?: number;
-}
-
-/**
- * Maps each kind to its specific metadata type
- */
-export interface KindMetadataMap {
-  [OriginalKind.App]: AppMetadata;
-  [OriginalKind.Agent]: AgentMetadata;
-  [OriginalKind.Module]: ModuleMetadata;
-  [OriginalKind.Dataset]: DatasetMetadata;
-  [OriginalKind.Media]: MediaMetadata;
-  [OriginalKind.Document]: DocumentMetadata;
-}
-
-/**
- * Type-safe metadata accessor
- */
-export type KindMetadata<K extends OriginalKind> = K extends keyof KindMetadataMap
-  ? KindMetadataMap[K]
-  : never;
-
-/**
- * Generic Original manifest with kind-specific metadata
- */
-export interface OriginalManifest<K extends OriginalKind = OriginalKind> extends BaseManifest {
-  /** The kind of Original */
-  kind: K;
-  
-  /** Kind-specific metadata */
-  metadata: KindMetadata<K>;
-}
-
-/**
- * Type-specific manifest aliases for convenience
- */
-export type AppManifest = OriginalManifest<OriginalKind.App>;
-export type AgentManifest = OriginalManifest<OriginalKind.Agent>;
-export type ModuleManifest = OriginalManifest<OriginalKind.Module>;
-export type DatasetManifest = OriginalManifest<OriginalKind.Dataset>;
-export type MediaManifest = OriginalManifest<OriginalKind.Media>;
-export type DocumentManifest = OriginalManifest<OriginalKind.Document>;
-
-/**
- * Union type of all possible manifests
- */
-export type AnyManifest = 
-  | AppManifest 
-  | AgentManifest 
-  | ModuleManifest 
-  | DatasetManifest 
-  | MediaManifest 
-  | DocumentManifest;
-
-/**
- * Result of validating a manifest
- */
-export interface ValidationResult {
-  /** Whether the manifest is valid */
-  isValid: boolean;
-  
-  /** Validation errors if any */
-  errors: ValidationError[];
-  
-  /** Validation warnings (non-fatal) */
-  warnings: ValidationWarning[];
-}
-
-/**
- * A validation error
- */
-export interface ValidationError {
-  /** Error code */
-  code: string;
-  
-  /** Human-readable message */
-  message: string;
-  
-  /** Path to the invalid field (e.g., "metadata.entrypoint") */
-  path?: string;
-  
-  /** The invalid value */
-  value?: unknown;
-}
-
-/**
- * A validation warning (non-fatal issue)
- */
-export interface ValidationWarning {
-  /** Warning code */
-  code: string;
-  
-  /** Human-readable message */
-  message: string;
-  
-  /** Path to the field with warning */
-  path?: string;
-  
-  /** Suggested fix */
-  suggestion?: string;
-}
-
-/**
- * Options for creating a typed Original
- */
-export interface CreateTypedOriginalOptions {
-  /** Skip validation (not recommended) */
-  skipValidation?: boolean;
-  
-  /** Treat warnings as errors */
-  strictMode?: boolean;
-}
-

package/src/kinds/validators/AgentValidator.ts

@@ -1,257 +0,0 @@
-/**
- * Agent Kind Validator
- * 
- * Validates manifests for AI agents or autonomous systems with capabilities and model info.
- */
-
-import { OriginalKind, type OriginalManifest, type ValidationResult, type AgentMetadata } from '../types';
-import { BaseKindValidator, ValidationUtils } from './base';
-
-/**
- * Known AI model providers
- */
-const KNOWN_PROVIDERS = [
-  'openai', 'anthropic', 'google', 'meta', 'mistral', 'cohere',
-  'huggingface', 'replicate', 'together', 'groq', 'perplexity',
-  'fireworks', 'local', 'custom',
-];
-
-/**
- * Valid memory types
- */
-const VALID_MEMORY_TYPES = ['stateless', 'session', 'persistent'];
-
-/**
- * Validator for Agent Originals
- */
-export class AgentValidator extends BaseKindValidator<OriginalKind.Agent> {
-  readonly kind = OriginalKind.Agent;
-  
-  protected validateKind(manifest: OriginalManifest<OriginalKind.Agent>): ValidationResult {
-    const errors: ValidationResult['errors'] = [];
-    const warnings: ValidationResult['warnings'] = [];
-    const metadata = manifest.metadata as AgentMetadata;
-    
-    // Validate metadata exists
-    if (!metadata || typeof metadata !== 'object') {
-      return ValidationUtils.failure([
-        ValidationUtils.error('MISSING_METADATA', 'Agent manifest must have metadata', 'metadata'),
-      ]);
-    }
-    
-    // Validate capabilities (required)
-    if (!metadata.capabilities) {
-      errors.push(ValidationUtils.error(
-        'MISSING_CAPABILITIES',
-        'Agent must specify capabilities',
-        'metadata.capabilities',
-      ));
-    } else if (!Array.isArray(metadata.capabilities)) {
-      errors.push(ValidationUtils.error(
-        'INVALID_CAPABILITIES',
-        'Capabilities must be an array of strings',
-        'metadata.capabilities',
-      ));
-    } else if (metadata.capabilities.length === 0) {
-      errors.push(ValidationUtils.error(
-        'EMPTY_CAPABILITIES',
-        'Agent must have at least one capability',
-        'metadata.capabilities',
-      ));
-    } else {
-      for (let i = 0; i < metadata.capabilities.length; i++) {
-        if (typeof metadata.capabilities[i] !== 'string') {
-          errors.push(ValidationUtils.error(
-            'INVALID_CAPABILITY',
-            `Capability at index ${i} must be a string`,
-            `metadata.capabilities[${i}]`,
-          ));
-        } else if (metadata.capabilities[i].length === 0) {
-          errors.push(ValidationUtils.error(
-            'EMPTY_CAPABILITY',
-            `Capability at index ${i} cannot be empty`,
-            `metadata.capabilities[${i}]`,
-          ));
-        }
-      }
-    }
-    
-    // Validate model if specified
-    if (metadata.model) {
-      if (typeof metadata.model !== 'object') {
-        errors.push(ValidationUtils.error(
-          'INVALID_MODEL',
-          'Model must be an object',
-          'metadata.model',
-        ));
-      } else {
-        // Model name is required
-        if (!metadata.model.name || typeof metadata.model.name !== 'string') {
-          errors.push(ValidationUtils.error(
-            'MISSING_MODEL_NAME',
-            'Model must have a name',
-            'metadata.model.name',
-          ));
-        }
-        
-        // Validate provider if specified
-        if (metadata.model.provider) {
-          const normalizedProvider = metadata.model.provider.toLowerCase();
-          if (!KNOWN_PROVIDERS.includes(normalizedProvider)) {
-            warnings.push(ValidationUtils.warning(
-              'UNKNOWN_PROVIDER',
-              `Model provider "${metadata.model.provider}" is not a commonly recognized provider`,
-              'metadata.model.provider',
-              `Consider using one of: ${KNOWN_PROVIDERS.join(', ')}`,
-            ));
-          }
-        }
-      }
-    }
-    
-    // Validate input/output types if specified
-    if (metadata.inputTypes) {
-      if (!Array.isArray(metadata.inputTypes)) {
-        errors.push(ValidationUtils.error(
-          'INVALID_INPUT_TYPES',
-          'Input types must be an array',
-          'metadata.inputTypes',
-        ));
-      }
-    }
-    
-    if (metadata.outputTypes) {
-      if (!Array.isArray(metadata.outputTypes)) {
-        errors.push(ValidationUtils.error(
-          'INVALID_OUTPUT_TYPES',
-          'Output types must be an array',
-          'metadata.outputTypes',
-        ));
-      }
-    }
-    
-    // Validate memory if specified
-    if (metadata.memory) {
-      if (typeof metadata.memory !== 'object') {
-        errors.push(ValidationUtils.error(
-          'INVALID_MEMORY',
-          'Memory must be an object',
-          'metadata.memory',
-        ));
-      } else {
-        if (!metadata.memory.type || !VALID_MEMORY_TYPES.includes(metadata.memory.type)) {
-          errors.push(ValidationUtils.error(
-            'INVALID_MEMORY_TYPE',
-            `Memory type must be one of: ${VALID_MEMORY_TYPES.join(', ')}`,
-            'metadata.memory.type',
-            metadata.memory.type,
-          ));
-        }
-        
-        if (metadata.memory.maxSize !== undefined && 
-            (typeof metadata.memory.maxSize !== 'number' || metadata.memory.maxSize <= 0)) {
-          errors.push(ValidationUtils.error(
-            'INVALID_MEMORY_SIZE',
-            'Memory maxSize must be a positive number',
-            'metadata.memory.maxSize',
-          ));
-        }
-      }
-    }
-    
-    // Validate tools if specified
-    if (metadata.tools) {
-      if (!Array.isArray(metadata.tools)) {
-        errors.push(ValidationUtils.error(
-          'INVALID_TOOLS',
-          'Tools must be an array',
-          'metadata.tools',
-        ));
-      } else {
-        for (let i = 0; i < metadata.tools.length; i++) {
-          const tool = metadata.tools[i];
-          const toolPath = `metadata.tools[${i}]`;
-          
-          if (!tool || typeof tool !== 'object') {
-            errors.push(ValidationUtils.error(
-              'INVALID_TOOL',
-              `Tool at index ${i} must be an object`,
-              toolPath,
-            ));
-            continue;
-          }
-          
-          if (!tool.name || typeof tool.name !== 'string') {
-            errors.push(ValidationUtils.error(
-              'MISSING_TOOL_NAME',
-              `Tool at index ${i} must have a name`,
-              `${toolPath}.name`,
-            ));
-          }
-          
-          if (!tool.description || typeof tool.description !== 'string') {
-            warnings.push(ValidationUtils.warning(
-              'MISSING_TOOL_DESC',
-              `Tool "${tool.name || i}" should have a description`,
-              `${toolPath}.description`,
-            ));
-          }
-        }
-      }
-    }
-    
-    // Validate rate limits if specified
-    if (metadata.rateLimit) {
-      if (typeof metadata.rateLimit !== 'object') {
-        errors.push(ValidationUtils.error(
-          'INVALID_RATE_LIMIT',
-          'Rate limit must be an object',
-          'metadata.rateLimit',
-        ));
-      } else {
-        if (metadata.rateLimit.requestsPerMinute !== undefined &&
-            (typeof metadata.rateLimit.requestsPerMinute !== 'number' || 
-             metadata.rateLimit.requestsPerMinute <= 0)) {
-          errors.push(ValidationUtils.error(
-            'INVALID_RPM',
-            'requestsPerMinute must be a positive number',
-            'metadata.rateLimit.requestsPerMinute',
-          ));
-        }
-        
-        if (metadata.rateLimit.tokensPerMinute !== undefined &&
-            (typeof metadata.rateLimit.tokensPerMinute !== 'number' || 
-             metadata.rateLimit.tokensPerMinute <= 0)) {
-          errors.push(ValidationUtils.error(
-            'INVALID_TPM',
-            'tokensPerMinute must be a positive number',
-            'metadata.rateLimit.tokensPerMinute',
-          ));
-        }
-      }
-    }
-    
-    // Suggest adding model info for AI agents
-    if (!metadata.model) {
-      warnings.push(ValidationUtils.warning(
-        'MISSING_MODEL',
-        'Consider adding model information if this is an AI-based agent',
-        'metadata.model',
-      ));
-    }
-    
-    // Suggest adding system prompt
-    if (!metadata.systemPrompt) {
-      warnings.push(ValidationUtils.warning(
-        'MISSING_SYSTEM_PROMPT',
-        'Consider adding a system prompt to define the agent\'s behavior',
-        'metadata.systemPrompt',
-      ));
-    }
-    
-    return errors.length > 0
-      ? ValidationUtils.failure(errors, warnings)
-      : ValidationUtils.success(warnings);
-  }
-}
-