feat: add OCI Generative AI provider — basic text completion

[fede-kamel]

Summary

• Add native OCI Generative AI text completion provider (OCICompletion) supporting generic (Meta, Google, OpenAI, xAI) and Cohere model families
• Shared OCI auth utilities (utilities/oci.py) for API key, security token, instance principal, and resource principal auth
• OCI registered as optional dependency (crewai[oci])
• 15 unit tests (mocked SDK) + 2 parametrized integration tests (tested live against meta.llama-3.3-70b-instruct, cohere.command-r-plus-08-2024, google.gemini-2.5-flash, openai.gpt-5.2-chat-latest)

This is PR 1 of a series — follow-up PRs will add streaming, tool calling, structured output, multimodal, and embeddings support.

Supersedes #4885 (closed per reviewer feedback to split by scope).
Tracking issue: #4944

What's included

File	Lines	What
utilities/oci.py	72	Shared get_oci_module() + create_oci_client_kwargs()
llms/providers/oci/completion.py	505	OCICompletion(BaseLLM) — init, message building, basic call/acall
llm.py	+13	Provider registration (routing, pattern matching, import)
pyproject.toml	+3	oci optional dependency
Tests	491	conftest + 15 unit + 2 integration (parametrized across models)

What's NOT included (deferred to follow-up PRs)

• Streaming (iter_stream, astream)
• Tool calling / function calling
• Structured output (response_model)
• Multimodal (vision, documents, audio, video)
• OCI embeddings provider
• OCI tools (will be a standalone PyPI package per community tools guidelines)

Test plan

• 15 unit tests pass (mocked OCI SDK, no credentials needed)
• Integration tests pass against 4 model families via OCI GenAI API:
  • meta.llama-3.3-70b-instruct
  • cohere.command-r-plus-08-2024
  • google.gemini-2.5-flash
  • openai.gpt-5.2-chat-latest
• Both sync (call) and async (acall) paths verified

---

Note

Medium Risk
Introduces a new native LLM provider and OCI authentication paths; risk is mainly around request/response translation and credential/config handling for a new external SDK.

Overview
Adds native Oracle Cloud Infrastructure (OCI) Generative AI support for basic chat/text completion via a new OCICompletion provider, including model-family request shaping (generic vs Cohere) and sync/async call paths with token-usage tracking.

Registers oci as a supported native provider in LLM routing (prefix handling + model pattern matching) and adds a shared utilities/oci.py helper for lazy SDK import plus multiple OCI auth modes. Includes an optional dependency crewai[oci] and a new test suite with mocked-SDK unit tests plus opt-in live integration tests.

