Merge branch 'main' into witold-swierzy-patch-8

Author: JesusGitHubOracle

.DS_Store

@@ -33,4 +33,14 @@ override.tf.json
 terraform.rc
 
 # Terraform lock files
-*.lock.hcl
+*.lock.hcl
+
+# Apple Users DS_Store
+.DS_Store
+
+#VSC files
+.vscode
+
+# Exclude cached Python binary files
+*.pyc
+__pycache__

.gitignore

@@ -1,22 +1,57 @@
-# Welcome to the Oracle Technology Specialists GitHub Repository
+# Technology Engineering GitHub Repository
 
-## Who are we?
+## Introduction
 
-We are a team of Oracle specialists focussing on technology cloud and software products. We answer questions, create demos and workshops, do hands-on guides, create code snippets and examples, and do health checks on existing solutions. We help our customers to find solutions to business challenges and to move workloads to Oracle cloud.
+### Who are we?
 
-## Why do we have a Git Repository?
+We are a team of Oracle specialists focusing on cloud and software products. We answer questions, create demos and workshops, provide hands-on guides, develop code snippets and examples, and perform health checks on existing solutions. We help our customers find solutions to business challenges and migrate workloads to the Oracle Cloud.
 
-We create all kinds of interesting assets in our line of work, which we believe should be open-source and accessible to everyone. We want to share our architecture patterns for solutions, technical step-by-step guides, and code examples. We believe this will simplify how we work internally in Oracle, while also sharing access to the same assets with our customers, implementation partners, and everyone interested. We want to be transparent on how we work and also grow the quality of our assets and best practices with the contribution coming from the community.
+### Why do we have a Git Repository?
 
-## How to use this Repository? 
+We create various interesting assets in our line of work, which we believe should be open-source and accessible to everyone. We want to share our architecture patterns for solutions, technical step-by-step guides, and code examples. We simplify how we work internally in Oracle, while also sharing access to the same assets with our customers, implementation partners, and everyone interested. We want to be transparent on how we work and also grow the quality of our assets and best practices, with contributions coming from the community.
+
+## Installation
+
+This is not a single software product repository, but a collection of various assets (code or not) in one single 'larger' repository. Thus, you won't 'install' this repository; rather, search it to find various interesting assets.
 
 We structure our assets by our internal product areas and reflect this in the folder structure of this repository. The repository will have at least four levels of folders, starting with the first representing a wider product area (like Infrastructure Cloud), followed by a specific product area (like Compute), followed by a product or cloud service (like Bare Metal Compute), and finally by an asset for that product (like How-to-Guides).
 
+As there is a lot of individual content within this repository and under a wider folder hierarchy, discovering that content is not as easy. Here's how you can find content or navigate the folder structure:
+
+- Manually search via navigation through the folder hierarchy
+- Use the search feature of GitHub on the top right-hand side of the browser - it works better if you are logged into your GitHub account. You can search specific code languages and filter content that way. Also, you can search for keywords such as 'Workshop'. Lastly, if you enter the search from a subfolder, you can choose to only search in that folder, hopefully resulting in more useful search results.
+- Use direct links to share a specific asset or folder of the repository.
+
+Some of our assets are code-based and can also be installed. There is always a README file within the asset folder, explaining the installation process.
+
+## Documentation
+
+As per the previous chapter on how to install, we have various assets in this one larger repository. If you find a code asset, it will have a README file for installation, documentation, and example purposes.
+
+## Examples
+
+As per the previous chapter on how to install, we have various assets in this one larger repository. If you find a code asset, it will have a README file for installation, documentation, and example purposes.
+
+See the bullet points from the chapter *Installation* list as an example on how to navigate the repository.
+
+## Help
+
+If you find an error, can't find what you were looking for, or would like to suggest a new asset, please use the Issues feature of GitHub (Account login required).
+
+## Contributing
+
+This project welcomes contributions from the community. Before submitting a pull request, please [review our contribution guide](./CONTRIBUTING.md).
+
+## Security
+
+Please consult the [security guide](./SECURITY.md) for our responsible security vulnerability disclosure process.
+
 ## License
+
 Copyright (c) 2025 Oracle and/or its affiliates.
 
 Licensed under the Universal Permissive License (UPL), Version 1.0.
 
 See [LICENSE](LICENSE) for more details.
 
-ORACLE AND ITS AFFILIATES DO NOT PROVIDE ANY WARRANTY WHATSOEVER, EXPRESS OR IMPLIED, FOR ANY SOFTWARE, MATERIAL OR CONTENT OF ANY KIND CONTAINED OR PRODUCED WITHIN THIS REPOSITORY, AND IN PARTICULAR SPECIFICALLY DISCLAIM ANY AND ALL IMPLIED WARRANTIES OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE.  FURTHERMORE, ORACLE AND ITS AFFILIATES DO NOT REPRESENT THAT ANY CUSTOMARY SECURITY REVIEW HAS BEEN PERFORMED WITH RESPECT TO ANY SOFTWARE, MATERIAL OR CONTENT CONTAINED OR PRODUCED WITHIN THIS REPOSITORY. IN ADDITION, AND WITHOUT LIMITING THE FOREGOING, THIRD PARTIES MAY HAVE POSTED SOFTWARE, MATERIAL OR CONTENT TO THIS REPOSITORY WITHOUT ANY REVIEW. USE AT YOUR OWN RISK. 
+ORACLE AND ITS AFFILIATES DO NOT PROVIDE ANY WARRANTY WHATSOEVER, EXPRESS OR IMPLIED, FOR ANY SOFTWARE, MATERIAL OR CONTENT OF ANY KIND CONTAINED OR PRODUCED WITHIN THIS REPOSITORY, AND IN PARTICULAR SPECIFICALLY DISCLAIM ANY AND ALL IMPLIED WARRANTIES OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE.  FURTHERMORE, ORACLE AND ITS AFFILIATES DO NOT REPRESENT THAT ANY CUSTOMARY SECURITY REVIEW HAS BEEN PERFORMED WITH RESPECT TO ANY SOFTWARE, MATERIAL OR CONTENT CONTAINED OR PRODUCED WITHIN THIS REPOSITORY. IN ADDITION, AND WITHOUT LIMITING THE FOREGOING, THIRD PARTIES MAY HAVE POSTED SOFTWARE, MATERIAL OR CONTENT TO THIS REPOSITORY WITHOUT ANY REVIEW. USE AT YOUR OWN RISK. 

.vscode/extensions.json

@@ -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.

LICENSE renamed to LICENSE.txt

@@ -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)