From f651d88a811ca629bf3a3f155062406c30290a85 Mon Sep 17 00:00:00 2001 From: Omar Salem <57724072+oomaroo02@users.noreply.github.com> Date: Thu, 3 Apr 2025 09:28:03 +0200 Subject: [PATCH] Update readme.md --- .../assistant-secretary-agent/readme.md | 195 ++++++++++++------ 1 file changed, 133 insertions(+), 62 deletions(-) diff --git a/ai/gen-ai-agents/assistant-secretary-agent/readme.md b/ai/gen-ai-agents/assistant-secretary-agent/readme.md index 2a2a077ea..70461a8ce 100644 --- a/ai/gen-ai-agents/assistant-secretary-agent/readme.md +++ b/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 ": "Netherlands", + "example 2@example.com": "Poland", + "example 3@example.com": "Italy" +} +``` + +**At line 812 in the code**: +```python +EMPLOYEE_CITY_MAP = { + "example example ": "Netherlands", + "example 2@example.com": "Poland", + "example 3@example.com": "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.