Metadata-Version: 2.4
Name: lighthouse-llm-registry
Version: 0.1.4
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-anthropic
Requires-Dist: langchain-core>=0.3.0
Requires-Dist: langchain-google-genai
Requires-Dist: langchain-groq
Requires-Dist: langchain-openai
Requires-Dist: openai
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
```

### 3. Image Generation (OpenAI DALL-E)

Register the DALL-E model and query it using the unified `.invoke(prompt)` interface. The wrapper handles both public URLs and base64 JSON responses (returning a Base64 data URI):

```python
# Register DALL-E config
global_registry.register_model_config(
    "dalle-gen",
    ModelConfig(
        provider="dalle",
        model_name="dall-e-3",  # or "dall-e-2" / "gpt-image-2"
        extra_params={
            "size": "1024x1024"  # Optional size configuration
        }
    )
)

# Resolve and generate image
model = global_registry.get_model("dalle-gen")
image_uri = model.invoke("a beautiful mountain lake at sunrise")
print(image_uri)  # Returns public URL or a base64 Data URI
```

---

## Web Search Capabilities

Depending on the provider, you can enable web search capability natively (Gemini) or by binding a search tool (OpenAI, Groq, Anthropic).

### 1. Google Gemini (Native Search Grounding)
Google Gemini models support native Google Search grounding directly at the API level (the API handles search internally and returns the final answer with citations):

```python
global_registry.register_model_config(
    "gemini-search",
    ModelConfig(
        provider="google",
        model_name="gemini-2.5-flash",
        extra_params={
            "tools": [{"google_search": {}}]
        }
    )
)

model = global_registry.get_model("gemini-search")
response = model.invoke("Who won the Formula 1 race yesterday?")
print(response.content)
```

### 2. OpenAI / Anthropic / Groq (Using Free DuckDuckGo Tool)
Other providers do not support native web search. You must bind an external search tool (like the free `DuckDuckGoSearchRun` tool) to the model and run it inside a LangChain agent:

```python
from langchain_community.tools import DuckDuckGoSearchRun
from langgraph.prebuilt import create_react_agent

# 1. Retrieve the standard model
model = global_registry.get_model("fast-chat")

# 2. Create the search tool
search_tool = DuckDuckGoSearchRun()

# 3. Create an agent combining the model and tool
agent = create_react_agent(model, tools=[search_tool])

# 4. Invoke the search agent
response = agent.invoke({"messages": [("user", "What is the stock price of Tesla today?")]})
print(response["messages"][-1].content)
```

---

## 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
```
