Merge branch 'main' into dependabot/pip/ai/generative-ai-service/Document-Processing-with-GenAI/smart-invoice-extraction/pillow-10.3.0

Author: AlexanderHodicke

ai/ai-document-understanding/README.md

@@ -23,7 +23,7 @@ Reviewed: 22.09.2025
 
 ## GitHub
 
-- [Enhanced Document Understanding with LLMs](https://github.com/oracle-devrel/technology-engineering/tree/main/ai/generative-ai-service/doc-understanding-and-genAI)
+- [Enhanced Document Understanding with LLMs](https://github.com/oracle-devrel/technology-engineering/tree/main/ai/generative-ai-service/Document%20Processing%20with%20GenAI/doc-understanding-and-genAI)
     - A Streamlit-based app comparing and expanding on traditional Document Understanding (OCI DU) + LLM approach vs. a multimodal LLM for extracting structured data from documents (PDFs, images). This is is aimed at highlighting the strengths of each of our services and the power GenAI brings in combining these approaches for the best handling of complex documents.
 - [Invoice Document Processing from Gmail into ERP systems using OCI Document Understanding & Oracle Integration Cloud](https://github.com/oracle-devrel/technology-engineering/tree/main/ai/ai-document-understanding/ai-email-invoice)
     - Explore how we can process invoice documents from Gmail into an ERP System in real-time using OCI Document Understanding and Oracle Integration Cloud (OIC). This solution combines a low-code approach to capture Gmail messages in real-time with Google Cloud Pub/Sub Adapter, extract invoice data with AI Document Understanding and create invoices in ERP systems using Oracle Integration Cloud ERP adapters.

ai/ai-speech/README.md

@@ -1,8 +1,12 @@
 # AI Speech
 
-OCI Speech is an AI service that applies automatic speech recognition technology to transform audio-based content into text. Developers can easily make API calls to integrate OCI Speech’s pre-trained models into their applications. OCI Speech can be used for accurate, text-normalized, time-stamped transcription via the console and REST APIs as well as command-line interfaces or SDKs. You can also use OCI Speech in an OCI Data Science notebook session. With OCI Speech, you can filter profanities, get confidence scores for both single words and complete transcriptions, and more.
+OCI Speech offers speech-to-text (STT) capabilities for files and real-time streams, as well as text-to-speech (TTS) functionality - All in one solution.
 
-Reviewed: 11.06.2026
+It’s accessible via Console, REST, CLI, and SDKs. Outputs are written to your Object Storage bucket as JSON (with word-level timestamps & confidences) and optionally SRT for captions.
+
+Recent updates include Live Transcribe for real-time ASR and Whisper model support for multilingual transcription alongside Oracle’s native ASR models.
+
+Reviewed: 25.09.2025
 
 # Table of Contents
 
@@ -28,10 +32,10 @@ Reviewed: 11.06.2026
 
 # Useful Links
 
+- [OCI Speech Release Notes](https://docs.oracle.com/en-us/iaas/releasenotes/services/speech/index.htm)
 - [AI Solutions Hub](https://www.oracle.com/artificial-intelligence/solutions/)
 - [Oracle AI Speech on oracle.com](https://www.oracle.com/artificial-intelligence/speech/)
 - [Oracle AI Speech documentation](https://docs.oracle.com/en-us/iaas/Content/speech/home.htm)
-- [Oracle Speech AI service now supports diarization](https://blogs.oracle.com/ai-and-datascience/post/oracle-speech-ai-service-now-supports-diarization)
 - [OCI Speech supports the Whisper model](https://blogs.oracle.com/ai-and-datascience/post/oci-speech-supports-the-whisper-model)
 - [OCI Speech supports text-to-speech and real-time transcription with customized vocabulary](https://blogs.oracle.com/ai-and-datascience/post/oci-speech-texttospeech-realtime-transcription-custom-vocab)
 

ai/ai-speech/podcast-generator/README.md

@@ -5,7 +5,7 @@ The application is designed to streamline podcast production through advanced AI
 This application is built using Oracle Visual Builder Cloud Service (VBCS), a powerful low-code platform that simplifies development and accelerates the creation of robust applications without extensive coding. With this low-code approach, even complex workflows are straightforward to set up, allowing developers to focus on leveraging AI's potential for high-quality audio synthesis.
 This AI-powered solution not only automates and optimizes the podcast creation process but also allows content creators to deliver professional audio content at scale efficiently.
 
-Reviewed: 24.04.2025
+Reviewed: 29.09.2025
 
 
 # When to use this asset?

ai/gen-ai-agents/agentsOCI-OpenAI-gateway/api/routers/chat.py

@@ -6,6 +6,7 @@
 import json
 import yaml
 import logging
+from urllib.parse import urlparse
 from typing import Annotated, Any, Dict, List, Optional, Tuple, Union
 
 import oci
@@ -133,6 +134,185 @@ def _extract_user_text(messages: List[Dict[str, Any]] | List[Any]) -> str:
                 )
     return ""
 
+def _normalize_source_location(source_location: Any) -> dict:
+    """
+    Returns a dict with display_name and url (when present).
+    Handles:
+      - OCI SDK objects with .url
+      - dict-like with 'url'
+      - JSON-stringified dicts
+      - raw URLs
+      - plain strings / paths
+    """
+    display_name = None
+    url_value = None
+
+    try:
+        # 1) SDK object with attribute 'url'
+        if hasattr(source_location, "url"):
+            url_value = getattr(source_location, "url") or None
+
+        # 2) dict-like
+        if url_value is None:
+            if isinstance(source_location, dict):
+                url_value = source_location.get("url")
+            else:
+                # 3) JSON-like string? try parse
+                if isinstance(source_location, str) and source_location.strip().startswith("{"):
+                    try:
+                        parsed = json.loads(source_location)
+                        if isinstance(parsed, dict):
+                            url_value = parsed.get("url")
+                            source_location = parsed
+                    except Exception:
+                        pass
+
+        # 4) If it's a URL string
+        if url_value is None and isinstance(source_location, str):
+            if source_location.startswith("http://") or source_location.startswith("https://"):
+                url_value = source_location
+
+        # Decide display_name
+        candidate_for_name = url_value or (source_location if isinstance(source_location, str) else None)
+        if candidate_for_name:
+            if isinstance(candidate_for_name, str) and (
+                candidate_for_name.startswith("http://") or candidate_for_name.startswith("https://")
+            ):
+                path = urlparse(candidate_for_name).path or ""
+                base = os.path.basename(path) or path.strip("/")
+                display_name = base or candidate_for_name
+            else:
+                display_name = os.path.basename(candidate_for_name) or str(candidate_for_name)
+        else:
+            display_name = None
+
+    except Exception as e:
+        logging.getLogger(__name__).warning(f"Failed to normalize source_location: {e}")
+        display_name = None
+        url_value = None
+
+    return {"display_name": display_name, "url": url_value}
+
+def _extract_citations_from_response(result, agent_name: str = "OCI Agent") -> Optional[Dict[str, Any]]:
+    try:
+        if not result or not hasattr(result, 'message') or not result.message:
+            return None
+        
+        message = result.message
+        if not hasattr(message, 'content') or not message.content:
+            return None
+        
+        content = message.content
+        if not hasattr(content, 'paragraph_citations') or not content.paragraph_citations:
+            return None
+        
+        paragraph_citations = []
+        for para_citation in content.paragraph_citations:
+            if hasattr(para_citation, 'paragraph') and hasattr(para_citation, 'citations'):
+                paragraph = para_citation.paragraph
+                citations = para_citation.citations
+                
+                citation_list = []
+                for citation in citations:
+                    normalized_loc = _normalize_source_location(getattr(citation, 'source_location', None))
+                    citation_dict = {
+                        "source_text": getattr(citation, 'source_text', None),
+                        "title": getattr(citation, 'title', None),
+                        "doc_id": getattr(citation, 'doc_id', None),
+                        "page_numbers": getattr(citation, 'page_numbers', None),
+                        "metadata": getattr(citation, 'metadata', None),
+                        "location_display": normalized_loc.get("display_name"),
+                        "location_url": normalized_loc.get("url"),
+                    }
+                    citation_list.append(citation_dict)
+                
+                paragraph_dict = {
+                    "paragraph": {
+                        "text": getattr(paragraph, 'text', '') or '',
+                        "start": getattr(paragraph, 'start', 0),
+                        "end": getattr(paragraph, 'end', 0)
+                    },
+                    "citations": citation_list
+                }
+                paragraph_citations.append(paragraph_dict)
+        
+        if paragraph_citations:
+            return {"paragraph_citations": paragraph_citations, "agent_name": agent_name}
+        
+        return None
+    except Exception as e:
+        logging.getLogger(__name__).warning(f"Failed to extract citations: {e}")
+        return None
+
+def _format_citations_for_display(citations: Dict[str, Any], agent_name: str = "OCI Agent") -> str:
+    """
+    Renders like:
+
+    --- Citations from [Agent Name] ---
+
+    1. Text: "..."
+       Sources:
+       1. Title: ...
+          Location: document.pdf
+          Document ID: ...
+          Pages: [1, 2]
+          Source: ...
+          Metadata: {...}
+
+    --- End Citations ---
+    """
+    if not citations or "paragraph_citations" not in citations:
+        return ""
+    
+    agent = citations.get("agent_name") or agent_name
+    blocks = []
+    blocks.append(f"\n\n--- Citations from [{agent}] ---\n")
+    
+    for idx, para_citation in enumerate(citations["paragraph_citations"], start=1):
+        p = para_citation.get("paragraph", {}) or {}
+        text = (p.get("text") or "").strip()
+        
+        line = []
+        # Ensure quoted text; json.dumps gives safe quoting and escapes
+        #line.append(f"{idx}. Text: {json.dumps(text) if text else '\"\"'}")
+        line.append("   Sources:")
+        
+        for jdx, c in enumerate(para_citation.get("citations", []) or [], start=1):
+            title = c.get("title")
+            loc_display = c.get("location_display")
+            doc_id = c.get("doc_id")
+            pages = c.get("page_numbers")
+            source_text = c.get("source_text")
+            metadata = c.get("metadata")
+            
+            line.append(f"   {jdx}. " + (f"Title: {title}" if title else "Title: (unknown)"))
+            if loc_display:
+                line.append(f"      Location: {loc_display}")
+            if doc_id:
+                line.append(f"      Document ID: {doc_id}")
+            if pages:
+                try:
+                    pages_str = json.dumps(pages, ensure_ascii=False)
+                except Exception:
+                    pages_str = str(pages)
+                line.append(f"      Pages: {pages_str}")
+            if source_text:
+                st = (source_text or "").strip()
+                if len(st) > 500:
+                    st = st[:500].rstrip() + "…"
+                #line.append(f"      Source: {st}")
+            if metadata:
+                try:
+                    md_str = json.dumps(metadata, ensure_ascii=False)
+                    line.append(f"      Metadata: {md_str}")
+                except Exception:
+                    pass
+        
+        blocks.append("\n".join(line) + "\n")
+    
+    blocks.append("--- End Citations ---")
+    return "\n".join(blocks)
+
 def _resolve_endpoint_ocid(region: str, endpoint_ocid: Optional[str], agent_ocid: Optional[str], compartment_ocid: Optional[str]) -> str:
     if endpoint_ocid:
         return endpoint_ocid
@@ -227,6 +407,13 @@ async def chat_completions(
             text = ""
             if getattr(result, "message", None) and getattr(result.message, "content", None):
                 text = getattr(result.message.content, "text", "") or ""
+            
+            agent_name = agent_cfg.get("name", "OCI Agent")
+            citations = _extract_citations_from_response(result, agent_name)
+            
+            if citations:
+                citation_text = _format_citations_for_display(citations, agent_name)
+                text += citation_text
         except oci.exceptions.ServiceError as se:
             raise HTTPException(status_code=502, detail=f"Agent chat failed ({se.status}): {getattr(se,'message',str(se))}")
 
@@ -257,6 +444,13 @@ async def chat_completions(
         result = runtime.chat(agent_endpoint_id=endpoint_id, chat_details=chat_details).data
         text = getattr(getattr(result, "message", None), "content", None)
         text = getattr(text, "text", "") if text else ""
+        
+        citations = _extract_citations_from_response(result, "OCI Agent")
+        
+        if citations:
+            citation_text = _format_citations_for_display(citations, "OCI Agent")
+            text += citation_text
+        
         tag = f"oci:agentendpoint:{endpoint_id}"
         if getattr(chat_request, "stream", False):
             return StreamingResponse(_stream_one_chunk(text, tag), media_type="text/event-stream", headers={"x-oci-session-id": session_id})

ai/gen-ai-agents/custom-rag-agent/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Luigi Saetta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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/gen-ai-agents/custom-rag-agent/README.md

@@ -1,11 +1,11 @@
-![UI](images/ui_image.png)
-
 # Custom RAG agent
 This repository contains the code for the development of a **custom RAG Agent**, based on **OCI Generative AI**, **Oracle 23AI** Vector Store and **LangGraph**
 
 **Author**: L. Saetta
 
-**Last updated**: 11/09/2025
+**Reviewed**: 23.09.2025
+
+![UI](images/ui_image.png)
 
 ## Design and implementation
 * The agent is implemented using **LangGraph**

ai/gen-ai-agents/custom-rag-agent/llm_with_mcp.py

@@ -102,7 +102,7 @@ async def _list_tools(self):
         Fetch tools from the MCP server using FastMCP. Must be async.
         """
         jwt = self.jwt_supplier()
-        
+
         logger.info("Listing tools from %s ...", self.mcp_url)
 
         # FastMCP requires async context + await for client ops.