clm-kernel 0.0.0__py3-none-any.whl

clm/layer3/agency/config.py

@@ -0,0 +1,220 @@
+"""
+LLM Configuration Module
+
+Centralized configuration for LLM providers and execution parameters.
+"""
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+from clm.cross_cutting.config.config_constants import (
+    LLM_DEFAULT_RETRY_COUNT,
+    LLM_DEFAULT_RETRY_DELAY_SECS,
+    LLM_DEFAULT_TIMEOUT_SECS,
+)
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Provider Configurations
+# ─────────────────────────────────────────────────────────────────────────────
+
+LLM_PROVIDERS = {
+    "ollama": {
+        "base_url": "http://localhost:11434",
+        "api_path": "/api/generate",
+        "chat_path": "/api/chat",
+        "models_path": "/api/tags",
+        "default_model": "qwen3:0.6b",
+        "available_models": ["qwen3:0.6b", "llama3:latest", "qwen3:latest"],
+    },
+    "mlc-llm": {
+        "base_url": "http://localhost:8000",
+        "api_path": "/v1/completions",
+        "chat_path": "/v1/chat/completions",
+        "models_path": "/v1/models",
+        "default_model": "Llama-3-8B-Instruct-q4f16_1-MLC",
+        "available_models": [],
+    },
+    "lmstudio": {
+        "base_url": "http://localhost:1234",
+        "api_path": "/v1/completions",
+        "chat_path": "/v1/chat/completions",
+        "models_path": "/v1/models",
+        "default_model": "local-model",
+        "available_models": [],
+    },
+    "openai": {
+        "base_url": "https://api.openai.com",
+        "api_path": "/v1/completions",
+        "chat_path": "/v1/chat/completions",
+        "models_path": "/v1/models",
+        "default_model": "gpt-4",
+        "available_models": ["gpt-4", "gpt-4-turbo", "gpt-3.5-turbo"],
+    },
+    "anthropic": {
+        "base_url": "https://api.anthropic.com",
+        "api_path": "/v1/messages",
+        "chat_path": "/v1/messages",
+        "models_path": None,
+        "default_model": "claude-3-sonnet-20240229",
+        "available_models": ["claude-3-opus", "claude-3-sonnet", "claude-3-haiku"],
+    },
+}
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Default Configuration
+# ─────────────────────────────────────────────────────────────────────────────
+
+DEFAULT_LLM_CONFIG = {
+    "temperature": 0.7,
+    "max_tokens": 2048,
+    "top_p": 1.0,
+    "top_k": 40,
+    "timeout": LLM_DEFAULT_TIMEOUT_SECS,
+    "stream": False,
+    "response_format": "text",
+    "retry_count": LLM_DEFAULT_RETRY_COUNT,
+    "retry_delay": LLM_DEFAULT_RETRY_DELAY_SECS,
+}
+
+# Output format options
+RESPONSE_FORMATS = ("text", "json", "structured", "markdown")
+
+# Default provider
+DEFAULT_PROVIDER = "ollama"
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# LLMConfig Dataclass
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+@dataclass
+class LLMConfig:
+    """
+    Configuration for LLM execution.
+
+    Supports multiple providers (Ollama, LMStudio, OpenAI, Anthropic) with
+    unified configuration interface.
+    """
+
+    # Provider settings
+    provider: str = DEFAULT_PROVIDER
+    model: str | None = None  # Uses provider default if None
+    endpoint_url: str | None = None  # Override provider base_url
+    api_key: str | None = None  # For authenticated providers
+
+    # Prompt structure
+    system_prompt: str = ""
+    assistant_instruction: str = ""
+
+    # Generation parameters
+    temperature: float = DEFAULT_LLM_CONFIG["temperature"]
+    max_tokens: int = DEFAULT_LLM_CONFIG["max_tokens"]
+    top_p: float = DEFAULT_LLM_CONFIG["top_p"]
+    top_k: int | None = DEFAULT_LLM_CONFIG["top_k"]
+    frequency_penalty: float = 0.0
+    presence_penalty: float = 0.0
+    stop_sequences: list[str] = field(default_factory=list)
+
+    # Response handling
+    response_format: str = DEFAULT_LLM_CONFIG["response_format"]
+    json_schema: dict | None = None  # For structured output
+
+    # Execution settings
+    timeout: int = DEFAULT_LLM_CONFIG["timeout"]
+    retry_count: int = DEFAULT_LLM_CONFIG["retry_count"]
+    retry_delay: float = DEFAULT_LLM_CONFIG["retry_delay"]
+    stream: bool = DEFAULT_LLM_CONFIG["stream"]
+
+    def __post_init__(self):
+        """Validate configuration after initialization."""
+        if self.provider not in LLM_PROVIDERS:
+            raise ValueError(
+                f"Unknown provider: {self.provider}. "
+                f"Available: {list(LLM_PROVIDERS.keys())}"
+            )
+
+        if self.response_format not in RESPONSE_FORMATS:
+            raise ValueError(
+                f"Unknown response format: {self.response_format}. "
+                f"Available: {RESPONSE_FORMATS}"
+            )
+
+    @property
+    def effective_model(self) -> str:
+        """Get the model to use, falling back to provider default."""
+        if self.model:
+            return self.model
+        return LLM_PROVIDERS[self.provider]["default_model"]
+
+    @property
+    def effective_base_url(self) -> str:
+        """Get the base URL, with optional override."""
+        if self.endpoint_url:
+            return self.endpoint_url.rstrip("/")
+        return LLM_PROVIDERS[self.provider]["base_url"]
+
+    def to_provider_params(self) -> dict[str, Any]:
+        """Convert to provider-specific generation parameters."""
+        params = {
+            "model": self.effective_model,
+            "temperature": self.temperature,
+        }
+
+        # Provider-specific parameter names
+        if self.provider == "ollama":
+            params["options"] = {
+                "num_predict": self.max_tokens,
+                "top_p": self.top_p,
+                "top_k": self.top_k,
+                "temperature": self.temperature,
+            }
+            if self.stop_sequences:
+                params["options"]["stop"] = self.stop_sequences
+        else:
+            # OpenAI-compatible format
+            params["max_tokens"] = self.max_tokens
+            params["top_p"] = self.top_p
+            if self.stop_sequences:
+                params["stop"] = self.stop_sequences
+            if self.frequency_penalty:
+                params["frequency_penalty"] = self.frequency_penalty
+            if self.presence_penalty:
+                params["presence_penalty"] = self.presence_penalty
+
+        return params
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "LLMConfig":
+        """Create from dictionary."""
+        return cls(**{k: v for k, v in data.items() if k in cls.__dataclass_fields__})
+
+    @classmethod
+    def from_concrete(
+        cls, concrete: dict[str, Any], context: dict[str, Any] = None
+    ) -> "LLMConfig":
+        """
+        Create LLMConfig from concrete implementation and context.
+
+        Merges llm_config from concrete with context overrides.
+        """
+        context = context or {}
+
+        # Start with defaults from concrete's llm_config
+        config_data = concrete.get("llm_config", {}).copy()
+
+        # Override with top-level concrete fields
+        for key in ["provider", "model", "system_prompt", "temperature", "max_tokens"]:
+            if key in concrete:
+                config_data[key] = concrete[key]
+
+        # Override with context
+        for key in cls.__dataclass_fields__:
+            if key in context:
+                config_data[key] = context[key]
+
+        return cls.from_dict(config_data)

