This repository contains practical Python examples that call Oracle Cloud Infrastructure (OCI) Generative AI endpoints through the OpenAI-compatible API.
Highlights from the most useful examples and demos:
Quickstart & Core:
examples/example01.py: minimal text request, ideal as first connectivity smoke test.examples/example02.py: streaming output token-by-token for chat/CLI-style incremental UX.examples/example03.py: structured parsing into typed objects (Pydantic), useful for automation flows.examples/example05.py: multi-turn state with the Conversations API plus streaming responses.examples/example06.py: reasoning summary output for debugging and response explainability.
Vector Stores & Retrieval:
examples/example18.py: file-search over vector stores with inline citations in final answers.
Tools & Multimodal:
examples/example23.py: end-to-end custom function tool calling loop (function_call+function_call_output).
Observability:
examples/example19.py: Langfuse tracing for non-streaming responses.
Auth & Security:
examples/example24.py: OCI Identity Domain OAuth2/JWT client-credentials flow.
Related demos and components:
connectors/create_connector.py+ related scripts inconnectors/: create/sync/manage vector-store connectors to Object Storage.demos/demo2: Streamlit chatbot with web search and Langfuse-integrated observability/tracing.demos/demo4: full RAG flow with progressive loading frompdf_rag/, strictfile_search, persistent conversation, streamed answers, and sidebar references with pages.demos/demo5: Streamlit vector-store explorer that returns retrieved chunk text and metadata for a user query.demos/demo6: LangGraph-style RAG backend with SSE plus Streamlit chat UI with streamed final answer and sidebar references from reranker.agents/streamlit_client: generalized Streamlit client for OCI hosted agent deployments with optional JWT authentication and.envdrag-and-drop configuration.
- Configuration:
docs/configurations.md - Testing:
docs/testing.md - Architecture:
docs/architecture.md
- Install base dependencies:
pip install -r requirements.txt-
Fill the
.envfile for your target production region (for example.env.prod-chicagoor.env.prod-frankfurt) with valid values for:PROJECT_ID,KEY1,COMPARTMENT_ID,VECTOR_STORE_ID(and Langfuse keys only if needed; otherwise they can be left unset/empty). -
Select active production profile:
source ./set_env.sh prod-chicago
./show_current_env.sh- Run a first connectivity example:
python -m examples.example01- Run one demo (example: Demo 4):
pip install -r demos/demo4/requirements.txt
streamlit run demos/demo4/app.pyExamples are grouped by topic. Use the category guides below for full per-script details.
| # | Category | Includes | Primary Focus | Detailed Guide |
|---|---|---|---|---|
| 1 | Quickstart & Core | example01-example06 |
First runs, streaming, conversation state, structured outputs, web search. | examples/README_quickstart.md |
| 2 | Vector Stores & Retrieval | example11-example18 |
Vector store lifecycle, ingestion, status checks, semantic search, file_search. | examples/README_vector_stores.md |
| 3 | Tools & Multimodal | example07, example21-example23 |
Vision input, image generation, code interpreter, custom function tools. | examples/README_tools_multimodal.md |
| 4 | Observability | example19-example20 |
Langfuse tracing for non-streaming and streaming calls. | examples/README_observability.md |
| 5 | Auth & Security | example24 |
OCI Identity Domain OAuth2/JWT client-credentials flow. | examples/README_auth.md |
| # | Demo | Folder | Purpose | Key API usage | Good for | Notes |
|---|---|---|---|---|---|---|
| 1 | Responses chatbot + web search | demos/demo1 |
Streamlit chatbot with multi-turn context and built-in web search. | conversations.create(...), responses.create(..., tools=[{"type":"web_search"}], stream=True) |
End-to-end chat UX demo using Responses API tools. | Includes basic UI/backend separation (app.py, backend.py, state.py). |
| 2 | Responses chatbot + web search + Langfuse | demos/demo2 |
Streamlit chatbot with multi-turn context, built-in web search, and Langfuse traces on LLM calls. | conversations.create(...), responses.create(..., tools=[{"type":"web_search"}], stream=True), langfuse.openai instrumentation |
End-to-end chat UX demo with observability/tracing. | Includes basic UI/backend separation (app.py, backend.py, state.py). |
| 3 | Structured extraction from legal PDFs | demos/demo3 |
Streamlit app that previews one uploaded PDF, extracts raw text, and produces structured JSON output. | files.create(...), responses.create(...) for PDF-to-text, responses.parse(..., text_format=ProceduraVendita) |
End-to-end document extraction pipeline with typed schema output. | Uses hybrid models: Gemini for text extraction + GPT-5.2 for structured parsing. |
| 4 | Full RAG with file_search | demos/demo4 |
Two-step RAG demo: progressive ingestion from pdf_rag/ and Streamlit chat UI on indexed docs. |
Loading: vector_stores.files.list(...), files.retrieve(...), files.create(...), vector_stores.files.create(...); Query: conversations.create(...), responses.create(..., tools=[{"type":"file_search"}], include=["file_search_call.results"], stream=True) |
Practical end-to-end RAG workflow with strict grounding, streaming UX, and citations. | Sidebar shows references (filename, pages) extracted from response annotations. |
| 5 | Vector store chunk explorer | demos/demo5 |
Streamlit explorer that executes semantic search on a vector store and renders retrieved chunks plus metadata. | vector_stores.search(...) |
Debugging retrieval quality and inspecting chunk-level evidence. | Sidebar shows runtime config (REGION, VECTOR_STORE_ID). |
| 6 | LangGraph-style RAG backend + Streamlit UI | demos/demo6 |
FastAPI backend with 4-node LangGraph-style RAG flow and standardized SSE events, plus Streamlit chat UI with history and real-time streamed answer. | POST /chat with text/event-stream; SemanticSearcher uses vector_stores.search(...); AnswerGenerator streams via Responses API |
Building and debugging event-driven agent orchestration with a lightweight chat frontend. | Sidebar shows runtime config and current-turn reranker references (filename, pages) in collapsible items. |
| # | Utility | File | Description |
|---|---|---|---|
| 1 | List all files | examples/list_all_files.py |
Lists all files in the configured project, page by page. |
| 2 | Delete all files | examples/delete_all_files.py |
Deletes all files in the configured project with per-file error handling. |
| 3 | List all vector stores | examples/list_all_vector_stores.py |
Lists all vector stores, page by page, with readable expiration time. |
| 4 | Delete all vector stores | examples/delete_all_vs.py |
Deletes all vector stores with per-item error handling. |
| # | Connector Utility | File | Description |
|---|---|---|---|
| 1 | Create connector | connectors/create_connector.py |
Creates an Object Storage connector for a vector store. |
| 2 | List connectors | connectors/list_connectors.py |
Lists vector store connectors in the configured compartment. |
| 3 | Connector stats | connectors/get_connector_stats.py |
Retrieves synchronization statistics for one connector. |
| 4 | Trigger file sync | connectors/trigger_file_sync.py |
Triggers a manual file sync operation for one connector. |
| 5 | Update connector | connectors/update_connector.py |
Updates connector settings such as source configuration and schedule. |
| 6 | Delete connector | connectors/delete_connector.py |
Deletes a connector by OCID. |
| 7 | Connector logs | connectors/get_connector_logs.py |
Retrieves and prints recent logs for one connector. |
| # | Agent Client | Folder | Purpose | Key API usage | Good for | Notes |
|---|---|---|---|---|---|---|
| 1 | Hello World agent (FastAPI + CLI) | agents/hello_world |
Minimal LangGraph-based agent with SSE API and CLI/JWT client variants. | GET /health, GET /ready, POST /chat (SSE); optional OAuth2 client-credentials token retrieval in JWT CLI client. |
First local agent run, API contract validation, and JWT end-to-end smoke tests. | Includes Docker/Docker Compose setup and demo6-like payload compatibility (name / user_request). |
| 2 | Deep Agents 01 (FastAPI + CLI) | agents/deep_agents01 |
Deep Agents example (LangChain/LangGraph) with separated backend, API, and CLI over OCI OpenAI-compatible endpoint. | GET /health, GET /ready, POST /chat (SSE); backend uses ChatOpenAI and forces Responses API mode for OCI compatibility. |
Local deep-agent orchestration and SSE streaming flow validation without JWT. | Uses local .env file (agents/deep_agents01/.env.local), dedicated tests, and explicit backend error surfacing. |
| 3 | Streamlit generalized hosted-agent client | agents/streamlit_client |
Streamlit UI to invoke OCI hosted agent deployments with custom JSON/text payloads and live SSE output. | POST to hosted agent endpoint with Accept: text/event-stream; optional OAuth2 client-credentials token retrieval from OCI Identity Domain. |
Manual endpoint validation, auth troubleshooting, and payload experimentation without writing code. | Supports sidebar config, URL derivation from GenAI application id, .env drag-and-drop mapping, event logging, and graceful stop on response.completed. |
- Python 3.11+
- An OCI Generative AI project and endpoint access
- A valid OCI API key with permissions for Generative AI
Install dependencies:
pip install -r requirements.txtIf you want to use Langfuse integration
pip install langfuseInstall test dependencies:
pip install -r requirements-dev.txtConfiguration details are documented in docs/configurations.md.
Secrets are loaded from environment profile files:
.env.prod-chicago.env.prod-frankfurt
This repository supports only production profiles (prod-*).
When you run source ./set_env.sh <profile>, the script exports:
AGENT_HUB_REGIONAGENT_HUB_ENV_FILE
These environment variables drive runtime configuration for the current shell session (instead of editing region values manually in code).
Each profile should define: PROJECT_ID, KEY1, COMPARTMENT_ID,
LANGFUSE_SECRET_KEY, LANGFUSE_PUBLIC_KEY, VECTOR_STORE_ID.
If you do not use Langfuse, LANGFUSE_SECRET_KEY and LANGFUSE_PUBLIC_KEY
can be unset or empty strings.
Authentication mode can be selected with OCI_AUTH_MODE:
user_principal(default if not set)session
Inference authentication mode can be selected with INFERENCE_AUTH_MODE:
api_key(default if not set, usesKEY1)user_principalsession
Use INFERENCE_AUTH_MODE only for inference/data-plane calls and
OCI_AUTH_MODE for control-plane operations (connectors/vector-store
management).
For details and setup examples, see
docs/configurations.md.
Set the active profile from repository root:
source ./set_env.sh prod-chicago
./show_current_env.shProfiles currently available:
prod-chicagoprod-frankfurt
Before running examples/demos/connectors, always select one of the profiles above in the same terminal session.
If a script returns 401 NotAuthenticated while using OCI session authentication:
- Ensure you selected the profile in the same shell session:
source ./set_env.sh prod-chicago- Refresh the OCI session token for your local OCI profile only if you are using session-based authentication (
OCI_AUTH_MODE=session):
oci session authenticate --profile-name DEFAULTFrom the repository root:
python -m examples.exampleXXFrom the repository root:
python -m connectors.script_nameFrom the repository root:
pip install -r demos/demo1/requirements.txt
streamlit run demos/demo1/app.py
pip install -r demos/demo2/requirements.txt
streamlit run demos/demo2/app.py
pip install -r demos/demo3/requirements.txt
streamlit run demos/demo3/app.py
pip install -r demos/demo4/requirements.txt
streamlit run demos/demo4/app.py
pip install -r demos/demo5/requirements.txt
streamlit run demos/demo5/app.py
pip install -r demos/demo6/requirements.txt
uvicorn demos.demo6.api:app --reload --port 8080
streamlit run demos/demo6/app.pyTesting details are documented in docs/testing.md.
Project structure and module layout are documented in docs/architecture.md.
See issues_found.md for a current OCI authorization/policy issue (404 with authorization failure) and policies snippet reference.
- The examples are intentionally compact and educational.
- You can copy each script as a starting point and adapt prompt, model ID, and output handling to your own workflows.