^{Reviewed by Cursor Bugbot for commit d7e6ffd. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• New Features

  • Added Oracle Cloud Infrastructure (OCI) Generative AI as a native LLM provider for CrewAI (sync/async support, model routing, request/response handling).
  • Added OCI utility to configure clients and authentication modes.

• Chores

  • Added optional dependency group for OCI SDK (requires oci>=2.168.0).

• Tests

  • Added unit tests, fixtures, and live integration tests for OCI provider.

[fede-kamel]

@greysonlalonde Hey! Following up on your feedback from #4885 — I split the original PR into smaller, scoped pieces. This is the first one: just the basic text completion provider for OCI GenAI (no streaming, no tools, no structured output, no multimodal, no embeddings).

I couldn't trim this one further — it's the minimal foundation (provider class + shared auth + registration) plus tests. The source code is ~600 lines and the rest is test fixtures/tests. Each follow-up PR will layer on one capability at a time.

Also, per the community tools guide you shared — the OCI tools (InvokeAgent, KnowledgeBase, ObjectStorage) will go into a standalone PyPI package (crewai-oci-tools), not into the crewAI repo.

Would appreciate a review whenever you get a chance. Thanks!

[fede-kamel]

@greysonlalonde @lorenzejay — bump for review.

Status

• ✅ Rebased onto main (was 51 behind, clean rebase)
• ✅ Real bug fix included: param-name routing now matches _is_openai_gpt5_family() instead of broad openai.*
• ✅ Live-tested end-to-end across all 7 model families OCI offers in us-chicago-1 via the v1 (/20231130/Chat) API

Bug fixed in the latest commit (d15e5d49)

_build_chat_request previously routed any openai.* model to max_completion_tokens, while _is_openai_gpt5_family() (used elsewhere in the same method for temperature and stop) only matches openai.gpt-5*. That mismatch meant openai.gpt-4o and openai.gpt-4.1 got the wrong field — the predicate is now consistent across all three call sites.

Live E2E verification — 7/7 pass

$ uv run --no-sync python <e2e probe>
model                                          budget  result
------------------------------------------------------------------------------
  ✅ openai.gpt-5.5                              256   'ok'   (max_completion_tokens)
  ✅ openai.gpt-5                                256   'ok'   (max_completion_tokens)
  ✅ openai.gpt-4o                                64   'Ok.'  (max_tokens)
  ✅ openai.gpt-4.1                               64   'ok'   (max_tokens)
  ✅ meta.llama-3.3-70b-instruct                  64   'ok'   (GENERIC)
  ✅ meta.llama-4-scout-17b-16e-instruct          64   'ok'   (GENERIC)
  ✅ cohere.command-latest                        64   'ok'   (COHERE / CohereChatRequest)

This includes openai.gpt-5.5 — the April 2026 GPT-5.5 release on OCI — which is functional through the crewAI provider.

Unit tests — 16/16 pass

$ uv run --no-sync pytest lib/crewai/tests/llms/oci/ -q
ss................                                                       [100%]
16 passed, 2 skipped in 3.54s

Two new tests cover the routing both ways:

• test_oci_gpt5_family_uses_max_completion_tokens — GPT-5.5 → max_completion_tokens
• test_oci_openai_gpt4o_keeps_max_tokens — GPT-4o → max_tokens (regression guard)

API correctness

The provider hits OCI's /20231130/ v1 API directly (the only public version — Oracle uses date-stamped versions, no v1/v2 split). GenericChatRequest (api_format=GENERIC) covers Llama / Gemini / Grok / Mistral / Nvidia / OpenAI families; CohereChatRequest (api_format=COHERE) covers Cohere. Both serving modes (on-demand + dedicated via OCID) are supported.

This is the foundation PR of the 7-PR series (#4961 streaming, #4962 tools, #4963 structured output, #4964 multimodal, #4966 embeddings, #4982 async). Ready when you are. 🙏

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 1135650e-33ae-4696-90b6-b7ac4fb0cb86

📥 Commits

Reviewing files that changed from the base of the PR and between 3645af6 and 27be9a5.

📒 Files selected for processing (1)

• lib/crewai/src/crewai/llms/providers/oci/completion.py

🚧 Files skipped from review as they are similar to previous changes (1)

• lib/crewai/src/crewai/llms/providers/oci/completion.py

---

📝 Walkthrough

Walkthrough

This PR adds OCI Generative AI as a native LLM provider: optional dependency, LLM routing updates, OCICompletion implementation with request/response handling and model-specific quirks, OCI client utilities for multiple auth modes, and unit + live integration tests.

Changes

OCI Generative AI Provider

Layer / File(s)	Summary
OCI Provider Registration and Routing lib/crewai/pyproject.toml, lib/crewai/src/crewai/llm.py, lib/crewai/src/crewai/llms/providers/oci/__init__.py	Adds oci>=2.168.0 optional dependency, registers "oci" in supported providers, maps oci/ model prefixes to provider "oci", adds pattern-matching for OCI model identifiers, and returns OCICompletion from native provider resolution.
OCI Client Configuration and Authentication lib/crewai/src/crewai/utilities/oci.py	Lazy-loads the optional OCI SDK and provides create_oci_client_kwargs() to assemble client kwargs and signers for API_KEY, SECURITY_TOKEN, INSTANCE_PRINCIPAL, and RESOURCE_PRINCIPAL auth flows.
OCICompletion Implementation lib/crewai/src/crewai/llms/providers/oci/completion.py	Implements OCICompletion: constructor, provider/serving-mode inference, message coercion/normalization, Cohere vs generic request shaping, conditional generation params (temperature, max_tokens vs max_completion_tokens, top_p/top_k, reasoning_effort, stop handling), response parsing (text, finish reason, usage), thread-safe client calls, lifecycle events, token tracking, and sync/async APIs.
Test Fixtures and Configuration lib/crewai/tests/llms/oci/conftest.py	Adds pytest fixtures and helpers: fake OCI SDK module, response factory functions, patch fixture for _get_oci_module, unit defaults, and live-test helpers that source models and config from environment variables.
Unit Tests: Routing, Initialization, and Request Building lib/crewai/tests/llms/oci/test_oci.py	Adds tests covering OCI routing, provider-family inference, initialization params, endpoint construction from region env var, chat call behavior for generic and Cohere responses, message normalization, model-family request quirks (GPT-5 uses max_completion_tokens, GPT-4o retains max_tokens, GPT-5 omits unsupported temperature/stop), and acall() delegation.
Integration Tests: Live OCI Completion lib/crewai/tests/llms/oci/test_oci_integration_basic.py	Adds two live integration tests (sync and async) that instantiate OCICompletion and perform a basic chat completion asserted to return non-empty text; tests are driven by environment-provided OCI config and models.

🎯 3 (Moderate) | ⏱️ ~25 minutes

🐰 A provider hopped in with OCI dreams,
Messages flow through LLM streams,
Tokens counted, responses parsed,
Async calls handled with threading's art,
Tests ensure the chat will gleam! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 72.55% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: adding an OCI Generative AI provider with basic text completion support, which aligns with the substantial implementation across multiple files (provider class, auth utilities, routing, and tests).
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@lib/crewai/tests/llms/oci/conftest.py`:
- Around line 170-175: The current pattern uses if os.getenv("VAR"):
config["key"] = os.getenv("VAR", "default") which makes the default unreachable;
change to capture the env value once and use it (e.g., value =
os.getenv("OCI_AUTH_TYPE"); if value: config["auth_type"] = value) for each of
OCI_AUTH_TYPE, OCI_AUTH_PROFILE, and OCI_AUTH_FILE_LOCATION (referencing config
and os.getenv) so you don't call os.getenv twice and eliminate the dead default
arguments.

In `@lib/crewai/tests/llms/oci/test_oci_integration_basic.py`:
- Line 7: Update the run instruction that points to
tests/llms/oci/test_oci_integration_basic.py so it uses the correct repository
path (lib/crewai/tests/llms/oci/test_oci_integration_basic.py); change the
command line shown (uv run pytest ...) to reference the full correct path or to
run pytest from repo root (e.g., uv run pytest
lib/crewai/tests/llms/oci/test_oci_integration_basic.py -v) so contributors can
execute the test as written.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: d79e554b-3f40-4adc-a0bb-6de0c6eff7e9

📥 Commits

Reviewing files that changed from the base of the PR and between a95d267 and 3645af6.

📒 Files selected for processing (9)

• lib/crewai/pyproject.toml
• lib/crewai/src/crewai/llm.py
• lib/crewai/src/crewai/llms/providers/oci/__init__.py
• lib/crewai/src/crewai/llms/providers/oci/completion.py
• lib/crewai/src/crewai/utilities/oci.py
• lib/crewai/tests/llms/oci/__init__.py
• lib/crewai/tests/llms/oci/conftest.py
• lib/crewai/tests/llms/oci/test_oci.py
• lib/crewai/tests/llms/oci/test_oci_integration_basic.py

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Remove redundant os.getenv() calls; defaults are unreachable dead code.

The pattern if os.getenv(X): followed by os.getenv(X, default) means the default parameter can never be used—you've already verified the variable is truthy. The defaults "API_KEY", "DEFAULT", and "~/.oci/config" on lines 171, 173, and 175 are dead code.

♻️ Simplify by removing the redundant second call

-    if os.getenv("OCI_AUTH_TYPE"):
-        config["auth_type"] = os.getenv("OCI_AUTH_TYPE", "API_KEY")
-    if os.getenv("OCI_AUTH_PROFILE"):
-        config["auth_profile"] = os.getenv("OCI_AUTH_PROFILE", "DEFAULT")
-    if os.getenv("OCI_AUTH_FILE_LOCATION"):
-        config["auth_file_location"] = os.getenv("OCI_AUTH_FILE_LOCATION", "~/.oci/config")
+    if auth_type := os.getenv("OCI_AUTH_TYPE"):
+        config["auth_type"] = auth_type
+    if auth_profile := os.getenv("OCI_AUTH_PROFILE"):
+        config["auth_profile"] = auth_profile
+    if auth_file := os.getenv("OCI_AUTH_FILE_LOCATION"):
+        config["auth_file_location"] = auth_file

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@lib/crewai/tests/llms/oci/conftest.py` around lines 170 - 175, The current
pattern uses if os.getenv("VAR"): config["key"] = os.getenv("VAR", "default")
which makes the default unreachable; change to capture the env value once and
use it (e.g., value = os.getenv("OCI_AUTH_TYPE"); if value: config["auth_type"]
= value) for each of OCI_AUTH_TYPE, OCI_AUTH_PROFILE, and OCI_AUTH_FILE_LOCATION
(referencing config and os.getenv) so you don't call os.getenv twice and
eliminate the dead default arguments.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fix the pytest path in the run instructions.

Line 7 points to tests/llms/oci/test_oci_integration_basic.py, but this file lives under lib/crewai/tests/..., so the command is likely wrong for contributors copying it verbatim.

Suggested diff

-    uv run pytest tests/llms/oci/test_oci_integration_basic.py -v
+    uv run pytest lib/crewai/tests/llms/oci/test_oci_integration_basic.py -v

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	uv run pytest tests/llms/oci/test_oci_integration_basic.py -v
	uv run pytest lib/crewai/tests/llms/oci/test_oci_integration_basic.py -v

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@lib/crewai/tests/llms/oci/test_oci_integration_basic.py` at line 7, Update
the run instruction that points to tests/llms/oci/test_oci_integration_basic.py
so it uses the correct repository path
(lib/crewai/tests/llms/oci/test_oci_integration_basic.py); change the command
line shown (uv run pytest ...) to reference the full correct path or to run
pytest from repo root (e.g., uv run pytest
lib/crewai/tests/llms/oci/test_oci_integration_basic.py -v) so contributors can
execute the test as written.

[fede-kamel]

Hi @greysonlalonde @lorenzejay — gentle nudge from the maintainer team.

This PR has been waiting for a fresh review since 2026-03-19. Since the last update:

• ✅ Rebased clean onto current main (was 65 commits behind; now mergeable, no conflicts)
• ✅ Coderabbit pre-merge checks now passing — the only flagged item was docstring coverage at 45.10%; just pushed 27be9a5a adding docstrings to all 14 missing methods on OCICompletion, coverage is now 100%
• ✅ Live-tested against OCI Generative AI us-chicago-1 (API_KEY auth) for Meta-Llama, Google-Gemini, OpenAI-GPT5, xAI-Grok, Cohere-Command families
• ✅ All 6 follow-up PRs (feat: add streaming support to OCI Generative AI provider #4961, feat: add tool calling support to OCI Generative AI provider #4962, feat: add structured output support to OCI Generative AI provider #4963, feat: add multimodal support to OCI Generative AI provider #4964, feat: add OCI Generative AI embeddings provider #4966, feat: add true async support to OCI provider via aiohttp #4982) also rebased clean — they're held in draft until this foundation lands

This is the scoped-down split that @greysonlalonde requested back in #4885. Happy to address any remaining concerns. Is there a way to get this into a review queue?

[github-actions]

This PR is stale because it has been open for 45 days with no activity.

[fede-kamel]

Rebased onto current main (85c467d) — merge conflicts resolved, PR is mergeable again.

Also addressed both CodeRabbit comments: the unreachable os.getenv defaults in the live-config fixture are gone, and the pytest run instructions now use the lib/crewai/ prefix.

Verified live against OCI Generative AI on-demand (us-chicago-1): basic completion passes for all five current model families — cohere.command-a-03-2025, meta.llama-4-scout-17b-16e-instruct, google.gemini-2.5-flash, xai.grok-4.3, and openai.gpt-oss-120b. Unit suite: 16 passed.

[fede-kamel]

@joaomdmoura @lorenzejay this provider stack is ready for review — rebased onto current main this week, all mergeable, and verified live against OCI Generative AI on-demand (all five current model families, plus the Cohere v2 vision format).

Suggested review order (each PR builds on the previous):

1. feat: add OCI Generative AI provider — basic text completion #4959 — core completion (this PR)
2. feat: add streaming support to OCI Generative AI provider #4961 — streaming
3. feat: add tool calling support to OCI Generative AI provider #4962 — tool calling
4. feat: add structured output support to OCI Generative AI provider #4963 — structured output
5. feat: add multimodal support to OCI Generative AI provider #4964 — multimodal + COHEREV2 api format
6. feat: add OCI Generative AI embeddings provider #4966 — embeddings (RAG factory)
7. feat: add true async support to OCI provider via aiohttp #4982 — true async via aiohttp

Happy to squash the stack into fewer PRs if you'd prefer it that way.