Merge branch 'main' into oag-rest-postman-request-sample

Author: oheimburger

ai/gen-ai-agents/README.md

@@ -18,6 +18,7 @@ Oracle’s Generative AI Agents is a fully managed service that combines the pow
 ## 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)
 - [Finance analytics agent created by our partner TPX impact](https://bit.ly/genai4analyst)
+- [Custom RAG agent, based on Langgraph](./custom-rag-agent)
 
 # Useful Links
 
@@ -38,3 +39,4 @@ Copyright (c) 2025 Oracle and/or its affiliates.
 Licensed under the Universal Permissive License (UPL), Version 1.0.
 
 See [LICENSE](https://github.com/oracle-devrel/technology-engineering/blob/main/LICENSE) for more details.
+

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

@@ -1,32 +1,46 @@
 ![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 DB and **LangGraph**
+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
 
 ## Design and implementation
 * The agent is implemented using **LangGraph**
 * Vector Search is implemented, using Langchain, on top of Oracle 23AI
 * A **reranker** can be used to refine the search
 
-Design decisions:
+### Design decisions:
 * For every node of the graph there is a dedicated Python class (a **Runnable**, as QueryRewriter...)
-* Reranker is implemented using a LLM. As other option, it is easy to plug-in, for example, Cohere reranker
+* **Reranker** is implemented using a LLM. As other option, it is easy to plug-in, for example, Cohere reranker
 * The agent is integrated with **OCI APM**, for **Observability**; Integration using **py-zipkin**
 * UI implemented using **Streamlit**
+* **Semantic Search** is also exposed as a [MCP server](./mcp_semantic_search_with_iam.py) 
 
-Streaming:
+### Streaming:
 * Support for streaming events from the agent: as soon as a step is completed (Vector Search, Reranking, ...) the UI is updated.
 For example, links to the documentation' chunks are displayed before the final answer is ready.
 * Streaming of the final answer.
 
+### MCP support:
+(07/2025) I have added an implementation of an **MCP** server that exposes the Semantic Search feature.
+* added a [demo LLM with MCP](./ui_mcp_agent.py) showing how to integrate a generic MCP server in a Chatbot using a LLM.
+
+**Security** can be handled in two ways:
+* custom: generate the **JWT token** using the library **PyJWT**
+* **OCI**: generate the JWT token using **OCI IAM**
+
 ## Status
-It is **wip**.
+It is always and proudly **WIP**.
 
 ## References
+For more information:
 * [Integration with OCI APM](https://luigi-saetta.medium.com/enhancing-observability-in-rag-solutions-with-oracle-cloud-6f93b2675f40)
 
 ## Advantages of the Agentic approach
-One of the primary advantages of the agentic approach is its modularity. 
+One of the primary advantages of the agentic approach is its **modularity**. 
 Customer requirements often surpass the simplicity of typical Retrieval-Augmented Generation (RAG) demonstrations. Implementing a framework like **LangGraph** necessitates organizing code into a modular sequence of steps, facilitating the seamless integration of additional features at appropriate places.​
 
 For example, to ensure that final responses do not disclose Personally Identifiable Information (PII) present in the knowledge base, one can simply append a node at the end of the graph. This node would process the generated answer, detect any PII, and anonymize it accordingly.
@@ -35,3 +49,5 @@ For example, to ensure that final responses do not disclose Personally Identifia
 * use Python 3.11
 * use the requirements.txt
 * create your config_private.py using the template provided
+* for MCP server: create a confidential application in **OCI IAM** to handle JWT tokens.
+

ai/gen-ai-agents/custom-rag-agent/README.md

@@ -40,6 +40,9 @@ class State(TypedDict):
     standalone_question: str = ""
 
     # similarity_search
+    # 30/06: modified, now they're a dict with
+    # page_content and metadata
+    # populated with docs_serializable (utils.py)
     retriever_docs: Optional[list] = []
     # reranker
     reranker_docs: Optional[list] = []

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

@@ -1,7 +1,7 @@
 """
 File name: answer_generator.py
 Author: Luigi Saetta
-Date last modified: 2025-03-31
+Date last modified: 2025-04-02
 Python Version: 3.11
 
 Description:
@@ -67,10 +67,8 @@ def build_context_for_llm(self, docs: list):
 
         docs: list[Documents]
         """
-        _context = ""
-
-        for doc in docs:
-            _context += doc.page_content + "\n\n"
+        # more Pythonic
+        _context = "\n\n".join(doc["page_content"] for doc in docs)
 
         return _context
 
@@ -79,7 +77,7 @@ def invoke(self, input: State, config=None, **kwargs):
         """
         Generate the final answer
         """
-        # get the config
+        # get the model_id from config
         model_id = config["configurable"]["model_id"]
 
         if config["configurable"]["main_language"] in self.dict_languages:
@@ -102,6 +100,7 @@ def invoke(self, input: State, config=None, **kwargs):
         try:
             llm = get_llm(model_id=model_id)
 
+            # docs are returned from the reranker
             _context = self.build_context_for_llm(input["reranker_docs"])
 
             system_prompt = PromptTemplate(

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

@@ -2,7 +2,7 @@
 File name: assistant_ui.py
 Author: Luigi Saetta
 Date created: 2024-12-04
-Date last modified: 2025-03-31
+Date last modified: 2025-07-01
 Python Version: 3.11
 
 Description:
@@ -15,7 +15,7 @@
     This code is released under the MIT License.
 
 Notes:
-    This is part of a  demo fro a RAG solution implemented
+    This is part of a  demo for a RAG solution implemented
     using LangGraph
 
 Warnings:
@@ -38,7 +38,7 @@
 from transport import http_transport
 from utils import get_console_logger
 
-# changed to better manage ENABLE_TRACING
+# changed to better manage ENABLE_TRACING (can be enabled from UI)
 import config
 
 # Constant
@@ -142,13 +142,14 @@ def register_feedback():
 
 st.sidebar.header("Options")
 
+st.sidebar.text_input(label="Region", value=config.REGION, disabled=True)
+
 # the collection used for semantic search
 st.session_state.collection_name = st.sidebar.selectbox(
     "Collection name",
     config.COLLECTION_LIST,
 )
 
-# add the choice of LLM (not used for now)
 st.session_state.main_language = st.sidebar.selectbox(
     "Select the language for the answer",
     config.LANGUAGE_LIST,
@@ -157,6 +158,9 @@ def register_feedback():
     "Select the Chat Model",
     config.MODEL_LIST,
 )
+
+st.sidebar.text_input(label="Embed Model", value=config.EMBED_MODEL_ID, disabled=True)
+
 st.session_state.enable_reranker = st.sidebar.checkbox(
     "Enable Reranker", value=True, disabled=False
 )
@@ -203,11 +207,11 @@ def register_feedback():
                     encoding=Encoding.V2_JSON,
                     sample_rate=100,
                 ) as span:
-                    # loop to manage streaming
                     # set the agent config
                     agent_config = {
                         "configurable": {
                             "model_id": st.session_state.model_id,
+                            "embed_model_type": config.EMBED_MODEL_TYPE,
                             "enable_reranker": st.session_state.enable_reranker,
                             "enable_tracing": config.ENABLE_TRACING,
                             "main_language": st.session_state.main_language,
@@ -219,6 +223,7 @@ def register_feedback():
                     if config.DEBUG:
                         logger.info("Agent config: %s", agent_config)
 
+                    # loop to manage streaming
                     for event in st.session_state.workflow.stream(
                         input_state,
                         config=agent_config,
@@ -248,13 +253,13 @@ def register_feedback():
                     # Stream
                     with st.chat_message(ASSISTANT):
                         response_container = st.empty()
-                        full_response = ""
+                        FULL_RESPONSE = ""
 
                         for chunk in answer_generator:
-                            full_response += chunk.content
-                            response_container.markdown(full_response + "▌")
+                            FULL_RESPONSE += chunk.content
+                            response_container.markdown(FULL_RESPONSE + "▌")
 
-                        response_container.markdown(full_response)
+                        response_container.markdown(FULL_RESPONSE)
 
                     elapsed_time = round((time.time() - time_start), 1)
                     logger.info("Elapsed time: %s sec.", elapsed_time)
@@ -268,7 +273,7 @@ def register_feedback():
 
                 # Add user/assistant message to chat history
                 add_to_chat_history(HumanMessage(content=question))
-                add_to_chat_history(AIMessage(content=full_response))
+                add_to_chat_history(AIMessage(content=FULL_RESPONSE))
 
                 # get the feedback
                 if st.session_state.get_feedback:

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

@@ -57,17 +57,22 @@ def fetch_text_data(self):
                 cursor.execute(query)
 
                 while True:
-                    rows = cursor.fetchmany(self.batch_size)  # Fetch records in batches
+                    # Fetch records in batches
+                    rows = cursor.fetchmany(self.batch_size)
                     if not rows:
-                        break  # Exit loop when no more data
+                        # Exit loop when no more data
+                        break
 
                     for row in rows:
-                        lob_data = row[0]  # This is a CLOB object
+                        # This is a CLOB object
+                        lob_data = row[0]
 
                         if isinstance(lob_data, oracledb.LOB):
-                            _results.append(lob_data.read())  # Read LOB content
+                            # Read LOB content
+                            _results.append(lob_data.read())
                         else:
-                            _results.append(str(lob_data))  # Fallback for non-LOB data
+                            # Fallback for non-LOB data
+                            _results.append(str(lob_data))
 
         return _results
 
@@ -116,18 +121,33 @@ def search(self, query, top_n=5):
 
 # Example Usage:
 # credential are packed in CONNECT_ARGS
-table_name = "BOOKS"
-text_column = "TEXT"
 
-# create the index
-bm25_search = BM25OracleSearch(table_name, text_column)
 
-questions = ["Chi è Luigi Saetta?", "What are the main innovation produced by GPT-4?"]
+def run_test():
+    """
+    To run a quick test.
+    """
+    table_name = "BOOKS"
+    text_column = "TEXT"
+
+    # create the index
+    bm25_search = BM25OracleSearch(table_name, text_column)
+
+    questions = [
+        "Chi è Luigi Saetta?",
+        "What are the main innovation produced by GPT-4?",
+    ]
+
+    for _question in questions:
+        results = bm25_search.search(_question, top_n=2)
+
+        # Print search results
+        for text, score in results:
+            print(f"Score: {score:.2f} - Text: {text}")
+            print("")
 
-for _question in questions:
-    results = bm25_search.search(_question, top_n=2)
 
-    # Print search results
-    for text, score in results:
-        print(f"Score: {score:.2f} - Text: {text}")
-        print("")
+#
+# Main
+#
+run_test()