@ancatag/nova-proto 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export declare const NOVA_SERVICE_PROTO: string;
+export declare const ENGINE_PROTO: string;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,kBAAkB,QAAwC,CAAC;AACxE,eAAO,MAAM,YAAY,QAAkC,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+export const NOVA_SERVICE_PROTO = join(__dirname, "nova-service.proto");
+export const ENGINE_PROTO = join(__dirname, "engine.proto");
+// export * from "./generated/nova-service";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,SAAS,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE/D,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC,SAAS,EAAE,oBAAoB,CAAC,CAAC;AACxE,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;AAC5D,4CAA4C"}

package/package.json

@@ -0,0 +1,27 @@
+{
+	"name": "@ancatag/nova-proto",
+	"version": "0.1.0",
+	"private": false,
+	"type": "module",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"files": [
+		"dist",
+		"src/**/*.proto"
+	],
+	"scripts": {
+		"build": "tsc",
+		"generate": "tsx ./scripts/generate.ts",
+		"prepublishOnly": "pnpm build"
+	},
+	"devDependencies": {
+		"@types/node": "^25.3.0",
+		"ts-node": "^10.9.2",
+		"ts-proto": "^2.11.2",
+		"tsx": "^4.21.0",
+		"typescript": "^5.9.3"
+	},
+	"dependencies": {
+		"@grpc/proto-loader": "^0.8.0"
+	}
+}

package/src/engine.proto

