Initial commit of Getting Started Guide

brnil6 · brnil6 · commit 6a3d17658dd1 · 2026-02-12T15:07:56.000+01:00
diff --git a/ai/generative-ai-service/a-getting-started-guide/LICENSE b/ai/generative-ai-service/a-getting-started-guide/LICENSE
@@ -0,0 +1,32 @@
+Copyright (c) 2026 Oracle and/or its affiliates.
+
+The Universal Permissive License (UPL), Version 1.0
+
+Subject to the condition set forth below, permission is hereby granted to any
+person obtaining a copy of this software, associated documentation and/or data
+(collectively the "Software"), free of charge and under any and all copyright
+rights in the Software, and any and all patent rights owned or freely
+licensable by each licensor hereunder covering either (i) the unmodified
+Software as contributed to or provided by such licensor, or (ii) the Larger
+Works (as defined below), to deal in both
+
+(a) the Software, and
+
+(b) any piece of software and/or hardware listed in the lrg_coverage.txt file,
+if one is included with the Software (each a "Covered Work", collectively
+"Covered Works"), that is available under a license listed in the
+lrg_coverage.txt file, if one is included with the Software (the "Covered
+License"), and
+
+without limitation, the right to copy, create derivative works of, display,
+perform, and distribute the Software and make, use, sell, offer for sale,
+import, export, have made, and have sold the Software and the Covered Works,
+in each case subject to the conditions and limitations set forth herein.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/ai/generative-ai-service/a-getting-started-guide/README.md b/ai/generative-ai-service/a-getting-started-guide/README.md
@@ -0,0 +1,79 @@
+# Getting Started with OCI Generative AI Service — Developer Onboarding Guide
+
+*A collection of step-by-step guides for developers onboarding to Oracle Cloud Infrastructure, covering how to connect applications to the OCI Generative AI Service using the OCI SDK, LangChain, and low-code platforms like n8n.*
+
+Author: Dejan Vlasakov
+
+Reviewed: 12.02.2026
+
+# When to use this asset?
+
+*Use this asset when onboarding developers to OCI Generative AI Service. It serves as both a walkthrough for the onboarding team and a reference handout for developers.*
+
+### Who
+- Developer onboarding teams introducing OCI Generative AI to new users
+- Developers connecting applications to OCI Generative AI for the first time
+- Solution architects evaluating integration patterns (SDK, LangChain, low-code)
+
+### When
+- Setting up a new project that calls OCI Generative AI (chat, embeddings, or RAG)
+- Integrating LangChain with OCI-hosted models for AI application development
+- Connecting low-code / no-code platforms (n8n, etc.) to OCI Generative AI via an OpenAI-compatible gateway
+- Onboarding workshops and enablement sessions
+
+# How to use this asset?
+
+*Pick the guide that matches your integration approach. Each guide includes prerequisites, working code examples, and environment configuration.*
+
+### Guide 1 — Oracle Database 26ai + OCI Generative AI (OCI SDK)
+
+End-to-end RAG pattern: create an OCI GenAI inference client, generate embeddings, perform vector similarity search in Oracle Database 26ai, and call the chat API with grounded context — all using the OCI Python SDK directly.
+
+**[Read the guide &rarr;](files/OracleDB-GenAIOCI-Connection.md)**
+
+### Guide 2 — LangChain + OCI Generative AI (`langchain-oci`)
+
+Set up the official `langchain-oci` package, instantiate chat and embedding models, and build prompt chains — using the dedicated LangChain integration for OCI.
+
+**[Read the guide &rarr;](files/LangChainOCI-GenAIOCI-Connection.md)**
+
+### Guide 3 — n8n + OCI Generative AI (OpenAI-compatible gateway)
+
+Deploy an OpenAI-compatible gateway that proxies requests to OCI GenAI, configure n8n to use it, and build a sample AI-powered summarisation workflow — no custom code required.
+
+**[Read the guide &rarr;](files/N8N-GenAIOCI-Connection.md)**
+
+### Common Prerequisites
+
+All three guides share the same foundational setup:
+
+1. An active OCI tenancy with Generative AI enabled
+2. IAM policies granting access to `generative-ai-family`
+3. OCI API key authentication configured locally (`~/.oci/config`)
+
+Each guide then adds tool-specific requirements (Python packages, LangChain, n8n, etc.).
+
+### File Structure
+```
+.
+├── README.md                              # This file
+├── LICENSE
+└── files/
+    ├── OracleDB-GenAIOCI-Connection.md    # Guide 1 – OCI SDK + Oracle DB 26ai
+    ├── LangChainOCI-GenAIOCI-Connection.md # Guide 2 – LangChain integration
+    └── N8N-GenAIOCI-Connection.md          # Guide 3 – n8n / low-code integration
+```
+
+# Useful Links
+
+- [OCI Generative AI Documentation](https://docs.oracle.com/en-us/iaas/Content/generative-ai/home.htm)
+- [OCI Generative AI — LangChain Integration](https://docs.oracle.com/en-us/iaas/Content/generative-ai/langchain.htm)
+- [OCI IAM Policies — Getting Started](https://docs.oracle.com/en-us/iaas/Content/Identity/Concepts/policygetstarted.htm)
+- [OCI API Key Authentication Setup](https://docs.oracle.com/en-us/iaas/Content/generative-ai/setup-oci-api-auth.htm)
+
+# License
+
+Copyright (c) 2026 Oracle and/or its affiliates.
+Licensed under the Universal Permissive License (UPL), Version 1.0.
+
+See [LICENSE](LICENSE) for more details.
diff --git a/ai/generative-ai-service/a-getting-started-guide/files/LangChainOCI-GenAIOCI-Connection.md b/ai/generative-ai-service/a-getting-started-guide/files/LangChainOCI-GenAIOCI-Connection.md
@@ -0,0 +1,101 @@
+## Integrating LangChain with OCI Generative AI
+We're excited to announce the official release of `langchain-oci`, the dedicated LangChain integration package for Oracle Cloud Infrastructure services.
+
+Install the LangChain OCI package with the following command:
+
+`pip install -U langchain-oci`
+
+**Note:** The OCI integrations that were available in the `langchain-community` are now deprecated. All future development, bug fixes, and feature enhancements will be hosted in the new dedicated repository. We recommend that you migrate to `langchain-oci` to ensure that you receive the following benefits:
+
+* Latest features and improvements
+* Security updates and bug fixes
+* Dedicated support and documentation
+* Performance optimizations
+
+To learn about OCI Generative AI's integration with LangChain, see the [Generative AI documentation](https://docs.oracle.com/iaas/Content/generative-ai/langchain.htm).
+
+### Prerequisites
+1. **OCI Account and Permissions:**
+   * Create or use an active OCI tenancy with Generative AI enabled.
+   * Set up IAM policies: Grant your user/group access to `generative-ai-family` in a sandbox compartment (e.g., `allow group <group-name> to manage generative-ai-family in compartment <compartment-name>`).
+   * Gather: Compartment OCID (from OCI Console > Identity & Security > Compartments).
+   * Docs: [OCI Generative AI Getting Started](https://docs.oracle.com/en-us/iaas/Content/generative-ai/home.htm) and [IAM Policies](https://docs.oracle.com/en-us/iaas/Content/Identity/Concepts/policygetstarted.htm).
+2. **OCI CLI and SDK Installation:**
+   * Install the OCI CLI (includes Python SDK for authentication).
+   * Command: `pip install oci-cli`.
+   * Verify: `oci --version`.
+   * Docs: [Install OCI CLI](https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/cliinstall.htm).
+3. **Python Packages:**
+   * Install core libraries:
+     ```bash
+     pip install langchain langchain-oci oci
+     ```
+   * `langchain`: Core framework.
+   * `langchain-oci`: Support for the OCI chat and embedding models.
+   * `oci`: SDK for auth and API calls.
+4. **[Set up OCI API key](https://docs.oracle.com/en-us/iaas/Content/generative-ai/setup-oci-api-auth.htm) authentication locally.**
+
+## Connecting LangChain to OCI Generative AI
+- Using a Chat Model: `ChatOCIGenAI` class exposes chat models from OCI Generative AI
+- Using a completion Model: `OCIGenAI` class exposes LLMs from OCI Generative AI
+- Using an embeddings Model: `OCIGenAIEmbeddings` class exposes embeddings from OCI Generative AI
+
+### 1. Basic LLM Instantiation and Invocation
+Start with a simple call to an on-demand model using API Key auth (default). This invokes the LLM directly.
+```python
+from langchain_oci import OCIGenAI
+
+# Initialize the OCI GenAI LLM interface
+llm = OCIGenAI(
+    model_id="cohere.command",  # On-demand model ID
+    service_endpoint="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com",
+    compartment_id="MY_OCID",  # Your compartment OCID
+    # Auth uses ~/.oci/config by default (API Key)
+)
+
+# Basic invocation with optional parameters
+response = llm.invoke("Tell me one fact about Earth", temperature=0.7)
+print(response)
+# Expected output: A generated fact, e.g., "Earth is the third planet from the Sun."
+```
+
+### 2. Prompt Chaining with LLMChain
+Chain a prompt template to the LLM for structured inputs/outputs. This example uses Session Token auth and passes model kwargs for consistency.
+```python
+from langchain_oci import OCIGenAI
+from langchain.chains import LLMChain
+from langchain_core.prompts import PromptTemplate
+
+# Initialize with Session Token auth and model parameters
+llm = OCIGenAI(
+    model_id="meta.llama-3.3-70b-instruct",  # Another on-demand model
+    service_endpoint="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com",
+    compartment_id="MY_OCID",
+    auth_type="SECURITY_TOKEN",
+    auth_profile="MY_PROFILE",  # Profile from ~/.oci/config
+    model_kwargs={
+        "temperature": 0.7,
+        "top_p": 0.75,  # Nucleus sampling
+        "max_tokens": 200  # Limit response length
+    }
+)
+
+# Define a prompt template
+prompt = PromptTemplate(
+    input_variables=["query"],
+    template="{query}"  # Simple template; customize for multi-step chaining
+)
+
+# Create the chain
+llm_chain = LLMChain(llm=llm, prompt=prompt)
+
+# Invoke the chain
+response = llm_chain.invoke("What is the capital of France?")
+print(response["text"])
+# Expected output: "The capital of France is Paris."
+```
+**Resources:**
+
+* [Full OCI GenAI + LangChain Guide](https://blogs.oracle.com/ai-and-datascience/developing-ai-apps-oci-generative-ai-langchain).
+* [LangChain OCI Integration Docs](https://docs.oracle.com/en-us/iaas/Content/generative-ai/langchain.htm).
+  
diff --git a/ai/generative-ai-service/a-getting-started-guide/files/N8N-GenAIOCI-Connection.md b/ai/generative-ai-service/a-getting-started-guide/files/N8N-GenAIOCI-Connection.md
@@ -0,0 +1,129 @@
+## Integrating n8n Workflows with OCI Generative AI
+
+### Prerequisites
+1. **OCI Account and Permissions:**
+   * Create or use an active OCI tenancy with Generative AI enabled.
+   * Set up IAM policies: Grant your user/group access to `generative-ai-family` in a sandbox compartment (e.g., `allow group <group-name> to manage generative-ai-family in compartment <compartment-name>`).
+   * Gather: Compartment OCID (from OCI Console > Identity & Security > Compartments).
+   * Docs: [OCI Generative AI Getting Started](https://docs.oracle.com/en-us/iaas/Content/generative-ai/home.htm) and [IAM Policies](https://docs.oracle.com/en-us/iaas/Content/Identity/Concepts/policygetstarted.htm).
+2. **[Set up OCI API key](https://docs.oracle.com/en-us/iaas/Content/generative-ai/setup-oci-api-auth.htm) authentication locally.**
+3. n8n installed and running (self-hosted or cloud version; version 1.0+ recommended for AI nodes).
+
+## Step 1: Launch the OCI GenAI Gateway
+The gateway runs a local server (port 8088) that mimics the OpenAI API, allowing n8n to interact with OCI models like those provided by OpenAI, Llama and Grok as an example.
+
+### Option 1: Run with Uvicorn (Local Development)
+From the repo root:
+
+1. Navigate to `./app` and install dependencies: `pip install -r requirements.txt`.
+2. Start the server:
+   ```bash
+   cd app
+   uvicorn app:app --host 0.0.0.0 --port 8088 --reload
+   ```
+   For production (Linux only, with Gunicorn for scaling):
+   ```bash
+   gunicorn app:app --workers 16 --worker-class uvicorn.workers.UvicornWorker --timeout 600 --bind 0.0.0.0:8088
+   ```
+
+### Option 2: Run with Podman (Containerized Deployment)
+
+1. Install Podman:
+   * Linux: `sudo apt install podman` (Ubuntu) or `sudo dnf install podman` (Fedora).
+   * macOS: `brew install podman`.
+   * Windows: Follow [Podman for Windows guide](https://podman.io/docs/installation#windows).
+2. Ensure `~/.oci/config` is set up (from prerequisites).
+3. Build and run:
+   ```bash
+   podman build -t oci_genai_gateway .
+   podman run -p 8088:8088 \
+     -v ~/.oci:/root/.oci:Z \
+     -it --name oci_genai_gateway oci_genai_gateway
+   ```
+4. Verify: Open `http://localhost:8088` in a browser (should show a health check or API docs). Check logs with `podman logs oci_genai_gateway`.
+
+**Gateway Endpoint:** The server exposes `/v1/chat/completions` (OpenAI-compatible) at `http://localhost:8088`.
+
+## Step 2: Configure n8n to Use the OCI Gateway
+In n8n, use the **OpenAI** node but point it to your local gateway as a custom endpoint. This lets you select OCI models seamlessly.
+
+1. In n8n, create a new workflow.
+2. Add an **OpenAI** node (under AI > Chat Models).
+3. Configure credentials:
+   * **API Key:** Leave blank or use a dummy value (gateway uses OCI auth).
+   * **Base URL:** `http://host.docker.internal:8088/v1` (for Podman/Docker; use `http://localhost:8088/v1` if running natively).
+   * **Model:** Select or enter an OCI model (list available models via gateway docs or OCI Console).
+n8n will now route requests through the gateway to OCI GenAI.
+
+## Step 3: Simple n8n Workflow Example – AI-Powered Text Summarization
+This example creates a workflow that triggers on a webhook (e.g., incoming email or form data), summarizes text using an OCI LLM, and sends the result via email. It demonstrates calling the LLM with minimal code.
+
+### Workflow Overview
+* **Trigger:** Webhook (receives input text).
+* **AI Node:** OpenAI (calls OCI via gateway for summarization).
+* **Output:** Email node (sends summary).
+
+### Step-by-Step Setup in n8n
+
+1. **Add Webhook Trigger:**
+   Drag Webhook node.
+   * Set Method: POST.
+   * Path: `/summarize` (test URL: `http://your-n8n-instance/webhook/summarize`).
+   * This receives JSON payload like `{"text": "Long article content here..."}`.
+2. **Add OpenAI Node for Summarization:**
+   * Connect after Webhook.
+   * Operation: Chat.
+   * Credentials: Use the custom setup from Step 2 (Base URL: `http://localhost:8088/v1`).
+   * Model: `meta.llama-3.3-70b-instruct` (or your preferred OCI model).
+   * Messages:
+     * Role: System – Prompt: `You are a helpful summarizer. Provide a concise 3-sentence summary.`
+     * Role: User – Prompt: `{{ $json.text }}` (references webhook input).
+   * Options: Temperature: 0.3 (for consistent outputs); Max Tokens: 200.
+   **Effective API Call (Behind the Scenes):**
+   The node generates a request like this to the gateway:
+   ```json
+   POST http://localhost:8088/v1/chat/completions
+   {
+     "model": "meta.llama-3.3-70b-instruct",
+     "messages": [
+       {"role": "system", "content": "You are a helpful summarizer. Provide a concise 3-sentence summary."},
+       {"role": "user", "content": "{{input_text}}"}
+     ],
+     "temperature": 0.3,
+     "max_tokens": 200
+   }
+   ```
+   The gateway forwards this to OCI GenAI, returning a response like:
+   ```json
+   {
+     "choices": [
+       {
+         "message": {
+           "role": "assistant",
+           "content": "Summary sentence 1. Sentence 2. Sentence 3."
+         }
+       }
+     ]
+   }
+   ```
+3. **Add Email Output Node:**
+   * Connect after OpenAI.
+   * Node: Send Email (or Gmail/SMTP).
+   * To: `recipient@example.com`.
+   * Subject: `AI Summary of Input`.
+   * Body: `{{ $json.choices[0].message.content }}` (extracts summary from AI response).
+4. **Activate and Test:**
+   * Save and activate the workflow.
+   * Send a POST request to the webhook (e.g., via curl):
+     ```bash
+     curl -X POST http://your-n8n-instance/webhook/summarize \
+       -H "Content-Type: application/json" \
+       -d '{"text": "Oracle OCI GenAI enables powerful automations. n8n connects apps seamlessly. Together, they boost productivity."}'
+     ```
+   * Check n8n executions: The workflow should summarize the text and email it.
+   * View logs in n8n for details (e.g., AI response parsing).
+
+## Troubleshooting & Tips
+* **Authentication Errors:** Verify `~/.oci/config` permissions and OCI policies (from prerequisites). Test with `oci` CLI commands like `oci os ns get`.
+* **Connection Issues:** Ensure port 8088 is open (firewall/OCI security lists). For Podman, use `--network=host` if needed.
+* **Model Not Found:** List OCI models in Console under **Analytics & AI > Generative AI**. Ensure your tenancy has the required permissions for `generative-ai-family`.
diff --git a/ai/generative-ai-service/a-getting-started-guide/files/OracleDB-GenAIOCI-Connection.md b/ai/generative-ai-service/a-getting-started-guide/files/OracleDB-GenAIOCI-Connection.md
