lighthouse-llm-registry 0.1.0__tar.gz

lighthouse_llm_registry-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+*.pyc
+.env
+dist/

lighthouse_llm_registry-0.1.0/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "python-envs.defaultEnvManager": "ms-python.python:system"
+}

lighthouse_llm_registry-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rohit Jagtap
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lighthouse_llm_registry-0.1.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: lighthouse-llm-registry
+Version: 0.1.0
+Summary: A global reusable LLM Registry wrapper for LangChain models with unified error mapping for Lighthouse Agents Factory
+Author-email: Rohit Jagtap <rohit.jagtap@lighthouseindia.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,anthropic,gemini,groq,langchain,llm,openai,registry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: all
+Requires-Dist: langchain-anthropic; extra == 'all'
+Requires-Dist: langchain-google-genai; extra == 'all'
+Requires-Dist: langchain-groq; extra == 'all'
+Requires-Dist: langchain-openai; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: langchain-anthropic; extra == 'anthropic'
+Provides-Extra: google
+Requires-Dist: langchain-google-genai; extra == 'google'
+Provides-Extra: groq
+Requires-Dist: langchain-groq; extra == 'groq'
+Provides-Extra: openai
+Requires-Dist: langchain-openai; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# LLM Registry
+
+A global, reusable LLM Registry wrapper for LangChain chat models. It enables unified model configuration management, lazy loading, and dynamic resolution of model providers (OpenAI, Groq, Anthropic, and Google Gemini).
+
+---
+
+## Installation & Setup
+
+> [!NOTE]
+> The distribution package name is **`lighthouse-llm-registry`** (hyphen), and the Python import package name is **`llm_registry`** (underscore).
+
+### 1. Installation
+
+Install the core package:
+
+```bash
+pip install lighthouse-llm-registry
+```
+
+To install specific provider SDK dependencies:
+
+```bash
+# OpenAI support
+pip install "lighthouse-llm-registry[openai]"
+
+# Groq support
+pip install "lighthouse-llm-registry[groq]"
+
+# Anthropic support
+pip install "lighthouse-llm-registry[anthropic]"
+
+# Google Gemini support
+pip install "lighthouse-llm-registry[google]"
+
+# Install all supported providers
+pip install "lighthouse-llm-registry[all]"
+```
+
+If installing from local source distribution:
+
+```bash
+pip install ".[all]"
+```
+
+### 2. API Keys Configuration
+
+Create a `.env` file in the root of your target project:
+
+```env
+OPENAI_API_KEY=your-openai-key
+GROQ_API_KEY=your-groq-key
+ANTHROPIC_API_KEY=your-anthropic-key
+GOOGLE_API_KEY=your-gemini-key
+LOCAL_MODEL_LINK=http://192.168.101.88:11434/api/chat
+LOCAL_MODEL=llama3.1:8b
+```
+
+---
+
+## Usage Guide
+
+### 1. Registration (Application Startup)
+
+Register your model configurations once at application startup (e.g., in your app's main entry point):
+
+```python
+# main.py
+from dotenv import load_dotenv
+from llm_registry import global_registry, ModelConfig
+
+# Load environment keys from .env
+load_dotenv()
+
+# Register OpenAI config (defaults to standard temperature/max_tokens rules)
+global_registry.register_model_config(
+    "primary-chat",
+    ModelConfig(
+        provider="openai",
+        model_name="gpt-4o-mini",
+        temperature=0.7
+    )
+)
+
+# Register Groq config
+global_registry.register_model_config(
+    "fast-chat",
+    ModelConfig(
+        provider="groq",
+        model_name="llama-3.1-8b-instant",
+        temperature=0.2
+    )
+)
+
+# Register Anthropic config (supports models like claude-opus-4-8)
+global_registry.register_model_config(
+    "legacy-chat",
+    ModelConfig(
+        provider="anthropic",
+        model_name="claude-opus-4-8"
+    )
+)
+
+# Register Local Ollama config (falls back to LOCAL_MODEL_LINK and LOCAL_MODEL if parameters are omitted)
+global_registry.register_model_config(
+    "local-chat",
+    ModelConfig(
+        provider="local",
+        model_name=""
+    )
+)
+```
+
+### 2. Resolution (Anywhere in your code)
+
+Resolve and query the model anywhere inside your application without importing specific provider SDKs:
+
+```python
+# agents/agent.py
+from llm_registry import global_registry
+
+class SimpleAgent:
+    def __init__(self):
+        # Dynamically resolve model from the global registry
+        self.model = global_registry.get_model("fast-chat")
+      
+    def respond(self, query: str) -> str:
+        # Standard LangChain invoke call
+        response = self.model.invoke(query)
+        return response.content
+
+# Example for Local Ollama Model:
+local_model = global_registry.get_model("local-chat")
+local_response = local_model.invoke([
+    {"role": "user", "content": "How are you today?"}
+])
+print(local_response)  # Returns direct text output
+```
+
+---
+
+## Running Playground tests
+
+An interactive chat test script is included under `tests/chat_test.py` to check your connections. Run it directly:
+
+```bash
+python tests/chat_test.py
+```

lighthouse_llm_registry-0.1.0/README.md

@@ -0,0 +1,147 @@
+# LLM Registry
+
+A global, reusable LLM Registry wrapper for LangChain chat models. It enables unified model configuration management, lazy loading, and dynamic resolution of model providers (OpenAI, Groq, Anthropic, and Google Gemini).
+
+---
+
+## Installation & Setup
+
+> [!NOTE]
+> The distribution package name is **`lighthouse-llm-registry`** (hyphen), and the Python import package name is **`llm_registry`** (underscore).
+
+### 1. Installation
+
+Install the core package:
+
+```bash
+pip install lighthouse-llm-registry
+```
+
+To install specific provider SDK dependencies:
+
+```bash
+# OpenAI support
+pip install "lighthouse-llm-registry[openai]"
+
+# Groq support
+pip install "lighthouse-llm-registry[groq]"
+
+# Anthropic support
+pip install "lighthouse-llm-registry[anthropic]"
+
+# Google Gemini support
+pip install "lighthouse-llm-registry[google]"
+
+# Install all supported providers
+pip install "lighthouse-llm-registry[all]"
+```
+
+If installing from local source distribution:
+
+```bash
+pip install ".[all]"
+```
+
+### 2. API Keys Configuration
+
+Create a `.env` file in the root of your target project:
+
+```env
+OPENAI_API_KEY=your-openai-key
+GROQ_API_KEY=your-groq-key
+ANTHROPIC_API_KEY=your-anthropic-key
+GOOGLE_API_KEY=your-gemini-key
+LOCAL_MODEL_LINK=http://192.168.101.88:11434/api/chat
+LOCAL_MODEL=llama3.1:8b
+```
+
+---
+
+## Usage Guide
+
+### 1. Registration (Application Startup)
+
+Register your model configurations once at application startup (e.g., in your app's main entry point):
+
+```python
+# main.py
+from dotenv import load_dotenv
+from llm_registry import global_registry, ModelConfig
+
+# Load environment keys from .env
+load_dotenv()
+
+# Register OpenAI config (defaults to standard temperature/max_tokens rules)
+global_registry.register_model_config(
+    "primary-chat",
+    ModelConfig(
+        provider="openai",
+        model_name="gpt-4o-mini",
+        temperature=0.7
+    )
+)
+
+# Register Groq config
+global_registry.register_model_config(
+    "fast-chat",
+    ModelConfig(
+        provider="groq",
+        model_name="llama-3.1-8b-instant",
+        temperature=0.2
+    )
+)
+
+# Register Anthropic config (supports models like claude-opus-4-8)
+global_registry.register_model_config(
+    "legacy-chat",
+    ModelConfig(
+        provider="anthropic",
+        model_name="claude-opus-4-8"
+    )
+)
+
+# Register Local Ollama config (falls back to LOCAL_MODEL_LINK and LOCAL_MODEL if parameters are omitted)
+global_registry.register_model_config(
+    "local-chat",
+    ModelConfig(
+        provider="local",
+        model_name=""
+    )
+)
+```
+
+### 2. Resolution (Anywhere in your code)
+
+Resolve and query the model anywhere inside your application without importing specific provider SDKs:
+
+```python
+# agents/agent.py
+from llm_registry import global_registry
+
+class SimpleAgent:
+    def __init__(self):
+        # Dynamically resolve model from the global registry
+        self.model = global_registry.get_model("fast-chat")
+      
+    def respond(self, query: str) -> str:
+        # Standard LangChain invoke call
+        response = self.model.invoke(query)
+        return response.content
+
+# Example for Local Ollama Model:
+local_model = global_registry.get_model("local-chat")
+local_response = local_model.invoke([
+    {"role": "user", "content": "How are you today?"}
+])
+print(local_response)  # Returns direct text output
+```
+
+---
+
+## Running Playground tests
+
+An interactive chat test script is included under `tests/chat_test.py` to check your connections. Run it directly:
+
+```bash
+python tests/chat_test.py
+```

lighthouse_llm_registry-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lighthouse-llm-registry"
+version = "0.1.0"
+description = "A global reusable LLM Registry wrapper for LangChain models with unified error mapping for Lighthouse Agents Factory"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "Rohit Jagtap", email = "rohit.jagtap@lighthouseindia.com"}
+]
+keywords = ["llm", "langchain", "registry", "ai", "openai", "groq", "anthropic", "gemini"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "langchain-core>=0.3.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+openai = ["langchain-openai"]
+anthropic = ["langchain-anthropic"]
+google = ["langchain-google-genai"]
+groq = ["langchain-groq"]
+all = [
+    "langchain-openai",
+    "langchain-anthropic",
+    "langchain-google-genai",
+    "langchain-groq"
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/llm_registry"]

lighthouse_llm_registry-0.1.0/src/llm_registry/__init__.py

@@ -0,0 +1,28 @@
+from llm_registry.registry import global_registry, LLMRegistry
+from llm_registry.config import ModelConfig
+from llm_registry.base import BaseLLMProvider
+from llm_registry.errors import (
+    LLMErrorDetails,
+    LLMInvocationError,
+    LLMRegistryError,
+    ModelAliasNotFoundError,
+    ModelCreationError,
+    ProviderDependencyError,
+    ProviderNotRegisteredError,
+)
+from llm_registry.result import LLMResult
+
+__all__ = [
+    "global_registry",
+    "LLMRegistry",
+    "ModelConfig",
+    "BaseLLMProvider",
+    "LLMErrorDetails",
+    "LLMInvocationError",
+    "LLMRegistryError",
+    "ModelAliasNotFoundError",
+    "ModelCreationError",
+    "ProviderDependencyError",
+    "ProviderNotRegisteredError",
+    "LLMResult",
+]

lighthouse_llm_registry-0.1.0/src/llm_registry/base.py

@@ -0,0 +1,9 @@
+from abc import ABC, abstractmethod
+from langchain_core.language_models import BaseChatModel
+from llm_registry.config import ModelConfig
+
+class BaseLLMProvider(ABC):
+    @abstractmethod
+    def create_model(self, config: ModelConfig) -> BaseChatModel:
+        """Instantiate and return a LangChain ChatModel based on the ModelConfig."""
+        pass

lighthouse_llm_registry-0.1.0/src/llm_registry/config.py

@@ -0,0 +1,9 @@
+from typing import Dict, Any, Optional
+from pydantic import BaseModel, Field
+
+class ModelConfig(BaseModel):
+    provider: str = Field(..., description="The LLM provider, e.g., 'openai', 'anthropic', 'google', 'groq'")
+    model_name: str = Field(..., description="The name of the model, e.g., 'gpt-4o', 'llama-3.1-8b-instant'")
+    temperature: Optional[float] = Field(None, ge=0.0, le=2.0, description="Temperature for sampling (optional)")
+    max_tokens: Optional[int] = Field(None, description="Max tokens to generate (optional)")
+    extra_params: Dict[str, Any] = Field(default_factory=dict, description="Any extra provider-specific parameter kwargs")

lighthouse_llm_registry-0.1.0/src/llm_registry/errors.py

@@ -0,0 +1,132 @@
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class LLMErrorDetails:
+    """Structured error details for provider and registry failures."""
+
+    provider: Optional[str]
+    model_name: Optional[str]
+    category: str
+    message: str
+    exception_type: str
+    status_code: Optional[int] = None
+    code: Optional[str] = None
+
+
+class LLMRegistryError(Exception):
+    """Base exception for all llm_registry errors."""
+
+    def __init__(self, message: str, details: Optional[LLMErrorDetails] = None):
+        super().__init__(message)
+        self.details = details
+
+
+class ModelAliasNotFoundError(LLMRegistryError, ValueError):
+    """Raised when an alias has not been registered."""
+
+
+class ProviderNotRegisteredError(LLMRegistryError, ValueError):
+    """Raised when no provider implementation exists for a model config."""
+
+
+class ProviderDependencyError(LLMRegistryError, ImportError):
+    """Raised when an optional provider dependency is not installed."""
+
+
+class ModelCreationError(LLMRegistryError):
+    """Raised when a provider cannot create a model instance."""
+
+
+class LLMInvocationError(LLMRegistryError):
+    """Raised when a provider API call fails."""
+
+
+def normalize_exception(
+    exc: Exception,
+    *,
+    provider: Optional[str] = None,
+    model_name: Optional[str] = None,
+) -> LLMErrorDetails:
+    """Map provider-specific exceptions into stable package-level details."""
+
+    exception_type = exc.__class__.__name__
+    message = str(exc) or exception_type
+    status_code = _get_status_code(exc)
+    code = _get_code(exc)
+    searchable = f"{exception_type} {message} {code or ''}".lower()
+
+    if status_code in {401, 403} or _contains_any(
+        searchable,
+        ("authentication", "permissiondenied", "unauthorized", "invalid api key", "api key"),
+    ):
+        category = "authentication"
+    elif status_code == 429 or _contains_any(searchable, ("ratelimit", "rate limit", "too many requests")):
+        category = "rate_limit"
+    elif _contains_any(searchable, ("quota", "insufficient_quota", "billing")):
+        category = "quota"
+    elif status_code in {408, 504} or _contains_any(searchable, ("timeout", "deadlineexceeded", "deadline exceeded")):
+        category = "timeout"
+    elif status_code in {400, 404, 422} or _contains_any(
+        searchable,
+        ("badrequest", "invalidrequest", "validation", "notfound", "not found"),
+    ):
+        category = "bad_request"
+    elif _contains_any(searchable, ("context_length", "maximum context", "token limit", "too many tokens")):
+        category = "context_length"
+    elif status_code and status_code >= 500:
+        category = "provider_server"
+    elif _contains_any(
+        searchable,
+        ("connection", "connecterror", "api connection", "service unavailable", "temporarily unavailable"),
+    ):
+        category = "connection"
+    else:
+        category = "unknown"
+
+    return LLMErrorDetails(
+        provider=provider,
+        model_name=model_name,
+        category=category,
+        message=message,
+        exception_type=exception_type,
+        status_code=status_code,
+        code=code,
+    )
+
+
+def _contains_any(value: str, needles: tuple[str, ...]) -> bool:
+    return any(needle in value for needle in needles)
+
+
+def _get_status_code(exc: Exception) -> Optional[int]:
+    for attr in ("status_code", "status", "http_status", "http_status_code"):
+        value = getattr(exc, attr, None)
+        if isinstance(value, int):
+            return value
+
+    response = getattr(exc, "response", None)
+    value = getattr(response, "status_code", None)
+    if isinstance(value, int):
+        return value
+
+    return None
+
+
+def _get_code(exc: Exception) -> Optional[str]:
+    for attr in ("code", "error_code", "type"):
+        value = getattr(exc, attr, None)
+        if value is not None:
+            return str(value)
+
+    body = getattr(exc, "body", None)
+    if isinstance(body, dict):
+        error = body.get("error", body)
+        if isinstance(error, dict):
+            for key in ("code", "type"):
+                value = error.get(key)
+                if value is not None:
+                    return str(value)
+
+    return None

lighthouse_llm_registry-0.1.0/src/llm_registry/providers/__init__.py

@@ -0,0 +1 @@
+# Providers package initialization.

lighthouse_llm_registry-0.1.0/src/llm_registry/providers/anthropic.py

@@ -0,0 +1,20 @@
+from langchain_core.language_models import BaseChatModel
+from llm_registry.base import BaseLLMProvider
+from llm_registry.config import ModelConfig
+
+class AnthropicProvider(BaseLLMProvider):
+    def create_model(self, config: ModelConfig) -> BaseChatModel:
+        from langchain_anthropic import ChatAnthropic
+        
+        kwargs = {
+            "model": config.model_name,
+        }
+        if config.temperature is not None:
+            kwargs["temperature"] = config.temperature
+        if config.max_tokens is not None:
+            kwargs["max_tokens"] = config.max_tokens
+            
+        return ChatAnthropic(
+            **kwargs,
+            **config.extra_params
+        )

lighthouse_llm_registry-0.1.0/src/llm_registry/providers/google.py

@@ -0,0 +1,20 @@
+from langchain_core.language_models import BaseChatModel
+from llm_registry.base import BaseLLMProvider
+from llm_registry.config import ModelConfig
+
+class GoogleProvider(BaseLLMProvider):
+    def create_model(self, config: ModelConfig) -> BaseChatModel:
+        from langchain_google_genai import ChatGoogleGenerativeAI
+        
+        kwargs = {
+            "model": config.model_name,
+        }
+        if config.temperature is not None:
+            kwargs["temperature"] = config.temperature
+        if config.max_tokens is not None:
+            kwargs["max_tokens"] = config.max_tokens
+            
+        return ChatGoogleGenerativeAI(
+            **kwargs,
+            **config.extra_params
+        )

lighthouse_llm_registry-0.1.0/src/llm_registry/providers/groq.py

@@ -0,0 +1,20 @@
+from langchain_core.language_models import BaseChatModel
+from llm_registry.base import BaseLLMProvider
+from llm_registry.config import ModelConfig
+
+class GroqProvider(BaseLLMProvider):
+    def create_model(self, config: ModelConfig) -> BaseChatModel:
+        from langchain_groq import ChatGroq
+        
+        kwargs = {
+            "model_name": config.model_name,
+        }
+        if config.temperature is not None:
+            kwargs["temperature"] = config.temperature
+        if config.max_tokens is not None:
+            kwargs["max_tokens"] = config.max_tokens
+            
+        return ChatGroq(
+            **kwargs,
+            **config.extra_params
+        )

lighthouse_llm_registry-0.1.0/src/llm_registry/providers/local_llm.py

@@ -0,0 +1,37 @@
+import os
+import requests
+from llm_registry.base import BaseLLMProvider
+from llm_registry.config import ModelConfig
+
+class LocalLLM:
+    def __init__(self, model=None, api_url=None):
+        # Fall back to environment variables if parameters are not explicitly passed
+        self.api_url = api_url or os.getenv("LOCAL_MODEL_LINK")
+        self.model = model or os.getenv("LOCAL_MODEL")
+        
+        if not self.api_url:
+            raise ValueError("LOCAL_MODEL_LINK not set in environment.")
+        if not self.model:
+            raise ValueError("LOCAL_MODEL not set in environment.")
+
+    def invoke(self, messages, **kwargs):
+        payload = {
+            "model": self.model,
+            "messages": messages,
+            "stream": False
+        }
+        payload.update(kwargs)
+        response = requests.post(self.api_url, json=payload)
+        response.raise_for_status()
+        data = response.json()
+        return data.get("message", {}).get("content", data)
+
+class LocalProvider(BaseLLMProvider):
+    def create_model(self, config: ModelConfig):
+        # Extract custom parameters from config model_name & extra_params
+        api_url = config.extra_params.get("api_url")
+        
+        return LocalLLM(
+            model=config.model_name,
+            api_url=api_url
+        )

lighthouse_llm_registry-0.1.0/src/llm_registry/providers/openai.py

@@ -0,0 +1,20 @@
+from langchain_core.language_models import BaseChatModel
+from llm_registry.base import BaseLLMProvider
+from llm_registry.config import ModelConfig
+
+class OpenAIProvider(BaseLLMProvider):
+    def create_model(self, config: ModelConfig) -> BaseChatModel:
+        from langchain_openai import ChatOpenAI
+        
+        kwargs = {
+            "model": config.model_name,
+        }
+        if config.temperature is not None:
+            kwargs["temperature"] = config.temperature
+        if config.max_tokens is not None:
+            kwargs["max_tokens"] = config.max_tokens
+            
+        return ChatOpenAI(
+            **kwargs,
+            **config.extra_params
+        )

lighthouse_llm_registry-0.1.0/src/llm_registry/registry.py

@@ -0,0 +1,143 @@
+from typing import Any, Dict
+from langchain_core.language_models import BaseChatModel
+
+from llm_registry.base import BaseLLMProvider
+from llm_registry.config import ModelConfig
+from llm_registry.errors import (
+    LLMErrorDetails,
+    LLMInvocationError,
+    LLMRegistryError,
+    ModelAliasNotFoundError,
+    ModelCreationError,
+    ProviderDependencyError,
+    ProviderNotRegisteredError,
+    normalize_exception,
+)
+from llm_registry.providers.openai import OpenAIProvider
+from llm_registry.providers.groq import GroqProvider
+from llm_registry.providers.anthropic import AnthropicProvider
+from llm_registry.providers.google import GoogleProvider
+from llm_registry.providers.local_llm import LocalProvider
+from llm_registry.result import LLMResult
+
+class LLMRegistry:
+    def __init__(self):
+        self._providers: Dict[str, BaseLLMProvider] = {}
+        self._configs: Dict[str, ModelConfig] = {}
+        
+        ############### Register default providers #######################
+        self.register_provider("openai", OpenAIProvider())
+        self.register_provider("groq", GroqProvider())
+        self.register_provider("anthropic", AnthropicProvider())
+        self.register_provider("google", GoogleProvider())
+        self.register_provider("local", LocalProvider())
+
+    def register_provider(self, name: str, provider: BaseLLMProvider):
+        """Register an LLM provider."""
+        self._providers[name.lower()] = provider
+
+    def register_model_config(self, alias: str, config: ModelConfig):
+        """Register a model configuration under an alias."""
+        self._configs[alias] = config
+
+    def get_model(self, alias: str) -> BaseChatModel:
+        """Instantiate and return the model configured for the given alias."""
+        if alias not in self._configs:
+            details = LLMErrorDetails(
+                provider=None,
+                model_name=None,
+                category="model_alias_not_found",
+                message=f"Model alias '{alias}' is not registered in the LLM Registry.",
+                exception_type="ModelAliasNotFoundError",
+            )
+            raise ModelAliasNotFoundError(
+                details.message,
+                details,
+            )
+            
+        config = self._configs[alias]
+        provider = self._providers.get(config.provider.lower())
+        if not provider:
+            details = LLMErrorDetails(
+                provider=config.provider,
+                model_name=config.model_name,
+                category="provider_not_registered",
+                message=f"No provider implementation found for '{config.provider}'.",
+                exception_type="ProviderNotRegisteredError",
+            )
+            raise ProviderNotRegisteredError(
+                details.message,
+                details,
+            )
+            
+        try:
+            return provider.create_model(config)
+        except ImportError as exc:
+            details = normalize_exception(
+                exc,
+                provider=config.provider,
+                model_name=config.model_name,
+            )
+            raise ProviderDependencyError(
+                f"Missing dependency for provider '{config.provider}': {exc}",
+                details,
+            ) from exc
+        except Exception as exc:
+            details = normalize_exception(
+                exc,
+                provider=config.provider,
+                model_name=config.model_name,
+            )
+            raise ModelCreationError(
+                f"Failed to create model '{config.model_name}' for provider '{config.provider}': {exc}",
+                details,
+            ) from exc
+
+    def invoke(self, alias: str, input: Any, **kwargs: Any) -> Any:
+        """Invoke a registered model and raise normalized package exceptions on failure."""
+        config = self._get_config(alias)
+        try:
+            model = self.get_model(alias)
+            return model.invoke(input, **kwargs)
+        except LLMRegistryError:
+            raise
+        except Exception as exc:
+            details = normalize_exception(
+                exc,
+                provider=config.provider,
+                model_name=config.model_name,
+            )
+            raise LLMInvocationError(
+                f"LLM API call failed for provider '{config.provider}' and model '{config.model_name}': {exc}",
+                details,
+            ) from exc
+
+    def safe_invoke(self, alias: str, input: Any, **kwargs: Any) -> LLMResult:
+        """Invoke a registered model and return structured success/error data."""
+        try:
+            response = self.invoke(alias, input, **kwargs)
+            return LLMResult(
+                ok=True,
+                content=getattr(response, "content", None),
+                raw_response=response,
+            )
+        except LLMRegistryError as exc:
+            return LLMResult(ok=False, error=exc.details)
+
+    def _get_config(self, alias: str) -> ModelConfig:
+        if alias not in self._configs:
+            details = LLMErrorDetails(
+                provider=None,
+                model_name=None,
+                category="model_alias_not_found",
+                message=f"Model alias '{alias}' is not registered in the LLM Registry.",
+                exception_type="ModelAliasNotFoundError",
+            )
+            raise ModelAliasNotFoundError(
+                details.message,
+                details,
+            )
+        return self._configs[alias]
+
+# Global registry singleton instance
+global_registry = LLMRegistry()

lighthouse_llm_registry-0.1.0/src/llm_registry/result.py

@@ -0,0 +1,13 @@
+from dataclasses import dataclass
+from typing import Any, Optional
+
+from llm_registry.errors import LLMErrorDetails
+
+
+@dataclass(frozen=True)
+class LLMResult:
+    ok: bool
+    content: Optional[str] = None
+    raw_response: Optional[Any] = None
+    error: Optional[LLMErrorDetails] = None
+

lighthouse_llm_registry-0.1.0/tests/chat_test.py

@@ -0,0 +1,115 @@
+import os
+import sys
+from dotenv import load_dotenv
+
+# --- Dynamic Path Configuration ---
+# Detects whether the script is run from /tests or the project root and appends /src
+current_dir = os.path.dirname(os.path.abspath(__file__))
+if os.path.basename(current_dir) == "tests":
+    project_root = os.path.dirname(current_dir)
+else:
+    project_root = current_dir
+
+sys.path.insert(0, os.path.join(project_root, "src"))
+
+# Import from your llm_registry package
+from llm_registry import global_registry, ModelConfig
+
+# Load API keys from your local .env file
+load_dotenv()
+
+# Dictionary to map user choices to model config registrations
+MODELS_MAP = {
+    "1": {
+        "alias": "openai-chat",
+        "name": "OpenAI (gpt-4o-mini)",
+        "config": ModelConfig(provider="openai", model_name="gpt-4o-mini", temperature=0.7),
+        "pip": "pip install langchain-openai"
+    },
+    "2": {
+        "alias": "groq-chat",
+        "name": "Groq (llama-3.1-8b-instant)",
+        "config": ModelConfig(provider="groq", model_name="llama-3.1-8b-instant", temperature=0.7),
+        "pip": "pip install langchain-groq"
+    },
+    "3": {
+        "alias": "anthropic-chat",
+        "name": "Anthropic (claude-opus-4-8)",
+        "config": ModelConfig(provider="anthropic", model_name="claude-opus-4-8"),
+        "pip": "pip install langchain-anthropic"
+    },
+    "4": {
+        "alias": "gemini-chat",
+        "name": "Google Gemini (gemini-2.5-flash)",
+        "config": ModelConfig(provider="google", model_name="gemini-2.5-flash", temperature=0.7),
+        "pip": "pip install langchain-google-genai"
+    }
+}
+
+def register_all_models():
+    """Register all configurations in the global registry."""
+    for key, model_info in MODELS_MAP.items():
+        global_registry.register_model_config(model_info["alias"], model_info["config"])
+
+def run_playground():
+    register_all_models()
+    
+    print("=" * 50)
+    print("           LLM REGISTRY PLAYGROUND")
+    print("=" * 50)
+    print("Select a provider/model to chat with:")
+    
+    for key, model_info in MODELS_MAP.items():
+        print(f"{key}. {model_info['name']}")
+        
+    choice = input("\nEnter choice (1-4): ").strip()
+    
+    if choice not in MODELS_MAP:
+        print("Invalid selection. Exiting.")
+        return
+        
+    model_info = MODELS_MAP[choice]
+    alias = model_info["alias"]
+    
+    try:
+        # Resolve model from the registry
+        model = global_registry.get_model(alias)
+        print(f"\n[Success] Resolved model for: {model_info['name']}")
+        print("Type 'exit' or 'quit' to end session.\n")
+        
+        while True:
+            user_input = input("You: ").strip()
+            if user_input.lower() in ["exit", "quit"]:
+                print("Exiting playground...")
+                break
+                
+            if not user_input:
+                continue
+                
+            print(f"[{alias} thinking...]")
+            result = global_registry.safe_invoke(alias, user_input)
+            if result.ok:
+                print(f"\nAI: {result.content}\n")
+            else:
+                error = result.error
+                print("\n[API Error]")
+                if error is None:
+                    print("Message: Unknown registry error\n")
+                    continue
+                print(f"Provider: {error.provider}")
+                print(f"Model: {error.model_name}")
+                print(f"Category: {error.category}")
+                if error.status_code is not None:
+                    print(f"Status Code: {error.status_code}")
+                if error.code is not None:
+                    print(f"Code: {error.code}")
+                print(f"Message: {error.message}\n")
+                
+    except ImportError as imp_err:
+        print(f"\n[Import Error]: Missing SDK dependencies.")
+        print(f"To use this provider, please run:  {model_info['pip']}")
+    except Exception as e:
+        print(f"\n[Error]: {e}")
+
+if __name__ == "__main__":
+    run_playground()

lighthouse_llm_registry-0.1.0/tests/local_llm.py

@@ -0,0 +1,16 @@
+from llm_registry import global_registry, ModelConfig
+
+# Register the local model configuration
+global_registry.register_model_config(
+    "ollama-chat",
+    ModelConfig(
+        provider="local",
+        model_name="llama3",
+        extra_params={"api_url": "http://localhost:11434/api/chat"}
+    )
+)
+
+# Resolve and invoke
+local_model = global_registry.get_model("ollama-chat")
+response = local_model.invoke("Hello, local model!")
+print(response)  # Outputs the direct text response

lighthouse_llm_registry-0.1.0/tests/test_groq.py

@@ -0,0 +1,59 @@
+import os
+import sys
+import unittest
+from dotenv import load_dotenv
+
+# --- Dynamic Path Configuration ---
+current_dir = os.path.dirname(os.path.abspath(__file__))
+project_root = os.path.dirname(current_dir)
+sys.path.insert(0, os.path.join(project_root, "src"))
+
+from llm_registry import global_registry, ModelConfig
+from langchain_core.language_models import BaseChatModel
+
+# Load API keys from .env file
+load_dotenv()
+
+class TestGroqRegistry(unittest.TestCase):
+    
+    def test_env_loaded(self):
+        """Test that the GROQ_API_KEY is successfully loaded from .env"""
+        api_key = os.getenv("GROQ_API_KEY")
+        self.assertIsNotNone(api_key, "GROQ_API_KEY is not defined in your .env file.")
+
+    def test_groq_registration_and_retrieval(self):
+        """Test that Groq is registered and resolves successfully from global_registry"""
+        config = ModelConfig(
+            provider="groq",
+            model_name="llama-3.1-8b-instant",
+            temperature=0.1
+        )
+        global_registry.register_model_config("my-groq-model", config)
+        
+        model = global_registry.get_model("my-groq-model")
+        
+        self.assertIsInstance(model, BaseChatModel, "The returned object is not a LangChain model.")
+        self.assertEqual(model.model_name, "llama-3.1-8b-instant")
+
+    def test_live_groq_api_call(self):
+        """Test a live request to Groq using your key"""
+        config = ModelConfig(
+            provider="groq",
+            model_name="llama-3.1-8b-instant",
+            temperature=0.0,
+            max_tokens=15
+        )
+        global_registry.register_model_config("groq-test-call", config)
+        model = global_registry.get_model("groq-test-call")
+        
+        try:
+            response = model.invoke("Say the word 'success' and nothing else.")
+            response_text = response.content.strip().lower()
+            
+            self.assertIn("success", response_text)
+            print(f"\n[Success] Live Groq API Connection verified. Model output: {response.content}")
+        except Exception as e:
+            self.fail(f"Live Groq API call failed with exception: {e}")
+
+if __name__ == "__main__":
+    unittest.main()

lighthouse_llm_registry-0.1.0/tests/test_local_env.py

@@ -0,0 +1,57 @@
+import os
+import sys
+from dotenv import load_dotenv
+
+# --- Dynamic Path Configuration ---
+current_dir = os.path.dirname(os.path.abspath(__file__))
+project_root = os.path.dirname(current_dir)
+sys.path.insert(0, os.path.join(project_root, "src"))
+
+from llm_registry import global_registry, ModelConfig
+
+# 1. Load your API keys and local configs from .env
+load_dotenv()
+
+# Setup simulated env parameters if not already present in the environment/dotenv file
+if not os.getenv("LOCAL_MODEL_LINK"):
+    os.environ["LOCAL_MODEL_LINK"] = "http://192.168.101.88:11434/api/chat"
+if not os.getenv("LOCAL_MODEL"):
+    os.environ["LOCAL_MODEL"] = "llama3.1:8b"
+
+def run_local_model_test():
+    print("=" * 50)
+    print("        LOCAL OLLAMA CONNECTION TEST")
+    print("=" * 50)
+    
+    print(f"Env LOCAL_MODEL_LINK: {os.getenv('LOCAL_MODEL_LINK')}")
+    print(f"Env LOCAL_MODEL:      {os.getenv('LOCAL_MODEL')}")
+    
+    # Register the local provider config. 
+    # By passing empty strings/None, it falls back dynamically to your .env variables!
+    global_registry.register_model_config(
+        "local-ollama",
+        ModelConfig(
+            provider="local",
+            model_name="",        # Falls back to os.getenv("LOCAL_MODEL")
+            extra_params={}       # Falls back to os.getenv("LOCAL_MODEL_LINK")
+        )
+    )
+
+    try:
+        # Resolve the model
+        model = global_registry.get_model("local-ollama")
+        print("\n[Success] Local model resolved successfully!")
+        
+        # Invoke a simple prompt (role/content layout for Ollama api/chat)
+        test_messages = [{"role": "user", "content": "Tell me what is UI"}]
+        print(f"Sending request to {model.api_url}...")
+        
+        response = model.invoke(test_messages)
+        print(f"\nResponse from Local LLM:\n{response}")
+        
+    except Exception as e:
+        print(f"\n[Connection Error]: {e}")
+        print("Please check that your Ollama server is running and accessible at the specified IP/port.")
+
+if __name__ == "__main__":
+    run_local_model_test()

lighthouse_llm_registry-0.1.0/tests/test_openai.py

@@ -0,0 +1,61 @@
+import os
+import sys
+import unittest
+from dotenv import load_dotenv
+
+# --- Dynamic Path Configuration ---
+# This adds the 'src/' folder to Python's search path so it finds 'llm_registry'
+current_dir = os.path.dirname(os.path.abspath(__file__))
+project_root = os.path.dirname(current_dir)
+sys.path.insert(0, os.path.join(project_root, "src"))
+
+# Now these imports will work successfully!
+from llm_registry.providers.openai import OpenAIProvider
+from llm_registry.config import ModelConfig
+from langchain_core.language_models import BaseChatModel
+
+# Load API keys from your local .env file
+load_dotenv()
+
+class TestOpenAIProvider(unittest.TestCase):
+    
+    def test_env_loaded(self):
+        """Test that the OpenAI API key is successfully loaded from .env"""
+        api_key = os.getenv("OPENAI_API_KEY")
+        self.assertIsNotNone(api_key, "OPENAI_API_KEY is not defined in your .env file.")
+
+    def test_provider_initialization(self):
+        """Test that OpenAIProvider instantiates a valid LangChain ChatModel"""
+        config = ModelConfig(
+            provider="openai",
+            model_name="gpt-4o-mini",
+            temperature=0.0
+        )
+        provider = OpenAIProvider()
+        model = provider.create_model(config)
+        
+        self.assertIsInstance(model, BaseChatModel, "The returned object is not a LangChain model.")
+        self.assertEqual(model.model_name, "gpt-4o-mini")
+
+    def test_live_api_call(self):
+        """Test a live request to OpenAI using your key"""
+        config = ModelConfig(
+            provider="openai",
+            model_name="gpt-4.1-mini",
+            temperature=0.0,
+            max_tokens=200
+        )
+        provider = OpenAIProvider()
+        model = provider.create_model(config)
+        
+        try:
+            response = model.invoke("Say the word 'success' and nothing else.")
+            response_text = response.content.strip().lower()
+            
+            self.assertIn("success", response_text)
+            print(f"\n[Success] Live API Connection verified. Model output: {response.content}")
+        except Exception as e:
+            self.fail(f"Live API call failed with exception: {e}")
+
+if __name__ == "__main__":
+    unittest.main()

lighthouse_llm_registry-0.1.0/tests/test_registry.py

@@ -0,0 +1,136 @@
+import os
+import sys
+import unittest
+
+# --- Dynamic Path Configuration ---
+# Detects whether the script is run from /tests or the project root and appends /src
+current_dir = os.path.dirname(os.path.abspath(__file__))
+if os.path.basename(current_dir) == "tests":
+    project_root = os.path.dirname(current_dir)
+else:
+    project_root = current_dir
+
+sys.path.insert(0, os.path.join(project_root, "src"))
+
+from llm_registry import (  # noqa: E402
+    BaseLLMProvider,
+    LLMInvocationError,
+    LLMRegistry,
+    ModelAliasNotFoundError,
+    ModelConfig,
+    ProviderDependencyError,
+    ProviderNotRegisteredError,
+)
+
+
+class FakeResponse:
+    content = "success"
+
+
+class FakeModel:
+    def __init__(self, exc=None):
+        self.exc = exc
+
+    def invoke(self, input, **kwargs):
+        if self.exc:
+            raise self.exc
+        return FakeResponse()
+
+
+class FakeProvider(BaseLLMProvider):
+    def __init__(self, model=None, exc=None):
+        self.model = model or FakeModel()
+        self.exc = exc
+
+    def create_model(self, config):
+        if self.exc:
+            raise self.exc
+        return self.model
+
+
+class FakeRateLimitError(Exception):
+    status_code = 429
+    code = "rate_limit_exceeded"
+
+
+class TestRegistryErrorHandling(unittest.TestCase):
+    def test_unknown_alias_raises_typed_error(self):
+        registry = LLMRegistry()
+
+        with self.assertRaises(ModelAliasNotFoundError) as ctx:
+            registry.get_model("missing")
+
+        self.assertEqual(ctx.exception.details.category, "model_alias_not_found")
+
+    def test_unknown_provider_raises_typed_error(self):
+        registry = LLMRegistry()
+        registry.register_model_config(
+            "bad-provider",
+            ModelConfig(provider="missing", model_name="x"),
+        )
+
+        with self.assertRaises(ProviderNotRegisteredError) as ctx:
+            registry.get_model("bad-provider")
+
+        self.assertEqual(ctx.exception.details.provider, "missing")
+        self.assertEqual(ctx.exception.details.category, "provider_not_registered")
+
+    def test_missing_dependency_is_normalized(self):
+        registry = LLMRegistry()
+        registry.register_provider("fake", FakeProvider(exc=ImportError("fake-sdk")))
+        registry.register_model_config(
+            "fake",
+            ModelConfig(provider="fake", model_name="fake-model"),
+        )
+
+        with self.assertRaises(ProviderDependencyError) as ctx:
+            registry.get_model("fake")
+
+        self.assertEqual(ctx.exception.details.provider, "fake")
+        self.assertEqual(ctx.exception.details.model_name, "fake-model")
+
+    def test_invoke_wraps_provider_api_error(self):
+        registry = LLMRegistry()
+        registry.register_provider("fake", FakeProvider(model=FakeModel(FakeRateLimitError("slow down"))))
+        registry.register_model_config(
+            "fake",
+            ModelConfig(provider="fake", model_name="fake-model"),
+        )
+
+        with self.assertRaises(LLMInvocationError) as ctx:
+            registry.invoke("fake", "hello")
+
+        self.assertEqual(ctx.exception.details.category, "rate_limit")
+        self.assertEqual(ctx.exception.details.status_code, 429)
+
+    def test_safe_invoke_returns_structured_result(self):
+        registry = LLMRegistry()
+        registry.register_provider("fake", FakeProvider(model=FakeModel(FakeRateLimitError("slow down"))))
+        registry.register_model_config(
+            "fake",
+            ModelConfig(provider="fake", model_name="fake-model"),
+        )
+
+        result = registry.safe_invoke("fake", "hello")
+
+        self.assertFalse(result.ok)
+        self.assertEqual(result.error.category, "rate_limit")
+        self.assertIsNone(result.content)
+
+    def test_safe_invoke_returns_success_result(self):
+        registry = LLMRegistry()
+        registry.register_provider("fake", FakeProvider())
+        registry.register_model_config(
+            "fake",
+            ModelConfig(provider="fake", model_name="fake-model"),
+        )
+
+        result = registry.safe_invoke("fake", "hello")
+
+        self.assertTrue(result.ok)
+        self.assertEqual(result.content, "success")
+        self.assertIsInstance(result.raw_response, FakeResponse)
+
+
+if __name__ == "__main__":
+    unittest.main()