@@ -0,0 +1,431 @@
+syntax = "proto3";
+
+package engine;
+
+// ===================================================================
+// NOVA ENGINE SERVICE
+// ===================================================================
+// Multi-modal AI generation service with intelligent model selection
+
+service EngineService {
+  // Model Selection
+  rpc SelectModel(SelectModelRequest) returns (SelectModelResponse);
+  rpc GetAvailableModels(GetModelsRequest) returns (GetModelsResponse);
+  rpc GetModelPresets(GetPresetsRequest) returns (GetPresetsResponse);
+  
+  // Generation - Text
+  rpc GenerateText(GenerateTextRequest) returns (stream GenerateTextResponse);
+  
+  // Generation - Image (Future)
+  rpc GenerateImage(GenerateImageRequest) returns (GenerateImageResponse);
+  
+  // Generation - Video (Future)
+  rpc GenerateVideo(GenerateVideoRequest) returns (GenerateVideoResponse);
+  
+  // Generation - Audio (Future)
+  rpc GenerateAudio(GenerateAudioRequest) returns (GenerateAudioResponse);
+  
+  // Provider Management
+  rpc GetProviders(GetProvidersRequest) returns (GetProvidersResponse);
+  rpc UpdateProvider(UpdateProviderRequest) returns (UpdateProviderResponse);
+  rpc CheckProviderHealth(CheckHealthRequest) returns (CheckHealthResponse);
+  
+  // Analytics & Metrics
+  rpc GetGenerationMetrics(GetMetricsRequest) returns (GetMetricsResponse);
+  rpc GetUsageStats(GetUsageStatsRequest) returns (GetUsageStatsResponse);
+  
+  // Cache Management
+  rpc ClearCache(ClearCacheRequest) returns (ClearCacheResponse);
+  rpc GetCacheStats(CacheStatsRequest) returns (CacheStatsResponse);
+}
+
+// ===================================================================
+// COMMON MESSAGES
+// ===================================================================
+
+message Empty {}
+
+message ErrorResponse {
+  string code = 1;
+  string message = 2;
+  map<string, string> details = 3;
+}
+
+// ===================================================================
+// MODEL SELECTION MESSAGES
+// ===================================================================
+
+message SelectModelRequest {
+  string character_id = 1;
+  string generation_type = 2; // "text", "image", "video", "audio"
+  optional string preferred_provider = 3;
+  optional string preferred_model = 4;
+}
+
+message SelectModelResponse {
+  string model_id = 1;
+  string model_name = 2;
+  string model_identifier = 3;
+  string provider = 4;
+  string integration_id = 5;
+  ModelConfig config = 6;
+  bool success = 7;
+  optional string error_message = 8;
+}
+
+message ModelConfig {
+  optional double temperature = 1;
+  optional int32 max_tokens = 2;
+  optional double top_p = 3;
+  repeated string stop_sequences = 4;
+  map<string, string> additional_params = 5;
+}
+
+message GetModelsRequest {
+  string generation_type = 1;
+  optional bool active_only = 2;
+  optional string provider = 3;
+}
+
+message GetModelsResponse {
+  repeated ModelInfo models = 1;
+}
+
+message ModelInfo {
+  string id = 1;
+  string name = 2;
+  string identifier = 3;
+  string type = 4;
+  string provider = 5;
+  string provider_name = 6;
+  bool is_active = 7;
+  bool is_default = 8;
+  int32 priority = 9;
+  optional ModelConfig default_config = 10;
+}
+
+message GetPresetsRequest {
+  optional string tier = 1;
+  optional bool active_only = 2;
+}
+
+message GetPresetsResponse {
+  repeated PresetInfo presets = 1;
+}
+
+message PresetInfo {
+  string id = 1;
+  string name = 2;
+  string description = 3;
+  string tier = 4;
+  bool is_active = 5;
+  bool is_default = 6;
+  optional ModelInfo model = 7;
+}
+
+// ===================================================================
+// TEXT GENERATION MESSAGES
+// ===================================================================
+
+message GenerateTextRequest {
+  string request_id = 1;
+  string model_id = 2;
+  repeated ChatMessage messages = 3;
+  optional string character_id = 4;
+  optional string user_id = 5;
+  optional string message_id = 6;
+  map<string, string> metadata = 7;
+  ModelConfig config = 8;
+  bool stream = 9;
+  optional string prompt = 10;
+}
+
+message ChatMessage {
+  string role = 1; // "user", "assistant", "system"
+  string content = 2;
+  optional string name = 3;
+}
+
+message GenerateTextResponse {
+  string request_id = 1;
+  string content = 2; // Text chunk for streaming
+  bool is_complete = 3;
+  optional GenerationMetadata generation_metadata = 4;
+  optional string error_message = 5;
+}
+
+message GenerationMetadata {
+  int32 tokens_used = 1;
+  int32 input_tokens = 2;
+  int32 output_tokens = 3;
+  int32 response_time_ms = 4;
+  bool cache_hit = 5;
+  bool semantic_match = 6;
+  string model_used = 7;
+  string provider_used = 8;
+  optional double estimated_cost = 9;
+}
+
+// ===================================================================
+// IMAGE GENERATION MESSAGES
+// ===================================================================
+
+message GenerateImageRequest {
+  string request_id = 1;
+  string model_id = 2;
+  string prompt = 3;
+  optional string negative_prompt = 4;
+  optional string character_id = 5;
+  optional string user_id = 6;
+  ImageConfig config = 7;
+  map<string, string> metadata = 8;
+}
+
+message ImageConfig {
+  int32 width = 1;
+  int32 height = 2;
+  int32 num_images = 3;
+  optional string style = 4;
+  optional double guidance_scale = 5;
+  optional int32 steps = 6;
+  optional string quality = 7; // "standard", "hd"
+}
+
+message GenerateImageResponse {
+  string request_id = 1;
+  repeated string image_urls = 2;
+  repeated bytes image_data = 3; // Optional raw image data
+  GenerationMetadata generation_metadata = 4;
+  bool success = 5;
+  optional string error_message = 6;
+}
+
+// ===================================================================
+// VIDEO GENERATION MESSAGES
+// ===================================================================
+
+message GenerateVideoRequest {
+  string request_id = 1;
+  string model_id = 2;
+  string prompt = 3;
+  optional string character_id = 4;
+  optional string user_id = 5;
+  VideoConfig config = 6;
+  map<string, string> metadata = 7;
+}
+
+message VideoConfig {
+  int32 duration_seconds = 1;
+  optional int32 fps = 2;
+  optional string resolution = 3; // "720p", "1080p", "4k"
+  optional string style = 4;
+  optional string aspect_ratio = 5; // "16:9", "9:16", "1:1"
+}
+
+message GenerateVideoResponse {
+  string request_id = 1;
+  string video_url = 2;
+  optional string thumbnail_url = 3;
+  GenerationMetadata generation_metadata = 4;
+  bool success = 5;
+  optional string error_message = 6;
+}
+
+// ===================================================================
+// AUDIO GENERATION MESSAGES
+// ===================================================================
+
+message GenerateAudioRequest {
+  string request_id = 1;
+  string model_id = 2;
+  string text = 3;
+  optional string character_id = 4;
+  optional string user_id = 5;
+  AudioConfig config = 6;
+  map<string, string> metadata = 7;
+}
+
+message AudioConfig {
+  optional string voice = 1;
+  optional double speed = 2;
+  optional int32 sample_rate = 3;
+  optional string format = 4; // "mp3", "wav", "ogg"
+  optional double stability = 5;
+  optional double similarity_boost = 6;
+}
+
+message GenerateAudioResponse {
+  string request_id = 1;
+  string audio_url = 2;
+  optional bytes audio_data = 3;
+  GenerationMetadata generation_metadata = 4;
+  bool success = 5;
+  optional string error_message = 6;
+}
+
+// ===================================================================
+// PROVIDER MANAGEMENT MESSAGES
+// ===================================================================
+
+message GetProvidersRequest {
+  optional string type = 1; // Filter by type: "text", "image", "video", "audio"
+  optional bool enabled_only = 2;
+}
+
+message GetProvidersResponse {
+  repeated ProviderInfo providers = 1;
+}
+
+message ProviderInfo {
+  string id = 1;
+  string name = 2;
+  string provider = 3;
+  string type = 4;
+  bool is_enabled = 5;
+  string status = 6;
+  int32 priority = 7;
+  ProviderHealth health = 8;
+  repeated string supported_features = 9;
+}
+
+message ProviderHealth {
+  bool is_healthy = 1;
+  int64 last_check_timestamp = 2;
+  optional int32 response_time_ms = 3;
+  optional string error_message = 4;
+  double uptime_percentage = 5;
+}
+
+message UpdateProviderRequest {
+  string provider_id = 1;
+  optional bool is_enabled = 2;
+  optional string status = 3;
+  optional int32 priority = 4;
+  map<string, string> config_updates = 5;
+}
+
+message UpdateProviderResponse {
+  bool success = 1;
+  string message = 2;
+  optional ProviderInfo updated_provider = 3;
+}
+
+message CheckHealthRequest {
+  optional string provider_id = 1; // Check specific provider or all if empty
+}
+
+message CheckHealthResponse {
+  map<string, ProviderHealth> health_status = 1;
+  int32 healthy_count = 2;
+  int32 total_count = 3;
+}
+
+// ===================================================================
+// ANALYTICS MESSAGES
+// ===================================================================
+
+message GetMetricsRequest {
+  string period_type = 1; // "hourly", "daily", "monthly"
+  int64 start_timestamp = 2;
+  int64 end_timestamp = 3;
+  optional string generation_type = 4;
+  optional string provider_id = 5;
+  optional string model_id = 6;
+}
+
+message GetMetricsResponse {
+  repeated MetricData metrics = 1;
+  MetricSummary summary = 2;
+}
+
+message MetricData {
+  int64 period_start = 1;
+  int64 period_end = 2;
+  string generation_type = 3;
+  int32 total_requests = 4;
+  int32 successful_requests = 5;
+  int32 failed_requests = 6;
+  int32 cached_requests = 7;
+  double avg_response_time = 8;
+  double p95_response_time = 9;
+  double cache_hit_rate = 10;
+  TokenUsage token_usage = 11;
+  double total_cost = 12;
+}
+
+message MetricSummary {
+  int32 total_requests = 1;
+  int32 total_successful = 2;
+  int32 total_failed = 3;
+  int32 total_cached = 4;
+  double overall_cache_hit_rate = 5;
+  double total_cost = 6;
+  TokenUsage total_tokens = 7;
+}
+
+message TokenUsage {
+  int32 input_tokens = 1;
+  int32 output_tokens = 2;
+  int32 total_tokens = 3;
+}
+
+message GetUsageStatsRequest {
+  optional string character_id = 1;
+  optional string user_id = 2;
+  int64 start_timestamp = 3;
+  int64 end_timestamp = 4;
+}
+
+message GetUsageStatsResponse {
+  map<string, int32> generations_by_type = 1;
+  TokenUsage total_tokens = 2;
+  double total_cost = 3;
+  int32 cache_hits = 4;
+  double cache_hit_rate = 5;
+  repeated ModelUsage model_usage = 6;
+}
+
+message ModelUsage {
+  string model_id = 1;
+  string model_name = 2;
+  int32 request_count = 3;
+  TokenUsage tokens = 4;
+  double cost = 5;
+}
+
+// ===================================================================
+// CACHE MANAGEMENT MESSAGES
+// ===================================================================
+
+message ClearCacheRequest {
+  optional string cache_type = 1; // "all", "generation", "model", "embedding"
+  optional string generation_type = 2; // Clear cache for specific type
+  optional bool force = 3; // Force clear even if recently used
+}
+
+message ClearCacheResponse {
+  bool success = 1;
+  string message = 2;
+  int32 entries_cleared = 3;
+}
+
+message CacheStatsRequest {
+  optional string cache_type = 1;
+}
+
+message CacheStatsResponse {
+  int64 total_entries = 1;
+  int64 total_hits = 2;
+  int64 total_misses = 3;
+  double hit_rate = 4;
+  int64 memory_usage_bytes = 5;
+  map<string, CacheTypeStats> stats_by_type = 6;
+}
+
+message CacheTypeStats {
+  string type = 1;
+  int64 entries = 2;
+  int64 hits = 3;
+  int64 misses = 4;
+  double hit_rate = 5;
+}

