weave-typescript 0.9.0 → 0.10.0

package/dist/weaveapi/llmx/v1/model.pb.d.ts

@@ -3,132 +3,250 @@ import { Architecture, Licensing, Safety, TechnicalSpecs, Training } from "./arc
 import { Capability } from "./capabilities.pb";
 import { Pricing } from "./pricing.pb";
 export declare const protobufPackage = "weaveapi.llmx.v1";
+/**
+ * Model represents a complete AI model with all its metadata, capabilities, and pricing.
+ * This is the primary entity for model discovery and comparison.
+ */
 export interface Model {
-    /** Unique internal identifier for this model record in our database */
+    /**
+     * Unique internal identifier for this model record in our database.
+     * Example: "mdl_01234567-89ab-cdef-0123-456789abcdef"
+     * Generated by our system, not provider-specific
+     */
     id: string;
-    /** Provider's unique identifier (e.g., "openai-123", "anthropic-456") */
+    /**
+     * Provider's unique identifier in our system.
+     * Example: "pvd_openai_2024", "pvd_anthropic_2024"
+     * Links to Provider entity
+     */
     providerId: string;
-    /** URL-friendly provider identifier (e.g., "openai", "anthropic") */
+    /**
+     * URL-friendly provider identifier for routing.
+     * Examples: "openai", "anthropic", "google", "meta"
+     * Used in API paths like /models/openai/gpt-4
+     */
     providerSlug: string;
-    /** Human-readable provider name (e.g., "OpenAI", "Anthropic") */
+    /**
+     * Human-readable provider name for display.
+     * Examples: "OpenAI", "Anthropic", "Google AI", "Meta AI"
+     */
     providerName: string;
-    /** Provider's specific model identifier (e.g., "gpt-4", "claude-3-opus") */
+    /**
+     * Provider's specific model identifier as they define it.
+     * Examples: "gpt-4-turbo-2024-04-09", "claude-3-opus-20240229"
+     * This is what you use in their API calls
+     */
     modelId: string;
-    /** Combined provider/model identifier (e.g., "openai/gpt-4") */
+    /**
+     * Combined provider/model identifier for unique referencing.
+     * Format: "{provider_slug}/{model_id}"
+     * Examples: "openai/gpt-4", "anthropic/claude-3-opus"
+     */
     slug: string;
-    /** Model's technical name (e.g., "gpt-4-turbo-2024-04-09") */
+    /**
+     * Model's full technical name from the provider.
+     * Examples: "gpt-4-turbo-2024-04-09", "claude-3-opus-20240229"
+     * May include version dates or technical details
+     */
     name: string;
-    /** User-friendly display name (e.g., "GPT-4 Turbo") */
+    /**
+     * User-friendly display name for UI presentation.
+     * Examples: "GPT-4 Turbo", "Claude 3 Opus", "Gemini Pro"
+     * Simplified version of technical name
+     */
     displayName: string;
-    /** Human-readable description of the model's purpose and capabilities */
+    /**
+     * Human-readable description of the model's purpose and capabilities.
+     * Example: "Most capable GPT-4 model, optimized for complex tasks requiring
+     * advanced reasoning, coding, and creative writing. Supports vision, function
+     * calling, and JSON mode."
+     */
     description: string;
-    /** Model version string (e.g., "2024-04-09", "v1.0") */
+    /**
+     * Model version string from provider.
+     * Examples: "2024-04-09", "v1.0", "preview-0125"
+     * May be date-based or semantic versioning
+     */
     version: string;
     /**
-     * Dates
-     * When the model was publicly released
+     * When the model was publicly released by the provider.
+     * Example: 2024-04-09 for GPT-4 Turbo April release
      */
     releaseDate: Date | undefined;
-    /** Last date of data used in training (knowledge cutoff) */
+    /**
+     * Last date of data used in training (knowledge cutoff).
+     * Example: 2023-12-01 means model knows events up to this date
+     * Important for factual queries and current events
+     */
     trainingDataCutoff: Date | undefined;
-    /** When the model will be/was deprecated (if applicable) */
+    /**
+     * When the model will be/was deprecated (if scheduled).
+     * Example: 2025-01-15 for planned sunset
+     * Null if no deprecation planned
+     */
     deprecationDate: Date | undefined;
     /**
-     * Capabilities - now uses detailed capability configurations
-     * List of specific capabilities this model supports (e.g., function calling, vision)
+     * List of specific capabilities this model supports.
+     * Examples: text_generation, function_calling, vision, code_interpreter
+     * See capabilities.proto for full enumeration
      */
     capabilities: Capability[];
     /**
-     * Classification
-     * Model type, architecture, and licensing information
+     * Model type, architecture, and licensing classification.
+     * Categorizes the model for filtering and comparison
      */
     classification: ModelClassification | undefined;
     /**
-     * Performance
-     * Benchmark scores and performance metrics
+     * Benchmark scores and performance metrics.
+     * Standardized scores for comparing model capabilities
      */
     performance: ModelPerformance | undefined;
     /**
-     * Tokens
-     * Token limits, processing speed, and tokenizer information
+     * Token limits, processing speed, and tokenizer information.
+     * Critical for understanding model constraints
      */
     tokens: TokenInfo | undefined;
     /**
-     * Pricing
-     * Cost per token for various operations (input, output, caching, etc.)
+     * Complete pricing structure for all operations.
+     * Includes standard, batch, cached, and tool pricing
      */
     pricing: Pricing | undefined;
     /**
-     * Configuration
-     * Supported parameter ranges (temperature, top_p, etc.)
+     * Supported parameter ranges for generation.
+     * Temperature, top_p, and other sampling parameters
      */
     configuration: Configuration | undefined;
     /**
-     * API Details
-     * Endpoint information and rate limits
+     * API endpoint information and rate limits.
+     * Everything needed to call the model programmatically
      */
     apiDetails: APIDetails | undefined;
     /**
-     * Availability
-     * Available regions and platforms where model can be accessed
+     * Available regions and platforms.
+     * Where and how the model can be accessed
      */
     availability: Availability | undefined;
     /**
-     * Architecture details
-     * Technical architecture information (transformer type, layers, etc.)
+     * Technical architecture information.
+     * Transformer type, layer count, attention mechanism, etc.
      */
     architecture: Architecture | undefined;
     /**
-     * Training information
-     * Details about training data, methods, and compute used
+     * Training dataset and methodology information.
+     * How the model was trained and on what data
      */
     training: Training | undefined;
     /**
-     * Safety and moderation
-     * Built-in safety features and content filtering
+     * Built-in safety features and content filtering.
+     * Moderation capabilities and safety guardrails
      */
     safety: Safety | undefined;
     /**
-     * Licensing information
-     * License type and usage restrictions
+     * License type and usage restrictions.
+     * Legal terms for using the model
      */
     licensing: Licensing | undefined;
     /**
-     * Technical specifications
-     * Hardware requirements and technical details
+     * Hardware requirements and technical details.
+     * Memory, compute requirements for self-hosting
      */
     technicalSpecs: TechnicalSpecs | undefined;
     /**
-     * Metadata
-     * When this model information was last updated in our system
+     * When this model information was last updated in our system.
+     * Example: 2024-08-25T10:30:00Z
+     * For tracking data freshness
      */
     lastScrapedAt: Date | undefined;
-    /** Sources where this model information was collected from */
+    /**
+     * Sources where this model information was collected from.
+     * Examples: ["https://openai.com/pricing", "https://platform.openai.com/docs"]
+     * For data provenance and verification
+     */
     dataSources: string[];
-    /** Whether the model is currently available for use */
+    /**
+     * Whether the model is currently available for use.
+     * false if model is down, in maintenance, or discontinued
+     */
     isActive: boolean;
-    /** Whether the model has been deprecated */
+    /**
+     * Whether the model has been officially deprecated.
+     * true once deprecation_date has passed or provider announces EOL
+     */
     isDeprecated: boolean;
-    /** If deprecated, the recommended replacement model's ID */
+    /**
+     * If deprecated, the recommended replacement model's ID.
+     * Example: "mdl_gpt4_turbo_2024" replacing "mdl_gpt4_2023"
+     * Helps with migration paths
+     */
     replacementModelId: string;
 }
