claude-code-workflow 6.2.7 → 6.3.0

package/ccw/src/types/litellm-api-config.ts

@@ -0,0 +1,402 @@
+/**
+ * LiteLLM API Configuration Type Definitions
+ *
+ * Defines types for provider credentials, cache strategies, custom endpoints,
+ * and the overall configuration structure for LiteLLM API integration.
+ */
+
+/**
+ * API format types (simplified)
+ * Most providers use OpenAI-compatible format
+ */
+export type ProviderType =
+  | 'openai'      // OpenAI-compatible format (most providers)
+  | 'anthropic'   // Anthropic format
+  | 'custom';     // Custom format
+
+/**
+ * Advanced provider settings for LiteLLM compatibility
+ * Maps to LiteLLM's provider configuration options
+ */
+export interface ProviderAdvancedSettings {
+  /** Request timeout in seconds (default: 300) */
+  timeout?: number;
+
+  /** Maximum retry attempts on failure (default: 3) */
+  maxRetries?: number;
+
+  /** Organization ID (OpenAI-specific) */
+  organization?: string;
+
+  /** API version string (Azure-specific, e.g., "2024-02-01") */
+  apiVersion?: string;
+
+  /** Custom HTTP headers as JSON object */
+  customHeaders?: Record<string, string>;
+
+  /** Requests per minute rate limit */
+  rpm?: number;
+
+  /** Tokens per minute rate limit */
+  tpm?: number;
+
+  /** Proxy server URL (e.g., "http://proxy.example.com:8080") */
+  proxy?: string;
+}
+
+/**
+ * Model type classification
+ */
+export type ModelType = 'llm' | 'embedding';
+
+/**
+ * Model capability metadata
+ */
+export interface ModelCapabilities {
+  /** Whether the model supports streaming responses */
+  streaming?: boolean;
+
+  /** Whether the model supports function/tool calling */
+  functionCalling?: boolean;
+
+  /** Whether the model supports vision/image input */
+  vision?: boolean;
+
+  /** Context window size in tokens */
+  contextWindow?: number;
+
+  /** Embedding dimension (for embedding models only) */
+  embeddingDimension?: number;
+
+  /** Maximum output tokens */
+  maxOutputTokens?: number;
+}
+
+/**
+ * Routing strategy for load balancing across multiple keys
+ */
+export type RoutingStrategy = 
+  | 'simple-shuffle'    // Random selection (default, recommended)
+  | 'weighted'          // Weight-based distribution
+  | 'latency-based'     // Route to lowest latency
+  | 'cost-based'        // Route to lowest cost
+  | 'least-busy';       // Route to least concurrent
+
+/**
+ * Individual API key configuration with optional weight
+ */
+export interface ApiKeyEntry {
+  /** Unique identifier */
+  id: string;
+
+  /** API key value or env var reference */
+  key: string;
+
+  /** Display label for this key */
+  label?: string;
+
+  /** Weight for weighted routing (default: 1) */
+  weight?: number;
+
+  /** Whether this key is enabled */
+  enabled: boolean;
+
+  /** Last health check status */
+  healthStatus?: 'healthy' | 'unhealthy' | 'unknown';
+
+  /** Last health check timestamp */
+  lastHealthCheck?: string;
+
+  /** Error message if unhealthy */
+  lastError?: string;
+}
+
+/**
+ * Health check configuration
+ */
+export interface HealthCheckConfig {
+  /** Enable automatic health checks */
+  enabled: boolean;
+
+  /** Check interval in seconds (default: 300) */
+  intervalSeconds: number;
+
+  /** Cooldown period after failure in seconds (default: 5) */
+  cooldownSeconds: number;
+
+  /** Number of failures before marking unhealthy (default: 3) */
+  failureThreshold: number;
+}
+
+
+/**
+ * Model-specific endpoint settings
+ * Allows per-model configuration overrides
+ */
+export interface ModelEndpointSettings {
+  /** Override base URL for this model */
+  baseUrl?: string;
+
+  /** Override timeout for this model */
+  timeout?: number;
+
+  /** Override max retries for this model */
+  maxRetries?: number;
+
+  /** Custom headers for this model */
+  customHeaders?: Record<string, string>;
+
+  /** Cache strategy for this model */
+  cacheStrategy?: CacheStrategy;
+}
+
+/**
+ * Model definition with type and grouping
+ */
+export interface ModelDefinition {
+  /** Unique identifier for this model */
+  id: string;
+
+  /** Display name for UI */
+  name: string;
+
+  /** Model type: LLM or Embedding */
+  type: ModelType;
+
+  /** Model series for grouping (e.g., "GPT-4", "Claude-3") */
+  series: string;
+
+  /** Whether this model is enabled */
+  enabled: boolean;
+
+  /** Model capabilities */
+  capabilities?: ModelCapabilities;
+
+  /** Model-specific endpoint settings */
+  endpointSettings?: ModelEndpointSettings;
+
+  /** Optional description */
+  description?: string;
+
+  /** Creation timestamp (ISO 8601) */
+  createdAt: string;
+
+  /** Last update timestamp (ISO 8601) */
+  updatedAt: string;
+}
+
+/**
+ * Provider credential configuration
+ * Stores API keys, base URLs, and provider metadata
+ */
+export interface ProviderCredential {
+  /** Unique identifier for this provider configuration */
+  id: string;
+
+  /** Display name for UI */
+  name: string;
+
+  /** Provider type */
+  type: ProviderType;
+
+  /** API key or environment variable reference (e.g., ${OPENAI_API_KEY}) */
+  apiKey: string;
+
+  /** Custom API base URL (optional, overrides provider default) */
+  apiBase?: string;
+
+  /** Whether this provider is enabled */
+  enabled: boolean;
+
+  /** Advanced provider settings (optional) */
+  advancedSettings?: ProviderAdvancedSettings;
+
+  /** Multiple API keys for load balancing */
+  apiKeys?: ApiKeyEntry[];
+
+  /** Routing strategy for multi-key load balancing */
+  routingStrategy?: RoutingStrategy;
+
+  /** Health check configuration */
+  healthCheck?: HealthCheckConfig;
+
+  /** LLM models configured for this provider */
+  llmModels?: ModelDefinition[];
+
+  /** Embedding models configured for this provider */
+  embeddingModels?: ModelDefinition[];
+
+  /** Creation timestamp (ISO 8601) */
+  createdAt: string;
+
+  /** Last update timestamp (ISO 8601) */
+  updatedAt: string;
+}
+
+/**
+ * Cache strategy for prompt context optimization
+ * Enables file-based caching to reduce token usage
+ */
+export interface CacheStrategy {
+  /** Whether caching is enabled for this endpoint */
+  enabled: boolean;
+
+  /** Time-to-live in minutes (default: 60) */
+  ttlMinutes: number;
+
+  /** Maximum cache size in KB (default: 512) */
+  maxSizeKB: number;
+
+  /** File patterns to cache (glob patterns like "*.md", "*.ts") */
+  filePatterns: string[];
+}
+
+/**
+ * Custom endpoint configuration
+ * Maps CLI identifiers to specific models and caching strategies
+ */
+export interface CustomEndpoint {
+  /** Unique CLI identifier (used in --model flag, e.g., "my-gpt4o") */
+  id: string;
+
+  /** Display name for UI */
+  name: string;
+
+  /** Reference to provider credential ID */
+  providerId: string;
+
+  /** Model identifier (e.g., "gpt-4o", "claude-3-5-sonnet-20241022") */
+  model: string;
+
+  /** Optional description */
+  description?: string;
+
+  /** Cache strategy for this endpoint */
+  cacheStrategy: CacheStrategy;
+
+  /** Whether this endpoint is enabled */
+  enabled: boolean;
+
+  /** Creation timestamp (ISO 8601) */
+  createdAt: string;
+
+  /** Last update timestamp (ISO 8601) */
+  updatedAt: string;
+}
+
+/**
+ * Global cache settings
+ * Applies to all endpoints unless overridden
+ */
+export interface GlobalCacheSettings {
+  /** Whether caching is globally enabled */
+  enabled: boolean;
+
+  /** Cache directory path (default: ~/.ccw/cache/context) */
+  cacheDir: string;
+
+  /** Maximum total cache size in MB (default: 100) */
+  maxTotalSizeMB: number;
+}
+
+/**
+ * CodexLens embedding provider selection for rotation
+ * Aggregates provider + model + all API keys
+ */
+export interface CodexLensEmbeddingProvider {
+  /** Reference to provider credential ID */
+  providerId: string;
+
+  /** Embedding model ID from the provider */
+  modelId: string;
+
+  /** Whether to use all API keys from this provider (default: true) */
+  useAllKeys: boolean;
+
+  /** Specific API key IDs to use (if useAllKeys is false) */
+  selectedKeyIds?: string[];
+
+  /** Weight for weighted routing (default: 1.0, applies to all keys from this provider) */
+  weight: number;
+
+  /** Maximum concurrent requests per key (default: 4) */
+  maxConcurrentPerKey: number;
+
+  /** Whether this provider is enabled for rotation */
+  enabled: boolean;
+}
+
+/**
+ * CodexLens multi-provider embedding rotation configuration
+ * Aggregates multiple providers with same model for parallel rotation
+ */
+export interface CodexLensEmbeddingRotation {
+  /** Whether multi-provider rotation is enabled */
+  enabled: boolean;
+
+  /** Selection strategy: round_robin, latency_aware, weighted_random */
+  strategy: 'round_robin' | 'latency_aware' | 'weighted_random';
+
+  /** Default cooldown seconds for rate-limited endpoints (default: 60) */
+  defaultCooldown: number;
+
+  /** Target model name that all providers should support (e.g., "qwen3-embedding") */
+  targetModel: string;
+
+  /** List of providers to aggregate for rotation */
+  providers: CodexLensEmbeddingProvider[];
+}
+
+/**
+ * Generic embedding pool configuration (refactored from CodexLensEmbeddingRotation)
+ * Supports automatic discovery of all providers offering a specific model
+ */
+export interface EmbeddingPoolConfig {
+  /** Whether embedding pool is enabled */
+  enabled: boolean;
+
+  /** Target embedding model name (e.g., "text-embedding-3-small") */
+  targetModel: string;
+
+  /** Selection strategy: round_robin, latency_aware, weighted_random */
+  strategy: 'round_robin' | 'latency_aware' | 'weighted_random';
+
+  /** Whether to automatically discover all providers offering targetModel */
+  autoDiscover: boolean;
+
+  /** Provider IDs to exclude from auto-discovery (optional) */
+  excludedProviderIds?: string[];
+
+  /** Default cooldown seconds for rate-limited endpoints (default: 60) */
+  defaultCooldown: number;
+
+  /** Default maximum concurrent requests per key (default: 4) */
+  defaultMaxConcurrentPerKey: number;
+}
+
+/**
+ * Complete LiteLLM API configuration
+ * Root configuration object stored in JSON file
+ */
+export interface LiteLLMApiConfig {
+  /** Configuration schema version */
+  version: number;
+
+  /** List of configured providers */
+  providers: ProviderCredential[];
+
+  /** List of custom endpoints */
+  endpoints: CustomEndpoint[];
+
+  /** Default endpoint ID (optional) */
+  defaultEndpoint?: string;
+
+  /** Global cache settings */
+  globalCacheSettings: GlobalCacheSettings;
+
+  /** CodexLens multi-provider embedding rotation config (deprecated, use embeddingPoolConfig) */
+  codexlensEmbeddingRotation?: CodexLensEmbeddingRotation;
+
+  /** Generic embedding pool configuration with auto-discovery support */
+  embeddingPoolConfig?: EmbeddingPoolConfig;
+}

