Merge branch 'main' into odifix

Author: mihai-tudor-oracle

ai/generative-ai-service/use-embedding-models/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.

ai/generative-ai-service/use-embedding-models/README.md

@@ -0,0 +1,91 @@
+# Use Embedding Models on OCI Generative AI
+
+*The absolute simplest code examples for generating text embeddings with the OCI Generative AI Service — embed a sentence or a whole file in about 20 lines of Python.*
+
+Author: Brona Nilsson
+
+Reviewed: 30.07.2026
+
+# When to use this asset?
+
+Use this asset when you need a minimal, copy-paste starting point for calling OCI Generative AI embedding models with the OCI Python SDK.
+
+### Who
+- Developers making their first embedding call on OCI
+- Solution architects preparing demos or proofs of concept
+- Anyone building semantic search, RAG, or clustering on OCI
+
+### When
+- You want to verify your tenancy, policies, and API key setup with the shortest possible script
+- You need a reference snippet to embed either a single sentence or the contents of a text file
+
+# How to use this asset?
+
+### Prerequisites
+
+1. An OCI tenancy with access to the Generative AI Service in a supported region (the examples use `eu-frankfurt-1` — change the `service_endpoint` if you use another region).
+2. An API key configured in `~/.oci/config` ([setup guide](https://docs.oracle.com/en-us/iaas/Content/generative-ai/setup-oci-api-auth.htm)).
+3. Python 3.9+ with the OCI SDK installed:
+
+```bash
+pip install -r files/requirements.txt
+```
+
+### Run the examples
+
+Copy `files/.env.example` to `files/.env` and set `OCI_COMPARTMENT_ID` to your compartment OCID (the `.env` file is git-ignored, so your OCID stays out of version control). Then:
+
+```bash
+# Embed a single sentence
+python files/embed_sentence.py
+
+# Embed a text file (one vector per paragraph)
+python files/embed_file.py files/sample.txt
+```
+
+Both scripts call the `cohere.embed-v4.0` model on demand and print the resulting embedding vectors.
+
+### The embedding model
+
+The scripts use `cohere.embed-v4.0`, the current embedding model on OCI Generative AI ([official model page](https://docs.oracle.com/en-us/iaas/Content/generative-ai/cohere-embed-4.htm)):
+
+| Model | Dimensions | Max tokens per input | Languages | Notes |
+|---|---|---|---|---|
+| `cohere.embed-v4.0` | 1536 (also 256 / 512 / 1024) | 512 per text input; up to 128,000 total per API call | Multilingual | Multimodal: can also embed one image per request (API only); Matryoshka embeddings — dimensions are truncatable; output types: float, int8, uint8, binary |
+
+The entire Cohere `embed-*-v3.0` family (English, Multilingual, Light, and Image variants) is **deprecated** — do not use it for new projects.
+
+The scripts call the model **on demand** (pay per request). If you host the model on a **dedicated AI cluster** instead, swap the `OnDemandServingMode` for the `DedicatedServingMode` shown commented out in each script, filling in your endpoint OCID ([dedicated AI clusters documentation](https://docs.oracle.com/en-us/iaas/Content/generative-ai/ai-cluster.htm)).
+
+Practical guidance:
+
+- `cohere.embed-v4.0` accepts `input_type` hints (`search_document` when indexing, `search_query` when querying) that improve retrieval quality.
+- Vectors are only comparable when produced by the same model at the same dimensions — use identical settings for both indexing and querying.
+- When storing vectors in a database (e.g. Oracle Database 26ai `VECTOR` columns), the column dimension must match the model output (1536 by default here). Note the service limits: at most 96 inputs per request, and each input must stay under 512 tokens — for large documents, split the text into chunks first (as `embed_file.py` does with paragraphs).
+
+### Repository structure
+
+```
+use-embedding-models/
+├── README.md
+├── LICENSE
+└── files/
+    ├── embed_sentence.py   # Embed one sentence
+    ├── embed_file.py       # Embed a text file, paragraph by paragraph
+    ├── sample.txt          # Demo file: 4 topic pairs to showcase semantic similarity
+    ├── .env.example        # Copy to .env and set your compartment OCID
+    └── requirements.txt
+```
+
+# Useful Links
+
+- [OCI Generative AI Documentation](https://docs.oracle.com/en-us/iaas/Content/generative-ai/home.htm)
+- [OCI Generative AI — Embedding Models](https://docs.oracle.com/en-us/iaas/Content/generative-ai/embed-models.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.

ai/generative-ai-service/use-embedding-models/files/.env.example

@@ -0,0 +1,2 @@
+# Copy to .env and fill in your own value
+OCI_COMPARTMENT_ID=...

ai/generative-ai-service/use-embedding-models/files/embed_file.py

@@ -0,0 +1,41 @@
+"""Embed the paragraphs of a text file with OCI Generative AI.
+
+Usage: python embed_file.py <path-to-text-file>
+"""
+import os
+import sys
+import oci
+from dotenv import load_dotenv
+
+load_dotenv()
+COMPARTMENT_ID = os.environ["OCI_COMPARTMENT_ID"]
+
+MODEL_ID = "cohere.embed-v4.0"
+
+# One embedding per paragraph (each input must stay under 512 tokens,
+# max 96 inputs per request)
+text = open(sys.argv[1], encoding="utf-8").read()
+paragraphs = [p.strip() for p in text.split("\n\n") if p.strip()][:96]
+
+client = oci.generative_ai_inference.GenerativeAiInferenceClient(
+    config=oci.config.from_file(),
+    service_endpoint="https://inference.generativeai.eu-frankfurt-1.oci.oraclecloud.com",
+)
+
+response = client.embed_text(
+    oci.generative_ai_inference.models.EmbedTextDetails(
+        serving_mode=oci.generative_ai_inference.models.OnDemandServingMode(
+            model_id=MODEL_ID
+        ),
+        # For a dedicated AI cluster, replace the serving_mode above with the
+        # endpoint OCID of your hosted model:
+        # serving_mode=oci.generative_ai_inference.models.DedicatedServingMode(
+        #     endpoint_id="ocid1.generativeaiendpoint.oc1.eu-frankfurt-1.replace-with-your-endpoint-ocid"
+        # ),
+        compartment_id=COMPARTMENT_ID,
+        inputs=paragraphs,
+    )
+)
+
+for paragraph, embedding in zip(paragraphs, response.data.embeddings):
+    print(f"{len(embedding)}-dim vector for: {paragraph[:60]}...")

ai/generative-ai-service/use-embedding-models/files/embed_sentence.py

@@ -0,0 +1,33 @@
+"""Embed a single sentence with OCI Generative AI."""
+import os
+import oci
+from dotenv import load_dotenv
+
+load_dotenv()
+COMPARTMENT_ID = os.environ["OCI_COMPARTMENT_ID"]
+
+MODEL_ID = "cohere.embed-v4.0"
+
+client = oci.generative_ai_inference.GenerativeAiInferenceClient(
+    config=oci.config.from_file(),
+    service_endpoint="https://inference.generativeai.eu-frankfurt-1.oci.oraclecloud.com",
+)
+
+response = client.embed_text(
+    oci.generative_ai_inference.models.EmbedTextDetails(
+        serving_mode=oci.generative_ai_inference.models.OnDemandServingMode(
+            model_id=MODEL_ID
+        ),
+        # For a dedicated AI cluster, replace the serving_mode above with the
+        # endpoint OCID of your hosted model:
+        # serving_mode=oci.generative_ai_inference.models.DedicatedServingMode(
+        #     endpoint_id="ocid1.generativeaiendpoint.oc1.eu-frankfurt-1.replace-with-your-endpoint-ocid"
+        # ),
+        compartment_id=COMPARTMENT_ID,
+        inputs=["Oracle Cloud Infrastructure makes embeddings easy."],
+    )
+)
+
+embedding = response.data.embeddings[0]
+print(f"Vector with {len(embedding)} dimensions:")
+print(embedding[:5], "...")

ai/generative-ai-service/use-embedding-models/files/requirements.txt

@@ -0,0 +1,2 @@
+oci
+python-dotenv

ai/generative-ai-service/use-embedding-models/files/sample.txt

@@ -0,0 +1,15 @@
+The chef reduced the sauce slowly over low heat, folding in butter until it turned glossy and rich.
+
+Compute instances can be scaled up or down on demand, and you only pay for the capacity you actually use.
+
+A good risotto needs constant stirring and warm stock added one ladle at a time until the rice is creamy.
+
+Object storage keeps unstructured data durable and highly available, replicated across fault domains in a region.
+
+The telescope captured light that had travelled for billions of years, revealing galaxies from the early universe.
+
+Astronomers detected water vapour in the atmosphere of a distant exoplanet orbiting within its star's habitable zone.
+
+The midfielder threaded a pass between two defenders, and the striker slotted the ball into the bottom corner.
+
+The home team's goalkeeper saved a penalty in stoppage time to secure the championship title.