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

Author: aliottoman

ai/gen-ai-agents/README.md

@@ -9,7 +9,11 @@ Oracle’s Generative AI Agents is a fully managed service that combines the pow
 - [Analysis of Structured Data and Use of AI Agents](https://luigi-saetta.medium.com/analysis-of-structured-data-and-use-of-ai-agents-a40f18da4ed5)
 - [AI Agents: The Future of Intelligent Systems in 2025](https://medium.com/@anshuman4luv/ai-agents-the-future-of-intelligent-systems-in-2025-5558c13aa328)
 - [LangChain vs LangGraph vs LangFlow vs LangSmith: A Detailed Comparison](https://medium.com/@anshuman4luv/langchain-vs-langgraph-vs-langflow-vs-langsmith-a-detailed-comparison-74bc0d7ddaa9)
-- [Developer Coaching: Unlock the power of Oracle AI](https://www.youtube.com/watch?v=6weQp8BugSg&t=2460s)
+- [Developer Coaching: Unlock the power of Oracle AI](https://www.youtube.com/watch?v=6weQp8BugSg&t)
+- [Build & Scale AI Agents with ODA & Oracle GenAI](https://www.youtube.com/watch?v=0qrxIzTvuaw)
+- [From Simple RAG to Agentic RAG: The Evolution of Retrieval-Augmented Generation](https://medium.com/@anshuman4luv/from-simple-rag-to-agentic-rag-the-evolution-of-retrieval-augmented-generation-9221a95a427e)
+- [Custom RAG Agents and NVIDIA NIM on Oracle OCI](https://luigi-saetta.medium.com/custom-rag-agents-and-nvidia-nim-on-oracle-oci-3568e1f1b59a)
+- [DMCC Transforms HR and Enterprise Operations with Oracle GenAI](https://blogs.oracle.com/ai-and-datascience/post/dmcc-transforms-hr-and-enterprise-operations-with-oracle-genai)
 
 ## Reusable Assets Overview
 - [HCM agent created by partner Conneqtion Group which contains agents to connect to Fusion HCM, Expense and many others](https://www.youtube.com/watch?v=OhZcWx_H_tQ)

ai/gen-ai-agents/sql-tool/README.md

@@ -0,0 +1,184 @@
+# Creating a NL2SQL Agent on OCI
+
+**1.  Introduction**
+
+- **Objective**: Step-by-step instructions for building and implementing
+  a SQL Agent.
+
+- **Overview**: SQL Agent simplifies data tasks by converting natural
+  language queries into SQL, leveraging large language models (LLMs).
+  Beyond language capabilities like summarization and text analysis,
+  LLMs generate SQL, enabling users to interact with databases
+  effortlessly, without requiring SQL expertise.
+
+**2. Prerequisites**
+
+- **Database Setup:**
+
+    Create the database (Oracle Base Database or Autonomous Database).
+    Database should be in a created in a private subnet (preferred) or
+    protected by access control from VCN.
+
+- **Create Table and Load Data**
+
+    Create tables in the above database and load data. You can follow instructions
+    [here](https://docs.public.content.oci.oraclecloud.com/en-us/iaas/autonomous-database-serverless/doc/load-data-autonomous.html#GUID-BCD09013-DFC9-4850-BBD2-6A90E9AE884B)
+    to connect to the DB and load data.
+
+- **Database Tool Connection:**
+
+    Create Database Tool Connection to connect to the above database.
+    Database Tool Connection should use a Private Endpoint to connect to database, You can follow this [doc](https://docs.public.content.oci.oraclecloud.com/en-us/iaas/database-tools/home.htm) for creating a DB tool connection to any Oracle database service in OCI.
+
+- **Prepare Tool Configuration Data**
+
+> User must keep the table DDLs handy before creating agent. Optionally,
+> they can also prepare Table Column Descriptions, In Context Examples
+> and Custom Instructions. These can be provided to inline to the Agent
+> creation wizard. Alternately, these can be uploaded Object Storage
+> Bucket and same be used in Agent creation wizard.
+
+- **Policies**
+
+  - Create a dynamic group with the below matching rules.
+    <img src="./media/image1.png"
+    style="width:6.26806in;height:1.30556in" />
+
+  - Add Policies to allow above dynamic group to access resources**:**
+
+allow dynamic-group \<dg-name\> to read database-tools-family in
+compartment \<compartment_name\>  
+allow dynamic-group \<dg-name\> to use database-tools-connections in
+compartment \<compartment_name\>  
+allow dynamic-group \<dg-name\> to read secret-family in compartment
+\<compartment_name\>  
+allow dynamic-group \<dg-name\> to read objects in tenancy
+
+**3. Setting Up the OCI Environment**
+
+**3.1 Logging into OCI Console**
+
+1.  Navigate to the [OCI Console](https://www.oracle.com/cloud/).
+
+2.  <img src="./media/image2.png"
+    style="width:6.34306in;height:3.30694in" />Enter your credentials
+    and click **Sign In** and open Generative AI Agents service.
+
+**4. Creating an agent**
+
+1.  Click on **Agent** and select the appropriate **Compartment** where
+    you want to create the agent.
+
+2.  Click on the **Create Agent** button and complete the required
+    fields:
+
+    1.  Basic Information
+
+        1.  Enter the mandatory fields: **Name** and **Welcome
+            Message**. The **Description** field is optional.
+
+        2.  Check the box to create endpoints for the agent.
+
+        3.  <img src="./media/image3.png"
+            style="width:6.94583in;height:3.29028in" />You can also
+            allow to add tags to organise this resource. For more info
+            check
+            [this](https://docs.oracle.com/en-us/iaas/Content/Tagging/Concepts/taggingoverview.htm).
+            Refer below screenshot.
+
+    2.  **Knowledge bases – Not required for SQL.**
+
+    3.  **Tools**: Select Conserve with your structured data in
+        database(SQL). Fill in the configuration as described below.
+
+        1.  **Name**: You need to give a meaningful name to your agent.
+
+        2.  **Description**: Provide a detailed summary of the data to
+            be used or query via this tool.
+
+        3.  **Database schema**: There are two options available to
+            import the database schema configuration for this tool.
+
+            - **Inline** –you can directly paste the SQL schema in the
+              text box.  
+              <img src="./media/image4.png" style="width:6.5in;height:3.79375in" />
+
+            - **Choose from object storage** – You can also import the
+              database schema configuration from an object storage
+              bucket. Ensure you have the correct access permissions for
+              this.  
+              <img src="./media/image5.png" style="width:6.55947in;height:3.06in" />
+
+        4.  **Model customization** : It has two option. Choose based on
+            your preference.
+
+            - Small(cost-effective) – takes less time to create but less
+              accuracy.
+
+            - Large(more accurate) – longer time but better accuracy.
+
+        5.  **Dialect** : slightly different variations of SQL, called
+            dialects. While the core SQL syntax is consistent. we
+            provide two option for this as well.
+
+            - SQLite
+
+            - Oracle SQL  
+              <img src="./media/image6.png" style="width:6.21798in;height:2.8782in" />
+
+        6.  **In-Context Learning Examples:** Provide examples to help
+            the tool generate more accurate queries. This step is
+            optional. You can import examples either inline or from an
+            object storage bucket. <img src="./media/image7.png"
+            style="width:6.89744in;height:1.08578in" />**  
+            **
+
+        7.  **Database tool connection:** you need to select and test
+            appropriate connection tool present in your compartment.  
+            <img src="./media/image8.png"
+            style="width:6.73316in;height:3.89387in" />
+
+        8.  **Enable SQL Execution**: To enable SQL execution, turn on
+            the **Enable SQL Execution** button. This allows the SQL
+            Agent to execute the query and return the result. If
+            disabled, the agent will not be able to execute the query.
+
+        9.  **Enable Self-Correction**: Enable **Self-Correction** by
+            turning on the **Enable Self-Correction** button. This
+            allows the SQL Agent to automatically correct the query if
+            any corrections are needed.  
+            <img src="./media/image9.png"
+            style="width:4.37304in;height:2.68482in" />
+
+        10. **Custom instructions** : you can give custom instructions
+            like below examples. Or can leave it empty.  
+            <img src="./media/image10.png"
+            style="width:6.52429in;height:0.98215in" />
+
+        11. D**escription of tables and columns:** You can use this
+            option to provide descriptions for tables and columns.
+            Descriptions can be imported from object storage, added
+            inline, or left blank (none).  
+            <img src="./media/image11.png" style="width:6.5in;height:2.02917in" />
+
+3.  <img src="./media/image12.png"
+    style="width:6.91319in;height:3.10278in" />Click on next button,
+    review and create an agent.
+
+**4. Launch chat**
+
+1.  Once the agent is ready and tool is created. You can launch the
+    chat.  
+    <img src="./media/image13.png" style="width:6.26806in;height:3.1in" />  
+      
+    2. This is how the chat interface will appear, displaying the same
+    **Welcome Message** that you provided earlier.  
+    <img src="./media/image14.png"
+    style="width:6.1604in;height:2.68086in" />
+
+2.  You can start asking some basic question to get SQL query like
+    this.  
+    <img src="./media/image15.png"
+    style="width:6.26806in;height:2.51389in" />
+
+3.  You can reset chat session to start new chat.

ai/gen-ai-agents/sql-tool/media/image1.png

@@ -0,0 +1 @@
+

ai/gen-ai-agents/sql-tool/media/image10.png

@@ -0,0 +1,54 @@
+# Travel Agent
+This repository contains all the code for a demo of a **Travel Agent**.
+The AI Agent enables a customer to get information about available destinations and to organize a trip, book flight, hotel...
+
+The agent has been developed using **OCI Generative AI** and **LangGraph**.
+
+## Configuration
+You only need to create a file, named config_private.py, with the value for **COMPARTMENT_OCID**.
+The compartment must be a compartment where you have setup the right policies to access OCI Generative AI.
+
+In config.py AUTH_TYPE is set to API_KEY, therefore you need to have in $HOME/.oci the key pair to access OCI.
+
+## List of libraries used
+* oci
+* langchain-community
+* langgraph
+* streamlit
+* fastapi
+* black
+* pydeck
+* uvicorn
+
+see also: requirements.txt
+
+## Demo data
+Demo data are contained in mock_data.py
+
+If you want some realistic results, you should ask to plan a trip from **Rome** to one
+of the following cities:
+* Amsterdam
+* Barcelona
+* Florence
+* Madrid
+* Valencia
+
+or, simply add other records to the JSON in mock_data.py.
+
+If you want to diplsay the positio of the Hotel in a map, you need to provide in the file
+correct values for latitude and longitude.
+
+## Supported languages
+As of now, the demo supports:
+* English
+* Italian
+
+to add other languages, you need to add the translations in translations.py and change, accordingly, some
+code in streamlit_app.py.
+
+
+
+
+
+
+

ai/gen-ai-agents/sql-tool/media/image11.png

@@ -0,0 +1,77 @@
+"""
+Base Node class for LangGraph nodes.
+
+This module defines a base class `BaseNode` for all LangGraph nodes,
+providing a standard logging interface via `log_info` and `log_error` methods.
+Each subclass should implement the `invoke(input, config=None)` method.
+"""
+
+import logging
+from langchain_core.runnables import Runnable
+
+
+class BaseNode(Runnable):
+    """
+    Abstract base class for LangGraph nodes.
+
+    All node classes in the graph should inherit from this base class.
+    It provides convenient logging utilities and stores a unique node name
+    for identification in logs and debugging.
+
+    Attributes:
+        name (str): Identifier for the node, used in logging.
+        logger (logging.Logger): Configured logger instance for the node.
+    """
+
+    def __init__(self, name: str):
+        """
+        Initialize the base node with a logger.
+
+        Args:
+            name (str): Unique name of the node for logging purposes.
+        """
+        self.name = name
+        self.logger = logging.getLogger(name)
+        self.logger.setLevel(logging.INFO)
+
+        # Attach a default console handler if no handlers are present
+        if not self.logger.handlers:
+            handler = logging.StreamHandler()
+            handler.setLevel(logging.INFO)
+            formatter = logging.Formatter(
+                "[%(asctime)s] %(levelname)s in %(name)s: %(message)s"
+            )
+            handler.setFormatter(formatter)
+            self.logger.addHandler(handler)
+
+    def log_info(self, message: str):
+        """
+        Log an informational message.
+
+        Args:
+            message (str): The message to log.
+        """
+        self.logger.info("[%s] %s", self.name, message)
+
+    def log_error(self, message: str):
+        """
+        Log an error message.
+
+        Args:
+            message (str): The error message to log.
+        """
+        self.logger.error("[%s] %s", self.name, message)
+
+    def invoke(self, state: dict, config=None, **kwargs) -> dict:
+        """
+        Abstract method to be implemented by subclasses.
+
+        Args:
+            state (dict): The current state of the workflow.
+            config (optional): Configuration options for the node.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            dict: Updated state after processing.
+        """
+        raise NotImplementedError("Subclasses must implement this method.")

ai/gen-ai-agents/sql-tool/media/image12.png

@@ -0,0 +1,40 @@
+"""
+General configuration options
+"""
+
+#
+# application configs
+#
+DEBUG = False
+
+# this is the list of the mandatory fields in user input
+# if any of these fields is missing, the agent will ask for clarification
+REQUIRED_FIELDS = [
+    "place_of_departure",
+    "destination",
+    "start_date",
+    "end_date",
+    "num_persons",
+    "transport_type",
+]
+
+# OCI GenAI services configuration
+
+# can be also INSTANCE_PRINCIPAL
+AUTH_TYPE = "API_KEY"
+
+REGION = "eu-frankfurt-1"
+SERVICE_ENDPOINT = f"https://inference.generativeai.{REGION}.oci.oraclecloud.com"
+
+# seems to work fine with both models
+MODEL_ID = "meta.llama-3.3-70b-instruct"
+# MODEL_ID = "cohere.command-a-03-2025"
+
+MAX_TOKENS = 2048
+
+# Mock API configuration
+HOTEL_API_URL = "http://localhost:8000/search/hotels"
+TRANSPORT_API_URL = "http://localhost:8000/search/transport"
+
+# Hotel Map
+MAP_STYLE = "https://basemaps.cartocdn.com/gl/positron-gl-style/style.json"

ai/gen-ai-agents/sql-tool/media/image13.png

@@ -0,0 +1,8 @@
+"""
+Config private template
+
+use it to create your config_private.py file
+This file contains sensitive information such as compartment OCIDs, and other
+"""
+
+COMPARTMENT_OCID = "ocid1.compartment.xxxx"