clm/layer3/agency/providers/__init__.py

@@ -0,0 +1,15 @@
+"""
+LLM Providers Package
+
+Provider implementations for different LLM services.
+"""
+
+from .base import LLMProvider
+from .mlc_llm import MLCLLMProvider
+from .ollama import OllamaProvider
+
+__all__ = [
+    "LLMProvider",
+    "OllamaProvider",
+    "MLCLLMProvider",
+]

clm/layer3/agency/providers/base.py

@@ -0,0 +1,91 @@
+"""
+LLM Provider Base Class
+
+Abstract base class defining the interface for LLM providers.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from clm.layer0.narrative import Either, Left
+
+
+class LLMProvider(ABC):
+    """
+    Abstract base class for LLM providers.
+
+    Implementations should handle:
+    - Connection to the LLM service
+    - Request formatting for the specific API
+    - Response parsing
+    - Error handling
+    """
+
+    provider_name: str = "base"
+
+    @abstractmethod
+    def complete(self, prompt: str, params: dict[str, Any]) -> Either[str, str]:
+        """
+        Generate text completion for a prompt.
+
+        Args:
+            prompt: The input prompt
+            params: Provider-specific generation parameters
+
+        Returns:
+            Either[Error, Response]: Left(error) or Right(completion)
+        """
+        pass
+
+    @abstractmethod
+    def chat(
+        self, messages: list[dict[str, str]], params: dict[str, Any]
+    ) -> Either[str, dict[str, Any]]:
+        """
+        Generate chat completion from messages.
+
+        Args:
+            messages: List of message dicts with 'role' and 'content'
+            params: Provider-specific generation parameters
+
+        Returns:
+            Either[Error, Response]: Left(error) or Right(response dict)
+        """
+        pass
+
+    @abstractmethod
+    def validate_connection(self) -> bool:
+        """
+        Check if the provider service is available.
+
+        Returns:
+            True if connection is valid, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    def list_models(self) -> Either[str, list[str]]:
+        """
+        List available models from the provider.
+
+        Returns:
+            Either[Error, ModelList]: Left(error) or Right(list of model names)
+        """
+        pass
+
+    def get_status(self) -> dict[str, Any]:
+        """
+        Get provider status information.
+
+        Returns:
+            Dictionary with provider status details
+        """
+        available = self.validate_connection()
+        models_result = self.list_models() if available else Left("Not connected")
+
+        return {
+            "provider": self.provider_name,
+            "available": available,
+            "models": models_result.value if models_result.is_right() else [],
+            "error": models_result.value if models_result.is_left() else None,
+        }