+/** ModelClassification categorizes models for filtering and comparison. */
 export interface ModelClassification {
-    /** foundation, fine-tuned, instruct, chat, reasoning */
+    /**
+     * Primary model type defining its training approach.
+     * Examples: "foundation", "fine-tuned", "instruct", "chat", "reasoning"
+     * "foundation" = base model, "instruct" = instruction-following
+     */
     modelType: string;
-    /** GPT, LLaMA, BERT, etc */
+    /**
+     * Underlying model architecture family.
+     * Examples: "GPT", "LLaMA", "BERT", "T5", "Transformer", "Mamba"
+     */
     architecture: string;
+    /**
+     * Approximate number of parameters in billions.
+     * Examples: 7 (7B), 70 (70B), 175 (175B for GPT-3)
+     */
     parameterCount: number;
+    /**
+     * Whether model weights are publicly available.
+     * true for LLaMA, Mistral; false for GPT-4, Claude
+     */
     isOpenSource: boolean;
+    /**
+     * Software license if open source.
+     * Examples: "MIT", "Apache-2.0", "Custom", "Proprietary"
+     */
     licenseType: string;
 }
+/** ModelPerformance captures standardized benchmark scores. */
 export interface ModelPerformance {
-    /** 0-10 */
+    /**
+     * General reasoning ability score (0-10 scale).
+     * Based on benchmarks like ARC, HellaSwag, MMLU
+     * Example: 8.5 for strong reasoning models
+     */
     reasoningScore: number;
+    /**
+     * Programming and code generation score (0-10).
+     * Based on HumanEval, MBPP benchmarks
+     * Example: 9.2 for specialized coding models
+     */
     codingScore: number;
+    /**
+     * Creative writing and generation score (0-10).
+     * Based on human evaluations and creative benchmarks
+     * Example: 7.8 for models good at storytelling
+     */
     creativeScore: number;
+    /**
+     * Factual accuracy and knowledge score (0-10).
+     * Based on TruthfulQA, factual benchmarks
+     * Example: 8.0 for models with good factual recall
+     */
     factualScore: number;
+    /**
+     * Mathematical reasoning score (0-10).
+     * Based on GSM8K, MATH benchmarks
+     * Example: 9.5 for models excelling at math
+     */
     mathScore: number;
-    /** mmlu, humaneval, etc */
+    /**
+     * Raw benchmark scores by name.
+     * Keys: "mmlu", "humaneval", "gsm8k", "truthfulqa", "arc", "hellaswag"
+     * Values: Actual benchmark scores (usually 0-100)
+     * Example: {"mmlu": 86.4, "humaneval": 92.0, "gsm8k": 95.0}
+     */
     benchmarkScores: {
         [key: string]: number;
     };
@@ -137,29 +255,95 @@ export interface ModelPerformance_BenchmarkScoresEntry {
     key: string;
     value: number;
 }
+/** TokenInfo describes token limits and processing capabilities. */
 export interface TokenInfo {
+    /**
+     * Maximum tokens the model can process in a single request.
+     * Examples: 4096, 8192, 32768, 128000, 200000
+     * Includes both input and output tokens
+     */
     contextWindow: number;
+    /**
+     * Maximum tokens that can be generated in response.
+     * Examples: 4096 for most models, 16384 for some
+     * May be less than context_window
+     */
     maxOutputTokens: number;
+    /**
+     * Tokenizer algorithm used.
+     * Examples: "cl100k_base" (GPT-4), "claude", "sentencepiece"
+     */
     tokenizer: string;
+    /**
+     * Average generation speed in tokens per second.
+     * Example: 50 for typical API, 100+ for optimized inference
+     * May vary based on load and tier
+     */
     tokensPerSecond: number;
 }
+/** Configuration defines supported generation parameters. */
 export interface Configuration {
+    /**
+     * Minimum allowed temperature value.
+     * Usually 0.0 for deterministic output
+     */
     temperatureMin: number;
+    /**
+     * Maximum allowed temperature value.
+     * Usually 1.0 or 2.0 for high randomness
+     */
     temperatureMax: number;
+    /**
+     * Default temperature if not specified.
+     * Typically 0.7 or 1.0
+     */
     temperatureDefault: number;
+    /**
+     * Minimum allowed top_p (nucleus sampling).
+     * Usually 0.0 to disable
+     */
     topPMin: number;
+    /**
+     * Maximum allowed top_p value.
+     * Usually 1.0 for full vocabulary
+     */
     topPMax: number;
 }
+/** APIDetails provides integration information. */
 export interface APIDetails {
+    /**
+     * Base API endpoint URL.
+     * Example: "https://api.openai.com/v1/chat/completions"
+     */
     endpoint: string;
+    /**
+     * API version identifier.
+     * Examples: "v1", "2024-02-01", "beta"
+     */
     version: string;
-    /** requests per minute */
+    /**
+     * Rate limit in requests per minute.
+     * Example: 500 for standard tier, 10000 for enterprise
+     */
     rateLimitRpm: number;
-    /** tokens per minute */
+    /**
+     * Rate limit in tokens per minute.
+     * Example: 90000 for GPT-4, 200000 for GPT-3.5
+     */
     rateLimitTpm: number;
 }
+/** Availability describes where the model can be accessed. */
 export interface Availability {
+    /**
+     * Geographic regions where available.
+     * Examples: ["us-east-1", "eu-west-1", "asia-pacific"]
+     * May use provider-specific region codes
+     */
     regions: string[];
+    /**
+     * Platforms/services offering the model.
+     * Examples: ["api", "playground", "azure", "vertex-ai", "bedrock"]
+     */
     platforms: string[];
 }
 export declare const Model: MessageFns<Model>;