Add framework helpers for LangChain, PydanticAI, and OpenAI Agents SDK

[fede-kamel]

Depends on: #10 (auth improvements) — please merge that first. Once merged, this PR's diff will only show the framework-specific additions.

Problem

The OCI Enterprise AI Agents documentation lists these frameworks as compatible:

Compatible agent frameworks include: OpenAI Agents SDK, OpenAI Codex SDK, Microsoft Agent Framework, LangChain, LangGraph, CrewAI, AutoGen, LlamaIndex, Pydantic

None of them work out of the box. Both OCI GenAI endpoints require custom headers that no framework exposes as parameters:

Endpoint	API format	Required header
/openai/v1	Responses	OpenAI-Project (GenAI Project OCID)
/openai/v1	Chat completions	opc-compartment-id
/20231130/actions/v1	Responses	opc-compartment-id
/20231130/actions/v1	Chat completions	opc-compartment-id

Verified against the live endpoint — every combination without the required header returns 400. There is no combination that works with just base_url + api_key like other providers (Together AI, Groq, Fireworks, Azure).

ChatOpenAI, PydanticAI Agent, etc. have no project or compartment_id parameter — there is no way to set these headers through their public API without workarounds.

Additionally, OCI IAM auth requires a custom httpx.Auth handler to sign requests. Only frameworks that accept a custom http_client= parameter can use it.

This means a developer following Oracle's docs will write:

from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
    model="openai.gpt-5.2",
    base_url="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/openai/v1",
    api_key=os.getenv("OCI_GENAI_API_KEY"),
    # project=PROJECT_OCID  ← doesn't exist in ChatOpenAI
    # compartment_id=...    ← doesn't exist either
)
# → fails with 400: "OpenAI-Project or opc-compartment-id must be provided"

Solution

One-liner builders that make the documented claim true:

from oci_genai_auth import build_langchain_chat

llm = build_langchain_chat(
    model="openai.gpt-5.2",
    project_ocid="ocid1.generativeaiproject.oc1...",
    profile_name="DEFAULT",
)
response = llm.invoke("Hello!")  # works

Each builder handles OCI signing + required header injection using only the framework's public API — no monkey-patches, no undocumented internals:

Builder	Framework	How it works
build_langchain_chat	LangChain / LangGraph	Passes pre-signed httpx.Client via http_client=
build_pydantic_ai_model	PydanticAI	Passes pre-signed AsyncOpenAI via OpenAIProvider(openai_client=)
configure_openai_agents	OpenAI Agents SDK	Calls set_default_openai_client() with pre-signed AsyncOpenAI
build_openai_client	OpenAI SDK	Convenience wrapper around the existing common.py pattern
build_http_client	Any framework	Low-level signed httpx.Client with project + compartment headers

Optional dependencies keep the library lightweight:

pip install oci-genai-auth[langchain]
pip install oci-genai-auth[pydantic-ai]
pip install oci-genai-auth[agents]

Includes region validation (regex) to prevent URL injection via the region parameter.

Test plan

• 15 unit tests for builders, auth resolution, header injection, region validation, and import error messages
• 5 live integration tests against the OCI endpoint (OpenAI sync, async, Agents SDK, LangChain, PydanticAI)
• Integration tests auto-skip without OCI_GENAI_* env vars
• All existing tests still pass

Future work

CrewAI, AutoGen, and LlamaIndex require workarounds using undocumented framework internals (litellm client passthrough, deepcopy patching, model name validator monkey-patching). These are intentionally excluded from this PR — they work today but could break on framework updates. They can be contributed as examples or added once those frameworks support custom http_client parameters.

Fixes #13

[fede-kamel]

@shenoyvvarun This builds on #10 (auth fixes). The OCI docs list LangChain, PydanticAI, and other frameworks as compatible, but none of them work out of the box because ChatOpenAI and other framework classes don't have a project parameter and can't set the required OpenAI-Project header. This PR adds one-liner builders that solve that — using only each framework's public API, no hacks.

[fede-kamel]

@shenoyvvarun Follow-up on this one as well — depends on #10 for the auth fixes. Ready for review. Thanks!

[shenoyvvarun]

Thank you for making this change, we really appreciate your contribution. I will most likely reject this PR waiting on @ericjy 's feedback.

• One of the key tenants used for designing this library has been to avoid adding SDK dependency. This is done in-order to keep release process and integration with new models onboarding easier.
• By keeping the core auth library simple, we rely on robust examples and docs to help customers use various SDKs like langchain, pydantic, openai etc.
• The initial version had more examples but, we decided keep it out of oci-genai-auth libary . Instead @OpheliaLjh is working on a dedicated repo in-order to house the docs.
• @ericjy Do you think meanwhile, we should add these examples until that repo is published? Also lmk if you agree with my reasoning

Also, Sharing the examples for the libraries you mentioned above

Langchain (PT mode),

ChatOpenAI(
        model="xai.grok-4-1-fast-reasoning",
        base_url="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/v1",
        api_key="not-used",
        http_client=httpx.Client(
            auth=OciSessionAuth(profile_name="DEFAULT"),
            headers={"opc-compartment-id": "ocid1.tenancy.oc1..example"}
        ),
    )

Langchain (Non PT mode)

ChatOpenAI(
        model="xai.grok-4-1-fast-reasoning",
        base_url="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/openai/v1",
        api_key="not-used",
        http_client=httpx.Client(
            auth=session_auth,
            headers={"OpenAI-Project": "ocid1.generativeaiproject.oc1.us-chicago-1.example_project"}
        ),
        use_responses_api=True,
        )
    
    
# verification:

first_response = llm.invoke("Hi, I'm Bob.")
print(first_response.text)

second_response = llm.invoke(
    "What is my name?",
    previous_response_id=first_response.id,
)
print(second_response.text)

Pydantic AI (Non-PT mode)

    async with httpx.AsyncClient(
        auth=session_auth,
        headers={"OpenAI-Project": project_id},
    ) as http_client:
        provider = OpenAIProvider(
            base_url="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/openai/v1",
            api_key="not-used",
            http_client=http_client,
        )
        model = OpenAIResponsesModel("xai.grok-4-1-fast-reasoning", provider=provider)
        agent = Agent(model)

        result = await agent.run("Tell me a joke about owls.")
        print(result.output)