Add comprehensive documentation overhaul with tutorials by fede-kamel · Pull Request #144 · oracle/langchain-oracle

fede-kamel · 2026-02-19T16:45:35Z

Summary

Comprehensive documentation overhaul for langchain-oci covering all features developed over the past 3 months.

Closes #145

Changes

Tutorials (8 comprehensive guides)

Tutorial	Description
01. Getting Started	Authentication, basic chat, provider intro
02. Vision & Multimodal	Images, PDFs, video, audio with Gemini
03. Building AI Agents	create_oci_agent(), checkpointing, memory
04. Tool Calling Mastery	Parallel tools, workflows, loop detection
05. Structured Output	Pydantic, JSON modes
07. Async for Production	ainvoke, astream, FastAPI integration
09. Provider Deep Dive	Meta, Gemini, Cohere, xAI, OpenAI specifics
10. Embeddings	Text + image embeddings, RAG patterns

Reference Documentation

docs/API_REFERENCE.md - Complete class/method signatures
docs/MODELS.md - Model IDs, capabilities, selection guide
docs/CHANGELOG.md - Version history

Other Changes

Enhanced CONTRIBUTING.md with dev setup, architecture
Updated README.md with complete tutorial links and API reference
Added pyproject.toml config for tutorials (ruff T201 ignore, mypy exclude)

Test Plan

All make lint checks pass (ruff check, ruff format, mypy)
All make test checks pass (Python 3.9, 3.12, 3.13)
Tutorial code examples are syntactically correct
Links in README resolve correctly

fede-kamel · 2026-02-20T22:46:18Z

I tested all 10 tutorials end-to-end with OCI GenAI and they all pass successfully:

Tutorial 01 - Getting Started: Authentication and basic chat work correctly
Tutorial 02 - Vision & Multimodal: Image, PDF, video, and audio processing verified with Gemini
Tutorial 03 - Building AI Agents: Agent creation, checkpointing, and memory tested
Tutorial 04 - Tool Calling Mastery: Parallel tools, workflows, and loop detection confirmed working
Tutorial 05 - Structured Output: Pydantic and JSON output modes validated
Tutorial 06 - Model Deployments: vLLM, TGI, and custom endpoint configurations verified
Tutorial 07 - Async for Production: ainvoke, astream, and FastAPI integration tested
Tutorial 08 - OpenAI Responses API: ChatOCIOpenAI and conversation stores working
Tutorial 09 - Provider Deep Dive: Meta, Gemini, Cohere, and xAI provider specifics confirmed
Tutorial 10 - Embeddings: Text and image embeddings with RAG patterns validated

All code examples execute without errors and produce expected results.

This commit introduces a complete documentation overhaul covering recent features including vision/multimodal, async support, agents, tool calling, and embeddings. Changes: - Rewrite libs/oci/README.md with full feature coverage - Add tutorials/ directory with progressive learning path - 8 comprehensive tutorials with code examples: - 01-getting-started: Authentication, ChatOCIGenAI, providers - 02-vision-and-multimodal: 13 vision models, Gemini PDF/video/audio - 03-building-ai-agents: create_oci_agent, checkpointing, HiTL - 04-tool-calling-mastery: parallel tools, workflows - 05-structured-output: Pydantic schemas, JSON modes - 07-async-for-production: ainvoke, astream, FastAPI - 10-embeddings: text & image embeddings, RAG patterns - Add tutorials/README.md with learning path index Features documented: - Vision support (13 models, load_image, encode_image) - Gemini multimodal (PDF, video, audio) - Async support (ainvoke, astream, abatch) - AI Agents (create_oci_agent, checkpointing, LangGraph) - Tool calling (parallel_tool_calls, max_sequential_tool_calls) - Structured output (with_structured_output, json_mode) - Image embeddings (embed_image, embed_image_batch)

