Implementation:Vibrantlabsai Ragas OCIGenAIWrapper

Knowledge Sources	Vibrantlabsai_Ragas
Domains	LLM Wrapper, OCI, Cloud Integration, LLM Evaluation
Last Updated	2026-02-12 00:00 GMT

Overview

The OCI Gen AI wrapper provides direct integration with Oracle Cloud Infrastructure Generative AI services for use with Ragas evaluation, without requiring LangChain or LlamaIndex intermediaries.

Description

The OCIGenAIWrapper class extends BaseRagasLLM to provide a native OCI Generative AI integration for Ragas. It wraps the OCI SDK's GenerativeAiClient to send generation requests to OCI-hosted models (such as Cohere Command) and return results in LangChain's LLMResult format, which is the standard output format used across Ragas LLM wrappers.

Key design decisions:

Lazy client initialization: The OCI client is not created at construction time. Instead, _get_client() initializes it on first use. If a pre-built client is passed via the client parameter, that is used directly, enabling dependency injection for testing.
Role-aware message conversion: The _convert_prompt_to_messages method converts LangChain PromptValue objects into OCI-compatible role-based message lists. It supports system, user, and assistant roles by inspecting LangChain message class names, and falls back to a single user message when only a string is available.
Default system prompt: An optional default_system_prompt parameter allows a system-level instruction to be prepended to every request.
Async via thread pool: Since the OCI SDK does not provide native async support, the agenerate_text method wraps synchronous API calls using asyncio.run_in_executor for compatibility with Ragas' async evaluation pipeline.
Analytics tracking: Both initialization and generation calls emit LLMUsageEvent analytics events via Ragas' track function, logging provider, model, and request counts.
Optional OCI SDK: The OCI SDK is imported at the module level inside a try/except block, making it an optional dependency. If the SDK is not installed and no pre-built client is provided, an ImportError is raised at construction time.

The module also provides a factory function oci_genai_factory that creates an OCIGenAIWrapper instance with all constructor parameters forwarded, providing a concise way to instantiate the wrapper.

Usage

Import this module when you need to use Oracle Cloud Infrastructure Generative AI models as the LLM backend for Ragas evaluation. Use oci_genai_factory for a convenient one-liner, or instantiate OCIGenAIWrapper directly for full control over configuration.

Code Reference

Source Location

Repository: Vibrantlabsai_Ragas
File: src/ragas/llms/oci_genai_wrapper.py

Signature

class OCIGenAIWrapper(BaseRagasLLM):
    def __init__(
        self,
        model_id: str,
        compartment_id: str,
        config: Optional[Dict[str, Any]] = None,
        endpoint_id: Optional[str] = None,
        run_config: Optional[RunConfig] = None,
        cache: Optional[Any] = None,
        default_system_prompt: Optional[str] = None,
        client: Optional[Any] = None,
    ): ...

    def generate_text(
        self,
        prompt: PromptValue,
        n: int = 1,
        temperature: Optional[float] = 0.01,
        stop: Optional[List[str]] = None,
        callbacks: Optional[Any] = None,
    ) -> LLMResult: ...

    async def agenerate_text(
        self,
        prompt: PromptValue,
        n: int = 1,
        temperature: Optional[float] = 0.01,
        stop: Optional[List[str]] = None,
        callbacks: Optional[Any] = None,
    ) -> LLMResult: ...

    def is_finished(self, response: LLMResult) -> bool: ...


def oci_genai_factory(
    model_id: str,
    compartment_id: str,
    config: Optional[Dict[str, Any]] = None,
    endpoint_id: Optional[str] = None,
    run_config: Optional[RunConfig] = None,
    cache: Optional[Any] = None,
    default_system_prompt: Optional[str] = None,
    client: Optional[Any] = None,
) -> OCIGenAIWrapper: ...

Import

from ragas.llms import OCIGenAIWrapper
from ragas.llms import oci_genai_factory

I/O Contract

Constructor Parameters