package/ccw-litellm/README.md

@@ -0,0 +1,180 @@
+# ccw-litellm
+
+Unified LiteLLM interface layer shared by ccw and codex-lens projects.
+
+## Features
+
+- **Unified LLM Interface**: Abstract interface for LLM operations (chat, completion)
+- **Unified Embedding Interface**: Abstract interface for text embeddings
+- **Multi-Provider Support**: OpenAI, Anthropic, Azure, and more via LiteLLM
+- **Configuration Management**: YAML-based configuration with environment variable substitution
+- **Type Safety**: Full type annotations with Pydantic models
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+### Configuration
+
+Create a configuration file at `~/.ccw/config/litellm-config.yaml`:
+
+```yaml
+version: 1
+default_provider: openai
+
+providers:
+  openai:
+    api_key: ${OPENAI_API_KEY}
+    api_base: https://api.openai.com/v1
+
+llm_models:
+  default:
+    provider: openai
+    model: gpt-4
+
+embedding_models:
+  default:
+    provider: openai
+    model: text-embedding-3-small
+    dimensions: 1536
+```
+
+### Usage
+
+#### LLM Client
+
+```python
+from ccw_litellm import LiteLLMClient, ChatMessage
+
+# Initialize client with default model
+client = LiteLLMClient(model="default")
+
+# Chat completion
+messages = [
+    ChatMessage(role="user", content="Hello, how are you?")
+]
+response = client.chat(messages)
+print(response.content)
+
+# Text completion
+response = client.complete("Once upon a time")
+print(response.content)
+```
+
+#### Embedder
+
+```python
+from ccw_litellm import LiteLLMEmbedder
+
+# Initialize embedder with default model
+embedder = LiteLLMEmbedder(model="default")
+
+# Embed single text
+vector = embedder.embed("Hello world")
+print(vector.shape)  # (1, 1536)
+
+# Embed multiple texts
+vectors = embedder.embed(["Text 1", "Text 2", "Text 3"])
+print(vectors.shape)  # (3, 1536)
+```
+
+#### Custom Configuration
+
+```python
+from ccw_litellm import LiteLLMClient, load_config
+
+# Load custom configuration
+config = load_config("/path/to/custom-config.yaml")
+
+# Use custom configuration
+client = LiteLLMClient(model="fast", config=config)
+```
+
+## Configuration Reference
+
+### Provider Configuration
+
+```yaml
+providers:
+  <provider_name>:
+    api_key: <api_key_or_${ENV_VAR}>
+    api_base: <base_url>
+```
+
+Supported providers: `openai`, `anthropic`, `azure`, `vertex_ai`, `bedrock`, etc.
+
+### LLM Model Configuration
+
+```yaml
+llm_models:
+  <model_name>:
+    provider: <provider_name>
+    model: <model_identifier>
+```
+
+### Embedding Model Configuration
+
+```yaml
+embedding_models:
+  <model_name>:
+    provider: <provider_name>
+    model: <model_identifier>
+    dimensions: <embedding_dimensions>
+```
+
+## Environment Variables
+
+The configuration supports environment variable substitution using the `${VAR}` or `${VAR:-default}` syntax:
+
+```yaml
+providers:
+  openai:
+    api_key: ${OPENAI_API_KEY}              # Required
+    api_base: ${OPENAI_API_BASE:-https://api.openai.com/v1}  # With default
+```
+
+## API Reference
+
+### Interfaces
+
+- `AbstractLLMClient`: Abstract base class for LLM clients
+- `AbstractEmbedder`: Abstract base class for embedders
+- `ChatMessage`: Message data class (role, content)
+- `LLMResponse`: Response data class (content, raw)
+
+### Implementations
+
+- `LiteLLMClient`: LiteLLM implementation of AbstractLLMClient
+- `LiteLLMEmbedder`: LiteLLM implementation of AbstractEmbedder
+
+### Configuration
+
+- `LiteLLMConfig`: Root configuration model
+- `ProviderConfig`: Provider configuration model
+- `LLMModelConfig`: LLM model configuration model
+- `EmbeddingModelConfig`: Embedding model configuration model
+- `load_config(path)`: Load configuration from YAML file
+- `get_config(path, reload)`: Get global configuration singleton
+- `reset_config()`: Reset global configuration (for testing)
+
+## Development
+
+### Running Tests
+
+```bash
+pytest tests/ -v
+```
+
+### Type Checking
+
+```bash
+mypy src/ccw_litellm
+```
+
+## License
+
+MIT