Tutorial 06 (Model Deployments): - ChatOCIModelDeployment, ChatOCIModelDeploymentVLLM, ChatOCIModelDeploymentTGI - vLLM and TGI specific parameters - Custom endpoint extension patterns - Streaming and async operations Tutorial 08 (OpenAI Responses API): - ChatOCIOpenAI for OpenAI Responses API compatibility - OCI authentication (session, resource principal, instance principal) - Conversation stores for persistent memory - Web search and hosted MCP integration - Migration guide from OpenAI Tutorial 09 (Provider Deep Dive): - Provider architecture and auto-detection - Meta Llama: vision, parallel tools, tool_result_guidance - Google Gemini: PDF, video, audio multimodal - Cohere: RAG with citations, V2 vision API - xAI Grok: reasoning content access - Provider selection guide and feature matrix

Reference Docs (libs/oci/docs/): - API_REFERENCE.md: Complete class/method signatures - MODELS.md: Model IDs, features, selection guide - CHANGELOG.md: Version history, migration guide CONTRIBUTING.md Enhancements: - Development setup with Poetry - Architecture overview diagram - Provider pattern explanation - Adding a new provider guide - Testing guidelines

- Add per-file-ignores for T201 (print) in tutorials - Fix E501 line length issues across all tutorial examples - Fix F841 unused variable warnings in demo functions

- Add tutorials 06, 08, 09 to the tutorials table - Add ChatOCIModelDeploymentVLLM and ChatOCIModelDeploymentTGI to API Reference

- Run ruff format on all tutorial files - Add tutorials/ to mypy exclude (demo code, not production)

