refactor: instructor_llm_factory merge with llm_factory (#2382)

Consolidates dual LLM factories into a single, explicit `llm_factory()`
API. Removes `instructor_llm_factory()` entirely.

## Changes

### Core Changes
- Unified `llm_factory()`: Single factory supporting multiple LLM
providers (OpenAI, Anthropic, Cohere, Google, LiteLLM)
  - Requires explicit parameters: `model`, `provider`, `client`
  - Returns: `InstructorBaseRagasLLM` (structured outputs only)
  - Clear error messages for missing parameters

- Removed `instructor_llm_factory()`: Deleted entirely (~97 lines)
  - Functionality merged into unified `llm_factory()`
  - Removed from public exports

### API Change
**Before:**
```py
from ragas.llms import instructor_llm_factory
llm = instructor_llm_factory("openai", model="gpt-4o", client=client)
```

**After:**
```py
from ragas.llms import llm_factory
llm = llm_factory("gpt-4o", client=client)  # provider defaults to "openai"
```

## Migration for Users

```py
# Old code
llm = llm_factory("gpt-4o-mini")

# Error message:
# ValueError: llm_factory() requires a client instance.
# Text-only mode has been removed.

# To migrate:
from openai import OpenAI
client = OpenAI(api_key='...')
llm = llm_factory('gpt-4o-mini', client=client)
```

## Notes
This is a **breaking change** for the public API, but justified because:
1. Old text-only factory was already deprecated
2. All new metrics require structured outputs (InstructorLLM)
3. Unified API is simpler and more maintainable
4. Clear error messages guide easy migration

Author: anistark

docs/howtos/customizations/metrics/_metrics_language_adaptation.md

@@ -30,9 +30,11 @@ As you can see, the instruction and demonstration are both in English. Setting u
 
 
 ```python
+from openai import OpenAI
 from ragas.llms import llm_factory
 
-llm = llm_factory()
+openai_client = OpenAI(api_key="sk-...")
+llm = llm_factory("gpt-4o-mini", client=openai_client)
 ```
 
 Now let's adapt it to 'hindi' as the target language using `adapt` method.

docs/howtos/customizations/metrics/_write_your_own_metric.md

@@ -32,9 +32,11 @@ choose_evaluator_llm.md
 
 
 ```python
+from openai import OpenAI
 from ragas.llms import llm_factory
 
-evaluator_llm = llm_factory("gpt-4o")
+openai_client = OpenAI(api_key="sk-...")
+evaluator_llm = llm_factory("gpt-4o", client=openai_client)
 ```
 
 ## Aspect Critic - Simple Criteria Scoring

docs/howtos/customizations/testgenerator/_persona_generator.md

@@ -44,14 +44,16 @@ And then you can use these personas in the testset generation process by passing
 
 
 ```python
+from openai import OpenAI
 from ragas.testset import TestsetGenerator
 from ragas.testset.graph import KnowledgeGraph
 from ragas.llms import llm_factory
 
 # Load the knowledge graph
 kg = KnowledgeGraph.load("../../../../experiments/gitlab_kg.json")
 # Initialize the Generator LLM
-llm = llm_factory("gpt-4o-mini")
+openai_client = OpenAI()
+llm = llm_factory("gpt-4o-mini", client=openai_client)
 
 # Initialize the Testset Generator
 testset_generator = TestsetGenerator(knowledge_graph=kg, persona_list=personas, llm=llm)

docs/howtos/customizations/testgenerator/_testgen-custom-single-hop.md

@@ -44,12 +44,12 @@ for doc in docs:
 You may use any of [your choice](./../../customizations/customize_models.md), here I am using models from open-ai.
 
 ```python
-from ragas.llms.base import llm_factory
+from openai import OpenAI
+from ragas.llms import llm_factory
 from ragas.embeddings import OpenAIEmbeddings
-import openai
 
-llm = llm_factory()
-openai_client = openai.OpenAI()
+openai_client = OpenAI()
+llm = llm_factory("gpt-4o-mini", client=openai_client)
 embedding = OpenAIEmbeddings(client=openai_client)
 ```
 

docs/howtos/customizations/testgenerator/_testgen-customisation.md

@@ -47,12 +47,12 @@ You may use any of [your choice](./../../customizations/customize_models.md), he
 
 
 ```python
-from ragas.llms.base import llm_factory
+from openai import OpenAI
+from ragas.llms import llm_factory
 from ragas.embeddings import OpenAIEmbeddings
-import openai
 
-llm = llm_factory()
-openai_client = openai.OpenAI()
+openai_client = OpenAI()
+llm = llm_factory("gpt-4o-mini", client=openai_client)
 embedding = OpenAIEmbeddings(client=openai_client)
 ```
 

examples/ragas_examples/improve_rag/evals.py

@@ -16,7 +16,7 @@
 from openai import AsyncOpenAI
 
 from ragas import Dataset, experiment
-from ragas.llms import instructor_llm_factory
+from ragas.llms import llm_factory
 from ragas.metrics import DiscreteMetric
 
 from .rag import RAG, BM25Retriever
@@ -206,7 +206,7 @@ async def run_experiment(mode: str = "naive", model: str = "gpt-5-mini", name: O
         dataset, 
         name=name or f"{datetime.now().strftime('%Y%m%d-%H%M%S')}_{'agenticrag' if mode == 'agentic' else 'naiverag'}",
         rag=rag,
-        llm=instructor_llm_factory("openai", model="gpt-5-mini", client=openai_client)
+        llm=llm_factory("gpt-5-mini", client=openai_client)
     )
 
     # Print basic results

examples/ragas_examples/judge_alignment/evals.py

@@ -17,7 +17,7 @@
 from openai import AsyncOpenAI
 
 from ragas import Dataset, experiment
-from ragas.llms import instructor_llm_factory
+from ragas.llms import llm_factory
 from ragas.metrics import DiscreteMetric
 from ragas.metrics.discrete import discrete_metric
 from ragas.metrics.result import MetricResult
@@ -173,8 +173,8 @@ async def main():
     # Initialize LLM client
     logger.info("Initializing LLM client with model: gpt-4o-mini")
     openai_client = AsyncOpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
-    llm = instructor_llm_factory("openai", model="gpt-4o-mini", client=openai_client)
-    
+    llm = llm_factory("gpt-4o-mini", client=openai_client)
+
     # Run baseline evaluation
     logger.info("Running baseline evaluation...")
     results = await judge_experiment.arun(
@@ -200,8 +200,8 @@ async def main_v2():
     # Initialize LLM client
     logger.info("Initializing LLM client with model: gpt-4o-mini")
     openai_client = AsyncOpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
-    llm = instructor_llm_factory("openai", model="gpt-4o-mini", client=openai_client)
-    
+    llm = llm_factory("gpt-4o-mini", client=openai_client)
+
     # Run v2 evaluation with improved prompt
     logger.info("Running v2 evaluation with improved prompt...")
     results = await judge_experiment.arun(

examples/ragas_examples/rag_eval/evals.py

@@ -3,14 +3,14 @@
 from openai import OpenAI
 
 from ragas import Dataset, experiment
-from ragas.llms import instructor_llm_factory
+from ragas.llms import llm_factory
 from ragas.metrics import DiscreteMetric
 
 from .rag import default_rag_client
 
 openai_client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
 rag_client = default_rag_client(llm_client=openai_client)
-llm = instructor_llm_factory("openai", model="gpt-4o", client=openai_client)
+llm = llm_factory("gpt-4o", client=openai_client)
 
 
 def load_dataset():

examples/ragas_examples/workflow_eval/evals.py

@@ -3,14 +3,14 @@
 from openai import OpenAI
 
 from ragas import Dataset, experiment
-from ragas.llms import instructor_llm_factory
+from ragas.llms import llm_factory
 from ragas.metrics import DiscreteMetric
 
 from .workflow import default_workflow_client
 
 openai_client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
 workflow_client = default_workflow_client()
-llm = instructor_llm_factory("openai", model="gpt-4o", client=openai_client)
+llm = llm_factory("gpt-4o", client=openai_client)
 
 
 def load_dataset():

pyproject.toml

@@ -117,7 +117,7 @@ preview = false
 
 [tool.pyright]
 include = ["src/ragas"]
-excludeTypeshedPaths = ["@types/*"]
+exclude = ["@types/*"]
 pythonVersion = "3.9"
 pythonPlatform = "All"
 typeCheckingMode = "basic"