clm/layer3/agency/providers/mlc_llm.py

@@ -0,0 +1,169 @@
+"""
+MLC LLM Provider Implementation
+
+Provider for the MLC LLM REST API (OpenAI compatible).
+Running via `mlc_llm serve`.
+"""
+
+import json
+import logging
+import urllib.error
+import urllib.request
+from typing import Any
+
+from clm.cross_cutting.config.config_constants import LLM_DEFAULT_TIMEOUT_SECS
+from clm.cross_cutting.utils.url_safety import safe_urlopen
+from clm.layer0.narrative import Either, Left, Right
+
+from ..config import LLM_PROVIDERS
+from .base import LLMProvider
+
+
+class MLCLLMProvider(LLMProvider):
+    """
+    MLC LLM provider for local execution via OpenAI-compatible API.
+
+    Compatible with:
+    - /v1/completions
+    - /v1/chat/completions
+    - /v1/models
+    """
+
+    provider_name = "mlc-llm"
+
+    def __init__(self, base_url: str = None, timeout: int = LLM_DEFAULT_TIMEOUT_SECS):
+        self.logger = logging.getLogger(__name__)
+        self.config = LLM_PROVIDERS["mlc-llm"]
+        self.base_url = (base_url or self.config["base_url"]).rstrip("/")
+        self.timeout = timeout
+
+    def _make_request(
+        self, endpoint: str, data: dict = None, method: str = "POST"
+    ) -> Either[str, dict]:
+        """Make HTTP request to MLC LLM API."""
+        url = f"{self.base_url}{endpoint}"
+
+        try:
+            if data:
+                request = urllib.request.Request(
+                    url,
+                    data=json.dumps(data).encode("utf-8"),
+                    headers={"Content-Type": "application/json"},
+                    method=method,
+                )
+            else:
+                request = urllib.request.Request(url, method=method)
+
+            with safe_urlopen(request, timeout=self.timeout) as response:
+                response_text = response.read().decode("utf-8")
+                return Right(json.loads(response_text))
+
+        except urllib.error.HTTPError as e:
+            error_body = e.read().decode("utf-8") if e.fp else str(e)
+            return Left(f"MLC-LLM HTTP error {e.code}: {error_body}")
+        except urllib.error.URLError as e:
+            return Left(f"MLC-LLM connection error: {e.reason}")
+        except json.JSONDecodeError as e:
+            return Left(f"MLC-LLM response parse error: {e}")
+        except (OSError, ConnectionError, ValueError) as e:
+            return Left(f"MLC-LLM request failed: {e}")
+
+    def complete(self, prompt: str, params: dict[str, Any]) -> Either[str, str]:
+        """
+        Generate text completion.
+        Using /v1/completions style.
+        """
+        data = {
+            "model": params.get("model", self.config["default_model"]),
+            "prompt": prompt,
+            "max_tokens": params.get("max_tokens", 128),
+            "temperature": params.get("temperature", 0.7),
+            "top_p": params.get("top_p", 1.0),
+            "stream": False,
+        }
+
+        if "stop" in params:
+            data["stop"] = params["stop"]
+
+        self.logger.debug(f"MLC-LLM complete request: model={data['model']}")
+
+        result = self._make_request(self.config["api_path"], data)
+
+        if result.is_left():
+            return result
+
+        response = result.value
+        # OpenAI format: {'choices': [{'text': '...'}]}
+        if "choices" in response and len(response["choices"]) > 0:
+            return Right(response["choices"][0].get("text", ""))
+        elif "error" in response:
+            return Left(f"MLC-LLM error: {response['error']}")
+        else:
+            return Left(f"Unexpected MLC-LLM response format: {response}")
+
+    def chat(
+        self, messages: list[dict[str, str]], params: dict[str, Any]
+    ) -> Either[str, dict[str, Any]]:
+        """
+        Generate chat completion.
+        Using /v1/chat/completions style.
+        """
+        data = {
+            "model": params.get("model", self.config["default_model"]),
+            "messages": messages,
+            "max_tokens": params.get("max_tokens", 128),
+            "temperature": params.get("temperature", 0.7),
+            "top_p": params.get("top_p", 1.0),
+            "stream": False,
+        }
+
+        if "stop" in params:
+            data["stop"] = params["stop"]
+
+        self.logger.debug(f"MLC-LLM chat request: model={data['model']}")
+
+        result = self._make_request(self.config["chat_path"], data)
+
+        if result.is_left():
+            return result
+
+        response = result.value
+        # OpenAI format: {'choices': [{'message': {'role': 'assistant', 'content': '...'}}]}
+        if "choices" in response and len(response["choices"]) > 0:
+            choice = response["choices"][0]
+            message = choice.get("message", {})
+            return Right(
+                {
+                    "content": message.get("content", ""),
+                    "role": message.get("role", "assistant"),
+                    "model": response.get("model", data["model"]),
+                    "usage": response.get("usage", {}),
+                }
+            )
+        elif "error" in response:
+            return Left(f"MLC-LLM error: {response['error']}")
+        else:
+            return Left(f"Unexpected MLC-LLM response format: {response}")
+
+    def validate_connection(self) -> bool:
+        """Check if MLC-LLM service is running via models endpoint."""
+        try:
+            result = self._make_request(self.config["models_path"], method="GET")
+            return result.is_right()
+        except (OSError, ConnectionError):
+            return False
+
+    def list_models(self) -> Either[str, list[str]]:
+        """List available api models."""
+        result = self._make_request(self.config["models_path"], method="GET")
+
+        if result.is_left():
+            return result
+
+        response = result.value
+        # OpenAI format: {'data': [{'id': 'model-id', ...}]}
+        if "data" in response and isinstance(response["data"], list):
+            models = [m.get("id", "unknown") for m in response["data"]]
+            return Right(models)
+        else:
+            return Left(f"Unexpected models response: {response}")