Implementation:Vibrantlabsai Ragas Llm Factory

Field	Value
Source Repository	explodinggradients/ragas
Source File	`src/ragas/llms/base.py`
Domains	NLP, Evaluation, LLM Integration
Last Updated	2026-02-12 00:00 GMT

Overview

Llm_Factory is the concrete factory function provided by the Ragas library for creating LLM instances that produce structured outputs. The llm_factory() function accepts a model name, provider identifier, and pre-initialized client, then returns an InstructorBaseRagasLLM instance with generate() and agenerate() methods that accept Pydantic models for validated, structured responses.

Description

The llm_factory() function is the recommended entry point for configuring LLMs in Ragas. It replaces the deprecated LangchainLLMWrapper and LlamaIndexLLMWrapper classes. The function:

Validates that a client instance is provided (text-only mode has been removed).
Auto-detects the best structured output adapter (Instructor vs. LiteLLM) based on the provider and client type, or accepts an explicit adapter choice.
Delegates to the selected adapter to create an InstructorLLM instance with provider-specific parameter mapping.
Tracks usage analytics for the LLM creation event.

The returned InstructorLLM object handles provider-specific parameter mapping internally (e.g., remapping max_tokens to max_completion_tokens for OpenAI reasoning models, wrapping parameters in generation_config for Google Gemini), and correctly detects whether the client is async-capable.

Usage

Use llm_factory() when you need to create an LLM instance for passing to evaluate(), for assigning to a metric's .llm attribute, or for any structured output generation within the Ragas framework.

Code Reference

Source location: src/ragas/llms/base.py, lines 606-748

Import statement:

from ragas.llms import llm_factory

Full function signature:

def llm_factory(
    model: str,
    provider: str = "openai",
    client: t.Optional[t.Any] = None,
    adapter: str = "auto",
    cache: t.Optional[CacheInterface] = None,
    mode: t.Optional[instructor.Mode] = None,
    **kwargs: t.Any,
) -> InstructorBaseRagasLLM:

Return type hierarchy:

class InstructorBaseRagasLLM(ABC):
    """Base class for LLMs using the Instructor library pattern."""

    @abstractmethod
    def generate(
        self, prompt: str, response_model: t.Type[T]
    ) -> T: ...

    @abstractmethod
    async def agenerate(
        self, prompt: str, response_model: t.Type[T]
    ) -> T: ...

class InstructorLLM(InstructorBaseRagasLLM):
    """Concrete implementation using Instructor for structured outputs."""
    def __init__(
        self,
        client: t.Any,
        model: str,
        provider: str,
        model_args: t.Optional[InstructorModelArgs] = None,
        cache: t.Optional[CacheInterface] = None,
        **kwargs,
    ): ...

I/O Contract

Direction	Parameter	Type	Description
Input	`model`	`str`	Model name (e.g., `"gpt-4o"`, `"claude-3-sonnet"`, `"gemini-2.0-flash"`).
Input	`provider`	`str`	LLM provider identifier. Default: `"openai"`. Supported: openai, anthropic, google, groq, mistral, azure, bedrock, deepseek, litellm, perplexity, xai, cohere.
Input	`client`	`Optional[Any]`	Pre-initialized provider client instance. Required. E.g., `OpenAI(...)` or `AsyncOpenAI(...)`.
Input	`adapter`	`str`	Structured output adapter. Default: `"auto"`. Options: `"auto"`, `"instructor"`, `"litellm"`.
Input	`cache`	`Optional[CacheInterface]`	Optional cache backend for caching LLM responses. E.g., `DiskCacheBackend()`.
Input	`mode`	`Optional[instructor.Mode]`	Instructor mode for structured outputs. Default: `Mode.JSON`. Options include `Mode.MD_JSON`, `Mode.TOOLS`, etc.
Input	`**kwargs`	`Any`	Additional model arguments: `temperature`, `max_tokens`, `top_p`, etc.
Output	return	`InstructorBaseRagasLLM`	LLM instance with `generate(prompt, response_model)` and `agenerate(prompt, response_model)` methods.

Usage Examples

Basic OpenAI configuration:

from openai import OpenAI
from ragas.llms import llm_factory

client = OpenAI(api_key="sk-...")
llm = llm_factory("gpt-4o-mini", client=client)

Anthropic configuration:

from anthropic import Anthropic
from ragas.llms import llm_factory

client = Anthropic(api_key="sk-ant-...")
llm = llm_factory("claude-3-sonnet", provider="anthropic", client=client)

With caching for cost reduction:

from openai import OpenAI
from ragas.llms import llm_factory
from ragas.cache import DiskCacheBackend

client = OpenAI(api_key="sk-...")
cache = DiskCacheBackend()
llm = llm_factory("gpt-4o-mini", client=client, cache=cache)

Async client:

from openai import AsyncOpenAI
from ragas.llms import llm_factory

client = AsyncOpenAI(api_key="sk-...")
llm = llm_factory("gpt-4o-mini", client=client)
# Use: response = await llm.agenerate(prompt, ResponseModel)

Custom instructor mode for non-standard backends:

import instructor
from openai import OpenAI
from ragas.llms import llm_factory

client = OpenAI(api_key="sk-...", base_url="https://custom-backend")
llm = llm_factory("custom-model", client=client, mode=instructor.Mode.MD_JSON)

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment