Merge pull request #1664 from oracle-devrel/omarsalemassistantagent

Update readme.md

Author: anshoracle

ai/gen-ai-agents/assistant-secretary-agent/readme.md

@@ -1,85 +1,156 @@
-Assistant Secretary Agent
-By Omar Salem
+# Assistant Secretary Agent
 
-Assistant Secretary Agent is a powerful AI chatbot that dynamically routes user input to different tools including mail, Google Calendar, Weather, Calculator, and OCI GenAI (Cohere) for general questions and OCI AI Agent RAG-based answers. It includes a Streamlit UI and supports multi-tool workflows like reading emails, summarizing, replying, scheduling meetings, fetching weather, and more.
+*An AI-powered assistant that routes user input across tools like Gmail, Google Calendar, Weather API, Calculator, and Oracle’s Generative AI services for smart, dynamic task automation.*
 
-Reviewed: March 31, 2025
+Reviewed: 31.03.2025
 
-1. Prepare Your Credentials
-Google API (Gmail + Calendar)
-Go to: Google Cloud Console
+---
 
-Enable Gmail API and Calendar API
+## When to use this asset?
 
-Create OAuth 2.0 credentials and download credentials.json
+Use this asset when you want to:
+- Automate tasks across Gmail, Calendar, and Weather
+- Get answers via OCI’s AI Agents and RAG-powered chat
+- Use a simple UI to interact with multiple tools seamlessly
+- Demo a multi-tool assistant combining local logic and cloud intelligence
 
-Place it in the project root directory
+Ideal for:
+- AI developers building assistants
+- Oracle consultants showcasing GenAI + agent capabilities
+- Technical users exploring LLM + API routing in real-world use cases
 
-The first time you run the assistant, a token.json will be created automatically after login.
+---
 
-☁️ OCI Generative AI (Cohere on OCI)
-Go to: OCI Console → Generative AI
+## How to use this asset?
 
-Select a model like cohere.command-r-plus-08-2024
+This assistant can be launched via:
+- **Terminal (CLI mode)**  
+- **Streamlit UI** for visual interaction
 
-Copy:
+It supports:
+- Reading and replying to emails  
+- Summarizing or replying smartly using GenAI  
+- Scheduling calendar events  
+- Fetching and advising based on weather  
+- Answering user queries via RAG and fallback GenAI tools
 
-model_id
+---
 
-compartment_id
+## Setup Instructions
 