Replace all references to google.gemini-2.0-flash with google.gemini-2.5-flash to match currently available models in OCI Generative AI. Files updated: - README.md - docs/API_REFERENCE.md - docs/MODELS.md - tutorials/01-getting-started/README.md - tutorials/02-vision-and-multimodal/README.md - tutorials/02-vision-and-multimodal/code/* - tutorials/09-provider-deep-dive/README.md - tutorials/09-provider-deep-dive/code/* - tests/integration_tests/chat_models/test_gemini_provider.py

- Clarify that OpenAI Responses API must be enabled in tenancy - Add note about 404 errors when API is not available - Add troubleshooting entry for /responses endpoint 404

The OpenAI Responses API (/responses endpoint) is not available in current OCI tenancies. Users should use ChatOCIGenAI with standard models instead.

Requires OCI Data Science infrastructure with GPU shapes and AQUA which is not available in all tenancies.

fede-kamel · 2026-02-20T22:50:14Z

Rebased against main and verified all tutorials still pass after the rebase.

paxiaatucsdedu · 2026-02-23T21:50:51Z

Is there model reference available from OCI side? Maybe we should use their model reference because OCI is updating their models constantly. I feel that it would be a huge effort to keep this model reference doc accurate, comprehensive, and up-to-date.

Done! Added a note at the top linking to OCI's official model reference documentation, clarifying this doc provides examples and guidance for using models with langchain-oci.

- Add note linking to OCI's official model reference in MODELS.md and README.md since models are updated frequently by OCI - Remove migration guide from CHANGELOG.md (redundant with tutorials) - Change Tutorial 03 (AI Agents) from Beginner to Intermediate level - Add note that max_tokens varies by model (not always 4096) - Clarify provider table shows examples, not comprehensive list - Add deprecation note for MetaProvider (use GenericProvider for Llama) - Remove duplicate entry in Gemini models table - Add OpenAI provider section to Tutorial 09 (ChatOCIOpenAI) - Fix API_REFERENCE.md: remove incorrect detail param from load_image, fix to_data_uri and encode_image signatures to match actual code - Fix VISION_MODELS import in Tutorial 02 (use langchain_oci, not utils.vision) - Update CONTRIBUTING.md to use make commands instead of poetry run - Remove "Adding a New Provider" section from CONTRIBUTING.md Signed-off-by: Federico Kamelhar <[email protected]>

fede-kamel · 2026-02-24T20:38:16Z

@paxiaatucsdedu I've addressed all the review feedback in commit da33f96:

Added notes linking to OCI's official model reference (since models update frequently)
Removed the migration guide from CHANGELOG.md
Changed Tutorial 03 (AI Agents) to Intermediate level
Added note that max_tokens varies by model
Clarified provider tables show examples, not comprehensive lists
Added MetaProvider deprecation note (use GenericProvider for Llama)
Fixed duplicate in Gemini models table
Added OpenAI provider section to Tutorial 09 (ChatOCIOpenAI)
Fixed API_REFERENCE.md signatures (load_image, encode_image, to_data_uri)
Fixed VISION_MODELS import in Tutorial 02
Updated CONTRIBUTING.md to use make commands
Removed 'Adding a New Provider' section from CONTRIBUTING.md

Please let me know if you'd like any additional changes!

fede-kamel · 2026-02-26T18:02:13Z

@paxiaatucsdedu Just following up - I've addressed all the review feedback. Let me know if there's anything else needed or if this is ready to merge. Thanks!

paxiaatucsdedu · 2026-02-27T21:02:23Z

+| Reasoning Content | ❌ | ❌ | ❌ | ✅ |
+| Streaming | ✅ | ✅ | ✅ | ✅ |
+| Async | ✅ | ✅ | ✅ | ✅ |
+


Did we test that this table is correct?

Would you like to add OpenAI models in this table?

Would you like to walk through the tutorial to check that OpenAI models are there in necessary places?
Thank you

Addressed all three points:

Testing: Yes! Ran 115 integration tests to validate the feature matrix:

test_multi_model.py: 32 passed (Meta, Cohere, xAI, OpenAI)

test_tool_calling.py: 15 passed (tool calling, parallel tools, tool_choice)

test_vision.py + test_gemini_provider.py: 46 passed (vision, multimodal)

test_chat_features.py: 22 passed (streaming, async, reasoning content)

OpenAI column: Added OpenAI to the feature matrix with Vision (GPT-4o), Parallel Tools, tool_choice, and Reasoning (o1).

Tutorial walk-through: Checked all tutorials. Added a note in Tutorial 01 pointing to ChatOCIOpenAI and Tutorial 08. OpenAI was already covered in Tutorial 09 Part 6.

Also added a disclaimer note that the matrix shows tested capabilities and links to OCI docs for latest features.

paxiaatucsdedu · 2026-02-27T21:03:32Z

+| `max_tokens` | Model-dependent | Maximum tokens in the response (varies by model) |
+| `top_p` | 0.0 - 1.0 | Nucleus sampling cutoff |
+| `top_k` | 1 - 500 | Number of top tokens to consider |
+


Is the top_k range 1-500 for all models?

Correct! Changed to "Model-dependent" with a note linking to OCI docs for specific model limits.

paxiaatucsdedu · 2026-02-27T21:05:40Z

+| `MetaProvider` | Llama 3.2/3.3/4, vision, parallel tools |
+| `GeminiProvider` | Multimodal (PDF, video, audio) |
+| `CohereProvider` | RAG, citations, V2 vision API |
+


Missing OpenAI models here.

Done! Added ChatOCIOpenAI row to the provider table with key features (gpt-4.1, o1, conversation stores).

paxiaatucsdedu · 2026-02-27T21:06:07Z

Would you like to go through the doc to make sure OpenAI models are mentioned in all necessary places?

Changes: - Remove Async Support from CHANGELOG 0.2.0 (in separate PR oracle#147) - Fix duplicate gemini-2.5-flash row, add gemini-2.5-flash-lite - Add OpenAI column to feature matrix in MODELS.md - Add note that feature matrix reflects tested capabilities - Fix top_k range to note it's model-dependent (not 1-500 for all) - Add ChatOCIOpenAI to provider table in Tutorial 09 - Fix OpenAI Vision capability (GPT-4o supports vision)

The multimodal tutorials were using an unsupported 'media' content type. Changed to use the correct formats: - PDF: document_url with data URL - Video: video_url with data URL This matches the provider's supported content types (text, image_url, document_url, video_url, audio_url) and fixes runtime errors when users try to run these tutorials. Tested with actual PDF and video files against Gemini 2.5 Flash.

fede-kamel · 2026-02-27T22:55:29Z

Final Verification Complete

Tutorials: 24/24 verified and working

Integration Tests: 115 passed, 11 skipped (no failures)

All review feedback has been addressed.

@paxiaatucsdedu

fede-kamel · 2026-02-27T22:58:20Z

Correction on skipped tests: The 11 skipped tests are for newer/preview models (Llama 4, Command-A, Grok 4) that have regional availability or rate limit constraints. All core model families (Llama 3.x, Gemini, Cohere Command-R, Grok 3, OpenAI) were tested and passed.

fede-kamel · 2026-02-27T22:59:11Z

Update: Tested the skipped models directly - all pass:

✅ meta.llama-4-maverick-17b-128e-instruct-fp8
✅ meta.llama-4-scout-17b-16e-instruct
✅ cohere.command-a-03-2025
✅ xai.grok-4-fast-non-reasoning

The pytest skips were due to missing OCI_COMPARTMENT_ID env var in the test runner, not model issues. All models functional.

fede-kamel · 2026-03-03T17:02:59Z

@YouNeedCryDear @paxiaatucsdedu could you please help review/check this PR when you have a moment? Thanks!

YouNeedCryDear · 2026-03-04T19:12:06Z

@fede-kamel Don't you think we should have something like https://reference.langchain.com/python/langchain-aws instead of hosting our own version in the repo as MD?

fede-kamel · 2026-03-04T19:33:38Z

Let's go in that direction - agree

YouNeedCryDear · 2026-03-06T20:07:37Z

Close this PR as already implemented by #152

oracle-contributor-agreement bot added the OCA Verified All contributors have signed the Oracle Contributor Agreement. label Feb 19, 2026

fede-kamel added 12 commits February 20, 2026 17:49

Update root README with feature matrix and badges

420a6dd

Fix linting issues in tutorial code examples

66f0b15

- Add per-file-ignores for T201 (print) in tutorials - Fix E501 line length issues across all tutorial examples - Fix F841 unused variable warnings in demo functions

Add missing tutorials and classes to README

8f55c7f

- Add tutorials 06, 08, 09 to the tutorials table - Add ChatOCIModelDeploymentVLLM and ChatOCIModelDeploymentTGI to API Reference

Fix formatting and exclude tutorials from mypy

7ee4798

- Run ruff format on all tutorial files - Add tutorials/ to mypy exclude (demo code, not production)

Restore original README.md content

d4c218d

Add prerequisites and troubleshooting for OpenAI Responses API tutorial

245cb96

- Clarify that OpenAI Responses API must be enabled in tenancy - Add note about 404 errors when API is not available - Add troubleshooting entry for /responses endpoint 404

Remove Tutorial 08 (OpenAI Responses API)

9351b68

The OpenAI Responses API (/responses endpoint) is not available in current OCI tenancies. Users should use ChatOCIGenAI with standard models instead.

Remove Tutorial 06 (Model Deployments)

718c2d3

Requires OCI Data Science infrastructure with GPU shapes and AQUA which is not available in all tenancies.

fede-kamel force-pushed the feature/documentation-updates branch from e9fa2bd to 718c2d3 Compare February 20, 2026 22:49

paxiaatucsdedu reviewed Feb 24, 2026

View reviewed changes

paxiaatucsdedu reviewed Feb 27, 2026

View reviewed changes

fede-kamel added 3 commits February 27, 2026 17:22

Add note pointing to ChatOCIOpenAI in Tutorial 01 provider table

e25fcda

YouNeedCryDear closed this Mar 6, 2026

Conversation

fede-kamel commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Tutorials (8 comprehensive guides)

Reference Documentation

Other Changes

Test Plan

Uh oh!

fede-kamel commented Feb 20, 2026

Uh oh!

fede-kamel commented Feb 20, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fede-kamel commented Feb 24, 2026

Uh oh!

fede-kamel commented Feb 26, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fede-kamel commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Final Verification Complete

Uh oh!

fede-kamel commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fede-kamel commented Feb 27, 2026

Uh oh!

fede-kamel commented Mar 3, 2026

Uh oh!

YouNeedCryDear commented Mar 4, 2026

Uh oh!

fede-kamel commented Mar 4, 2026

Uh oh!

YouNeedCryDear commented Mar 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

fede-kamel commented Feb 19, 2026 •

edited

Loading

fede-kamel commented Feb 27, 2026 •

edited

Loading

fede-kamel commented Feb 27, 2026 •

edited

Loading