Name	Type	Required	Description
model_id	str	Yes	The OCI model ID to use for generation (e.g., `"cohere.command"`)
compartment_id	str	Yes	The OCI compartment OCID
config	Dict[str, Any]	No	OCI configuration dictionary; uses default from `oci.config.from_file()` if not provided
endpoint_id	str	No	Optional endpoint ID for custom model deployment endpoints
run_config	RunConfig	No	Ragas run configuration; creates a default `RunConfig()` if not provided
cache	Any	No	Optional cache backend for response caching
default_system_prompt	str	No	System-level instruction prepended to every request
client	Any	No	Pre-built OCI GenerativeAiClient instance; bypasses lazy initialization if provided

Inputs (generate_text / agenerate_text)

Name	Type	Required	Description
prompt	PromptValue	Yes	LangChain prompt value to convert and send to OCI
n	int	No	Number of completions to generate (default: 1)
temperature	float	No	Sampling temperature (default: 0.01)
stop	List[str]	No	Stop sequences for generation
callbacks	Any	No	LangChain-compatible callbacks (currently unused)

Outputs

Name	Type	Description
return	LLMResult	LangChain `LLMResult` containing a list of generation lists, each with a `Generation` object holding the generated text

Usage Examples

Basic Usage with Default Config

from ragas.llms import oci_genai_factory

llm = oci_genai_factory(
    model_id="cohere.command",
    compartment_id="ocid1.compartment.oc1..example"
)

# Use with Ragas evaluation
from langchain_core.prompt_values import StringPromptValue
prompt = StringPromptValue(text="What is machine learning?")
result = llm.generate_text(prompt)
print(result.generations[0][0].text)

With Custom Config and System Prompt

from ragas.llms import OCIGenAIWrapper

llm = OCIGenAIWrapper(
    model_id="cohere.command",
    compartment_id="ocid1.compartment.oc1..example",
    config={
        "user": "ocid1.user.oc1..example",
        "key_file": "~/.oci/private_key.pem",
        "fingerprint": "aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99",
        "tenancy": "ocid1.tenancy.oc1..example",
        "region": "us-phoenix-1",
    },
    default_system_prompt="You are a helpful assistant for evaluating AI outputs.",
)

Async Usage

import asyncio
from ragas.llms import oci_genai_factory
from langchain_core.prompt_values import StringPromptValue

llm = oci_genai_factory(
    model_id="cohere.command",
    compartment_id="ocid1.compartment.oc1..example"
)

async def main():
    prompt = StringPromptValue(text="Explain RAG in one sentence.")
    result = await llm.agenerate_text(prompt)
    print(result.generations[0][0].text)

asyncio.run(main())

With Custom Endpoint

from ragas.llms import oci_genai_factory

llm = oci_genai_factory(
    model_id="cohere.command",
    compartment_id="ocid1.compartment.oc1..example",
    endpoint_id="ocid1.generativeaiendpoint.oc1..example"
)

Internal Mechanics

Message Conversion

The _convert_prompt_to_messages method produces role-aware message lists for the OCI API:

If default_system_prompt is set, a system message is prepended.
If the prompt has a to_messages() method (LangChain chat-style), each message is inspected for role via class name heuristics (system, human/user, ai/assistant).
Falls back to to_string() or str() conversion as a single user message.

Generation Request Structure

The _create_generation_request method builds the OCI API request dict:

{
    "compartment_id": self.compartment_id,
    "serving_mode": {"model_id": self.model_id},  # or {"endpoint_id": ...}
    "inference_request": {
        "messages": [...],
        "max_tokens": 1000,
        "temperature": 0.01,
    },
}

When endpoint_id is set, it replaces the model_id in the serving mode.

Related Pages

BaseRagasLLM - base class from ragas.llms.base
oci - Oracle Cloud Infrastructure SDK (optional, lazily imported)
RunConfig - Ragas run configuration from ragas.run_config
LLMUsageEvent - analytics event from ragas._analytics
LLMResult - LangChain result type from langchain_core.outputs
PromptValue - LangChain prompt type from langchain_core.prompt_values

Page Connections

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

Principle

Implementation

Heuristic

Environment