package/ccw-litellm/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ccw-litellm"
+version = "0.1.0"
+description = "Unified LiteLLM interface layer shared by ccw and codex-lens"
+requires-python = ">=3.10"
+authors = [{ name = "ccw-litellm contributors" }]
+dependencies = [
+  "litellm>=1.0.0",
+  "pyyaml",
+  "numpy",
+  "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0",
+]
+
+[project.scripts]
+ccw-litellm = "ccw_litellm.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["ccw_litellm*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

package/ccw-litellm/src/ccw_litellm/__init__.py

@@ -0,0 +1,47 @@
+"""ccw-litellm package.
+
+This package provides a small, stable interface layer around LiteLLM to share
+between the ccw and codex-lens projects.
+"""
+
+from __future__ import annotations
+
+from .clients import LiteLLMClient, LiteLLMEmbedder
+from .config import (
+    EmbeddingModelConfig,
+    LiteLLMConfig,
+    LLMModelConfig,
+    ProviderConfig,
+    get_config,
+    load_config,
+    reset_config,
+)
+from .interfaces import (
+    AbstractEmbedder,
+    AbstractLLMClient,
+    ChatMessage,
+    LLMResponse,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # Abstract interfaces
+    "AbstractEmbedder",
+    "AbstractLLMClient",
+    "ChatMessage",
+    "LLMResponse",
+    # Client implementations
+    "LiteLLMClient",
+    "LiteLLMEmbedder",
+    # Configuration
+    "LiteLLMConfig",
+    "ProviderConfig",
+    "LLMModelConfig",
+    "EmbeddingModelConfig",
+    "load_config",
+    "get_config",
+    "reset_config",
+]
+