addition of Phishing Email Detector Agent and case studies

Our-Case-Study-to-understand_2.md

@@ -0,0 +1,161 @@
+---
+
+## Understanding the Daily Traffic Alert Agent
+
+### A Simple Case Study
+
+---
+
+## 1. The Problem in Simple Terms
+
+Every morning, you need to leave home on time to reach college or work.
+But traffic changes every day — some days it takes 30 minutes, some days 60.
+
+**Without the agent:**
+1. You wake up and manually open Google Maps
+2. You check the current traffic to your destination
+3. You calculate when to leave
+4. You set a reminder yourself
+
+You do this **every single day, manually**.
+
+---
+
+## 2. The Agent Way
+
+With the Traffic Alert Agent:
+
+➡️ You set up your details **once** (home, destination, departure time)
+➡️ The agent **automatically checks traffic every day**
+➡️ It **alerts you at the right time** before you need to leave
+
+No manual checking. No forgetting. It just works.
+
+---
+
+## 3. What Is This Agent Actually Doing?
+
+It is:
+- Following a **fixed set of steps** every day
+- Using the **Google Maps API** to get real traffic data
+- Calculating your leave time based on current conditions
+- Printing a formatted alert for you
+
+Think of it as a **smart alarm clock** that checks traffic before it rings.
+
+---
+
+## 4. The Three Steps (DAG)
+
+The agent follows exactly **3 steps in order**, every time it runs:
+
+```
+Load Config → Get Traffic → Format Report
+```
+
+### Step 1: Load Config
+Reads your saved preferences from `traffic_config.json`
+- Your home address
+- Your destination
+- Your departure time
+- How many minutes before to alert you
+
+### Step 2: Get Traffic
+Calls Google Maps Distance Matrix API with your addresses.
+Gets back:
+- Normal travel time (no traffic)
+- Current travel time (with live traffic)
+- Delay in minutes
+- Traffic status (🟢 Light / 🟡 Moderate / 🔴 Heavy)
+
+**If no API key is found** → runs in Demo Mode with simulated realistic data.
+The demo still works perfectly. No API key is required to try it.
+
+### Step 3: Format Report
+Takes the traffic data and builds a clean, readable alert:
+```
+╔══════════════════════════════════════════╗
+       🚗  DAILY TRAFFIC ALERT
+╚══════════════════════════════════════════╝
+  ⏰  Alert time    : 60 min before departure
+  🕐  Departure     : 09:00
+  📍  From          : Koregaon Park, Pune
+  🏢  To            : Hinjewadi Phase 1, Pune
+  📏  Distance      : 18.3 km
+  🕑  Normal time   : 28 mins
+  🚦  With traffic  : 52 mins
+  🔴 Heavy traffic
+  ✅  Recommended leave by: 08:03 AM
+```
+
+---
+
+## 5. Mapping to Framework Terms
+
+| What the Agent Does         | Framework Term  |
+|-----------------------------|-----------------|
+| Reads your config file      | Tool            |
+| Calls Google Maps API       | Tool            |
+| Formats the alert message   | Tool            |
+| The order: step 1→2→3       | DAG             |
+| Running all steps together  | Flow            |
+| The overall agent system    | Agent           |
+
+---
+
+## 6. The Self-Healing Fallback (Key Feature)
+
+This agent was designed so the **demo always works**, even without a real API key.
+
+| Situation                        | What Happens                          |
+|----------------------------------|---------------------------------------|
+| Google Maps API key present      | Real live traffic data from Google    |
+| No API key / API key = "demo"    | Simulated realistic traffic data      |
+| `googlemaps` library not installed | Same simulated fallback              |
+
+The simulated data even changes based on **time of day** — it gives heavier
+traffic during morning and evening rush hours, lighter traffic at night.
+This makes the demo feel real and meaningful.
+
+---
+
+## 7. State Persistence (Why `traffic_config.json` Exists)
+
+The agent saves your preferences to a local JSON file.
+This means:
+- You set up your details **once**
+- Every time the agent runs after that, it **remembers** your settings
+- No database, no cloud, no account — just a simple local file
+
+This is what the framework calls **state persistence**.
+
+---
+
+## 8. How to Run It
+
+```bash
+# Set PYTHONPATH first (required)
+export PYTHONPATH=$(pwd)          # Linux/macOS
+$env:PYTHONPATH = (Get-Location).Path  # Windows PowerShell
+
+# Step 1: Set up your preferences (run once)
+python sampleagents/traffic_agent.py --setup
+
+# Step 2: One-time check right now
+python sampleagents/traffic_agent.py --check
+
+# Step 3: Run daily scheduler (keeps running in background)
+python sampleagents/traffic_agent.py --run
+```
+
+**No API key needed for demo** — just run `--check` after `--setup`.
+
+---
+
+## 9. Final One-Line Understanding
+
+> You tell the agent your home, destination, and departure time once —
+> and every day it automatically checks live traffic and tells you
+> exactly when to leave.
+
+---

