lighthouse-llm-registry 0.1.4

A global reusable LLM Registry wrapper for LangChain models with unified error mapping for Lighthouse Agents Factory

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:

pip install lighthouse-llm-registry

To install specific provider SDK dependencies:

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

pip install ".[all]"

2. API Keys Configuration

Create a .env file in the root of your target project:

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):

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

# 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):

# 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):

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:

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:

python tests/chat_test.py