agentic-base (#4)

- first commit (9b406094e66833776ff788397b51f7ba733fcdc1)
- Merge branch 'pr/4' into agentic-base (9125b1add395861a3af9d6d414c4514745d0d90c)
- agentic_base made (4f321e93870d8b10efa6c4587ab58585217018e2)

agentic_implementation/agent.py

@@ -0,0 +1,141 @@
+# agent.py
+
+import json
+from typing import Dict, Any
+
+from re_act import (
+    get_plan_from_llm,
+    think,
+    act,
+    store_name_email_mapping,
+    extract_sender_info,
+    client
+)
+from schemas import PlanStep
+from logger import logger  # from logger.py
+
+
+def run_agent():
+    """
+    Main REPL loop for the email agent.
+    """
+    logger.info("Starting Email Agent REPL...")
+    print("🤖 Email Agent ready. Type 'exit' to quit.\n")
+
+    while True:
+        try:
+            user_query = input("🗨 You: ").strip()
+            logger.info("Received user input: %s", user_query)
+
+            if user_query.lower() in ("exit", "quit"):
+                logger.info("Exit command detected, shutting down agent.")
+                print("👋 Goodbye!")
+                break
+
+            # 1) Generate plan
+            try:
+                plan = get_plan_from_llm(user_query)
+                logger.debug("Generated plan: %s", plan)
+            except Exception as e:
+                logger.error("Failed to generate plan: %s", e)
+                print(f"❌ Could not generate a plan: {e}")
+                continue
+
+            # print plan for user transparency
+            print("\n\n plan:")
+            print(plan)
+            print("\n\n")
+
+            results: Dict[str, Any] = {}
+
+            # 2) Execute each plan step
+            for step in plan.plan:
+                logger.info("Processing step: %s", step.action)
+
+                if step.action == "done":
+                    logger.info("Encountered 'done' action. Plan complete.")
+                    print("✅ Plan complete.")
+                    break
+
+                try:
+                    should_run, updated_step, user_prompt = think(step, results, user_query)
+                    logger.debug(
+                        "Think outcome for '%s': should_run=%s, updated_step=%s, user_prompt=%s",
+                        step.action, should_run, updated_step, user_prompt
+                    )
+                except Exception as e:
+                    logger.error("Error in think() for step '%s': %s", step.action, e)
+                    print(f"❌ Error in planning step '{step.action}': {e}")
+                    break
+
+                # Handle user prompt (e.g., missing email mapping)
+                if user_prompt:
+                    logger.info("User prompt required: %s", user_prompt)
+                    print(f"❓ {user_prompt}")
+                    user_input = input("📧 Email: ").strip()
+
+                    try:
+                        sender_info = extract_sender_info(user_query)
+                        sender_intent = sender_info.get("sender_intent", "")
+                        store_name_email_mapping(sender_intent, user_input)
+                        logger.info("Stored mapping: %s -> %s", sender_intent, user_input)
+                        print(f"✅ Stored mapping: {sender_intent} → {user_input}")
+
+                        # Retry current step
+                        should_run, updated_step, _ = think(step, results, user_query)
+                        logger.debug(
+                            "Post-mapping think outcome: should_run=%s, updated_step=%s",
+                            should_run, updated_step
+                        )
+                    except Exception as e:
+                        logger.error("Error storing mapping or retrying step '%s': %s", step.action, e)
+                        print(f"❌ Error storing mapping or retrying step: {e}")
+                        break
+
+                if not should_run:
+                    logger.info("Skipping step: %s", step.action)
+                    print(f"⏭️  Skipping `{step.action}`")
+                    continue
+
+                # Execute the action
+                try:
+                    output = act(updated_step)
+                    results[updated_step.action] = output
+                    logger.info("Action '%s' executed successfully.", updated_step.action)
+                    print(f"🔧 Ran `{updated_step.action}` → {output}")
+                except Exception as e:
+                    logger.error("Error executing action '%s': %s", updated_step.action, e)
+                    print(f"❌ Error running `{updated_step.action}`: {e}")
+                    break
+
+            # 3) Summarize results via LLM
+            try:
+                summary_rsp = client.chat.completions.create(
+                    model="gpt-4o-mini",
+                    temperature=0.0,
+                    messages=[
+                        {"role": "system", "content": "Summarize these results for the user in a friendly way."},
+                        {"role": "assistant", "content": json.dumps(results)}
+                    ],
+                )
+                summary = summary_rsp.choices[0].message.content
+                logger.info("Summary generated successfully.")
+                print("\n📋 Summary:\n" + summary)
+            except Exception as e:
+                logger.error("Failed to generate summary: %s", e)
+                print("\n❌ Failed to generate summary.")
+
+            print("\nAnything else I can help you with?\n")
+
+        except KeyboardInterrupt:
+            logger.info("KeyboardInterrupt received, shutting down.")
+            print("\n👋 Goodbye!")
+            break
+        except Exception as e:
+            logger.exception("Unexpected error in REPL loop: %s", e)
+            print(f"❌ Unexpected error: {e}")
+            continue
+
+
+if __name__ == "__main__":
+    run_agent()

agentic_implementation/email_db.json

@@ -0,0 +1,14 @@
+{
+  "[email protected]": {
+    "emails": [
+      {
+        "date": "07-Jun-2025",
+        "time": "16:42:51",
+        "subject": "testing",
+        "content": "hi bro",
+        "message_id": "<CAPziNCaSuVqpqNNfsRjhVbx22jN_vos3EGK_Odt-8WiD0HRKKQ@mail.gmail.com>"
+      }
+    ],
+    "last_scraped": "08-Jun-2025"
+  }
+}

agentic_implementation/email_scraper.py

@@ -0,0 +1,267 @@
+#!/usr/bin/env python3
+"""
+Enhanced Email Scraper with Intelligent Caching
+"""
+
+import os
+import imaplib
+import json
+from email import message_from_bytes
+from bs4 import BeautifulSoup
+from datetime import datetime, timedelta
+from dotenv import load_dotenv
+from zoneinfo import ZoneInfo
+from email.utils import parsedate_to_datetime
+from typing import List, Dict
+
+load_dotenv()
+
+# Email credentials
+APP_PASSWORD = os.getenv("APP_PASSWORD")
+EMAIL_ID = os.getenv("EMAIL_ID")
+EMAIL_DB_FILE = "email_db.json"
+
+def _imap_connect():
+    """Connect to Gmail IMAP server"""
+    try:
+        mail = imaplib.IMAP4_SSL("imap.gmail.com")
+        mail.login(EMAIL_ID, APP_PASSWORD)
+        mail.select('"[Gmail]/All Mail"')
+        return mail
+    except Exception as e:
+        print(f"IMAP connection failed: {e}")
+        raise
+
+def _email_to_clean_text(msg):
+    """Extract clean text from email message"""
+    # Try HTML first
+    html_content = None
+    text_content = None
+    
+    if msg.is_multipart():
+        for part in msg.walk():
+            content_type = part.get_content_type()
+            if content_type == "text/html":
+                try:
+                    html_content = part.get_payload(decode=True).decode(errors="ignore")
+                except:
+                    continue
+            elif content_type == "text/plain":
+                try:
+                    text_content = part.get_payload(decode=True).decode(errors="ignore")
+                except:
+                    continue
+    else:
+        # Non-multipart message
+        content_type = msg.get_content_type()
+        try:
+            content = msg.get_payload(decode=True).decode(errors="ignore")
+            if content_type == "text/html":
+                html_content = content
+            else:
+                text_content = content
+        except:
+            pass
+    
+    # Clean HTML content
+    if html_content:
+        soup = BeautifulSoup(html_content, "html.parser")
+        # Remove script and style elements
+        for script in soup(["script", "style"]):
+            script.decompose()
+        return soup.get_text(separator=' ', strip=True)
+    elif text_content:
+        return text_content.strip()
+    else:
+        return ""
+
+def _load_email_db() -> Dict:
+    """Load email database from file"""
+    if not os.path.exists(EMAIL_DB_FILE):
+        return {}
+    try:
+        with open(EMAIL_DB_FILE, "r") as f:
+            return json.load(f)
+    except (json.JSONDecodeError, IOError):
+        print(f"Warning: Could not load {EMAIL_DB_FILE}, starting with empty database")
+        return {}
+
+def _save_email_db(db: Dict):
+    """Save email database to file"""
+    try:
+        with open(EMAIL_DB_FILE, "w") as f:
+            json.dump(db, f, indent=2)
+    except IOError as e:
+        print(f"Error saving database: {e}")
+        raise
+
+def _date_to_imap_format(date_str: str) -> str:
+    """Convert DD-MMM-YYYY to IMAP date format"""
+    try:
+        dt = datetime.strptime(date_str, "%d-%b-%Y")
+        return dt.strftime("%d-%b-%Y")
+    except ValueError:
+        raise ValueError(f"Invalid date format: {date_str}. Expected DD-MMM-YYYY")
+
+def _is_date_in_range(email_date: str, start_date: str, end_date: str) -> bool:
+    """Check if email date is within the specified range"""
+    try:
+        email_dt = datetime.strptime(email_date, "%d-%b-%Y")
+        start_dt = datetime.strptime(start_date, "%d-%b-%Y")
+        end_dt = datetime.strptime(end_date, "%d-%b-%Y")
+        return start_dt <= email_dt <= end_dt
+    except ValueError:
+        return False
+
+def scrape_emails_from_sender(sender_email: str, start_date: str, end_date: str) -> List[Dict]:
+    """
+    Scrape emails from specific sender within date range
+    Uses intelligent caching to avoid re-scraping
+    """
+    print(f"Scraping emails from {sender_email} between {start_date} and {end_date}")
+    
+    # Load existing database
+    db = _load_email_db()
+    sender_email = sender_email.lower().strip()
+    
+    # Check if we have cached emails for this sender
+    if sender_email in db:
+        cached_emails = db[sender_email].get("emails", [])
+        
+        # Filter cached emails by date range
+        filtered_emails = [
+            email for email in cached_emails
+            if _is_date_in_range(email["date"], start_date, end_date)
+        ]
+        
+        # Check if we need to scrape more recent emails
+        last_scraped = db[sender_email].get("last_scraped", "01-Jan-2020")
+        today = datetime.today().strftime("%d-%b-%Y")
+        
+        if last_scraped == today and filtered_emails:
+            print(f"Using cached emails (last scraped: {last_scraped})")
+            return filtered_emails
+    
+    # Need to scrape emails
+    try:
+        mail = _imap_connect()
+        
+        # Prepare IMAP search criteria
+        start_imap = _date_to_imap_format(start_date)
+        # Add one day to end_date for BEFORE criteria (IMAP BEFORE is exclusive)
+        end_dt = datetime.strptime(end_date, "%d-%b-%Y") + timedelta(days=1)
+        end_imap = end_dt.strftime("%d-%b-%Y")
+        
+        search_criteria = f'(FROM "{sender_email}") SINCE "{start_imap}" BEFORE "{end_imap}"'
+        print(f"IMAP search: {search_criteria}")
+        
+        # Search for emails
+        status, data = mail.search(None, search_criteria)
+        if status != 'OK':
+            raise Exception(f"IMAP search failed: {status}")
+        
+        email_ids = data[0].split()
+        print(f"Found {len(email_ids)} emails")
+        
+        scraped_emails = []
+        
+        # Process each email
+        for i, email_id in enumerate(email_ids):
+            try:
+                print(f"Processing email {i+1}/{len(email_ids)}")
+                
+                # Fetch email
+                status, msg_data = mail.fetch(email_id, "(RFC822)")
+                if status != 'OK':
+                    continue
+                
+                # Parse email
+                msg = message_from_bytes(msg_data[0][1])
+                
+                # Extract information
+                subject = msg.get("Subject", "No Subject")
+                content = _email_to_clean_text(msg)
+                
+                # Parse date
+                date_header = msg.get("Date", "")
+                if date_header:
+                    try:
+                        dt_obj = parsedate_to_datetime(date_header)
+                        # Convert to IST
+                        ist_dt = dt_obj.astimezone(ZoneInfo("Asia/Kolkata"))
+                        email_date = ist_dt.strftime("%d-%b-%Y")
+                        email_time = ist_dt.strftime("%H:%M:%S")
+                    except:
+                        email_date = datetime.today().strftime("%d-%b-%Y")
+                        email_time = "00:00:00"
+                else:
+                    email_date = datetime.today().strftime("%d-%b-%Y")
+                    email_time = "00:00:00"
+                
+                # Get message ID for deduplication
+                message_id = msg.get("Message-ID", f"missing-{email_id.decode()}")
+                
+                scraped_emails.append({
+                    "date": email_date,
+                    "time": email_time,
+                    "subject": subject,
+                    "content": content[:2000],  # Limit content length
+                    "message_id": message_id
+                })
+                
+            except Exception as e:
+                print(f"Error processing email {email_id}: {e}")
+                continue
+        
+        mail.logout()
+        
+        # Update database
+        if sender_email not in db:
+            db[sender_email] = {"emails": [], "last_scraped": ""}
+        
+        # Merge with existing emails (avoid duplicates)
+        existing_emails = db[sender_email].get("emails", [])
+        existing_ids = {email.get("message_id") for email in existing_emails}
+        
+        new_emails = [
+            email for email in scraped_emails 
+            if email["message_id"] not in existing_ids
+        ]
+        
+        # Update database
+        db[sender_email]["emails"] = existing_emails + new_emails
+        db[sender_email]["last_scraped"] = datetime.today().strftime("%d-%b-%Y")
+        
+        # Save database
+        _save_email_db(db)
+        
+        # Return filtered results
+        all_emails = db[sender_email]["emails"]
+        filtered_emails = [
+            email for email in all_emails
+            if _is_date_in_range(email["date"], start_date, end_date)
+        ]
+        
+        print(f"Scraped {len(new_emails)} new emails, returning {len(filtered_emails)} in date range")
+        return filtered_emails
+        
+    except Exception as e:
+        print(f"Email scraping failed: {e}")
+        raise
+
+# Test the scraper
+if __name__ == "__main__":
+    # Test scraping
+    try:
+        emails = scrape_emails_from_sender(
+            "[email protected]", 
+            "01-Jun-2025", 
+            "07-Jun-2025"
+        )
+        
+        print(f"\nFound {len(emails)} emails:")
+        for email in emails[:3]:  # Show first 3
+            print(f"- {email['date']} {email['time']}: {email['subject']}")
+            
+    except Exception as e:
+        print(f"Test failed: {e}")

agentic_implementation/logger.py

@@ -0,0 +1,25 @@
+import logging
+import sys
+
+def configure_logger(name: str = None, level: int = logging.INFO) -> logging.Logger:
+    """
+    Configure and return a logger with a StreamHandler to stdout.
+    Use this function in any module to get a consistent logger.
+    """
+    logger = logging.getLogger(name)
+    logger.setLevel(level)
+
+    # Avoid adding multiple handlers to the same logger
+    if not logger.handlers:
+        handler = logging.StreamHandler(sys.stdout)
+        handler.setLevel(level)
+        formatter = logging.Formatter(
+            '%(asctime)s %(levelname)s %(name)s - %(message)s'
+        )
+        handler.setFormatter(formatter)
+        logger.addHandler(handler)
+
+    return logger
+
+# Module-level default logger
+logger = configure_logger()

agentic_implementation/name_mapping.json

@@ -0,0 +1,3 @@
+{
+  "dev agarwal": "[email protected]"
+}

agentic_implementation/re_act.py

@@ -0,0 +1,245 @@
+# orchestrator.py
+
+import os
+import json
+import re
+from typing import Any, Dict, Tuple, Optional
+from datetime import datetime
+
+from dotenv import load_dotenv
+from openai import OpenAI
+
+from schemas import Plan, PlanStep, FetchEmailsParams
+from tools import TOOL_MAPPING
+
+# Load .env and initialize OpenAI client
+load_dotenv()
+api_key = os.getenv("OPENAI_API_KEY")
+if not api_key:
+    raise RuntimeError("Missing OPENAI_API_KEY in environment")
+client = OpenAI(api_key=api_key)
+
+# File paths for name mapping
+NAME_MAPPING_FILE = "name_mapping.json"
+
+# === Hard-coded list of available actions ===
+SYSTEM_PLAN_PROMPT = """
+You are an email assistant agent. You have access to the following actions:
+
+  • fetch_emails - fetch emails based on sender and date criteria (includes date extraction)
+  • show_email - display specific email content
+  • analyze_emails - analyze email patterns or content
+  • draft_reply - create a reply to an email
+  • send_reply - send a drafted reply
+  • done - complete the task
+
+When the user gives you a query, output _only_ valid JSON of this form:
+
+{
+  "plan": [
+    "fetch_emails",
+    ...,
+    "done"
+  ]
+}
+
+Rules:
+- Use "fetch_emails" when you need to retrieve emails (it automatically handles date extraction)
+- The final entry _must_ be "done"
+- If no tool is needed, return `{"plan":["done"]}`
+
+Example: For "show me emails from dev today" → ["fetch_emails", "done"]
+"""
+
+SYSTEM_VALIDATOR_TEMPLATE = """
+You are a plan validator.  
+Context (results so far):  
+{context}
+
+Next action:  
+{action}
+
+Reply _only_ with JSON:
+{{
+  "should_execute": <true|false>,
+  "parameters": <null or a JSON object with this action's parameters>
+}}
+"""
+
+
+def _load_name_mapping() -> Dict[str, str]:
+    """Load name to email mapping from JSON file"""
+    if not os.path.exists(NAME_MAPPING_FILE):
+        return {}
+    try:
+        with open(NAME_MAPPING_FILE, "r") as f:
+            return json.load(f)
+    except (json.JSONDecodeError, IOError):
+        return {}
+
+
+def _save_name_mapping(mapping: Dict[str, str]):
+    """Save name to email mapping to JSON file"""
+    with open(NAME_MAPPING_FILE, "w") as f:
+        json.dump(mapping, f, indent=2)
+
+
+def store_name_email_mapping(name: str, email: str):
+    """Store new name to email mapping"""
+    name_mapping = _load_name_mapping()
+    name_mapping[name.lower().strip()] = email.lower().strip()
+    _save_name_mapping(name_mapping)
+
+
+def extract_sender_info(query: str) -> Dict:
+    """
+    Extract sender information from user query using LLM
+    """
+    system_prompt = """
+You are an email query parser that extracts sender information.
+
+Given a user query, extract the sender intent - the person/entity they want emails from.
+This could be:
+- A person's name (e.g., "dev", "john smith", "dev agarwal")
+- A company/service (e.g., "amazon", "google", "linkedin")
+- An email address (e.g., "[email protected]")
+
+Examples:
+- "emails from dev agarwal last week" → "dev agarwal"
+- "show amazon emails from last month" → "amazon"  
+- "emails from [email protected] yesterday" → "[email protected]"
+- "get messages from sarah" → "sarah"
+
+Return ONLY valid JSON:
+{
+  "sender_intent": "extracted name, company, or email"
+}
+"""
+    
+    response = client.chat.completions.create(
+        model="gpt-4o-mini",
+        temperature=0.0,
+        messages=[
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": query}
+        ],
+    )
+    
+    result = json.loads(response.choices[0].message.content)
+    return result
+
+
+def resolve_sender_email(sender_intent: str) -> Tuple[Optional[str], bool]:
+    """
+    Resolve sender intent to actual email address
+    Returns: (email_address, needs_user_input)
+    """
+    # Check if it's already an email address
+    if "@" in sender_intent:
+        return sender_intent.lower(), False
+    
+    # Load name mapping
+    name_mapping = _load_name_mapping()
+    
+    # Normalize the intent (lowercase for comparison)
+    normalized_intent = sender_intent.lower().strip()
+    
+    # Check direct match
+    if normalized_intent in name_mapping:
+        return name_mapping[normalized_intent], False
+    
+    # Check partial matches (fuzzy matching)
+    for name, email in name_mapping.items():
+        if normalized_intent in name.lower() or name.lower() in normalized_intent:
+            return email, False
+    
+    # No match found
+    return None, True
+
+
+def get_plan_from_llm(user_query: str) -> Plan:
+    """
+    Ask the LLM which actions to run, in order. No parameters here.
+    """
+    response = client.chat.completions.create(
+        model="gpt-4o-mini",
+        temperature=0.0,
+        messages=[
+            {"role": "system", "content": SYSTEM_PLAN_PROMPT},
+            {"role": "user",   "content": user_query},
+        ],
+    )
+
+    plan_json = json.loads(response.choices[0].message.content)
+    steps = [PlanStep(action=a) for a in plan_json["plan"]]
+    return Plan(plan=steps)
+
+
+def think(
+    step: PlanStep,
+    context: Dict[str, Any],
+    user_query: str
+) -> Tuple[bool, Optional[PlanStep], Optional[str]]:
+    """
+    Fill in parameters or skip based on the action:
+     - fetch_emails: extract sender and pass the raw query for date extraction
+     - others: ask the LLM validator for params
+    
+    Returns: (should_execute, updated_step, user_prompt_if_needed)
+    """
+    # 1) fetch_emails → extract sender and pass query for internal date extraction
+    if step.action == "fetch_emails":
+        # Extract sender using LLM
+        sender_info = extract_sender_info(user_query)
+        sender_intent = sender_info.get("sender_intent", "")
+        
+        if not sender_intent:
+            return False, None, None
+        
+        # Resolve sender to email address
+        email_address, needs_input = resolve_sender_email(sender_intent)
+        
+        if needs_input:
+            # Need user input for email address
+            prompt_msg = f"I don't have an email address for '{sender_intent}'. Please provide the email address:"
+            return False, None, prompt_msg
+        
+        params = FetchEmailsParams(
+            email=email_address,
+            query=user_query  # Pass the full query for date extraction
+        )
+        return True, PlanStep(action="fetch_emails", parameters=params), None
+
+    # 2) everything else → validate & supply params via LLM
+    prompt = SYSTEM_VALIDATOR_TEMPLATE.format(
+        context=json.dumps(context, indent=2),
+        action=step.action,
+    )
+    response = client.chat.completions.create(
+        model="gpt-4o-mini",
+        temperature=0.0,
+        messages=[
+            {"role": "system",  "content": "Validate or supply parameters for this action."},
+            {"role": "user",    "content": prompt},
+        ],
+    )
+    verdict = json.loads(response.choices[0].message.content)
+    if not verdict.get("should_execute", False):
+        return False, None, None
+
+    return True, PlanStep(
+        action=step.action,
+        parameters=verdict.get("parameters")
+    ), None
+
+
+def act(step: PlanStep) -> Any:
+    """
+    Dispatch to the actual implementation in tools.py.
+    """
+    fn = TOOL_MAPPING.get(step.action)
+    if fn is None:
+        raise ValueError(f"Unknown action '{step.action}'")
+
+    kwargs = step.parameters.model_dump() if step.parameters else {}
+    return fn(**kwargs)

agentic_implementation/schemas.py

@@ -0,0 +1,48 @@
+# schemas.py
+
+from pydantic import BaseModel, EmailStr
+from typing import List, Literal, Optional, Union
+
+
+
+class FetchEmailsParams(BaseModel):
+    email: str
+    query: str  # Changed from start_date/end_date to query for internal date extraction
+
+
+class ShowEmailParams(BaseModel):
+    message_id: str
+
+class AnalyzeEmailsParams(BaseModel):
+    emails: List[dict]
+
+class DraftReplyParams(BaseModel):
+    email: dict
+    tone: Optional[Literal["formal", "informal"]] = "formal"
+
+class SendReplyParams(BaseModel):
+    message_id: str
+    reply_body: str
+
+
+ToolParams = Union[
+    FetchEmailsParams,
+    ShowEmailParams,
+    AnalyzeEmailsParams,
+    DraftReplyParams,
+    SendReplyParams
+]
+
+class PlanStep(BaseModel):
+    action: Literal[
+        "fetch_emails",
+        "show_email",
+        "analyze_emails",
+        "draft_reply",
+        "send_reply",
+        "done",
+    ]
+    parameters: Optional[ToolParams] = None
+    
+class Plan(BaseModel):
+    plan: List[PlanStep]

agentic_implementation/tools.py

@@ -0,0 +1,193 @@
+from schemas import (
+    FetchEmailsParams,
+    ShowEmailParams,
+    AnalyzeEmailsParams,
+    DraftReplyParams,
+    SendReplyParams,
+)
+from typing import Any, Dict
+from email_scraper import scrape_emails_from_sender, _load_email_db, _save_email_db, _is_date_in_range
+from datetime import datetime
+from typing import List
+from openai import OpenAI
+import json
+from dotenv import load_dotenv
+import os
+
+# Load environment variables from .env file
+load_dotenv()
+
+# Initialize OpenAI client
+OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
+client = OpenAI(api_key=OPENAI_API_KEY)
+
+
+def extract_date_range(query: str) -> Dict[str, str]:
+    """
+    Use an LLM to extract a date range from a user query.
+    Returns {"start_date":"DD-MMM-YYYY","end_date":"DD-MMM-YYYY"}.
+    """
+    today_str = datetime.today().strftime("%d-%b-%Y")
+    system_prompt = f"""
+You are a date‐range extractor. Today is {today_str}.
+
+Given a user query (in natural language), return _only_ valid JSON with:
+  {{
+    "start_date": "DD-MMM-YYYY",
+    "end_date":   "DD-MMM-YYYY"
+  }}
+
+Interpret relative dates as:
+- "today"       → {today_str} to {today_str}
+- "yesterday"   → 1 day ago to 1 day ago
+- "last week"   → 7 days ago to {today_str}
+- "last month"  → 30 days ago to {today_str}
+- "last N days" → N days ago to {today_str}
+
+Examples:
+- "emails from dev agarwal last week"  
+  → {{ "start_date": "01-Jun-2025", "end_date": "{today_str}" }}
+- "show me emails yesterday"  
+  → {{ "start_date": "06-Jun-2025", "end_date": "06-Jun-2025" }}
+
+Return _only_ the JSON object—no extra text.
+"""
+
+    messages = [
+        {"role": "system",  "content": system_prompt},
+        {"role": "user",    "content": query}
+    ]
+    resp = client.chat.completions.create(
+        model="gpt-4o-mini",
+        temperature=0.0,
+        messages=messages
+    )
+    content = resp.choices[0].message.content.strip()
+
+    # Try direct parse; if the model added fluff, strip to the JSON block.
+    try:
+        return json.loads(content)
+    except json.JSONDecodeError:
+        start = content.find("{")
+        end = content.rfind("}") + 1
+        return json.loads(content[start:end])
+
+
+def fetch_emails(email: str, query: str) -> Dict:
+    """
+    Fetch emails from a sender within a date range extracted from the query.
+    Now returns both date info and emails.
+    
+    Args:
+        email: The sender's email address
+        query: The original user query (for date extraction)
+    
+    Returns:
+        Dict with date_info and emails
+    """
+    # Extract date range from query
+    date_info = extract_date_range(query)
+    start_date = date_info.get("start_date")
+    end_date = date_info.get("end_date")
+    
+    # Fetch emails using the existing scraper
+    emails = scrape_emails_from_sender(email, start_date, end_date)
+    
+    # Return both date info and emails
+    return {
+        "date_info": date_info,
+        "emails": emails,
+        "email_count": len(emails)
+    }
+
+
+def show_email(message_id: str) -> Dict:
+    """
+    Retrieve the full email record (date, time, subject, content, etc.)
+    from the local cache by message_id.
+    """
+    db = _load_email_db()  # returns { sender_email: { "emails": [...], "last_scraped": ... }, ... }
+
+    # Search each sender's email list
+    for sender_data in db.values():
+        for email in sender_data.get("emails", []):
+            if email.get("message_id") == message_id:
+                return email
+
+    # If we didn't find it, raise or return an error structure
+    raise ValueError(f"No email found with message_id '{message_id}'")
+
+
+def draft_reply(email: Dict, tone: str) -> str:
+    # call LLM to generate reply
+    # return a dummy reply for now
+    print(f"Drafting reply for email {email['id']} with tone: {tone}")
+    return f"Drafted reply for email {email['id']} with tone {tone}."
+    ...
+
+
+def send_reply(message_id: str, reply_body: str) -> Dict:
+    # SMTP / Gmail API send
+    print(f"Sending reply to message {message_id} with body: {reply_body}")
+    ...
+
+
+def analyze_emails(emails: List[Dict]) -> Dict:
+    """
+    Summarize and extract insights from a list of emails.
+    Returns a dict with this schema:
+      {
+        "summary": str,        # a concise overview of all emails
+        "insights": [str, ...] # list of key observations or stats
+      }
+    """
+    # 1) Prepare the email payload
+    emails_payload = json.dumps(emails, ensure_ascii=False)
+
+    # 2) Build the LLM prompt
+    system_prompt = """
+You are an expert email analyst. You will be given a JSON array of email objects,
+each with keys: date, time, subject, content, message_id.
+
+Your job is to produce _only_ valid JSON with two fields:
+1. summary: a 1–2 sentence high-level overview of these emails.
+2. insights: a list of 3–5 bullet-style observations or statistics 
+   (e.g. "2 job offers found", "overall positive tone", "next action: reply").
+
+Output exactly:
+
+{
+  "summary": "...",
+  "insights": ["...", "...", ...]
+}
+"""
+    messages = [
+        {"role": "system",  "content": system_prompt},
+        {"role": "user",    "content": f"Here are the emails:\n{emails_payload}"}
+    ]
+
+    # 3) Call the LLM
+    response = client.chat.completions.create(
+        model="gpt-4o-mini",
+        temperature=0.0,
+        messages=messages
+    )
+
+    # 4) Parse and return
+    content = response.choices[0].message.content.strip()
+    try:
+        return json.loads(content)
+    except json.JSONDecodeError:
+        # In case the model outputs extra text, extract the JSON block
+        start = content.find('{')
+        end = content.rfind('}') + 1
+        return json.loads(content[start:end])
+
+
+TOOL_MAPPING = {
+    "fetch_emails": fetch_emails,
+    "show_email": show_email,
+    "analyze_emails": analyze_emails,
+    "draft_reply": draft_reply,
+    "send_reply": send_reply,
+}

server/email_db.json

@@ -115,5 +115,21 @@
       }
     ],
     "last_scraped": "07-Jun-2025"
+  },
+  "[email protected]": {
+    "emails": [],
+    "last_scraped": "07-Jun-2025"
+  },
+  "[email protected]": {
+    "emails": [
+      {
+        "date": "07-Jun-2025",
+        "time": "16:42:51",
+        "subject": "testing",
+        "content": "hi bro",
+        "message_id": "<CAPziNCaSuVqpqNNfsRjhVbx22jN_vos3EGK_Odt-8WiD0HRKKQ@mail.gmail.com>"
+      }
+    ],
+    "last_scraped": "07-Jun-2025"
   }
 }

server/name_mapping.json

@@ -0,0 +1,3 @@
+{
+  "dev": "[email protected]"
+}