OCI Generative AI Integration for LangChain

src/oss/python/integrations/chat/oci_generative_ai.mdx

@@ -1,76 +1,267 @@
 ---
 title: "ChatOCIGenAI integration"
-description: "Integrate with the ChatOCIGenAI chat model using LangChain Python."
+description: "Integrate with ChatOCIGenAI chat model using LangChain Python."
 ---
 
-This guide provides a quick overview for getting started with OCIGenAI [chat models](/oss/langchain/models). For detailed documentation of all ChatOCIGenAI features and configurations head to the [API reference](https://python.langchain.com/api_reference/community/chat_models/langchain_community.chat_models.oci_generative_ai.ChatOCIGenAI.html).
+This doc will help you get started with Oracle Cloud Infrastructure (OCI) Generative AI [chat models](/oss/langchain/models). OCI Generative AI is a fully managed service providing state-of-the-art, customizable large language models covering a wide range of use cases through a single API. Access ready-to-use pretrained models or create and host fine-tuned custom models on dedicated AI clusters.
 
-Oracle Cloud Infrastructure (OCI) Generative AI is a fully managed service that provides a set of state-of-the-art, customizable Large Language Models (LLMs) that cover a wide range of use cases, and which is available through a single API.
-Using the OCI Generative AI service you can access ready-to-use pretrained models, or create and host your own fine-tuned custom models based on your own data on dedicated AI clusters. Detailed documentation of the service and API is available __[here](https://docs.oracle.com/en-us/iaas/Content/generative-ai/home.htm)__ and __[here](https://docs.oracle.com/en-us/iaas/api/#/en/generative-ai/20231130/)__.
+For detailed documentation, see the [OCI Generative AI documentation](https://docs.oracle.com/en-us/iaas/Content/generative-ai/home.htm) and [API reference](https://docs.oracle.com/en-us/iaas/api/#/en/generative-ai/20231130/).
 
 ## Overview
 
 ### Integration details
 
-| Class | Package | Serializable | [JS support](https://js.langchain.com/docs/integrations/chat/oci_generative_ai) |
-| :--- | :--- | :---: |  :---: |
-| [ChatOCIGenAI](https://python.langchain.com/api_reference/community/chat_models/langchain_community.chat_models.oci_generative_ai.ChatOCIGenAI.html) | [langchain-community](https://python.langchain.com/api_reference/community/index.html) | ❌ | ❌ |
+| Class | Package | Serializable | JS support | Downloads | Version |
+| :--- | :--- | :---: |  :---: | :---: | :---: |
+| [ChatOCIGenAI](https://python.langchain.com/api_reference/oci/chat_models/langchain_oci.chat_models.oci_genai.ChatOCIGenAI.html) | [langchain-oci](https://python.langchain.com/api_reference/oci/index.html) | beta | ❌ | ![PyPI - Downloads](https://img.shields.io/pypi/dm/langchain-oci?style=flat-square&label=%20) | ![PyPI - Version](https://img.shields.io/pypi/v/langchain-oci?style=flat-square&label=%20) |
 
 ### Model features
 
 | [Tool calling](/oss/langchain/tools/) | [Structured output](/oss/langchain/structured-output) | [Image input](/oss/langchain/messages#multimodal) | Audio input | Video input | [Token-level streaming](/oss/langchain/streaming/) | Native async | [Token usage](/oss/langchain/models#token-usage) | [Logprobs](/oss/langchain/models#log-probabilities) |
 | :---: | :---: | :---: |  :---: | :---: | :---: | :---: | :---: | :---: |
-| ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ |
+| ✅ | ✅ | ✅ | ✅ (Gemini) | ✅ (Gemini) | ✅ | ✅ | ✅ | ❌ |
 
 ## Setup
 
-To access OCIGenAI models you'll need to install the `oci` and `langchain-community` packages.
-
-### Credentials
+### Installation
 
-The credentials and authentication methods supported for this integration are equivalent to those used with other OCI services and follow the __[standard SDK authentication](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/sdk_authentication_methods.htm)__ methods, specifically API Key, session token, instance principal, and resource principal.
+<CodeGroup>
+```bash pip
+pip install -qU langchain-oci oci
+```
 
-API key is the default authentication method used in the examples above. The following example demonstrates how to use a different authentication method (session token)
+```bash uv
+uv add langchain-oci oci
+```
+</CodeGroup>
 
-### Installation
+### Credentials
 
-The LangChain OCIGenAI integration lives in the `langchain-community` package and you will also need to install the `oci` package:
+Set up authentication with the OCI CLI (creates `~/.oci/config`):
 
-```python
-pip install -qU langchain-community oci
+```bash
+oci setup config
 ```
 
-## Instantiation
+For other auth methods (session tokens, instance principals), see [OCI SDK authentication](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/sdk_authentication_methods.htm).
 
-Now we can instantiate our model object and generate chat completions:
+## Instantiation
 
 ```python
-from langchain_community.chat_models.oci_generative_ai import ChatOCIGenAI
-from langchain.messages import AIMessage, HumanMessage, SystemMessage
+from langchain_oci import ChatOCIGenAI
 
-chat = ChatOCIGenAI(
-    model_id="cohere.command-r-16k",
+llm = ChatOCIGenAI(
+    model_id="meta.llama-3.3-70b-instruct",
     service_endpoint="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com",
-    compartment_id="MY_OCID",
-    model_kwargs={"temperature": 0.7, "max_tokens": 500},
+    compartment_id="ocid1.compartment.oc1..your-compartment-id",
+    model_kwargs={"temperature": 0.7, "max_tokens": 500},  # Optional
 )
 ```
 
+**Key parameters:**
+- `model_id` - The model to use (see [available models](#available-models))
+- `service_endpoint` - Regional endpoint (`us-chicago-1`, `eu-frankfurt-1`, etc.)
+- `compartment_id` - Your OCI compartment OCID
+- `model_kwargs` - Model settings like temperature, max_tokens
+
 ## Invocation
 
 ```python
 messages = [
-    SystemMessage(content="your are an AI assistant."),
-    AIMessage(content="Hi there human!"),
-    HumanMessage(content="tell me a joke."),
+    (
+        "system",
+        "You are a helpful assistant that translates English to French.",
+    ),
+    ("human", "I love programming."),
 ]
-response = chat.invoke(messages)
+ai_msg = llm.invoke(messages)
+print(ai_msg.content)
 ```
 
+```text
+J'adore la programmation.
+```
+
+### Multi-turn Conversations
+
 ```python
+from langchain.messages import HumanMessage, AIMessage
+
+messages = [
+    HumanMessage(content="Hi, I'm Alice."),
+    AIMessage(content="Hello Alice! How can I help you today?"),
+    HumanMessage(content="What's my name?"),
+]
+
+response = llm.invoke(messages)
 print(response.content)
 ```
 
-## API reference
+```text
+Your name is Alice.
+```
+
+## Streaming
+
+Get responses as they're generated:
+
+```python
+for chunk in llm.stream(messages):
+    print(chunk.content, end="", flush=True)
+```
+
+## Async
+
+Use async for concurrent requests or non-blocking applications:
+
+```python
+import asyncio
+
+# Async generation
+response = await llm.ainvoke("What is 2+2?")
+
+# Async streaming
+async for chunk in llm.astream("Tell me a story"):
+    print(chunk.content, end="")
+
+# Run multiple requests concurrently
+results = await asyncio.gather(
+    llm.ainvoke("What is 2+2?"),
+    llm.ainvoke("What is 3+3?"),
+)
+```
+
+## Tool Calling
+
+Give models access to external functions (APIs, databases, etc.):
+
+```python
+from langchain.tools import tool
+
+@tool
+def get_weather(city: str) -> str:
+    """Get the weather for a city."""
+    # In production, call a weather API
+    return f"Weather in {city}: 72°F, sunny"
+
+llm_with_tools = llm.bind_tools([get_weather])
+response = llm_with_tools.invoke("What's the weather in Chicago?")
+
+# Model decides to call the tool
+print(response.tool_calls)
+# [{'name': 'get_weather', 'args': {'city': 'Chicago'}, 'id': 'call_1'}]
+```
+
+**Parallel tools** (Llama 4+ only) execute multiple tools simultaneously:
+
+```python
+llm = ChatOCIGenAI(model_id="meta.llama-4-scout-17b-16e-instruct", ...)
+llm_with_tools = llm.bind_tools(
+    [get_weather, get_time],
+    parallel_tool_calls=True,
+)
+# "Weather in Chicago and time in NYC?" → calls both tools at once
+```
+
+## Structured Output
+
+Extract data into Pydantic models for type-safe parsing:
+
+```python
+from pydantic import BaseModel
+
+class Person(BaseModel):
+    name: str
+    age: int
+    email: str
+
+structured_llm = llm.with_structured_output(Person)
+result = structured_llm.invoke("John is 30 years old, email john@example.com")
+
+print(result.name)   # "John"
+print(result.age)    # 30
+print(result.email)  # "john@example.com"
+```
+
+## Vision & Multimodal
+
+Analyze images with vision-capable models:
+
+```python
+from langchain.messages import HumanMessage
+from langchain_oci import ChatOCIGenAI, load_image
+
+llm = ChatOCIGenAI(model_id="meta.llama-3.2-90b-vision-instruct", ...)
+
+message = HumanMessage(content=[
+    {"type": "text", "text": "What's in this image?"},
+    load_image("./photo.jpg"),  # Or use a URL
+])
+
+response = llm.invoke([message])
+```
+
+**Vision-capable models:** Llama 3.2 Vision, Gemini 2.0/2.5, Grok 4, Command A Vision
+
+## Gemini Multimodal (PDF, Video, Audio)
+
+Gemini models process PDFs, videos, and audio:
+
+```python
+import base64
+from langchain.messages import HumanMessage
+
+llm = ChatOCIGenAI(model_id="google.gemini-2.5-flash", ...)
+
+# Load file as base64
+with open("document.pdf", "rb") as f:
+    data = base64.b64encode(f.read()).decode()
+
+message = HumanMessage(content=[
+    {"type": "text", "text": "Summarize this document"},
+    {"type": "media", "data": data, "mime_type": "application/pdf"}
+])
+
+response = llm.invoke([message])
+```
+
+**Supported formats:** PDF, MP4/MOV video, MP3/WAV audio (Gemini 2.0/2.5 only)
+
+## Configuration
+
+Control model behavior with `model_kwargs`:
+
+```python
+llm = ChatOCIGenAI(
+    model_id="meta.llama-3.3-70b-instruct",
+    model_kwargs={
+        "temperature": 0.7,    # Creativity (0-1)
+        "max_tokens": 500,     # Response length limit
+        "top_p": 0.9,         # Nucleus sampling
+    },
+    # ... other params
+)
+```
+
+## Available Models
+
+| Provider | Example Models | Key Features |
+|----------|----------------|--------------|
+| **Meta** | Llama 3.2/3.3/4 (Scout, Maverick) | Vision, parallel tools |
+| **Google** | Gemini 2.0/2.5 Flash, Pro | PDF, video, audio |
+| **xAI** | Grok 3, Grok 4 | Vision, reasoning |
+| **Cohere** | Command R+, Command A | RAG, vision |
+
+See the [OCI model catalog](https://docs.oracle.com/en-us/iaas/Content/generative-ai/pretrained-models.htm) for the complete list and regional availability.
+
+## API Reference
+
+For detailed documentation of all ChatOCIGenAI features and configurations, see the [API reference](https://python.langchain.com/api_reference/oci/chat_models/langchain_oci.chat_models.oci_genai.ChatOCIGenAI.html).
+
+## Related
 
-For detailed documentation of all ChatOCIGenAI features and configurations head to the API reference: [python.langchain.com/api_reference/community/chat_models/langchain_community.chat_models.oci_generative_ai.ChatOCIGenAI.html](https://python.langchain.com/api_reference/community/chat_models/langchain_community.chat_models.oci_generative_ai.ChatOCIGenAI.html)
+- [OCI Provider Overview](/oss/integrations/providers/oci)
+- [OCI Embeddings](/oss/integrations/text_embedding/oci_generative_ai)
+- [Tool Calling Guide](/oss/langchain/tools/)
+- [Structured Output Guide](/oss/langchain/structured-output)
+- [Multimodal Messages](/oss/langchain/messages#multimodal)