package/src/nova-service.proto

@@ -0,0 +1,472 @@
+// ===================================================================
+// NOVA SERVICE gRPC DEFINITION
+// ===================================================================
+// Multi-modal AI generation service with flexible model selection
+// Supports text, image, video, and audio generation
+
+syntax = "proto3";
+
+package nova.service;
+
+import "google/protobuf/timestamp.proto";
+import "google/protobuf/duration.proto";
+
+// ===================================================================
+// SERVICE DEFINITION
+// ===================================================================
+
+service NovaService {
+  // Text Generation (FULLY IMPLEMENTED with Ollama)
+  rpc GenerateText(GenerateTextRequest) returns (GenerateTextResponse);
+  rpc StreamText(GenerateTextRequest) returns (stream GenerateTextStreamResponse);
+  
+  // Image Generation (NULL IMPLEMENTATION - Coming Soon)
+  rpc GenerateImage(GenerateImageRequest) returns (GenerateImageResponse);
+  
+  // Audio Generation (NULL IMPLEMENTATION - Coming Soon)
+  rpc GenerateAudio(GenerateAudioRequest) returns (GenerateAudioResponse);
+  
+  // Video Generation (NULL IMPLEMENTATION - Coming Soon)
+  rpc GenerateVideo(GenerateVideoRequest) returns (GenerateVideoResponse);
+  
+  // Administrative & Management
+  rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse);
+  rpc ListModels(ListModelsRequest) returns (ListModelsResponse);
+  rpc ListPresets(ListPresetsRequest) returns (ListPresetsResponse);
+}
+
+// ===================================================================
+// GENERATION TYPE ENUMS
+// ===================================================================
+
+enum GenerationType {
+  GENERATION_TYPE_UNSPECIFIED = 0;
+  GENERATION_TYPE_TEXT = 1;
+  GENERATION_TYPE_IMAGE = 2;
+  GENERATION_TYPE_VIDEO = 3;
+  GENERATION_TYPE_AUDIO = 4;
+}
+
+enum StreamingMode {
+  STREAMING_MODE_NONE = 0;
+  STREAMING_MODE_TOKEN = 1;        // Stream token by token
+  STREAMING_MODE_CHUNK = 2;        // Stream in chunks
+}
+
+// ===================================================================
+// MODEL SELECTION STRATEGIES
+// ===================================================================
+
+message ModelSelection {
+  oneof selection_strategy {
+    // Option 1: Use a preset ID (RECOMMENDED)
+    string preset_id = 1;
+    
+    // Option 2: Specify exact model UUID
+    string model_id = 2;
+    
+    // Option 3: Provider + Generation Type + Parameters
+    ProviderSelection provider_selection = 3;
+    
+    // Option 4: Auto-select best model for generation type
+    GenerationType auto_select = 4;
+  }
+}
+
+message ProviderSelection {
+  string provider_id = 1;    // ProviderIntegration.id
+  GenerationType type = 2;   // Text, Image, Video, Audio
+  map<string, string> parameters = 3; // Provider-specific params
+  int32 priority = 4;        // Selection priority
+}
+
+// ===================================================================
+// REQUEST/RESPONSE MESSAGES
+// ===================================================================
+
+// ----- TEXT GENERATION -----
+
+message GenerateTextRequest {
+  string prompt = 1;
+  GenerationContext context = 2;
+  ModelSelection model_selection = 3;
+  
+  // Generation parameters
+  int32 max_tokens = 4;
+  float temperature = 5;
+  float top_p = 6;
+  float top_k = 7;
+  string stop_sequences = 8;
+  bool include_context = 9;
+  
+  // Streaming
+  StreamingMode streaming_mode = 10;
+  bool enable_streaming = 11;
+  
+  // Request metadata
+  string request_id = 12;
+  string client_id = 13;
+  string character_id = 14;
+  string user_id = 15;
+  google.protobuf.Duration timeout = 16;
+  
+  // Generation options
+  bool enable_cache = 17;
+  bool enable_semantic_cache = 18;
+  bool retry_on_failure = 19;
+  int32 max_retries = 20;
+}
+
+message GenerateTextResponse {
+  GenerationResult result = 1;
+  ModelInfo used_model = 2;
+  UsageStats usage = 3;
+  google.protobuf.Duration processing_time = 4;
+  bool cached = 5;
+  bool semantic_cache_hit = 6;
+}
+
+message GenerateTextStreamResponse {
+  string token = 1;
+  int32 token_index = 2;
+  ModelInfo used_model = 3;
+  GenerationError error = 4;
+  bool completed = 5;
+  UsageStats usage = 6;
+}
+
+// ----- IMAGE GENERATION (NULL IMPLEMENTATION) -----
+
+message GenerateImageRequest {
+  string prompt = 1;
+  GenerationContext context = 2;
+  ModelSelection model_selection = 3;
+  
+  // Image parameters
+  int32 width = 4;
+  int32 height = 5;
+  string style = 6;
+  int32 num_images = 7;
+  string negative_prompt = 8;
+  
+  // Request metadata
+  string request_id = 9;
+  string client_id = 10;
+  string character_id = 11;
+  string user_id = 12;
+  google.protobuf.Duration timeout = 13;
+  
+  // Generation options
+  bool enable_cache = 14;
+  bool retry_on_failure = 15;
+}
+
+message GenerateImageResponse {
+  // NULL IMPLEMENTATION - Coming Soon
+  GenerationError error = 1; // Returns "NOT_IMPLEMENTED" with message
+  string message = 2;        // "Image generation coming soon"
+  GenerationResult result = 3;
+  ModelInfo used_model = 4;
+}
+
+// ----- AUDIO GENERATION (NULL IMPLEMENTATION) -----
+
+message GenerateAudioRequest {
+  string text = 1;
+  GenerationContext context = 2;
+  ModelSelection model_selection = 3;
+  
+  // Audio parameters
+  string voice = 4;
+  float speed = 5;
+  float pitch = 6;
+  string format = 7;
+  
+  // Request metadata
+  string request_id = 8;
+  string client_id = 9;
+  string character_id = 10;
+  string user_id = 11;
+  google.protobuf.Duration timeout = 12;
+  
+  // Generation options
+  bool enable_cache = 13;
+  bool retry_on_failure = 14;
+}
+
+message GenerateAudioResponse {
+  // NULL IMPLEMENTATION - Coming Soon
+  GenerationError error = 1; // Returns "NOT_IMPLEMENTED" with message
+  string message = 2;        // "Audio generation coming soon"
+  GenerationResult result = 3;
+  ModelInfo used_model = 4;
+}
+
+// ----- VIDEO GENERATION (NULL IMPLEMENTATION) -----
+
+message GenerateVideoRequest {
+  string prompt = 1;
+  GenerationContext context = 2;
+  ModelSelection model_selection = 3;
+  
+  // Video parameters
+  int32 duration = 4;
+  int32 width = 5;
+  int32 height = 6;
+  int32 fps = 7;
+  string style = 8;
+  
+  // Request metadata
+  string request_id = 9;
+  string client_id = 10;
+  string character_id = 11;
+  string user_id = 12;
+  google.protobuf.Duration timeout = 13;
+  
+  // Generation options
+  bool enable_cache = 14;
+  bool retry_on_failure = 15;
+}
+
+message GenerateVideoResponse {
+  // NULL IMPLEMENTATION - Coming Soon
+  GenerationError error = 1; // Returns "NOT_IMPLEMENTED" with message
+  string message = 2;        // "Video generation coming soon"
+  GenerationResult result = 3;
+  ModelInfo used_model = 4;
+}
+
+// ===================================================================
+// CONTEXT & SUPPORTING MESSAGES
+// ===================================================================
+
+message GenerationContext {
+  // Character context
+  string character_id = 1;
+  CharacterPersonality personality = 2;
+  
+  // Conversation history (for context)
+  repeated Message conversation_history = 3;
+  
+  // User preferences
+  map<string, string> user_preferences = 4;
+  
+  // Session information
+  string session_id = 5;
+  google.protobuf.Timestamp session_start = 6;
+  
+  // Custom metadata
+  map<string, string> metadata = 7;
+}
+
+message CharacterPersonality {
+  string name = 1;
+  string description = 2;
+  repeated string traits = 3;
+  string background = 4;
+  repeated string interests = 5;
+  string speaking_style = 6;
+  map<string, string> custom_fields = 7;
+}
+
+message Message {
+  string role = 1;        // "user", "assistant", "system"
+  string content = 2;
+  google.protobuf.Timestamp timestamp = 3;
+  map<string, string> metadata = 4;
+}
+
+// ===================================================================
+// RESULT & ERROR MESSAGES
+// ===================================================================
+
+message GenerationResult {
+  string result = 1;              // Main result (text, URL, etc.)
+  repeated string additional_data = 2; // Extra information
+  map<string, string> metadata = 3;     // Generation metadata
+  string content_type = 4;        // "text", "image_url", "audio_url", etc.
+  google.protobuf.Timestamp generated_at = 5;
+}
+
+message ModelInfo {
+  string model_id = 1;
+  string model_name = 2;
+  string provider_id = 3;
+  string provider_name = 4;
+  GenerationType generation_type = 5;
+  map<string, string> configuration = 6;
+  string version = 7;
+}
+
+message UsageStats {
+  int32 input_tokens = 1;
+  int32 output_tokens = 2;
+  int32 total_tokens = 3;
+  double cost_estimate = 4;
+  int32 requests_made = 5;
+  int32 cache_hits = 6;
+  int32 semantic_cache_hits = 7;
+}
+
+message GenerationError {
+  ErrorCode error_code = 1;
+  string error_message = 2;
+  string error_details = 3;
+  bool retryable = 4;
+  int32 retry_after_seconds = 5;
+  ErrorCategory category = 6;
+  
+  // Context about the error
+  string provider_id = 7;
+  string model_id = 8;
+  string request_id = 9;
+  
+  // Debug information
+  map<string, string> debug_info = 10;
+}
+
+enum ErrorCode {
+  ERROR_CODE_UNSPECIFIED = 0;
+  ERROR_CODE_SUCCESS = 1;
+  ERROR_CODE_INVALID_REQUEST = 2;
+  ERROR_CODE_AUTHENTICATION_FAILED = 3;
+  ERROR_CODE_ACCESS_DENIED = 4;
+  ERROR_CODE_MODEL_NOT_FOUND = 5;
+  ERROR_CODE_PROVIDER_UNAVAILABLE = 6;
+  ERROR_CODE_RATE_LIMIT_EXCEEDED = 7;
+  ERROR_CODE_QUOTA_EXCEEDED = 8;
+  ERROR_CODE_PROMPT_TOO_LONG = 9;
+  ERROR_CODE_PARAMETER_ERROR = 10;
+  ERROR_CODE_GENERATION_FAILED = 11;
+  ERROR_CODE_TIMEOUT = 12;
+  ERROR_CODE_INTERNAL_ERROR = 13;
+  ERROR_CODE_SERVICE_UNAVAILABLE = 14;
+  ERROR_CODE_NOT_IMPLEMENTED = 15;
+  ERROR_CODE_DATABASE_ERROR = 16;
+  ERROR_CODE_CACHE_ERROR = 17;
+  ERROR_CODE_VECTOR_DB_ERROR = 18;
+  ERROR_CODE_PROVIDER_TIMEOUT = 19;
+  ERROR_CODE_PROVIDER_RATE_LIMIT = 20;
+  ERROR_CODE_PROVIDER_AUTH_ERROR = 21;
+  ERROR_CODE_PROVIDER_QUOTA_EXCEEDED = 22;
+  ERROR_CODE_PROVIDER_INVALID_REQUEST = 23;
+  ERROR_CODE_PROVIDER_GENERATION_FAILED = 24;
+  ERROR_CODE_MAINTENANCE_MODE = 25;
+  ERROR_CODE_DEPRECATED_MODEL = 26;
+}
+
+enum ErrorCategory {
+  ERROR_CATEGORY_UNSPECIFIED = 0;
+  ERROR_CATEGORY_CLIENT = 1;           // Client error (4xx)
+  ERROR_CATEGORY_SERVER = 2;           // Server error (5xx)
+  ERROR_CATEGORY_PROVIDER = 3;         // Provider error
+  ERROR_CATEGORY_RATE_LIMIT = 4;       // Rate limiting
+  ERROR_CATEGORY_AUTHENTICATION = 5;   // Auth related
+  ERROR_CATEGORY_AUTHORIZATION = 6;    // Permission related
+  ERROR_CATEGORY_VALIDATION = 7;       // Input validation
+  ERROR_CATEGORY_QUOTA = 8;            // Quota/limit exceeded
+  ERROR_CATEGORY_NOT_FOUND = 9;        // Resource not found
+  ERROR_CATEGORY_NOT_IMPLEMENTED = 10; // Feature not implemented
+  ERROR_CATEGORY_MAINTENANCE = 11;     // Service maintenance
+  ERROR_CATEGORY_TEMPORARY = 12;       // Temporary error, retry later
+  ERROR_CATEGORY_PERMANENT = 13;       // Permanent error, no retry
+}
+
+// ===================================================================
+// ADMINISTRATIVE MESSAGES
+// ===================================================================
+
+message HealthCheckRequest {
+  bool include_details = 1;
+  bool check_providers = 2;
+  bool check_cache = 3;
+  bool check_database = 4;
+}
+
+message HealthCheckResponse {
+  ServiceStatus status = 1;
+  string message = 2;
+  google.protobuf.Timestamp timestamp = 3;
+  repeated ProviderHealth provider_health = 4;
+  SystemMetrics metrics = 5;
+}
+
+message ServiceStatus {
+  StatusCode status = 1;
+  int32 uptime_seconds = 2;
+  int32 total_requests = 3;
+  int32 active_requests = 4;
+  double cpu_usage = 5;
+  double memory_usage = 6;
+  int32 cache_hit_rate = 7;
+  int32 semantic_cache_hit_rate = 8;
+}
+
+enum StatusCode {
+  STATUS_CODE_HEALTHY = 0;
+  STATUS_CODE_DEGRADED = 1;
+  STATUS_CODE_UNHEALTHY = 2;
+  STATUS_CODE_MAINTENANCE = 3;
+  STATUS_CODE_UNKNOWN = 4;
+}
+
+message ProviderHealth {
+  string provider_id = 1;
+  string provider_name = 2;
+  bool is_healthy = 3;
+  int32 response_time_ms = 4;
+  repeated GenerationType supported_types = 5;
+  string error_message = 6;
+  google.protobuf.Timestamp last_check = 7;
+}
+
+message SystemMetrics {
+  int32 total_providers = 1;
+  int32 active_providers = 2;
+  int32 total_models = 3;
+  int32 active_models = 4;
+  int32 total_presets = 5;
+  int32 active_clients = 6;
+  int32 cache_size = 7;
+  int32 vector_cache_size = 8;
+}
+
+message ListModelsRequest {
+  GenerationType type = 1;
+  bool active_only = 2;
+  string provider_id = 3;
+  bool include_inactive = 4;
+}
+
+message ListModelsResponse {
+  repeated ModelInfo models = 1;
+  int32 total_count = 2;
+  int32 active_count = 3;
+}
+
+message ListPresetsRequest {
+  GenerationType type = 1;
+  string tier = 2;  // "free", "basic", "premium", "unlimited"
+  bool active_only = 3;
+}
+
+message ModelPreset {
+  string preset_id = 1;
+  string name = 2;
+  string description = 3;
+  string tier = 4;
+  GenerationType type = 5;
+  string model_id = 6;
+  ModelInfo model_info = 7;
+  map<string, string> parameters = 8;
+  bool is_default = 9;
+  bool is_active = 10;
+  map<string, string> features = 11;
+}
+
+message ListPresetsResponse {
+  repeated ModelPreset presets = 1;
+  int32 total_count = 2;
+  int32 active_count = 3;
+}
+