Our-Case-Study-to-understand_3.md

@@ -0,0 +1,190 @@
+---
+
+## Understanding the Phishing Email Detector Agent
+
+### A Simple Case Study
+
+---
+
+## 1. The Problem in Simple Terms
+
+Phishing emails are fake emails designed to trick you into:
+- Clicking malicious links
+- Giving away passwords or personal information
+- Believing a trusted brand (PayPal, Amazon, Google) is contacting you
+
+**Without the agent:**
+1. You receive a suspicious email
+2. You read it and try to judge if it looks fake
+3. You manually check the sender address
+4. You google whether the links are safe
+5. You decide — often incorrectly
+
+This is slow, unreliable, and most people get it wrong.
+
+---
+
+## 2. The Agent Way
+
+With the Phishing Detector Agent:
+
+➡️ You give it the email (text, `.eml` file, or run the built-in demo)
+➡️ The agent **automatically extracts suspicious signals**
+➡️ It **scores the email from 0 to 100** for phishing risk
+➡️ It **lists every red flag** it found
+➡️ An LLM reasons about it like a **cybersecurity analyst** and gives advice
+
+No manual checking. Clear verdict. Actionable advice.
+
+---
+
+## 3. What Makes This More Agentic Than Other Sample Agents?
+
+The Phishing Detector is a step further:
+
+- The **LLM actually reasons** about the email — it does not just generate text,
+  it weighs evidence and forms a judgment
+- The LLM can **challenge or confirm** the rule-based findings
+- It can catch **subtle signals** that fixed rules miss
+  (e.g. overly formal language, unusual greeting style, tone mismatch)
+
+The rules find obvious red flags. The LLM finds the ones rules cannot.
+
+---
+
+## 4. The Four Steps (DAG)
+
+```
+extract_features → check_patterns → llm_analyze → generate_report
+```
+
+### Step 1: Extract Features
+Pulls structural information out of the email:
+- Sender domain (e.g. `paypa1-security-alert.com`)
+- All URLs found in the body
+- Whether links use HTTP or HTTPS
+- URL domain extensions (`.tk`, `.ml`, `.xyz` are suspicious)
+- Urgency words (`urgent`, `click here`, `suspended`, `expires`)
+- Requests for sensitive data (`password`, `credit card`, `SSN`)
+
+### Step 2: Check Patterns (Rule-Based Scoring)
+Compares extracted features against known phishing patterns.
+Produces a **risk score from 0–100** and a list of red flags.
+
+| Pattern Detected                        | Score Added |
+|-----------------------------------------|-------------|
+| Domain impersonation (paypa1 vs paypal) | +30         |
+| Suspicious TLD in URL (.tk, .ml, etc.)  | +20         |
+| HTTP links instead of HTTPS             | +15         |
+| High-pressure urgency language (3+)     | +20         |
+| Sensitive data requested                | +25         |
+| URL domain spoofing                     | +25         |
+
+Score is capped at 100.
+
+### Step 3: LLM Analysis
+Takes everything from Steps 1 and 2 and sends it to an LLM
+with a prompt that says: *"You are a cybersecurity analyst. Review this email
+and its extracted features. What is your expert assessment?"*
+
+The LLM:
+- Validates or challenges the rule-based score
+- Finds subtle signals the rules missed
+- Explains its reasoning in plain language
+- States a final verdict: LIKELY SAFE / LOW RISK / MEDIUM RISK / HIGH RISK / CRITICAL THREAT
+
+**If no API key is available** → a smart simulated analysis runs instead,
+using the rule scores to generate a realistic advisory. The demo always works.
+
+### Step 4: Generate Report
+Assembles everything into a clean structured output:
+```
+  RISK LEVEL  : 🔴 HIGH RISK
+  RISK SCORE  : 85/100
+  URLs Found  : 1
+  Analysis    : SIMULATED (rule-based-fallback)
+
+  🚩 RED FLAGS (4):
+     • Domain impersonation: sender uses 'paypa1-security-alert.com'
+       which mimics 'paypal.com'
+     • Suspicious TLD in URL: uses '.tk' (common in malicious domains)
+     • High-pressure language: urgent, suspended, deleted, verify now
+     • Requests sensitive information: social security, credit card
+```
+
+---
+
+## 5. Mapping to Framework Terms
+
+| What the Agent Does                      | Framework Term  |
+|------------------------------------------|-----------------|
+| Pull URLs, sender, urgency words         | Tool            |
+| Score against phishing patterns          | Tool            |
+| Parse a `.eml` file into readable text   | Tool            |
+| LLM reasoning step                       | FunctionTask    |
+| The order: extract→check→analyze→report  | DAG             |
+| Running all steps together               | Flow            |
+| The overall agent system                 | Agent           |
+
+---
+
+## 6. The Three Demo Emails (No Setup Needed)
+
+The agent ships with 3 built-in sample emails so anyone can run it instantly:
+
+| Email                  | Expected Result     | What It Tests                        |
+|------------------------|---------------------|--------------------------------------|
+| PayPal suspension fake | 🔴 HIGH RISK        | Domain spoofing + sensitive data ask |
+| GitHub PR merged       | 🟢 LIKELY SAFE      | Legitimate notification pattern      |
+| Amazon reward claim    | 🟠 MEDIUM RISK      | Borderline scam language + bad URL   |
+
+These three together demonstrate the full spectrum of the agent's judgment —
+from obvious phishing to clean legitimate email to the tricky middle ground.
+
+---
+
+## 7. Dual LLM Support (Gemini + OpenRouter)
+
+The agent supports two LLM providers so it works for anyone:
+
+| Provider       | Why It's Included                                  |
+|----------------|----------------------------------------------------|
+| Google Gemini  | Easy free API key from Google AI Studio            |
+| OpenRouter     | Free DeepSeek access, popular alternative          |
+| Neither        | Simulated fallback — demo runs with zero setup     |
+
+The agent auto-detects which key is available and picks the right provider.
+You never need to configure this manually.
+
+---
+
+## 8. Input Modes
+
+The agent accepts emails in three different ways:
+
+```bash
+# Mode 1: Built-in demo (no input needed)
+python sampleagents/phishing_detector_agent.py
+
+# Mode 2: Analyze a raw text string
+python sampleagents/phishing_detector_agent.py --text "Urgent! Your account is suspended..."
+
+# Mode 3: Analyze a real .eml file
+python sampleagents/phishing_detector_agent.py --eml path/to/email.eml
+
+# Mode 4: Use with live Gemini LLM
+python sampleagents/phishing_detector_agent.py --gemini YOUR_API_KEY
+
+# Mode 5: Use with live OpenRouter/DeepSeek
+python sampleagents/phishing_detector_agent.py --openrouter YOUR_API_KEY
+```
+
+---
+
+## 9. Final One-Line Understanding
+
+> You give the agent an email — it automatically extracts suspicious signals,
+> scores the phishing risk from 0 to 100, lists every red flag,
+> and an LLM explains exactly why it is dangerous and what you should do.
+
+---