Merge branch 'main' into dependabot/pip/ai/generative-ai-service/hr-goal-alignment/files/aiohttp-3.12.14

Author: AlexanderHodicke

.gitignore

@@ -39,4 +39,8 @@ terraform.rc
 .DS_Store
 
 #VSC files
-.vscode
+.vscode
+
+# Exclude cached Python binary files
+*.pyc
+__pycache__

ai/gen-ai-agents/Document Understanding MCP AI Agent/LICENSE.txt

@@ -0,0 +1,35 @@
+Copyright (c) 2025 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 lrgrwrks.txt file if
+one is included with the Software (each a "Larger Work" to which the Software
+is contributed by such licensors),
+
+without restriction, including without limitation the rights 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 Larger Work(s), and to sublicense the foregoing rights on
+either these or other terms.
+
+This license is subject to the following condition:
+The above copyright notice and either this complete permission notice or at
+a minimum a reference to the UPL must 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/Document Understanding MCP AI Agent/README.md

@@ -0,0 +1,157 @@
+# MCP Document Understanding Invoice Agent
+
+The **Document Understanding Agent** is an AI-powered assistant designed to extract and understand text from documents (e.g., PDFs, images) using Oracle Cloud Infrastructure (OCI) Generative AI Agents and Document Understanding services.
+
+This tool demonstrates an end-to-end workflow involving:
+
+- File upload (via React frontend)
+- File storage in OCI Object Storage
+- Text extraction with OCI Document Understanding
+- Summary and reasoning via a GenAI Agent powered by MCP (Model Context Protocol)
+
+The architecture is modular and can be easily extended by adding tools directly from the OCI Console, such as a RAG (Retrieval-Augmented Generation) tool or any other custom MCP-compatible tool, enabling more advanced workflows beyond document extraction—such as contextual question answering, validation, enrichment, or classification
+
+---
+
+## When to use this asset?
+
+Use this assistant when you want to:
+
+- Automatically extract text from scanned documents (images, PDFs)
+- Invoke OCI Document Understanding tools through an AI agent
+- Demonstrate AI-based document orchestration on OCI and Validation
+
+### Ideal for:
+
+- AI developers building document understanding pipelines
+- Oracle Cloud users integrating Generative AI with Object Storage
+- Showing document AI capabilities
+
+---
+
+## How to use this asset?
+
+### Start the Backend
+
+Navigate to the backend directory and run:
+
+```bash
+cd backend
+python mcp_server_docunderstandingobjectextract.py
+(In a different terminal)
+uvicorn apiserverdocunderstandingobjectextract:app --reload --port 8001
+```
+
+This does the following:
+
+- Starts a local MCP server with a tool (`ocr_extract_from_object_storage2`) that wraps OCI Document Understanding.
+- Starts a FastAPI server that handles file uploads and routes them to Object Storage + the agent.
+
+### Start the Frontend
+
+In a separate terminal:
+
+```bash
+cd oci-genai-agent-llama-react-frontend
+npm install
+npm run dev
+```
+
+You will see a chat interface at [http://localhost:3000](http://localhost:3000), with support for file uploads (PDF, PNG, etc).
+
+When you send a file:
+
+- It's shown as a preview
+- Uploaded to the backend
+- Saved in OCI Object Storage
+- Routed to the GenAI Agent with an instruction like:
+
+```
+Extract text from object storage. Namespace: <namespace>, Bucket: <bucket>, Name: <filename>
+```
+
+---
+
+## ⚙️ Setup Instructions
+
+### 1. OCI Config
+
+Set the following in `~/.oci/config`:
+
+```ini
+[DEFAULT]
+user=ocid1.user.oc1..exampleuniqueID
+fingerprint=xx:xx:xx:xx
+key_file=~/.oci/oci_api_key.pem
+tenancy=ocid1.tenancy.oc1..exampleuniqueID
+region=us-chicago-1
+```
+
+### 2. Object Storage Setup
+
+- Create a bucket (e.g., `bucket-20250714-1419`)
+- Make sure the user has permission to `put_object` and `get_namespace`
+
+### 3. MCP Tooling
+
+- `mcp_server_docunderstandingobjectextract.py` exposes a tool `ocr_extract_from_object_storage2`
+- This is picked up by the agent automatically on FastAPI startup
+
+---
+
+## ✨ Key Features
+
+| Feature                | Description                                                       |
+| ---------------------- | ----------------------------------------------------------------- |
+| File Upload            | Upload images or PDFs through the React UI                        |
+| OCI Object Storage     | All files are stored securely in your OCI bucket                  |
+| OCR Extraction         | Uses OCI Document Understanding to extract text from scanned docs |
+| GenAI Agent            | Routes and responds to user requests intelligently                |
+| Tool Orchestration     | Agent can invoke tools dynamically (via MCP)                      |
+| Natural Language Reply | AI explains extracted results in human-readable format            |
+
+---
+
+## Prompt Customization
+
+The main agent prompt is set as:
+
+```
+If the user wants to extract text from a document in Object Storage,
+call the `ocr_extract_from_object_storage2` tool with the `namespace`, `bucket`, and `name`.
+```
+
+You can modify this in `apiserverdocunderstandingobjectextract.py` under `Agent(...)` setup.
+
+---
+
+## Useful for:
+
+- Demos of OCI Document Understanding + GenAI Agents
+- Building your own document processing pipeline
+- AI chatbots that take file input and analyze content
+
+---
+
+## Directory Structure
+
+```bash
+backend/
+├── apiserverdocunderstandingobjectextract.py   # FastAPI app
+├── mcp_server_docunderstandingobjectextract.py # MCP server with document OCR tool
+
+oci-genai-agent-llama-react-frontend/
+├── src/
+│   └── app/
+│       └── contexts/
+│           └── ChatContext.js                  # Hooks into backend API
+```
+
+---
+
+## License
+
+Copyright (c) 2025 Oracle and/or its affiliates.
+Licensed under the Universal Permissive License (UPL), Version 1.0.
+
+See LICENSE for more details.

ai/gen-ai-agents/Document Understanding MCP AI Agent/files/Backend/__pycache__/apiserverdocunderstandingobjectextract.cpython-312.pyc

@@ -0,0 +1,86 @@
+# backend/apiserver.py
+import logging
+from fastapi import FastAPI, UploadFile, File, Form
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from rich.logging import RichHandler
+from rich.markup import escape
+
+import oci
+from mcp.client.session_group import StreamableHttpParameters
+from oci.addons.adk import Agent, AgentClient
+from oci.addons.adk.mcp import MCPClientStreamableHttp
+
+# — Logging —
+logging.basicConfig(level=logging.INFO, format="%(message)s", handlers=[RichHandler()])
+logger = logging.getLogger(__name__)
+
+# — FastAPI Setup —
+app = FastAPI()
+app.add_middleware(CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"])
+
+BUCKET_NAME = "bucket-20250714-1419"
+
+@app.on_event("startup")
+async def startup_event():
+    logger.info("Connecting to MCP…")
+    mcp_params = StreamableHttpParameters(url="http://localhost:8000/mcp")
+    mcp_client = await MCPClientStreamableHttp(params=mcp_params, name="Smart Toolbox MCP").__aenter__()
+
+    client = AgentClient(auth_type="api_key", debug=False, region="us-chicago-1")
+    agent = Agent(
+        client=client,
+        agent_endpoint_id="ocid1.genaiagentendpoint",
+        instructions=(
+"If the user wants to extract text from a document in Object Storage, "
+"call the `ocr_extract_from_object_storage2` tool with the `namespace`, `bucket`, and `name`."
+
+        ),
+        tools=[await mcp_client.as_toolkit()],
+    )
+    agent.setup()
+    app.state.agent = agent
+    logger.info(" Agent ready.")
+
+@app.post("/chat")
+async def chat(message: str = Form(...), file: UploadFile = File(None)):
+    if file:
+        try:
+            file_bytes = await file.read()
+            file_name = file.filename
+
+            config = oci.config.from_file()
+            obj_client = oci.object_storage.ObjectStorageClient(config)
+            namespace = obj_client.get_namespace().data
+
+            # Upload file
+            obj_client.put_object(namespace, BUCKET_NAME, file_name, file_bytes)
+            logger.info(f" Uploaded {file_name} to {BUCKET_NAME}")
+
+            # Inject the correct call instruction to the agent
+            message = f"Extract text from object storage. Namespace: {namespace}, Bucket: {BUCKET_NAME}, Name: {file_name}"
+
+        except Exception as e:
+            logger.exception(" Upload failed")
+            return JSONResponse({"error": f"Upload failed: {str(e)}"}, status_code=500)
+
+    try:
+        result = await app.state.agent.run_async(message)
+
+        if isinstance(result.output, dict) and result.output.get("type") == "function":
+            name = result.output["name"]
+            args = result.output["parameters"]
+            logger.info(" Agent calls tool: %s(%r)", name, args)
+
+            tool_out = await app.state.agent.invoke_tool(name, args)
+            followup = await app.state.agent.run_async({"type": "tool", "name": name, "output": tool_out})
+            out = followup.output if not isinstance(followup.output, dict) else followup.output.get("text", "")
+        else:
+            out = result.output if not isinstance(result.output, dict) else result.output.get("text", "")
+
+        logger.info(" Replying: %s", escape(out))
+        return JSONResponse({"text": out})
+
+    except Exception:
+        logger.exception(" Chat error")
+        return JSONResponse({"error": "internal error"}, status_code=500)

ai/gen-ai-agents/Document Understanding MCP AI Agent/files/Backend/apiserverdocunderstandingobjectextract.py

@@ -0,0 +1,8 @@
+[DEFAULT]
+user=ocid1.user....
+fingerprint=c6:4f:6
+tenancy=ocid1.tenan...
+region=eu-frankfurt-1
+key_file=~/.oc
+
+

ai/gen-ai-agents/Document Understanding MCP AI Agent/files/Backend/config

@@ -0,0 +1,33 @@
+"""
+OCI models configuration and general config
+"""
+
+DEBUG = False
+
+MODEL_ID = "meta.llama-3.3-70b-instruct"
+
+AUTH = "API_KEY"
+SERVICE_ENDPOINT = "https://inference.generativeai.eu-frankfurt-1.oci.oraclecloud.com"
+
+TEMPERATURE = 0.1
+MAX_TOKENS = 1024
+TOP_P = 0.9
+
+# OCI general
+COMPARTMENT_ID = "ocid1.compartment."
+
+# history management
+MAX_MSGS_IN_HISTORY = 10
+# low, cause we're generating code
+MAX_ROWS_IN_SAMPLE = 10
+
+# integration with RAG
+# RAG_AGENT_ID = "ocid1.genaiagentendpoint.oc1"
+# RAG_AGENT_ENDPOINT = "https://agent-runtime.generativeai.us-chicago-1.oci.oraclecloud.com"
+# switched to Ali Agent
+RAG_AGENT_ID = "ocid1.genaiagentend"
+RAG_AGENT_ENDPOINT = (
+    "https://agent-runtime.generativeai.uk-london-1.oci.oraclecloud.com"
+)
+
+

ai/gen-ai-agents/Document Understanding MCP AI Agent/files/Backend/config.py

@@ -0,0 +1,63 @@
+import os
+import logging
+from rich.logging import RichHandler
+from rich.markup import escape
+
+import oci
+from oci.ai_document.models import (
+    AnalyzeDocumentDetails,
+    ObjectLocation,
+    ObjectStorageDocumentDetails,
+    DocumentTextExtractionFeature,
+)
+
+from mcp.server.fastmcp import FastMCP
+
+# — Logging —
+logging.basicConfig(level=logging.INFO, format="%(message)s", handlers=[RichHandler()])
+logger = logging.getLogger(__name__)
+
+# — MCP Setup —
+os.environ["MCP_PORT"] = "8000"
+mcp = FastMCP("Smart Toolbox")
+
+@mcp.tool()
+def ocr_extract_from_object_storage2(namespace: str, bucket: str, name: str) -> str:
+    """
+    Extract text from a document in Object Storage using Document Understanding.
+    """
+    try:
+        cfg = oci.config.from_file()
+        du_client = oci.ai_document.AIServiceDocumentClient(cfg)
+
+        doc = ObjectStorageDocumentDetails(
+            source="OBJECT_STORAGE",
+            namespace_name=namespace,
+            bucket_name=bucket,
+            object_name=name
+        )
+
+        feats = [DocumentTextExtractionFeature(feature_type="TEXT_EXTRACTION")]
+
+        details = AnalyzeDocumentDetails(
+            compartment_id="ocid1.compartment.oc1..aaa",
+            document=doc,
+            features=feats
+        )
+
+        resp = du_client.analyze_document(analyze_document_details=details)
+
+        text = "\n".join(
+            line.text for page in resp.data.pages or [] for line in page.lines or []
+        ).strip()
+
+        logger.info(" Extracted %d characters from %s", len(text), name)
+        return text or "No text found in document."
+
+    except Exception as e:
+        logger.exception(" Document extraction failed")
+        return f"Error: {str(e)}"
+
+if __name__ == "__main__":
+    print(" MCP server running at http://localhost:8000/mcp")
+    mcp.run(transport="streamable-http")