-endpoint (e.g., https://inference.generativeai.us-chicago-1.oci.oraclecloud.com)
+### 🔑 Google API (Gmail + Calendar)
+1. Go to **[Google Cloud Console](https://console.cloud.google.com)**
+2. Enable the **Gmail API** and **Calendar API**
+3. Create **OAuth 2.0 Credentials** and download `credentials.json`
+4. Place `credentials.json` in your project root
+5. The first time you run the assistant, a `token.json` will be created automatically
 
-Paste them in oci_models.py
+---
 
-https://docs.oracle.com/en-us/iaas/Content/generative-ai-agents/overview.htm
-Do the same for the OCI AI AGENT endpoint. Create an AI Agent with a knowledge base and add your RAG documents in that knowledge base.
+### ☁️ OCI Generative AI (Cohere on OCI)
+1. Go to **OCI Console → Generative AI**
+2. Select a model like `cohere.command-r-plus-08-2024`
+3. Copy the following values:
+   - `model_id`
+   - `compartment_id`
+   - `endpoint` (e.g., `https://inference.generativeai.us-chicago-1.oci.oraclecloud.com`)
+4. Paste these in `oci_models.py`
 
-Weather API
-Get a free API key from: weatherapi.com
+🔗 [OCI GenAI Agent Guide](https://docs.oracle.com/en-us/iaas/Content/generative-ai-agents/overview.htm)
 
-Add the key to tools.py in:
+Also create an **AI Agent** in OCI with a knowledge base, and upload your RAG documents into that knowledge base.
 
-python
-Copy
-Edit
+---
 
+### 🌦️ Weather API
+1. Sign up at [weatherapi.com](https://www.weatherapi.com/)
+2. Get a free API key
+3. In `tools.py`, update this line with your key:
+```python
 WEATHER_API_KEY = "your_api_key_here"
+```
 
-2. Start the Chatbot
-Terminal Mode
-bash
-Copy
-Edit
+---
+
+### 💬 Start the Assistant
+
+**Terminal Mode**
+```bash
 python assistant.py
-Streamlit UI
-bash
-Copy
-Edit
-streamlit run ui.py
-You’ll see the full chat interface with interactive steps and decision routing.
-
-3. Key Features
-Tool	Description
- Fetch Gmail	Retrieves unread emails, summarizes them
- Select Email	Lets you read the full email body
- OCI AI Agent (RAG)	Provides answers from RAG agent based on sender's country
- Smart Replies	Generates professional replies using OCI GenAI
- Send Email	Sends reply to the original sender
- Schedule Emails	Delay sending with background job
- Weather + Advice	Current weather or forecast with clothing tips
- Book Meetings	Books Google Calendar events & fetches weather for the date
- Fallback Q&A	General questions or how-to help using OCI GenAI
- Calculator	Extracts & evaluates math from user input
-
-4. Notes
-Fully dynamic: user messages are routed in real-time using Cohere model hosted on OCI.
-
-Each tool is modular and can be expanded or replaced.
-
-Streamlit UI shows each step with visual feedback.
-
-5. License
-Licensed under the Universal Permissive License (UPL), Version 1.0.
-See LICENSE for details.
+```
+
+**Streamlit UI**
+```bash
+streamlit run frontend.py
+```
+
+---
+
+## Key Features
+
+| Tool               | Description                                                                 |
+|--------------------|-----------------------------------------------------------------------------|
+| Fetch Gmail        | Retrieves and summarizes unread emails                                      |
+| Select Email       | Shows full email body                                                       |
+| OCI AI Agent (RAG) | Answers based on Oracle AI Agent + RAG knowledge base                       |
+| Smart Replies      | Drafts professional responses with OCI GenAI                               |
+| Send Email         | Sends reply to the original sender                                          |
+| Schedule Emails    | Delays email sending using background job                                  |
+| Weather + Advice   | Gives weather report with clothing suggestion                              |
+| Book Meetings      | Creates Google Calendar events and checks weather for that date            |
+| Fallback Q&A       | Handles general questions using OCI GenAI                                  |
+| Calculator         | Parses and evaluates math queries                                           |
+
+---
+
+## ⚠️ Notes
+
+- The assistant dynamically routes user queries using Cohere (hosted on OCI)
+- Each tool is modular — easy to extend or replace
+- Streamlit UI provides real-time visibility on tool routing
+
+---
+
+### 🔁 Update Email Mappings (Required)
+
+To match received emails to locations (for RAG/OCI agent logic), update:
+
+**At line 397 in the code**:
+```python
+EMPLOYEE_DATA = {
+    "example example <[email protected]>": "Netherlands",
+    "example [email protected]": "Poland",
+    "example [email protected]": "Italy"
+}
+```
+
+**At line 812 in the code**:
+```python
+EMPLOYEE_CITY_MAP = {
+    "example example <[email protected]>": "Netherlands",
+    "example [email protected]": "Poland",
+    "example [email protected]": "Italy"
+}
+```
+
+Replace these keys with the **actual email addresses** you'll be receiving messages from.
+
+---
+
+## Useful Links
+
+- [Oracle Generative AI Agents](https://docs.oracle.com/en-us/iaas/Content/generative-ai-agents/overview.htm)
+    - Overview of OCI's GenAI agent features
+- [Oracle Cloud Docs](https://docs.oracle.com/en/cloud/)
+    - Full documentation for OCI services
+- [Weather API](https://www.weatherapi.com/)
+    - Used for real-time weather data
+
+---
+
+## License
+
+Copyright (c) 2024 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.