fix: rename agent folders to remove spaces

eod_review_agent/README.md

@@ -0,0 +1,110 @@
+# End-of-Day Review Agent
+
+Fires every day at 6:30 PM. Pulls everything from your day —
+meetings, emails sent/received, tasks done vs pending, tomorrow's
+calendar — and generates a structured EOD review + shutdown checklist.
+
+Delivers via Email + WhatsApp + Notion.
+
+## File structure
+
+```
+eod_review_agent/
+├── eod_review.py      ← Main entry point
+├── data_fetcher.py    ← Pulls all 4 data sources
+├── review_llm.py      ← Groq call + system prompt
+├── delivery.py        ← Email / WhatsApp / Notion / file
+├── tasks.txt          ← Edit daily if not using Notion tasks
+├── requirements.txt
+└── .env.example
+```
+
+## Quick start
+
+```bash
+# 1. Install
+pip install -r requirements.txt
+
+# 2. Configure
+cp .env.example .env
+# Add GROQ_API_KEY at minimum
+
+# 3. Copy Google credentials from Daily Planner Agent
+cp ../daily_planner_agent/credentials.json .
+cp ../daily_planner_agent/token.json .
+
+# 4. Add today's tasks to tasks.txt (or connect Notion)
+nano tasks.txt
+
+# 5. Test immediately
+python eod_review.py
+
+# 6. Run on schedule
+python eod_review.py --schedule
+```
+
+## Tasks: two options
+
+**Option A — Simple (tasks.txt):**
+Edit `tasks.txt` each morning, mark `[done]` as you complete things.
+The agent reads it at 6:30 PM.
+
+**Option B — Notion database:**
+Set `NOTION_TASKS_DB_ID` in `.env`. Your Notion database needs:
+- A `Name` (title) property
+- A `Status` (checkbox or select) property
+- A `Due` or `Created` date property
+
+## Sample output
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+END OF DAY — Wednesday, 14 May 2026
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+TODAY AT A GLANCE
+🗓  Meetings  : 3 meetings, ~2 hrs
+📧  Emails    : 8 received, 3 sent
+✅  Tasks Done: 2 of 5
+
+WHAT YOU ACCOMPLISHED
+• Completed the TechVentix demo — Rajesh confirmed he wants to proceed to pilot
+• Merged PR #47 — sprint blocker cleared, team can proceed
+• Replied to all starred emails (3/3)
+
+WHAT'S STILL OPEN
+⬜ Follow up on invoice INV-2031 — send a firm payment reminder first thing tomorrow
+⬜ Update project roadmap — can be done in your 13:00 focus block tomorrow
+⬜ Weekly status report — delegate the data pull to Amit, you write the summary
+
+EMAIL FOLLOW-UPS NEEDED
+- Rajesh confirmed pilot interest — send onboarding doc and next steps tonight or first thing
+- Accounts team re: INV-2031 — needs a direct call, not just email
+
+TOMORROW PREVIEW
+10:00–11:30  Sprint planning — bring updated velocity chart
+14:00–14:30  1:1 with manager — prepare 3 updates: TechVentix pilot, PR status, Q2 targets
+
+REFLECTION
+Strong client outcome today, but 2 hrs in meetings left the afternoon fragmented.
+Tomorrow's sprint planning is your biggest commitment — prep it tonight in 20 min.
+
+SHUT DOWN RITUAL ✓
+□ Pending tasks moved to tomorrow's list
+□ Urgent emails flagged for morning
+□ Calendar checked for 8 AM conflicts
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Run permanently in background
+
+```bash
+nohup python eod_review.py --schedule > eod_review.log 2>&1 &
+```
+
+Or via cron (more reliable):
+```bash
+crontab -e
+# Add:
+30 18 * * 1-6 cd /path/to/eod_review_agent && python eod_review.py >> eod_review.log 2>&1
+```

eod_review_agent/data_fetcher.py

@@ -0,0 +1,402 @@
+"""
+data_fetcher.py
+================
+Fetches all data needed for the EOD review:
+  1. Meetings had today           (Google Calendar)
+  2. Emails received today        (Gmail)
+  3. Emails sent today            (Gmail sent)
+  4. Tasks completed vs pending   (Notion API or local tasks.txt)
+  5. Tomorrow's calendar preview  (Google Calendar)
+"""
+
+import os
+import json
+import requests
+from datetime import datetime, timedelta, timezone
+from google.oauth2.credentials import Credentials
+from google_auth_oauthlib.flow import InstalledAppFlow
+from google.auth.transport.requests import Request
+from googleapiclient.discovery import build
+
+SCOPES = [
+    "https://www.googleapis.com/auth/calendar.readonly",
+    "https://www.googleapis.com/auth/gmail.readonly",
+]
+CREDENTIALS_FILE = "credentials.json"
+TOKEN_FILE       = "token.json"
+
+
+# ─── AUTH ─────────────────────────────────────────────────────────────────────
+
+def get_google_service(api_name: str, api_version: str):
+    creds = None
+    if os.path.exists(TOKEN_FILE):
+        creds = Credentials.from_authorized_user_file(TOKEN_FILE, SCOPES)
+    if not creds or not creds.valid:
+        if creds and creds.expired and creds.refresh_token:
+            creds.refresh(Request())
+        else:
+            if not os.path.exists(CREDENTIALS_FILE):
+                raise FileNotFoundError(
+                    "Missing credentials.json — copy from Daily Planner Agent folder."
+                )
+            flow = InstalledAppFlow.from_client_secrets_file(CREDENTIALS_FILE, SCOPES)
+            creds = flow.run_local_server(port=0)
+        with open(TOKEN_FILE, "w") as f:
+            f.write(creds.to_json())
+    return build(api_name, api_version, credentials=creds)
+
+
+# ─── MAIN FETCH ───────────────────────────────────────────────────────────────
+
+def fetch_all_data() -> dict:
+    """Fetch all data sources and return as a single dict."""
+    return {
+        "date_today":        datetime.now().strftime("%A, %d %B %Y"),
+        "meetings_today":    get_meetings_today(),
+        "emails_received":   get_emails_received_today(),
+        "emails_sent":       get_emails_sent_today(),
+        "tasks":             get_tasks(),
+        "tomorrow_meetings": get_tomorrow_meetings(),
+    }
+
+
+# ─── 1. MEETINGS TODAY ────────────────────────────────────────────────────────
+
+def get_meetings_today() -> list[dict]:
+    """Fetch all calendar events that occurred today."""
+    try:
+        service = get_google_service("calendar", "v3")
+        now = datetime.now(timezone.utc)
+        start = now.replace(hour=0, minute=0, second=0, microsecond=0)
+        # Only fetch meetings that have already started (up to now)
+        end = now
+
+        result = service.events().list(
+            calendarId="primary",
+            timeMin=start.isoformat(),
+            timeMax=end.isoformat(),
+            singleEvents=True,
+            orderBy="startTime",
+            maxResults=20,
+        ).execute()
+
+        meetings = []
+        for e in result.get("items", []):
+            start_raw = e.get("start", {})
+            end_raw   = e.get("end", {})
+            start_str = start_raw.get("dateTime", start_raw.get("date", ""))
+            end_str   = end_raw.get("dateTime", end_raw.get("date", ""))
+
+            def fmt(s):
+                try:
+                    return datetime.fromisoformat(s).strftime("%H:%M")
+                except Exception:
+                    return s
+
+            attendees = [
+                a.get("email", "") for a in e.get("attendees", [])
+                if not a.get("self", False)
+            ]
+
+            meetings.append({
+                "title":     e.get("summary", "Untitled"),
+                "start":     fmt(start_str),
+                "end":       fmt(end_str),
+                "attendees": attendees,
+                "duration":  _duration_mins(start_str, end_str),
+            })
+
+        return meetings or _demo_meetings_today()
+
+    except FileNotFoundError:
+        return _demo_meetings_today()
+    except Exception as e:
+        print(f"  Calendar error: {e}")
+        return _demo_meetings_today()
+
+
+# ─── 2. EMAILS RECEIVED TODAY ─────────────────────────────────────────────────
+
+def get_emails_received_today(max_results: int = 20) -> list[dict]:
+    """Fetch emails received today (inbox)."""
+    try:
+        service = get_google_service("gmail", "v1")
+        today_str = datetime.now().strftime("%Y/%m/%d")
+        query = f"after:{today_str} -category:promotions -category:social in:inbox"
+
+        result = service.users().messages().list(
+            userId="me", q=query, maxResults=max_results
+        ).execute()
+
+        return _parse_messages(service, result.get("messages", []))
+
+    except Exception as e:
+        print(f"  Gmail received error: {e}")
+        return _demo_emails_received()
+
+
+# ─── 3. EMAILS SENT TODAY ─────────────────────────────────────────────────────
+
+def get_emails_sent_today(max_results: int = 15) -> list[dict]:
+    """Fetch emails you sent today."""
+    try:
+        service = get_google_service("gmail", "v1")
+        today_str = datetime.now().strftime("%Y/%m/%d")
+        query = f"in:sent after:{today_str}"
+
+        result = service.users().messages().list(
+            userId="me", q=query, maxResults=max_results
+        ).execute()
+
+        return _parse_messages(service, result.get("messages", []))
+
+    except Exception as e:
+        print(f"  Gmail sent error: {e}")
+        return _demo_emails_sent()
+
+
+def _parse_messages(service, messages: list) -> list[dict]:
+    emails = []
+    for msg in messages:
+        detail = service.users().messages().get(
+            userId="me",
+            id=msg["id"],
+            format="metadata",
+            metadataHeaders=["Subject", "From", "To", "Date"]
+        ).execute()
+
+        headers = {
+            h["name"]: h["value"]
+            for h in detail.get("payload", {}).get("headers", [])
+        }
+        snippet = detail.get("snippet", "").replace("'", "'")[:150]
+
+        emails.append({
+            "subject": headers.get("Subject", "(no subject)"),
+            "from":    headers.get("From", ""),
+            "to":      headers.get("To", ""),
+            "snippet": snippet,
+            "starred": "STARRED" in detail.get("labelIds", []),
+        })
+    return emails
+
+
+# ─── 4. TASKS ─────────────────────────────────────────────────────────────────
+
+def get_tasks() -> list[dict]:
+    """
+    Fetch tasks from Notion database or fall back to local tasks.txt.
+    Set NOTION_TASKS_DB_ID in .env for Notion integration.
+    Otherwise, create a tasks.txt file with lines like:
+        [done] Write project proposal
+        [pending] Review PR #47
+        [pending] Call Rajesh
+    """
+    notion_db = os.getenv("NOTION_TASKS_DB_ID")
+    if notion_db:
+        return _get_notion_tasks(notion_db)
+    else:
+        return _get_local_tasks()
+
+
+def _get_notion_tasks(db_id: str) -> list[dict]:
+    """Fetch today's tasks from a Notion database."""
+    token = os.getenv("NOTION_TOKEN")
+    if not token:
+        return []
+
+    try:
+        today = datetime.now().strftime("%Y-%m-%d")
+        headers = {
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+            "Notion-Version": "2022-06-28",
+        }
+
+        # Query tasks created or due today
+        payload = {
+            "filter": {
+                "or": [
+                    {"property": "Due", "date": {"equals": today}},
+                    {"property": "Created", "date": {"equals": today}},
+                ]
+            }
+        }
+
+        resp = requests.post(
+            f"https://api.notion.com/v1/databases/{db_id}/query",
+            headers=headers,
+            json=payload,
+            timeout=10,
+        )
+        resp.raise_for_status()
+        pages = resp.json().get("results", [])
+
+        tasks = []
+        for page in pages:
+            props = page.get("properties", {})
+            title_prop = props.get("Name", props.get("Title", {}))
+            title_items = title_prop.get("title", [])
+            title = title_items[0]["plain_text"] if title_items else "Untitled"
+
+            # Try to get status
+            status_prop = props.get("Status", props.get("Checkbox", {}))
+            done = False
+            if status_prop.get("type") == "checkbox":
+                done = status_prop.get("checkbox", False)
+            elif status_prop.get("type") == "status":
+                done = status_prop.get("status", {}).get("name", "").lower() in ("done", "complete", "completed")
+
+            tasks.append({"title": title, "done": done})
+
+        return tasks or _demo_tasks()
+
+    except Exception as e:
+        print(f"  Notion tasks error: {e}")
+        return _demo_tasks()
+
+
+def _get_local_tasks() -> list[dict]:
+    """
+    Read from local tasks.txt.
+    Format each line as:
+        [done] Task name
+        [pending] Task name
+    """
+    tasks_file = os.getenv("TASKS_FILE", "tasks.txt")
+    tasks = []
+
+    if not os.path.exists(tasks_file):
+        return _demo_tasks()
+
+    with open(tasks_file, "r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            if line.lower().startswith("[done]"):
+                tasks.append({"title": line[6:].strip(), "done": True})
+            elif line.lower().startswith("[pending]"):
+                tasks.append({"title": line[9:].strip(), "done": False})
+            else:
+                tasks.append({"title": line, "done": False})
+
+    return tasks or _demo_tasks()
+
+
+# ─── 5. TOMORROW'S MEETINGS ───────────────────────────────────────────────────
+
+def get_tomorrow_meetings() -> list[dict]:
+    """Fetch tomorrow's calendar events."""
+    try:
+        service = get_google_service("calendar", "v3")
+        now = datetime.now(timezone.utc)
+        tomorrow_start = (now + timedelta(days=1)).replace(
+            hour=0, minute=0, second=0, microsecond=0
+        )
+        tomorrow_end = tomorrow_start.replace(hour=23, minute=59, second=59)
+
+        result = service.events().list(
+            calendarId="primary",
+            timeMin=tomorrow_start.isoformat(),
+            timeMax=tomorrow_end.isoformat(),
+            singleEvents=True,
+            orderBy="startTime",
+            maxResults=10,
+        ).execute()
+
+        meetings = []
+        for e in result.get("items", []):
+            start_raw = e.get("start", {})
+            end_raw   = e.get("end", {})
+            start_str = start_raw.get("dateTime", start_raw.get("date", ""))
+            end_str   = end_raw.get("dateTime", end_raw.get("date", ""))
+
+            def fmt(s):
+                try:
+                    return datetime.fromisoformat(s).strftime("%H:%M")
+                except Exception:
+                    return s
+
+            attendees = [
+                a.get("email", "") for a in e.get("attendees", [])
+                if not a.get("self", False)
+            ]
+
+            meetings.append({
+                "title":     e.get("summary", "Untitled"),
+                "start":     fmt(start_str),
+                "end":       fmt(end_str),
+                "attendees": attendees,
+            })
+
+        return meetings or _demo_tomorrow_meetings()
+
+    except FileNotFoundError:
+        return _demo_tomorrow_meetings()
+    except Exception as e:
+        print(f"  Tomorrow calendar error: {e}")
+        return _demo_tomorrow_meetings()
+
+
+# ─── UTILITIES ────────────────────────────────────────────────────────────────
+
+def _duration_mins(start_str: str, end_str: str) -> int:
+    try:
+        start = datetime.fromisoformat(start_str)
+        end   = datetime.fromisoformat(end_str)
+        return int((end - start).total_seconds() / 60)
+    except Exception:
+        return 0
+
+
+# ─── DEMO DATA ────────────────────────────────────────────────────────────────
+
+def _demo_meetings_today() -> list[dict]:
+    print("  Using demo meeting data.")
+    return [
+        {"title": "Team standup", "start": "09:00", "end": "09:30",
+         "attendees": ["team@company.com"], "duration": 30},
+        {"title": "Client demo — TechVentix", "start": "11:00", "end": "12:00",
+         "attendees": ["rajesh@techventix.com"], "duration": 60},
+        {"title": "HR review call", "start": "15:00", "end": "15:30",
+         "attendees": ["hr@company.com"], "duration": 30},
+    ]
+
+def _demo_emails_received() -> list[dict]:
+    print("  Using demo email data.")
+    return [
+        {"subject": "Re: Project proposal", "from": "Rajesh <rajesh@client.com>",
+         "snippet": "Looks good, let's proceed with the pilot.", "starred": True},
+        {"subject": "PR #47 merged", "from": "GitHub <noreply@github.com>",
+         "snippet": "Amit merged pull request #47 into main.", "starred": False},
+        {"subject": "Invoice paid", "from": "Razorpay <noreply@razorpay.com>",
+         "snippet": "Payment of ₹45,000 received from TechVentix.", "starred": False},
+    ]
+
+def _demo_emails_sent() -> list[dict]:
+    return [
+        {"subject": "Demo follow-up", "to": "rajesh@techventix.com",
+         "snippet": "Thanks for your time today. Sharing the pilot details.", "starred": False},
+        {"subject": "PR review comments", "to": "amit@team.com",
+         "snippet": "Left comments on lines 45-67. Please fix before re-review.", "starred": False},
+    ]
+
+def _demo_tasks() -> list[dict]:
+    print("  Using demo task data.")
+    return [
+        {"title": "Reply to Rajesh demo follow-up", "done": True},
+        {"title": "Review PR #47",                  "done": True},
+        {"title": "Follow up on invoice INV-2031",  "done": False},
+        {"title": "Update project roadmap doc",     "done": False},
+        {"title": "Send weekly report to manager",  "done": False},
+    ]
+
+def _demo_tomorrow_meetings() -> list[dict]:
+    return [
+        {"title": "Sprint planning", "start": "10:00", "end": "11:30",
+         "attendees": ["team@company.com"]},
+        {"title": "1:1 with manager", "start": "14:00", "end": "14:30",
+         "attendees": ["manager@company.com"]},
+    ]

eod_review_agent/delivery.py

@@ -0,0 +1,183 @@
+"""
+delivery.py
+============
+Delivers the EOD review via Email, WhatsApp, and Notion.
+Also saves a local copy to eod_reviews/ folder.
+"""
+
+import os
+import smtplib
+import requests
+from email.mime.text import MIMEText
+from email.mime.multipart import MIMEMultipart
+from datetime import datetime
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+def deliver_review(review: str, data: dict):
+    """Deliver EOD review to all configured channels."""
+    today   = data.get("date_today", datetime.now().strftime("%A, %d %B %Y"))
+    subject = f"End-of-Day Review — {today}"
+
+    # Always print to console
+    print("\n" + "="*54)
+    print(review)
+    print("="*54 + "\n")
+
+    # Always save locally
+    _save_to_file(review)
+    print("  ✓ Saved to eod_reviews/ folder")
+
+    # Email
+    if os.getenv("EMAIL_ENABLED", "false").lower() == "true":
+        try:
+            _send_email(subject, review)
+            print("  ✓ Email sent")
+        except Exception as e:
+            print(f"  ✗ Email failed: {e}")
+
+    # WhatsApp
+    if os.getenv("WHATSAPP_ENABLED", "false").lower() == "true":
+        try:
+            _send_whatsapp(review)
+            print("  ✓ WhatsApp sent")
+        except Exception as e:
+            print(f"  ✗ WhatsApp failed: {e}")
+
+    # Notion
+    if os.getenv("NOTION_ENABLED", "false").lower() == "true":
+        try:
+            _save_to_notion(review, subject)
+            print("  ✓ Saved to Notion")
+        except Exception as e:
+            print(f"  ✗ Notion failed: {e}")
+
+
+# ─── EMAIL ────────────────────────────────────────────────────────────────────
+
+def _send_email(subject: str, body: str):
+    sender    = os.getenv("EMAIL_SENDER")
+    password  = os.getenv("EMAIL_PASSWORD")
+    recipient = os.getenv("EMAIL_RECIPIENT", sender)
+
+    if not sender or not password:
+        raise ValueError("EMAIL_SENDER and EMAIL_PASSWORD required in .env")
+
+    msg = MIMEMultipart("alternative")
+    msg["Subject"] = subject
+    msg["From"]    = sender
+    msg["To"]      = recipient
+
+    msg.attach(MIMEText(body, "plain"))
+    msg.attach(MIMEText(_to_html(body), "html"))
+
+    with smtplib.SMTP_SSL("smtp.gmail.com", 465) as server:
+        server.login(sender, password)
+        server.sendmail(sender, recipient, msg.as_string())
+
+
+def _to_html(text: str) -> str:
+    EMOJI_COLORS = {
+        "✅": "#27ae60", "⬜": "#e67e22", "⭐": "#f1c40f",
+        "🗓": "#3498db", "📧": "#9b59b6", "□": "#95a5a6",
+    }
+    lines = text.split("\n")
+    html  = []
+    for line in lines:
+        if line.startswith("━"):
+            html.append("<hr style='border:1px solid #ddd;margin:12px 0'>")
+        elif line.startswith("END OF DAY"):
+            html.append(f"<h2 style='color:#2c3e50;font-family:sans-serif'>{line}</h2>")
+        elif line.isupper() and len(line) > 3 and not line.startswith("□"):
+            html.append(f"<h3 style='color:#555;font-family:sans-serif;margin-top:16px'>{line}</h3>")
+        elif line.strip():
+            html.append(f"<p style='font-family:sans-serif;color:#333;margin:4px 0;line-height:1.5'>{line}</p>")
+    return f"""
+    <div style='max-width:620px;margin:0 auto;padding:24px;background:#fff'>
+        {''.join(html)}
+        <p style='color:#bbb;font-size:11px;margin-top:24px'>
+            Sent by your End-of-Day Review Agent at {datetime.now().strftime('%H:%M')}
+        </p>
+    </div>
+    """
+
+
+# ─── WHATSAPP ─────────────────────────────────────────────────────────────────
+
+def _send_whatsapp(message: str):
+    try:
+        from twilio.rest import Client
+    except ImportError:
+        raise ImportError("Run: pip install twilio")
+
+    sid      = os.getenv("TWILIO_ACCOUNT_SID")
+    auth     = os.getenv("TWILIO_AUTH_TOKEN")
+    from_num = os.getenv("TWILIO_FROM")
+    to_num   = os.getenv("TWILIO_TO")
+
+    if not all([sid, auth, from_num, to_num]):
+        raise ValueError("Twilio credentials missing in .env")
+
+    client = Client(sid, auth)
+    # Split into 1600-char chunks (WhatsApp limit)
+    for chunk in [message[i:i+1600] for i in range(0, len(message), 1600)]:
+        client.messages.create(body=chunk, from_=from_num, to=to_num)
+
+
+# ─── NOTION ───────────────────────────────────────────────────────────────────
+
+def _save_to_notion(review: str, title: str):
+    token = os.getenv("NOTION_TOKEN")
+    db_id = os.getenv("NOTION_DATABASE_ID")
+
+    if not token or not db_id:
+        raise ValueError("NOTION_TOKEN and NOTION_DATABASE_ID required in .env")
+
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Content-Type": "application/json",
+        "Notion-Version": "2022-06-28",
+    }
+
+    blocks = []
+    for para in review.split("\n"):
+        if not para.strip():
+            continue
+        if para.startswith("━"):
+            blocks.append({"object": "block", "type": "divider", "divider": {}})
+        else:
+            blocks.append({
+                "object": "block",
+                "type": "paragraph",
+                "paragraph": {
+                    "rich_text": [{"type": "text", "text": {"content": para[:2000]}}]
+                }
+            })
+
+    payload = {
+        "parent": {"database_id": db_id},
+        "properties": {
+            "Name": {"title": [{"text": {"content": title}}]},
+            "Date": {"date": {"start": datetime.now().strftime("%Y-%m-%d")}},
+        },
+        "children": blocks[:100],
+    }
+
+    resp = requests.post(
+        "https://api.notion.com/v1/pages",
+        headers=headers,
+        json=payload,
+        timeout=15,
+    )
+    resp.raise_for_status()
+
+
+# ─── FILE SAVE ────────────────────────────────────────────────────────────────
+
+def _save_to_file(review: str):
+    os.makedirs("eod_reviews", exist_ok=True)
+    filename = f"eod_reviews/{datetime.now().strftime('%Y-%m-%d')}.txt"
+    with open(filename, "w", encoding="utf-8") as f:
+        f.write(review)

eod_review_agent/eod_review.py

@@ -0,0 +1,79 @@
+"""
+End-of-Day Review Agent
+========================
+Fires every day at 6:30 PM.
+Pulls data from 4 sources:
+  - Google Calendar (meetings had today)
+  - Gmail (emails sent & received today)
+  - Tasks (Notion or local file)
+  - Google Calendar again (tomorrow's preview)
+Then generates a structured EOD review + tomorrow prep via Groq.
+Delivers via Email + WhatsApp + Notion.
+
+Usage:
+    python eod_review.py            # Run once immediately
+    python eod_review.py --schedule # Run on schedule at 6:30 PM daily
+"""
+
+import os
+import argparse
+import schedule
+import time
+from datetime import datetime
+import os as _os
+from dotenv import load_dotenv
+
+from data_fetcher import fetch_all_data
+from review_llm import generate_eod_review
+from delivery import deliver_review
+
+load_dotenv(_os.path.join(_os.path.dirname(_os.path.abspath(__file__)), "..", ".env"))
+
+
+def run_agent():
+    print(f"\n{'='*54}")
+    print(f"End-of-Day Review Agent — {datetime.now().strftime('%A %d %B %Y, %H:%M')}")
+    print("="*54)
+
+    print("\n[1/3] Fetching today's data...")
+    data = fetch_all_data()
+    print(f"      Meetings today : {len(data['meetings_today'])}")
+    print(f"      Emails received: {len(data['emails_received'])}")
+    print(f"      Emails sent    : {len(data['emails_sent'])}")
+    print(f"      Tasks          : {len(data['tasks'])}")
+    print(f"      Tomorrow events: {len(data['tomorrow_meetings'])}")
+
+    print("\n[2/3] Generating review with Groq...")
+    review = generate_eod_review(data)
+    print("      Review generated.")
+
+    print("\n[3/3] Delivering review...")
+    deliver_review(review, data)
+
+    print("\nDone! End-of-day review delivered.\n")
+    return review
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="End-of-Day Review Agent")
+    parser.add_argument("--schedule", action="store_true",
+                        help="Run on schedule at 6:30 PM daily")
+    parser.add_argument("--time", default="18:30",
+                        help="Schedule time HH:MM (default: 18:30)")
+    args = parser.parse_args()
+
+    if args.schedule:
+        print(f"Scheduler started. Will run daily at {args.time}.")
+        print("Press Ctrl+C to stop.\n")
+        schedule.every().day.at(args.time).do(run_agent)
+        # Run once immediately on start
+        run_agent()
+        while True:
+            schedule.run_pending()
+            time.sleep(60)
+    else:
+        review = run_agent()
+        print("\n" + "="*54)
+        print("YOUR END-OF-DAY REVIEW:")
+        print("="*54)
+        print(review)

eod_review_agent/eod_reviews/2026-05-14.txt

@@ -0,0 +1,35 @@
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+END OF DAY — Thursday, 14 May 2026
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+TODAY AT A GLANCE
+🗓  Meetings  : 3 meetings, total 2 hrs
+📧  Emails    : 3 received, 2 sent
+✅  Tasks Done: 2 of 11 total
+
+WHAT YOU ACCOMPLISHED
+* Successfully completed the client demo with TechVentix and sent a follow-up email with pilot details.
+* Approved PR #47 and left review comments on lines 45-67 for Amit to address.
+* Responded to Rajesh's email regarding the project proposal, moving the pilot forward.
+
+WHAT'S STILL OPEN
+* Follow up on overdue invoice INV-2031: Send a reminder email to the client with a clear deadline for payment.
+* Update project roadmap document: Allocate 30 minutes tomorrow to review and update the document.
+* Send weekly status report to manager: Prepare a draft tonight and review it before sending it to the manager tomorrow.
+
+EMAIL FOLLOW-UPS NEEDED
+* Rajesh's response to the demo follow-up email: Wait for his confirmation on the pilot details.
+* Amit's response to PR review comments: Follow up on the changes made to the code.
+
+TOMORROW PREVIEW
+* 10:00–11:30  Sprint planning: Review the team's tasks and objectives for the upcoming sprint.
+* 14:00–14:30  1:1 with manager: Prepare an update on your tasks and discuss any challenges or concerns.
+
+REFLECTION
+You had a productive day with effective meetings and task management, but there are still 9 pending tasks that need attention. Consider prioritizing tasks based on urgency and importance to manage your workload better.
+
+SHUT DOWN RITUAL ✓
+□ Pending tasks moved to tomorrow's list
+□ Urgent emails flagged for morning
+□ Calendar checked for 8 AM conflicts
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

eod_review_agent/requirements.txt

@@ -0,0 +1,9 @@
+groq>=0.9.0
+google-auth>=2.27.0
+google-auth-oauthlib>=1.2.0
+google-auth-httplib2>=0.2.0
+google-api-python-client>=2.120.0
+python-dotenv>=1.0.0
+schedule>=1.2.0
+requests>=2.31.0
+twilio>=9.0.0

eod_review_agent/review_llm.py

@@ -0,0 +1,146 @@
+"""
+review_llm.py
+==============
+Sends all day's data to Groq and returns a structured EOD review.
+"""
+
+import os
+from groq import Groq
+
+SYSTEM_PROMPT = """You are a sharp personal productivity coach wrapping up the day for a busy IT professional in Ahmedabad, India.
+
+You receive a full summary of their day: meetings had, emails received and sent, tasks done vs pending, and tomorrow's calendar.
+
+Generate a concise, honest end-of-day review in EXACTLY this format:
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+END OF DAY — [Day, Date]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+TODAY AT A GLANCE
+🗓  Meetings  : [N meetings, total X hrs]
+📧  Emails    : [N received, N sent]
+✅  Tasks Done: [N of N total]
+
+WHAT YOU ACCOMPLISHED
+[2-3 bullet points — specific wins from meetings, emails, and tasks completed]
+
+WHAT'S STILL OPEN
+[Bullet each pending task with a one-line suggestion: carry forward / delegate / drop]
+
+EMAIL FOLLOW-UPS NEEDED
+[List 1-3 emails that likely need a reply or action tomorrow. If none: "Inbox actioned."]
+
+TOMORROW PREVIEW
+[List each meeting with time and one-line prep note]
+[If no meetings: "No meetings tomorrow — protect it for deep work."]
+
+REFLECTION
+[One honest, specific observation about today — productivity pattern, energy use, or a lesson]
+
+SHUT DOWN RITUAL ✓
+□ Pending tasks moved to tomorrow's list
+□ Urgent emails flagged for morning
+□ Calendar checked for 8 AM conflicts
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Rules:
+- Be specific — reference actual meeting names, email subjects, task titles from the data.
+- "What's still open" must have concrete next-action suggestions, not vague "follow up."
+- Reflection must be honest and personal, not generic motivational fluff.
+- Total length: under 400 words.
+- Tone: calm, grounded, like a trusted coach reviewing the day with you.
+"""
+
+
+def generate_eod_review(data: dict) -> str:
+    """
+    Generate end-of-day review from the day's collected data.
+
+    Args:
+        data: Dict from data_fetcher.fetch_all_data()
+
+    Returns:
+        Formatted EOD review string
+    """
+    api_key = os.getenv("GROQ_API_KEY")
+    if not api_key:
+        raise ValueError("GROQ_API_KEY not found in .env")
+
+    client = Groq(api_key=api_key)
+    context = _build_context(data)
+
+    response = client.chat.completions.create(
+        model="llama-3.3-70b-versatile",
+        max_tokens=1200,
+        messages=[
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "user",   "content": context},
+        ]
+    )
+
+    return response.choices[0].message.content
+
+
+def _build_context(data: dict) -> str:
+    lines = [f"DATE: {data['date_today']}", ""]
+
+    # Meetings today
+    meetings = data.get("meetings_today", [])
+    total_mins = sum(m.get("duration", 0) for m in meetings)
+    lines.append(f"MEETINGS TODAY ({len(meetings)}, ~{total_mins} min total):")
+    if meetings:
+        for m in meetings:
+            att = ", ".join(m.get("attendees", [])) or "internal"
+            lines.append(f"  - {m['start']}–{m['end']}  {m['title']}  [{att}]")
+    else:
+        lines.append("  No meetings today.")
+    lines.append("")
+
+    # Emails received
+    received = data.get("emails_received", [])
+    lines.append(f"EMAILS RECEIVED TODAY ({len(received)}):")
+    for e in received[:10]:
+        flag = "⭐ " if e.get("starred") else "   "
+        lines.append(f"  {flag}From: {e['from']} | {e['subject']} | {e['snippet'][:100]}")
+    if not received:
+        lines.append("  None.")
+    lines.append("")
+
+    # Emails sent
+    sent = data.get("emails_sent", [])
+    lines.append(f"EMAILS SENT TODAY ({len(sent)}):")
+    for e in sent[:8]:
+        lines.append(f"  - To: {e.get('to','')} | {e['subject']} | {e['snippet'][:100]}")
+    if not sent:
+        lines.append("  None sent today.")
+    lines.append("")
+
+    # Tasks
+    tasks = data.get("tasks", [])
+    done    = [t for t in tasks if t.get("done")]
+    pending = [t for t in tasks if not t.get("done")]
+    lines.append(f"TASKS ({len(done)} done, {len(pending)} pending):")
+    if done:
+        lines.append("  Completed:")
+        for t in done:
+            lines.append(f"    ✅ {t['title']}")
+    if pending:
+        lines.append("  Still pending:")
+        for t in pending:
+            lines.append(f"    ⬜ {t['title']}")
+    if not tasks:
+        lines.append("  No tasks data available.")
+    lines.append("")
+
+    # Tomorrow
+    tomorrow = data.get("tomorrow_meetings", [])
+    lines.append(f"TOMORROW'S CALENDAR ({len(tomorrow)} meetings):")
+    if tomorrow:
+        for m in tomorrow:
+            att = ", ".join(m.get("attendees", [])) or "internal"
+            lines.append(f"  - {m['start']}–{m['end']}  {m['title']}  [{att}]")
+    else:
+        lines.append("  No meetings scheduled tomorrow.")
+
+    return "\n".join(lines)

eod_review_agent/tasks.txt

@@ -0,0 +1,12 @@
+# tasks.txt — Edit this file daily with your tasks
+# Format:
+#   [done]    Task you completed today
+#   [pending] Task still to do
+#
+# The EOD Review Agent reads this file at 6:30 PM.
+
+[done] Reply to Rajesh demo follow-up email
+[done] Review and approve PR #47
+[pending] Follow up on overdue invoice INV-2031
+[pending] Update project roadmap document
+[pending] Send weekly status report to manager

knowledge_agent/cli.py

@@ -0,0 +1,224 @@
+"""
+cli.py — Command-line interface for the Knowledge Agent
+=======================================================
+Usage examples:
+    python cli.py index                          # index ./documents/
+    python cli.py index --dir ~/my_docs          # index a custom folder
+    python cli.py index --force                  # force re-index everything
+    python cli.py ask "What is our pricing?"     # one-shot Q&A
+    python cli.py chat                           # interactive chat loop
+    python cli.py list                           # list indexed documents
+    python cli.py stats                          # show DB stats
+    python cli.py delete report.pdf              # remove a document
+"""
+
+import argparse
+import sys
+import os
+from typing import List, Dict
+
+# ── Pretty printing helpers ───────────────────────────────────────────────────
+try:
+    from rich.console import Console
+    from rich.markdown import Markdown
+    from rich.table import Table
+    from rich.panel import Panel
+    from rich import print as rprint
+    RICH = True
+    console = Console()
+except ImportError:
+    RICH = False
+    console = None
+
+from knowledge_api import (
+    query_knowledge,
+    index_docs,
+    index_single,
+    get_knowledge_stats,
+    list_indexed_docs,
+    delete_doc,
+)
+
+
+def print_answer(result: Dict):
+    answer  = result.get("answer", "")
+    sources = result.get("sources", [])
+    chunks  = result.get("chunks_used", 0)
+
+    if RICH:
+        console.print(Panel(
+            Markdown(answer),
+            title="[bold cyan]Answer[/bold cyan]",
+            border_style="cyan",
+        ))
+        if sources:
+            console.print(f"[dim]Sources ({chunks} chunks): {', '.join(sources)}[/dim]")
+    else:
+        print("\n" + "="*60)
+        print("ANSWER:")
+        print(answer)
+        if sources:
+            print(f"\nSources ({chunks} chunks): {', '.join(sources)}")
+        print("="*60 + "\n")
+
+
+def cmd_index(args):
+    docs_dir = args.dir or "./documents"
+    print(f"[Knowledge Agent] Indexing documents in: {docs_dir}")
+    index_docs(docs_dir=docs_dir, force=args.force)
+
+
+def cmd_ask(args):
+    question = " ".join(args.question)
+    if RICH:
+        console.print(f"\n[bold]Question:[/bold] {question}")
+    else:
+        print(f"\nQuestion: {question}")
+
+    result = query_knowledge(question, top_k=args.top_k)
+    print_answer(result)
+
+
+def cmd_chat(args):
+    """Interactive REPL — keeps asking questions until the user exits."""
+    if RICH:
+        console.print(Panel(
+            "[bold cyan]Knowledge Agent — Interactive Chat[/bold cyan]\n"
+            "Ask anything about your documents.\n"
+            "Type [yellow]exit[/yellow] or [yellow]quit[/yellow] to stop.",
+            border_style="cyan",
+        ))
+    else:
+        print("\n" + "="*60)
+        print(" Knowledge Agent — Interactive Chat")
+        print(" Type 'exit' to quit.")
+        print("="*60 + "\n")
+
+    while True:
+        try:
+            if RICH:
+                question = console.input("[bold green]You:[/bold green] ").strip()
+            else:
+                question = input("You: ").strip()
+        except (KeyboardInterrupt, EOFError):
+            print("\nGoodbye!")
+            break
+
+        if not question:
+            continue
+        if question.lower() in ("exit", "quit", "q", "bye"):
+            print("Goodbye!")
+            break
+
+        # Special commands in chat mode
+        if question.lower() == "/stats":
+            cmd_stats(args)
+            continue
+        if question.lower() == "/list":
+            cmd_list(args)
+            continue
+        if question.lower().startswith("/index "):
+            path = question[7:].strip()
+            index_single(path)
+            continue
+
+        result = query_knowledge(question, top_k=args.top_k if hasattr(args, "top_k") else 5)
+        print_answer(result)
+
+
+def cmd_list(args):
+    docs = list_indexed_docs()
+    if not docs:
+        print("No documents indexed yet.")
+        return
+
+    if RICH:
+        table = Table(title="Indexed Documents", border_style="cyan")
+        table.add_column("File", style="bold")
+        table.add_column("Status")
+        table.add_column("Path", style="dim")
+        for d in docs:
+            status = "[green]✓ exists[/green]" if d["exists"] else "[red]✗ missing[/red]"
+            table.add_row(d["name"], status, d["path"])
+        console.print(table)
+    else:
+        print(f"\n{'File':<40} {'Status':<12} Path")
+        print("-" * 80)
+        for d in docs:
+            status = "✓ exists" if d["exists"] else "✗ missing"
+            print(f"{d['name']:<40} {status:<12} {d['path']}")
+
+
+def cmd_stats(args):
+    stats = get_knowledge_stats()
+    if RICH:
+        console.print(Panel(
+            f"[bold]Total chunks:[/bold]   {stats['total_chunks']}\n"
+            f"[bold]Indexed files:[/bold]  {stats['indexed_files']}\n"
+            f"[bold]Embed model:[/bold]    {stats['embed_model']}\n"
+            f"[bold]ChromaDB dir:[/bold]   {stats['chroma_dir']}",
+            title="[cyan]Knowledge Base Stats[/cyan]",
+            border_style="cyan",
+        ))
+    else:
+        print("\nKnowledge Base Stats:")
+        for k, v in stats.items():
+            print(f"  {k}: {v}")
+
+
+def cmd_delete(args):
+    filename = args.filename
+    confirm = input(f"Delete all chunks for '{filename}'? [y/N] ").strip().lower()
+    if confirm == "y":
+        delete_doc(filename)
+        print(f"Deleted: {filename}")
+    else:
+        print("Cancelled.")
+
+
+# ── Argument parser ───────────────────────────────────────────────────────────
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="knowledge",
+        description="Personal Knowledge Agent — RAG over your documents",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # index
+    p_index = subparsers.add_parser("index", help="Index documents into ChromaDB")
+    p_index.add_argument("--dir",   default=None,  help="Documents directory (default: ./documents)")
+    p_index.add_argument("--force", action="store_true", help="Force re-index all files")
+    p_index.set_defaults(func=cmd_index)
+
+    # ask
+    p_ask = subparsers.add_parser("ask", help="Ask a one-shot question")
+    p_ask.add_argument("question", nargs="+", help="Your question (in quotes or multiple words)")
+    p_ask.add_argument("--top-k", dest="top_k", type=int, default=5,
+                       help="Number of chunks to retrieve (default: 5)")
+    p_ask.set_defaults(func=cmd_ask)
+
+    # chat
+    p_chat = subparsers.add_parser("chat", help="Interactive chat loop")
+    p_chat.add_argument("--top-k", dest="top_k", type=int, default=5)
+    p_chat.set_defaults(func=cmd_chat)
+
+    # list
+    p_list = subparsers.add_parser("list", help="List indexed documents")
+    p_list.set_defaults(func=cmd_list)
+
+    # stats
+    p_stats = subparsers.add_parser("stats", help="Show knowledge base statistics")
+    p_stats.set_defaults(func=cmd_stats)
+
+    # delete
+    p_del = subparsers.add_parser("delete", help="Remove a document from the index")
+    p_del.add_argument("filename", help="Filename to delete (e.g. report.pdf)")
+    p_del.set_defaults(func=cmd_delete)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

knowledge_agent/indexer.py

@@ -0,0 +1,317 @@
+"""
+indexer.py — Document Indexer for Knowledge Agent
+Loads PDFs, Word docs, .txt, and .md files, chunks them,
+embeds with sentence-transformers, and stores in ChromaDB.
+"""
+
+import os
+import hashlib
+import json
+from pathlib import Path
+from typing import List, Dict, Optional
+from datetime import datetime
+
+import chromadb
+from chromadb.config import Settings
+from sentence_transformers import SentenceTransformer
+from langchain_text_splitters import RecursiveCharacterTextSplitter
+
+# ── Document loaders ────────────────────────────────────────────────────────
+import pdfplumber                          # PDF text extraction
+from docx import Document as DocxDocument  # Word docs
+import markdown                            # Markdown → plain text
+import re
+
+# ── Config ───────────────────────────────────────────────────────────────────
+CHROMA_DIR   = os.getenv("CHROMA_DIR", "./chroma_db")
+DOCS_DIR     = os.getenv("DOCS_DIR",   "./documents")
+MODEL_NAME   = os.getenv("EMBED_MODEL", "all-MiniLM-L6-v2")   # ~80 MB, fast
+COLLECTION   = "knowledge_base"
+CHUNK_SIZE   = 800    # characters per chunk
+CHUNK_OVERLAP= 120    # overlap so context isn't lost at boundaries
+META_FILE    = "./chroma_db/indexed_files.json"  # tracks what's been indexed
+
+SUPPORTED_EXTENSIONS = {".pdf", ".docx", ".doc", ".txt", ".md", ".markdown"}
+
+
+# ── Helpers ──────────────────────────────────────────────────────────────────
+
+def _file_hash(path: str) -> str:
+    """MD5 hash of file contents — used to detect changes."""
+    h = hashlib.md5()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(8192), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _load_meta() -> Dict[str, str]:
+    """Load the {filepath: hash} index from disk."""
+    if os.path.exists(META_FILE):
+        with open(META_FILE) as f:
+            return json.load(f)
+    return {}
+
+
+def _save_meta(meta: Dict[str, str]):
+    os.makedirs(os.path.dirname(META_FILE), exist_ok=True)
+    with open(META_FILE, "w") as f:
+        json.dump(meta, f, indent=2)
+
+
+# ── Text extraction ──────────────────────────────────────────────────────────
+
+def extract_text_from_pdf(path: str) -> str:
+    """Extract all text from a PDF using pdfplumber."""
+    text_parts = []
+    try:
+        with pdfplumber.open(path) as pdf:
+            for page in pdf.pages:
+                page_text = page.extract_text()
+                if page_text:
+                    text_parts.append(page_text)
+    except Exception as e:
+        print(f"  [WARN] PDF extraction error for {path}: {e}")
+    return "\n\n".join(text_parts)
+
+
+def extract_text_from_docx(path: str) -> str:
+    """Extract paragraph text from a .docx file."""
+    try:
+        doc = DocxDocument(path)
+        paragraphs = [p.text for p in doc.paragraphs if p.text.strip()]
+        return "\n\n".join(paragraphs)
+    except Exception as e:
+        print(f"  [WARN] DOCX extraction error for {path}: {e}")
+        return ""
+
+
+def extract_text_from_md(path: str) -> str:
+    """Convert Markdown to plain text (strips HTML tags)."""
+    with open(path, encoding="utf-8") as f:
+        raw = f.read()
+    html = markdown.markdown(raw)
+    # Strip HTML tags
+    plain = re.sub(r"<[^>]+>", " ", html)
+    return plain.strip()
+
+
+def extract_text_from_txt(path: str) -> str:
+    with open(path, encoding="utf-8", errors="replace") as f:
+        return f.read()
+
+
+def extract_text(path: str) -> str:
+    """Route to the correct extractor based on file extension."""
+    ext = Path(path).suffix.lower()
+    if ext == ".pdf":
+        return extract_text_from_pdf(path)
+    elif ext in (".docx", ".doc"):
+        return extract_text_from_docx(path)
+    elif ext in (".md", ".markdown"):
+        return extract_text_from_md(path)
+    else:
+        return extract_text_from_txt(path)
+
+
+# ── Chunking ─────────────────────────────────────────────────────────────────
+
+def chunk_text(text: str) -> List[str]:
+    """
+    Split text into overlapping chunks using LangChain's splitter.
+    Tries to split on paragraphs / sentences first to keep context intact.
+    """
+    splitter = RecursiveCharacterTextSplitter(
+        chunk_size=CHUNK_SIZE,
+        chunk_overlap=CHUNK_OVERLAP,
+        separators=["\n\n", "\n", ". ", " ", ""],
+    )
+    return splitter.split_text(text)
+
+
+# ── Indexer class ──���──────────────────────────────────────────────────────────
+
+class KnowledgeIndexer:
+    """
+    Manages the ChromaDB collection and sentence-transformer embeddings.
+    This class is the single source of truth for what's in the vector store.
+    """
+
+    def __init__(self):
+        print(f"[Indexer] Loading embedding model: {MODEL_NAME} ...")
+        self.embedder = SentenceTransformer(MODEL_NAME)
+
+        print(f"[Indexer] Connecting to ChromaDB at: {CHROMA_DIR}")
+        os.makedirs(CHROMA_DIR, exist_ok=True)
+        self.client = chromadb.PersistentClient(path=CHROMA_DIR)
+        self.collection = self.client.get_or_create_collection(
+            name=COLLECTION,
+            metadata={"hnsw:space": "cosine"},   # cosine similarity for RAG
+        )
+        print(f"[Indexer] Collection '{COLLECTION}' has "
+              f"{self.collection.count()} chunks.")
+
+    # ── Public API ────────────────────────────────────────────────────────────
+
+    def index_directory(self, docs_dir: str = DOCS_DIR, force: bool = False):
+        """
+        Walk docs_dir, index any new or changed files.
+        Set force=True to re-index everything regardless of hash.
+        """
+        docs_dir = Path(docs_dir)
+        if not docs_dir.exists():
+            print(f"[Indexer] Creating documents directory: {docs_dir}")
+            docs_dir.mkdir(parents=True)
+
+        meta = {} if force else _load_meta()
+        files = [
+            p for p in docs_dir.rglob("*")
+            if p.is_file() and p.suffix.lower() in SUPPORTED_EXTENSIONS
+        ]
+
+        if not files:
+            print(f"[Indexer] No supported documents found in {docs_dir}")
+            return
+
+        new_count = skipped_count = error_count = 0
+        for filepath in files:
+            path_str = str(filepath)
+            current_hash = _file_hash(path_str)
+
+            if not force and meta.get(path_str) == current_hash:
+                skipped_count += 1
+                continue  # unchanged file
+
+            print(f"  → Indexing: {filepath.name}")
+            try:
+                self._index_file(path_str, filepath.name)
+                meta[path_str] = current_hash
+                new_count += 1
+            except Exception as e:
+                print(f"    [ERROR] Failed to index {filepath.name}: {e}")
+                error_count += 1
+
+        _save_meta(meta)
+        print(f"\n[Indexer] Done. "
+              f"New/updated: {new_count} | Skipped: {skipped_count} | "
+              f"Errors: {error_count} | "
+              f"Total chunks in DB: {self.collection.count()}")
+
+    def index_single_file(self, path: str):
+        """Index (or re-index) a single file by path."""
+        filepath = Path(path)
+        if not filepath.exists():
+            raise FileNotFoundError(f"File not found: {path}")
+        if filepath.suffix.lower() not in SUPPORTED_EXTENSIONS:
+            raise ValueError(f"Unsupported file type: {filepath.suffix}")
+
+        print(f"[Indexer] Indexing file: {filepath.name}")
+        self._index_file(path, filepath.name)
+
+        # Update meta
+        meta = _load_meta()
+        meta[path] = _file_hash(path)
+        _save_meta(meta)
+        print(f"[Indexer] Done. Total chunks: {self.collection.count()}")
+
+    def query(self, question: str, top_k: int = 5) -> List[Dict]:
+        """
+        Embed the question and retrieve top_k most similar chunks.
+        Returns a list of dicts with keys: text, source, score.
+        """
+        if self.collection.count() == 0:
+            return []
+
+        q_embedding = self.embedder.encode(question).tolist()
+        results = self.collection.query(
+            query_embeddings=[q_embedding],
+            n_results=min(top_k, self.collection.count()),
+            include=["documents", "metadatas", "distances"],
+        )
+
+        chunks = []
+        docs      = results["documents"][0]
+        metadatas = results["metadatas"][0]
+        distances = results["distances"][0]
+
+        for doc, meta, dist in zip(docs, metadatas, distances):
+            chunks.append({
+                "text":   doc,
+                "source": meta.get("source", "unknown"),
+                "page":   meta.get("page", ""),
+                "score":  round(1 - dist, 4),   # cosine similarity (higher = better)
+            })
+        return chunks
+
+    def list_documents(self) -> List[Dict]:
+        """Return unique source documents currently in the DB."""
+        meta = _load_meta()
+        docs = []
+        for path_str, file_hash in meta.items():
+            p = Path(path_str)
+            docs.append({
+                "name": p.name,
+                "path": path_str,
+                "hash": file_hash,
+                "exists": p.exists(),
+            })
+        return docs
+
+    def delete_document(self, filename: str):
+        """Remove all chunks belonging to a source file."""
+        self.collection.delete(where={"source": filename})
+        # Remove from meta
+        meta = _load_meta()
+        meta = {k: v for k, v in meta.items() if Path(k).name != filename}
+        _save_meta(meta)
+        print(f"[Indexer] Deleted all chunks for: {filename}")
+
+    def get_stats(self) -> Dict:
+        return {
+            "total_chunks": self.collection.count(),
+            "indexed_files": len(_load_meta()),
+            "chroma_dir": CHROMA_DIR,
+            "embed_model": MODEL_NAME,
+        }
+
+    # ── Private ───────────────────────────────────────────────────────────────
+
+    def _index_file(self, path: str, filename: str):
+        """Extract → chunk → embed → upsert into ChromaDB."""
+        # 1. Extract text
+        text = extract_text(path)
+        if not text.strip():
+            print(f"    [WARN] No text extracted from {filename}")
+            return
+
+        # 2. Chunk
+        chunks = chunk_text(text)
+        if not chunks:
+            return
+
+        # 3. Remove old chunks for this file (handles re-indexing)
+        try:
+            self.collection.delete(where={"source": filename})
+        except Exception:
+            pass  # Collection might not have this source yet
+
+        # 4. Embed + upsert in batches of 100
+        BATCH = 100
+        for i in range(0, len(chunks), BATCH):
+            batch_chunks = chunks[i : i + BATCH]
+            embeddings = self.embedder.encode(batch_chunks).tolist()
+            ids = [f"{filename}_{i+j}" for j in range(len(batch_chunks))]
+            metadatas = [
+                {
+                    "source":    filename,
+                    "chunk_idx": i + j,
+                    "indexed_at": datetime.now().isoformat(),
+                }
+                for j in range(len(batch_chunks))
+            ]
+            self.collection.upsert(
+                ids=ids,
+                embeddings=embeddings,
+                documents=batch_chunks,
+                metadatas=metadatas,
+            )

knowledge_agent/knowledge_api.py

@@ -0,0 +1,125 @@
+"""
+knowledge_api.py — Public interface for the Knowledge Agent
+============================================================
+This module is the integration layer for the Master Orchestrator and any
+other agent that needs to query your personal document store.
+
+Usage from another agent:
+    from knowledge_agent.knowledge_api import query_knowledge, index_docs
+
+It is intentionally stateless at the call level — the KnowledgeIndexer
+caches the ChromaDB connection internally for performance.
+"""
+
+from typing import List, Dict, Optional
+from indexer import KnowledgeIndexer
+from llm import generate_answer, stream_answer
+
+# Module-level singleton — one DB connection shared across all calls
+# (safe for single-process use; FastAPI uses one process by default)
+_indexer: Optional[KnowledgeIndexer] = None
+
+
+def _get_indexer() -> KnowledgeIndexer:
+    global _indexer
+    if _indexer is None:
+        _indexer = KnowledgeIndexer()
+    return _indexer
+
+
+# ── Core public functions ─────────────────────────────────────────────────────
+
+def query_knowledge(
+    question: str,
+    top_k: int = 5,
+    return_sources: bool = True,
+) -> Dict:
+    """
+    PRIMARY ENTRY POINT for the Master Orchestrator and other agents.
+
+    Ask a question against your indexed personal documents.
+
+    Args:
+        question:       Natural language question.
+        top_k:          Number of chunks to retrieve from ChromaDB.
+        return_sources: If True, include source filenames in the response.
+
+    Returns:
+        {
+            "answer":  str,          # LLM-generated, grounded answer
+            "sources": [str, ...],   # source filenames (if return_sources=True)
+            "chunks_used": int,      # number of relevant chunks found
+            "question": str,         # echo back for logging
+        }
+
+    Example:
+        >>> result = query_knowledge("What is our refund policy?")
+        >>> print(result["answer"])
+    """
+    indexer = _get_indexer()
+    chunks  = indexer.query(question, top_k=top_k)
+
+    if not chunks:
+        return {
+            "answer":      "No documents have been indexed yet. "
+                           "Please run `index_docs()` first.",
+            "sources":     [],
+            "chunks_used": 0,
+            "question":    question,
+        }
+
+    result = generate_answer(question, chunks)
+    result["question"] = question
+
+    if not return_sources:
+        result.pop("sources", None)
+
+    return result
+
+
+def index_docs(docs_dir: str = "./documents", force: bool = False):
+    """
+    Index (or re-index) all supported documents in docs_dir.
+    Called by the CLI, the web UI, and can be called by the Orchestrator
+    to trigger a refresh after new documents are added.
+
+    Args:
+        docs_dir: Path to the folder containing your documents.
+        force:    Re-index everything even if files haven't changed.
+    """
+    indexer = _get_indexer()
+    indexer.index_directory(docs_dir=docs_dir, force=force)
+
+
+def index_single(path: str):
+    """Index a single file immediately (called by file-watcher or API upload)."""
+    indexer = _get_indexer()
+    indexer.index_single_file(path)
+
+
+def get_knowledge_stats() -> Dict:
+    """Return stats about the current knowledge base (for health checks)."""
+    return _get_indexer().get_stats()
+
+
+def list_indexed_docs() -> List[Dict]:
+    """List all documents currently indexed."""
+    return _get_indexer().list_documents()
+
+
+def delete_doc(filename: str):
+    """Remove a document and all its chunks from the index."""
+    _get_indexer().delete_document(filename)
+
+
+def stream_knowledge_answer(question: str, top_k: int = 5):
+    """
+    Streaming variant — yields tokens one by one.
+    Used by the FastAPI /stream endpoint for the web UI.
+    """
+    indexer = _get_indexer()
+    chunks  = indexer.query(question, top_k=top_k)
+    if not chunks:
+        yield "No documents indexed yet."
+        return
+    yield from stream_answer(question, chunks)

knowledge_agent/llm.py

@@ -0,0 +1,160 @@
+"""
+llm.py — Groq-powered RAG answer generation for Knowledge Agent
+Takes a question + retrieved context chunks → returns a grounded answer.
+"""
+
+import os
+from typing import List, Dict, Optional
+from groq import Groq
+
+# ── Config ────────────────────────────────────────────────────────────────────
+GROQ_API_KEY  = os.getenv("GROQ_API_KEY", "")
+GROQ_MODEL    = os.getenv("GROQ_MODEL", "llama-3.3-70b-versatile")
+MAX_TOKENS    = int(os.getenv("LLM_MAX_TOKENS", "1500"))
+TEMPERATURE   = float(os.getenv("LLM_TEMPERATURE", "0.2"))
+
+# How many context chunks to pass to the LLM
+TOP_K_CHUNKS  = int(os.getenv("TOP_K_CHUNKS", "5"))
+
+# Minimum similarity score to include a chunk (0–1, cosine)
+MIN_SCORE     = float(os.getenv("MIN_CHUNK_SCORE", "0.30"))
+
+# ── System prompt ─────────────────────────────────────────────────────────────
+SYSTEM_PROMPT = """You are a precise, helpful personal knowledge assistant.
+You answer questions STRICTLY based on the document excerpts provided below.
+
+Rules:
+- Ground every claim in the provided context. Cite source filenames inline like [source.pdf].
+- If the context doesn't contain enough information, say so clearly — do NOT hallucinate.
+- Be concise and structured. Use bullet points or numbered lists when helpful.
+- If asked for a summary, provide a well-organised paragraph-style answer.
+- When multiple documents cover the same topic, synthesise them coherently.
+"""
+
+
+def _build_context_block(chunks: List[Dict]) -> str:
+    """Format retrieved chunks into a readable context block for the prompt."""
+    filtered = [c for c in chunks if c.get("score", 0) >= MIN_SCORE]
+    if not filtered:
+        return "No relevant context found in your documents."
+
+    lines = []
+    for i, c in enumerate(filtered, 1):
+        source = c.get("source", "unknown")
+        score  = c.get("score", 0)
+        text   = c.get("text", "").strip()
+        lines.append(f"[Excerpt {i} | Source: {source} | Relevance: {score:.2f}]\n{text}")
+
+    return "\n\n---\n\n".join(lines)
+
+
+def _build_user_message(question: str, context: str) -> str:
+    return f"""Here are relevant excerpts from your personal documents:
+
+{context}
+
+---
+
+Question: {question}
+
+Answer (cite sources inline):"""
+
+
+# ── Main function ─────────────────────────────────────────────────────────────
+
+def generate_answer(
+    question: str,
+    chunks: List[Dict],
+    conversation_history: Optional[List[Dict]] = None,
+) -> Dict:
+    """
+    Generate a grounded answer using Groq + retrieved chunks.
+
+    Args:
+        question: The user's question.
+        chunks:   List of dicts from KnowledgeIndexer.query()
+                  Each has keys: text, source, score.
+        conversation_history: Optional list of prior {role, content} turns
+                              for multi-turn chat support.
+
+    Returns:
+        {
+            "answer": str,
+            "sources": [str, ...],    # unique source filenames cited
+            "chunks_used": int,
+            "model": str,
+        }
+    """
+    if not GROQ_API_KEY:
+        raise EnvironmentError(
+            "GROQ_API_KEY is not set. Add it to your .env file."
+        )
+
+    client = Groq(api_key=GROQ_API_KEY)
+
+    # Build context from retrieved chunks
+    context = _build_context_block(chunks)
+    user_message = _build_user_message(question, context)
+
+    # Build message list (supports conversational follow-ups)
+    messages = [{"role": "system", "content": SYSTEM_PROMPT}]
+    if conversation_history:
+        messages.extend(conversation_history)
+    messages.append({"role": "user", "content": user_message})
+
+    # ── Call Groq ──────────────────────────────────────────────────────────────
+    response = client.chat.completions.create(
+        model=GROQ_MODEL,
+        messages=messages,
+        temperature=TEMPERATURE,
+        max_completion_tokens=MAX_TOKENS,
+    )
+
+    answer = response.choices[0].message.content.strip()
+
+    # Extract unique source filenames from chunks that met the score threshold
+    sources = list({
+        c["source"]
+        for c in chunks
+        if c.get("score", 0) >= MIN_SCORE
+    })
+
+    return {
+        "answer":      answer,
+        "sources":     sources,
+        "chunks_used": len([c for c in chunks if c.get("score", 0) >= MIN_SCORE]),
+        "model":       GROQ_MODEL,
+    }
+
+
+# ── Streaming variant (used by FastAPI for real-time web UI) ──────────────────
+
+def stream_answer(question: str, chunks: List[Dict]):
+    """
+    Generator that yields answer tokens one by one for SSE streaming.
+    Usage: for token in stream_answer(q, chunks): ...
+    """
+    if not GROQ_API_KEY:
+        yield "ERROR: GROQ_API_KEY not set."
+        return
+
+    client = Groq(api_key=GROQ_API_KEY)
+    context = _build_context_block(chunks)
+    user_message = _build_user_message(question, context)
+
+    messages = [
+        {"role": "system",  "content": SYSTEM_PROMPT},
+        {"role": "user",    "content": user_message},
+    ]
+
+    stream = client.chat.completions.create(
+        model=GROQ_MODEL,
+        messages=messages,
+        temperature=TEMPERATURE,
+        max_completion_tokens=MAX_TOKENS,
+        stream=True,
+    )
+
+    for chunk in stream:
+        if chunk.choices[0].delta.content:
+            yield chunk.choices[0].delta.content

knowledge_agent/main.py

@@ -0,0 +1,70 @@
+"""
+main.py — Knowledge Agent entry point
+======================================
+Starts:
+  1. File watcher (background thread) — auto-indexes new/changed documents
+  2. FastAPI web server (foreground)  — CLI and web UI
+
+Run:
+    python main.py                     # web UI on http://localhost:8000
+    python main.py --port 8080         # custom port
+    python main.py --no-watcher        # disable file watcher
+    python main.py --index-on-start    # index all docs before starting
+"""
+
+import argparse
+import os
+import sys
+import uvicorn
+
+import os as _os
+from dotenv import load_dotenv
+load_dotenv(_os.path.join(_os.path.dirname(_os.path.abspath(__file__)), "..", ".env"))
+
+DOCS_DIR = os.getenv("DOCS_DIR", "./documents")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Knowledge Agent — Personal RAG server"
+    )
+    parser.add_argument("--host",           default="0.0.0.0",
+                        help="Bind host (default: 0.0.0.0)")
+    parser.add_argument("--port",           type=int, default=8000,
+                        help="Port (default: 8000)")
+    parser.add_argument("--no-watcher",     action="store_true",
+                        help="Disable the file-system watcher")
+    parser.add_argument("--index-on-start", action="store_true",
+                        help="Re-index all documents before starting server")
+    parser.add_argument("--reload",         action="store_true",
+                        help="Enable uvicorn auto-reload (development)")
+    args = parser.parse_args()
+
+    # ── Optional: index on startup ─────────────────────────────────────────
+    if args.index_on_start:
+        print("[Main] Indexing documents on startup …")
+        from knowledge_api import index_docs
+        index_docs(docs_dir=DOCS_DIR)
+
+    # ── File watcher (background thread) ──────────────────────────────────
+    if not args.no_watcher:
+        from watcher import start_watcher_thread
+        wt = start_watcher_thread(docs_dir=DOCS_DIR)
+        print(f"[Main] File watcher started for: {DOCS_DIR}")
+
+    # ── Start FastAPI ──────────────────────────────────────────────────────
+    print(f"\n[Main] Starting Knowledge Agent on http://{args.host}:{args.port}")
+    print("[Main] Web UI:  http://localhost:{port}".format(port=args.port))
+    print("[Main] API docs: http://localhost:{port}/docs\n".format(port=args.port))
+
+    uvicorn.run(
+        "web_app:app",
+        host=args.host,
+        port=args.port,
+        reload=args.reload,
+        log_level="info",
+    )
+
+
+if __name__ == "__main__":
+    main()

knowledge_agent/requirements.txt

@@ -0,0 +1,32 @@
+# ── Knowledge Agent — Python Dependencies ────────────────────────────────────
+# Install: pip install -r requirements.txt
+
+# ── Core AI / LLM ─────────────────────────────────────────────────────────────
+groq>=0.9.0                         # Groq API client (llama-3.3-70b-versatile)
+sentence-transformers>=2.7.0        # Local embeddings (all-MiniLM-L6-v2, free)
+
+# ── Vector Store ──────────────────────────────────────────────────────────────
+chromadb>=0.5.0                     # Local persistent vector database
+
+# ── Document Loading ──────────────────────────────────────────────────────────
+pdfplumber>=0.11.0                  # PDF text extraction
+python-docx>=1.1.0                  # Word document (.docx) reader
+markdown>=3.6                       # Markdown → plain text conversion
+
+# ── Text Splitting ────────────────────────────────────────────────────────────
+langchain-text-splitters>=0.2.0     # RecursiveCharacterTextSplitter
+
+# ── Web Server ────────────────────────────────────────────────────────────────
+fastapi>=0.111.0                    # REST API + SSE streaming
+uvicorn[standard]>=0.30.0           # ASGI server
+python-multipart>=0.0.9             # File upload support
+
+# ── CLI ────────────────────────────────────────────────────────────────────────
+rich>=13.7.0                        # Pretty terminal output (optional but nice)
+
+# ── File Watcher ──────────────────────────────────────────────────────────────
+watchdog>=4.0.0                     # File-system event monitoring
+
+# ── Config ────────────────────────────────────────────────────────────────────
+python-dotenv>=1.0.0                # .env file loader
+pydantic>=2.0.0                     # Data validation (used by FastAPI)

knowledge_agent/watcher.py

@@ -0,0 +1,177 @@
+"""
+watcher.py — File-system watcher for auto re-indexing
+======================================================
+Watches the documents directory for new, modified, or deleted files
+and automatically updates the ChromaDB index.
+
+Run standalone:  python watcher.py
+Or import:       from watcher import start_watcher_thread
+"""
+
+import os
+import time
+import threading
+from pathlib import Path
+
+try:
+    from watchdog.observers import Observer
+    from watchdog.events import FileSystemEventHandler, FileSystemEvent
+    WATCHDOG_AVAILABLE = True
+except ImportError:
+    WATCHDOG_AVAILABLE = False
+    print("[Watcher] watchdog not installed — falling back to polling watcher.")
+
+from knowledge_api import index_single, delete_doc
+
+DOCS_DIR = os.getenv("DOCS_DIR", "./documents")
+SUPPORTED = {".pdf", ".docx", ".doc", ".txt", ".md", ".markdown"}
+
+# Debounce time in seconds (avoid re-indexing for rapid successive saves)
+DEBOUNCE_SECONDS = 2.0
+
+
+# ── Watchdog handler ──────────────────────────────────────────────────────────
+
+class DocumentHandler(FileSystemEventHandler):
+    """Handles file-system events and triggers indexing."""
+
+    def __init__(self):
+        self._timers: dict = {}  # path → Timer (debounce)
+
+    def _debounced_index(self, path: str):
+        """Cancel any pending timer for this path and set a new one."""
+        if path in self._timers:
+            self._timers[path].cancel()
+        timer = threading.Timer(DEBOUNCE_SECONDS, self._do_index, args=[path])
+        self._timers[path] = timer
+        timer.start()
+
+    @staticmethod
+    def _do_index(path: str):
+        print(f"[Watcher] Indexing: {Path(path).name}")
+        try:
+            index_single(path)
+            print(f"[Watcher] ✓ Done: {Path(path).name}")
+        except Exception as e:
+            print(f"[Watcher] ✗ Error indexing {path}: {e}")
+
+    def on_created(self, event: FileSystemEvent):
+        if not event.is_directory and Path(event.src_path).suffix.lower() in SUPPORTED:
+            print(f"[Watcher] New file detected: {Path(event.src_path).name}")
+            self._debounced_index(event.src_path)
+
+    def on_modified(self, event: FileSystemEvent):
+        if not event.is_directory and Path(event.src_path).suffix.lower() in SUPPORTED:
+            print(f"[Watcher] File modified: {Path(event.src_path).name}")
+            self._debounced_index(event.src_path)
+
+    def on_deleted(self, event: FileSystemEvent):
+        if not event.is_directory and Path(event.src_path).suffix.lower() in SUPPORTED:
+            fname = Path(event.src_path).name
+            print(f"[Watcher] File deleted: {fname} — removing from index.")
+            try:
+                delete_doc(fname)
+            except Exception as e:
+                print(f"[Watcher] Error removing {fname}: {e}")
+
+    def on_moved(self, event: FileSystemEvent):
+        # Treat as delete old + create new
+        if not event.is_directory:
+            if Path(event.src_path).suffix.lower() in SUPPORTED:
+                delete_doc(Path(event.src_path).name)
+            if Path(event.dest_path).suffix.lower() in SUPPORTED:
+                self._debounced_index(event.dest_path)
+
+
+# ── Polling fallback ──────────────────────────────────────────────────────────
+
+class PollingWatcher:
+    """
+    Simple polling watcher for when watchdog isn't available.
+    Checks file modification times every POLL_INTERVAL seconds.
+    """
+    POLL_INTERVAL = 10  # seconds
+
+    def __init__(self, docs_dir: str):
+        self.docs_dir = Path(docs_dir)
+        self._seen: dict = {}  # path → mtime
+
+    def run(self):
+        print(f"[Watcher] Polling {self.docs_dir} every {self.POLL_INTERVAL}s …")
+        while True:
+            self._poll()
+            time.sleep(self.POLL_INTERVAL)
+
+    def _poll(self):
+        current = {}
+        for p in self.docs_dir.rglob("*"):
+            if p.is_file() and p.suffix.lower() in SUPPORTED:
+                current[str(p)] = p.stat().st_mtime
+
+        # New or modified
+        for path, mtime in current.items():
+            if path not in self._seen or self._seen[path] != mtime:
+                print(f"[Watcher] Change detected: {Path(path).name}")
+                try:
+                    index_single(path)
+                except Exception as e:
+                    print(f"[Watcher] Error: {e}")
+
+        # Deleted
+        for path in set(self._seen) - set(current):
+            fname = Path(path).name
+            print(f"[Watcher] Deleted: {fname}")
+            try:
+                delete_doc(fname)
+            except Exception as e:
+                print(f"[Watcher] Error removing {fname}: {e}")
+
+        self._seen = current
+
+
+# ── Public API ────────────────���───────────────────────────────────────────────
+
+def start_watcher(docs_dir: str = DOCS_DIR, blocking: bool = True):
+    """
+    Start the file watcher.
+    Set blocking=False to run in a background thread (used by web_app.py).
+    """
+    os.makedirs(docs_dir, exist_ok=True)
+
+    if WATCHDOG_AVAILABLE:
+        handler  = DocumentHandler()
+        observer = Observer()
+        observer.schedule(handler, path=docs_dir, recursive=True)
+        observer.start()
+        print(f"[Watcher] Watching {docs_dir} with watchdog …")
+        try:
+            if blocking:
+                while True:
+                    time.sleep(1)
+            # Non-blocking: caller is responsible for keeping process alive
+        except KeyboardInterrupt:
+            observer.stop()
+            print("[Watcher] Stopped.")
+        observer.join()
+    else:
+        pw = PollingWatcher(docs_dir)
+        if blocking:
+            pw.run()
+        else:
+            t = threading.Thread(target=pw.run, daemon=True)
+            t.start()
+            return t
+
+
+def start_watcher_thread(docs_dir: str = DOCS_DIR) -> threading.Thread:
+    """
+    Start the watcher in a background daemon thread.
+    Returns the thread (for monitoring only — it's a daemon so it stops with the process).
+    """
+    t = threading.Thread(target=start_watcher, args=(docs_dir, True), daemon=True)
+    t.start()
+    return t
+
+
+if __name__ == "__main__":
+    start_watcher(DOCS_DIR, blocking=True)

knowledge_agent/web_app.py

@@ -0,0 +1,658 @@
+"""
+web_app.py — FastAPI web UI + REST API for the Knowledge Agent
+==============================================================
+Run with:  uvicorn web_app:app --host 0.0.0.0 --port 8000 --reload
+
+Endpoints:
+  GET  /              → Web UI (chat interface)
+  POST /api/ask       → JSON Q&A
+  GET  /api/stream    → SSE streaming answer
+  POST /api/index     → Trigger re-indexing
+  POST /api/upload    → Upload and index a new document
+  GET  /api/docs-list → List indexed documents
+  GET  /api/stats     → Knowledge base stats
+  DELETE /api/doc/{filename} → Remove a document
+"""
+
+import os
+import shutil
+import asyncio
+from pathlib import Path
+from typing import Optional
+
+from fastapi import FastAPI, UploadFile, File, HTTPException, Query
+from fastapi.responses import HTMLResponse, StreamingResponse, JSONResponse
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+
+from knowledge_api import (
+    query_knowledge,
+    index_docs,
+    index_single,
+    get_knowledge_stats,
+    list_indexed_docs,
+    delete_doc,
+    stream_knowledge_answer,
+)
+
+DOCS_DIR = os.getenv("DOCS_DIR", "./documents")
+
+# ── App setup ─────────────────────────────────────────────────────────────────
+app = FastAPI(
+    title="Knowledge Agent",
+    description="Personal RAG system over your documents",
+    version="1.0.0",
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# ── Request / Response models ─────────────────────────────────────────────────
+class AskRequest(BaseModel):
+    question: str
+    top_k: int = 5
+
+class IndexRequest(BaseModel):
+    docs_dir: Optional[str] = None
+    force: bool = False
+
+
+# ── REST API endpoints ────────────────────────────────────────────────────────
+
+@app.post("/api/ask")
+async def ask(req: AskRequest):
+    """Ask a question and get a grounded answer from your documents."""
+    if not req.question.strip():
+        raise HTTPException(400, "Question cannot be empty.")
+    result = query_knowledge(req.question, top_k=req.top_k)
+    return result
+
+
+@app.get("/api/stream")
+async def stream(
+    question: str = Query(..., description="Your question"),
+    top_k: int = Query(5, description="Number of chunks to retrieve"),
+):
+    """
+    SSE endpoint — streams the answer token by token.
+    Used by the web UI for a typing-cursor effect.
+    """
+    if not question.strip():
+        raise HTTPException(400, "Question cannot be empty.")
+
+    def event_generator():
+        for token in stream_knowledge_answer(question, top_k=top_k):
+            # SSE format: "data: <token>\n\n"
+            yield f"data: {token}\n\n"
+        yield "data: [DONE]\n\n"
+
+    return StreamingResponse(
+        event_generator(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "X-Accel-Buffering": "no",
+        },
+    )
+
+
+@app.post("/api/index")
+async def trigger_index(req: IndexRequest):
+    """Trigger indexing of the documents directory."""
+    docs_dir = req.docs_dir or DOCS_DIR
+    # Run in a thread pool so we don't block the event loop
+    loop = asyncio.get_event_loop()
+    await loop.run_in_executor(
+        None, lambda: index_docs(docs_dir=docs_dir, force=req.force)
+    )
+    stats = get_knowledge_stats()
+    return {"message": "Indexing complete.", "stats": stats}
+
+
+@app.post("/api/upload")
+async def upload_document(file: UploadFile = File(...)):
+    """
+    Upload a document file; save it to the documents dir and index it.
+    Supports: .pdf, .docx, .txt, .md
+    """
+    allowed = {".pdf", ".docx", ".doc", ".txt", ".md", ".markdown"}
+    ext = Path(file.filename).suffix.lower()
+    if ext not in allowed:
+        raise HTTPException(400, f"Unsupported file type: {ext}. Allowed: {allowed}")
+
+    os.makedirs(DOCS_DIR, exist_ok=True)
+    dest = os.path.join(DOCS_DIR, file.filename)
+
+    # Save file
+    with open(dest, "wb") as f:
+        shutil.copyfileobj(file.file, f)
+
+    # Index it
+    loop = asyncio.get_event_loop()
+    await loop.run_in_executor(None, lambda: index_single(dest))
+
+    return {
+        "message": f"'{file.filename}' uploaded and indexed.",
+        "path": dest,
+    }
+
+
+@app.get("/api/docs-list")
+async def docs_list():
+    """List all documents currently in the knowledge base."""
+    return {"documents": list_indexed_docs()}
+
+
+@app.get("/api/stats")
+async def stats():
+    """Return knowledge base statistics."""
+    return get_knowledge_stats()
+
+
+@app.delete("/api/doc/{filename}")
+async def remove_doc(filename: str):
+    """Remove a document and all its chunks from the index."""
+    delete_doc(filename)
+    return {"message": f"Deleted '{filename}' from the knowledge base."}
+
+
+# ── Web UI ────────────────────────────────────────────────────────────────────
+
+@app.get("/", response_class=HTMLResponse)
+async def ui():
+    """Serve the single-page chat interface."""
+    return HTMLResponse(content=WEB_UI_HTML)
+
+
+# ── HTML for the web UI (self-contained, no build step needed) ────────────────
+WEB_UI_HTML = """<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Knowledge Agent</title>
+<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@300;400;600&display=swap" rel="stylesheet">
+<style>
+  :root {
+    --bg:       #0d0f14;
+    --surface:  #161921;
+    --border:   #2a2f3d;
+    --accent:   #5b8def;
+    --accent2:  #7ecfb0;
+    --text:     #d4dae8;
+    --muted:    #5c6480;
+    --danger:   #e05c7a;
+    --mono:     'IBM Plex Mono', monospace;
+    --sans:     'IBM Plex Sans', sans-serif;
+  }
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  body {
+    background: var(--bg);
+    color: var(--text);
+    font-family: var(--sans);
+    height: 100vh;
+    display: flex;
+    flex-direction: column;
+  }
+
+  /* ── Header ── */
+  header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 14px 24px;
+    border-bottom: 1px solid var(--border);
+    background: var(--surface);
+    flex-shrink: 0;
+  }
+  .logo {
+    font-family: var(--mono);
+    font-size: 1rem;
+    color: var(--accent);
+    letter-spacing: .04em;
+  }
+  .logo span { color: var(--accent2); }
+  .header-actions { display: flex; gap: 10px; }
+  .btn {
+    font-family: var(--mono);
+    font-size: .75rem;
+    padding: 6px 14px;
+    border: 1px solid var(--border);
+    border-radius: 4px;
+    background: transparent;
+    color: var(--text);
+    cursor: pointer;
+    transition: all .15s;
+  }
+  .btn:hover { border-color: var(--accent); color: var(--accent); }
+  .btn.primary { background: var(--accent); border-color: var(--accent); color: #fff; }
+  .btn.primary:hover { opacity: .85; }
+  .btn.danger { border-color: var(--danger); color: var(--danger); }
+
+  /* ── Layout ── */
+  .main { display: flex; flex: 1; overflow: hidden; }
+
+  /* ── Sidebar ── */
+  .sidebar {
+    width: 260px;
+    border-right: 1px solid var(--border);
+    background: var(--surface);
+    display: flex;
+    flex-direction: column;
+    flex-shrink: 0;
+    overflow: hidden;
+  }
+  .sidebar-section { padding: 16px; border-bottom: 1px solid var(--border); }
+  .sidebar-title {
+    font-family: var(--mono);
+    font-size: .65rem;
+    text-transform: uppercase;
+    letter-spacing: .12em;
+    color: var(--muted);
+    margin-bottom: 10px;
+  }
+  #stats-panel { font-size: .78rem; line-height: 1.9; color: var(--muted); }
+  #stats-panel strong { color: var(--text); }
+  .doc-list { flex: 1; overflow-y: auto; padding: 8px 0; }
+  .doc-item {
+    padding: 8px 16px;
+    font-size: .78rem;
+    color: var(--muted);
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    cursor: default;
+  }
+  .doc-item .dot { width: 6px; height: 6px; border-radius: 50%; background: var(--accent2); flex-shrink: 0; }
+  .doc-item .del {
+    margin-left: auto;
+    color: var(--danger);
+    cursor: pointer;
+    font-size: .9rem;
+    opacity: 0;
+    transition: opacity .15s;
+  }
+  .doc-item:hover .del { opacity: 1; }
+
+  /* Upload zone */
+  .upload-zone {
+    margin: 0 16px 16px;
+    border: 1px dashed var(--border);
+    border-radius: 6px;
+    padding: 12px;
+    text-align: center;
+    font-size: .75rem;
+    color: var(--muted);
+    cursor: pointer;
+    transition: border-color .15s;
+  }
+  .upload-zone:hover { border-color: var(--accent); color: var(--accent); }
+  #file-input { display: none; }
+
+  /* ── Chat area ── */
+  .chat-area {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+  }
+  .messages {
+    flex: 1;
+    overflow-y: auto;
+    padding: 28px 32px;
+    display: flex;
+    flex-direction: column;
+    gap: 24px;
+  }
+  .msg { display: flex; gap: 14px; }
+  .msg-avatar {
+    width: 30px; height: 30px;
+    border-radius: 4px;
+    display: flex; align-items: center; justify-content: center;
+    font-family: var(--mono);
+    font-size: .65rem;
+    font-weight: 500;
+    flex-shrink: 0;
+    margin-top: 2px;
+  }
+  .msg.user .msg-avatar  { background: #2b3354; color: var(--accent); }
+  .msg.agent .msg-avatar { background: #1e3330; color: var(--accent2); }
+  .msg-body { flex: 1; }
+  .msg-label {
+    font-size: .68rem;
+    font-family: var(--mono);
+    color: var(--muted);
+    margin-bottom: 5px;
+    text-transform: uppercase;
+    letter-spacing: .08em;
+  }
+  .msg-text {
+    font-size: .875rem;
+    line-height: 1.75;
+    color: var(--text);
+    white-space: pre-wrap;
+    word-break: break-word;
+  }
+  .msg.user .msg-text { color: #aebcdc; }
+  .sources-bar {
+    margin-top: 10px;
+    font-size: .7rem;
+    font-family: var(--mono);
+    color: var(--muted);
+  }
+  .sources-bar span {
+    display: inline-block;
+    background: #1a2238;
+    border: 1px solid var(--border);
+    border-radius: 3px;
+    padding: 2px 8px;
+    margin: 2px 3px 0 0;
+    color: var(--accent);
+  }
+
+  /* ── Input row ── */
+  .input-row {
+    padding: 18px 32px;
+    border-top: 1px solid var(--border);
+    display: flex;
+    gap: 10px;
+    background: var(--surface);
+    flex-shrink: 0;
+  }
+  #question-input {
+    flex: 1;
+    background: var(--bg);
+    border: 1px solid var(--border);
+    border-radius: 6px;
+    padding: 12px 16px;
+    font-family: var(--sans);
+    font-size: .875rem;
+    color: var(--text);
+    resize: none;
+    outline: none;
+    transition: border-color .15s;
+    line-height: 1.5;
+    min-height: 48px;
+    max-height: 160px;
+  }
+  #question-input:focus { border-color: var(--accent); }
+  #question-input::placeholder { color: var(--muted); }
+  #send-btn {
+    align-self: flex-end;
+    height: 48px;
+    padding: 0 22px;
+  }
+
+  /* ── Status bar ── */
+  #status-bar {
+    padding: 6px 32px;
+    font-size: .7rem;
+    font-family: var(--mono);
+    color: var(--muted);
+    background: var(--bg);
+    border-top: 1px solid var(--border);
+    flex-shrink: 0;
+  }
+
+  /* Scrollbar */
+  ::-webkit-scrollbar { width: 6px; }
+  ::-webkit-scrollbar-track { background: transparent; }
+  ::-webkit-scrollbar-thumb { background: var(--border); border-radius: 3px; }
+
+  /* Loading dots */
+  .typing { display: flex; gap: 5px; align-items: center; padding: 4px 0; }
+  .typing .dot { width: 6px; height: 6px; border-radius: 50%; background: var(--accent); animation: blink 1.2s infinite; }
+  .typing .dot:nth-child(2) { animation-delay: .2s; }
+  .typing .dot:nth-child(3) { animation-delay: .4s; }
+  @keyframes blink { 0%,80%,100%{opacity:.2} 40%{opacity:1} }
+
+  .empty-state {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    color: var(--muted);
+    font-size: .875rem;
+    gap: 10px;
+    text-align: center;
+  }
+  .empty-state .icon { font-size: 2.5rem; margin-bottom: 4px; }
+</style>
+</head>
+<body>
+
+<header>
+  <div class="logo">knowledge<span>_agent</span></div>
+  <div class="header-actions">
+    <button class="btn" onclick="loadStats()">↻ Refresh</button>
+    <button class="btn primary" onclick="triggerIndex()">⚡ Re-index</button>
+  </div>
+</header>
+
+<div class="main">
+  <!-- Sidebar -->
+  <div class="sidebar">
+    <div class="sidebar-section">
+      <div class="sidebar-title">Knowledge Base</div>
+      <div id="stats-panel">Loading…</div>
+    </div>
+    <div class="sidebar-section" style="flex:1;overflow:hidden;display:flex;flex-direction:column;padding-bottom:0">
+      <div class="sidebar-title">Indexed Documents</div>
+      <div class="doc-list" id="doc-list"></div>
+    </div>
+    <div class="upload-zone" onclick="document.getElementById('file-input').click()">
+      ＋ Upload document
+    </div>
+    <input type="file" id="file-input" accept=".pdf,.docx,.txt,.md,.markdown"
+           onchange="uploadFile(this.files[0])">
+  </div>
+
+  <!-- Chat -->
+  <div class="chat-area">
+    <div class="messages" id="messages">
+      <div class="empty-state" id="empty-state">
+        <div class="icon">🧠</div>
+        <strong>Ask anything about your documents</strong>
+        <span>Add files via the sidebar, then start asking questions.</span>
+      </div>
+    </div>
+
+    <div class="input-row">
+      <textarea id="question-input"
+                placeholder="Ask a question about your documents…"
+                rows="1"
+                onkeydown="handleKey(event)"></textarea>
+      <button class="btn primary" id="send-btn" onclick="sendQuestion()">Ask →</button>
+    </div>
+    <div id="status-bar">Ready</div>
+  </div>
+</div>
+
+<script>
+// ── State ──────────────────────────────────────────────────────────────────
+let isLoading = false;
+
+// ── On load ────────────────────────────────────────────────────────────────
+window.addEventListener('DOMContentLoaded', () => {
+  loadStats();
+  loadDocs();
+  autoResize(document.getElementById('question-input'));
+});
+
+// ── Stats & docs ───────────────────────────────────────────────────────────
+async function loadStats() {
+  try {
+    const r = await fetch('/api/stats');
+    const s = await r.json();
+    document.getElementById('stats-panel').innerHTML =
+      `<strong>${s.total_chunks}</strong> chunks indexed<br>
+       <strong>${s.indexed_files}</strong> documents<br>
+       <span style="font-size:.7rem">${s.embed_model}</span>`;
+  } catch(e) {
+    document.getElementById('stats-panel').textContent = 'Error loading stats.';
+  }
+}
+
+async function loadDocs() {
+  try {
+    const r = await fetch('/api/docs-list');
+    const data = await r.json();
+    const list = document.getElementById('doc-list');
+    list.innerHTML = '';
+    if (!data.documents.length) {
+      list.innerHTML = '<div class="doc-item" style="font-style:italic">No documents yet</div>';
+      return;
+    }
+    data.documents.forEach(doc => {
+      const div = document.createElement('div');
+      div.className = 'doc-item';
+      div.innerHTML = `
+        <span class="dot"></span>
+        <span style="overflow:hidden;text-overflow:ellipsis;white-space:nowrap"
+              title="${doc.path}">${doc.name}</span>
+        <span class="del" onclick="removeDoc('${doc.name}', this)" title="Remove">✕</span>`;
+      list.appendChild(div);
+    });
+  } catch(e) {}
+}
+
+async function removeDoc(name, el) {
+  if (!confirm(`Remove "${name}" from the knowledge base?`)) return;
+  await fetch(`/api/doc/${encodeURIComponent(name)}`, { method: 'DELETE' });
+  el.closest('.doc-item').remove();
+  loadStats();
+}
+
+async function triggerIndex() {
+  setStatus('Indexing documents…');
+  try {
+    const r = await fetch('/api/index', { method: 'POST',
+      headers: {'Content-Type':'application/json'},
+      body: JSON.stringify({ force: false })
+    });
+    const d = await r.json();
+    setStatus(`Indexing complete — ${d.stats.total_chunks} chunks.`);
+    loadStats(); loadDocs();
+  } catch(e) { setStatus('Indexing failed.'); }
+}
+
+async function uploadFile(file) {
+  if (!file) return;
+  setStatus(`Uploading ${file.name}…`);
+  const fd = new FormData();
+  fd.append('file', file);
+  try {
+    const r = await fetch('/api/upload', { method: 'POST', body: fd });
+    const d = await r.json();
+    setStatus(d.message);
+    loadStats(); loadDocs();
+  } catch(e) { setStatus('Upload failed.'); }
+  document.getElementById('file-input').value = '';
+}
+
+// ── Chat ───────────────────────────────────────────────────────────────────
+function handleKey(e) {
+  if (e.key === 'Enter' && !e.shiftKey) { e.preventDefault(); sendQuestion(); }
+  setTimeout(() => autoResize(e.target), 0);
+}
+
+function autoResize(el) {
+  el.style.height = 'auto';
+  el.style.height = Math.min(el.scrollHeight, 160) + 'px';
+}
+
+async function sendQuestion() {
+  const input = document.getElementById('question-input');
+  const question = input.value.trim();
+  if (!question || isLoading) return;
+
+  isLoading = true;
+  input.value = '';
+  input.style.height = '48px';
+  document.getElementById('send-btn').disabled = true;
+  document.getElementById('empty-state')?.remove();
+
+  addMessage('user', question);
+  const agentMsg = addMessage('agent', '', true);
+  setStatus('Searching knowledge base…');
+
+  // SSE streaming
+  try {
+    const url = `/api/stream?question=${encodeURIComponent(question)}&top_k=5`;
+    const es = new EventSource(url);
+    let buffer = '';
+
+    es.onmessage = (e) => {
+      if (e.data === '[DONE]') {
+        es.close();
+        finishMessage(agentMsg, buffer);
+        isLoading = false;
+        document.getElementById('send-btn').disabled = false;
+        setStatus('Ready');
+        return;
+      }
+      buffer += e.data;
+      agentMsg.querySelector('.msg-text').textContent = buffer;
+      scrollToBottom();
+    };
+    es.onerror = () => {
+      es.close();
+      if (!buffer) {
+        agentMsg.querySelector('.msg-text').textContent =
+          'Error: Could not reach the server.';
+      }
+      isLoading = false;
+      document.getElementById('send-btn').disabled = false;
+      setStatus('Error');
+    };
+  } catch(e) {
+    agentMsg.querySelector('.msg-text').textContent = 'Unexpected error.';
+    isLoading = false;
+    document.getElementById('send-btn').disabled = false;
+    setStatus('Error');
+  }
+}
+
+function addMessage(role, text, loading = false) {
+  const container = document.getElementById('messages');
+  const div = document.createElement('div');
+  div.className = `msg ${role}`;
+  const label = role === 'user' ? 'You' : 'Agent';
+  const avatarText = role === 'user' ? 'YOU' : 'KB';
+  div.innerHTML = `
+    <div class="msg-avatar">${avatarText}</div>
+    <div class="msg-body">
+      <div class="msg-label">${label}</div>
+      <div class="msg-text">${loading ? '<div class="typing"><div class="dot"></div><div class="dot"></div><div class="dot"></div></div>' : escapeHtml(text)}</div>
+    </div>`;
+  container.appendChild(div);
+  scrollToBottom();
+  return div;
+}
+
+function finishMessage(div, text) {
+  div.querySelector('.msg-text').textContent = text;
+  scrollToBottom();
+}
+
+function scrollToBottom() {
+  const c = document.getElementById('messages');
+  c.scrollTop = c.scrollHeight;
+}
+
+function setStatus(msg) {
+  document.getElementById('status-bar').textContent = msg;
+}
+
+function escapeHtml(s) {
+  return s.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');
+}
+</script>
+</body>
+</html>"""

linkedin_agent/README.md

@@ -0,0 +1,142 @@
+# LinkedIn Agent — Personal AI OS
+
+Monitors your LinkedIn feed, drafts comments and connection messages,
+and generates high-quality post ideas daily.
+
+## What it does
+
+| Capability | Detail |
+|---|---|
+| **Feed analysis** | Scans feed, finds high-engagement posts worth commenting on |
+| **Smart comments** | Drafts genuine, value-adding comments (never "Great post!") |
+| **Connection messages** | Personalised 300-char connection notes |
+| **Post drafts** | 6 post formats: thought leadership, how-to, story, list, hot take, celebration |
+| **Hook scoring** | Rates each post 1-10 on hook, value, authenticity, engagement |
+| **Engagement plan** | Tells you exactly who to engage with + why + how long it'll take |
+| **4 outputs** | HTML email · WhatsApp · Notion DB · Markdown drafts file |
+| **CLI** | One-off commands for posts, connections, feed |
+
+---
+
+## File structure
+
+```
+linkedin_agent/
+├── main_agent.py       # Orchestrator, scheduler, CLI
+├── data_fetcher.py     # RapidAPI + Serper fallback + mock mode
+├── llm.py              # 6 Groq prompts: analysis, plan, comment, connect, post, score
+├── linkedin_store.py   # Local JSON: drafts, history, connections, feed snapshots
+├── delivery.py         # Email HTML, WhatsApp, Notion, Markdown
+├── .env.example
+├── requirements.txt
+└── README.md
+```
+
+---
+
+## Setup
+
+```bash
+pip install -r requirements.txt
+cp .env.example .env
+# Fill in your details
+```
+
+### 3 data source options
+
+**Option A — RapidAPI (real LinkedIn data)**
+1. Go to [rapidapi.com](https://rapidapi.com)
+2. Search "LinkedIn Data API" — subscribe to free tier
+3. Add `RAPIDAPI_KEY` to your `.env`
+
+**Option B — Serper only (public post search)**
+1. Get free key at [serper.dev](https://serper.dev)
+2. Searches Google for LinkedIn posts in your niche
+3. No LinkedIn login needed
+
+**Option C — Mock mode (development/testing)**
+```env
+LINKEDIN_MOCK_MODE=true
+```
+Uses realistic dummy data — great for testing the full pipeline without any API keys.
+
+---
+
+## Usage
+
+```bash
+# Daily digest (feed + engagement plan + post idea + delivery)
+python main_agent.py --feed
+
+# Draft connection message for someone
+python main_agent.py --connect "Priya Sharma" --role "CTO" --company "Zepto"
+
+# Draft a specific type of post
+python main_agent.py --draft-post --post-type thought_leadership
+python main_agent.py --draft-post --post-type story --topic "my first startup failure"
+python main_agent.py --draft-post --post-type how_to --topic "building AI agents"
+
+# Run as daemon (daily at 9:30 AM)
+python main_agent.py --daemon
+```
+
+---
+
+## Post types
+
+| Type | Format | Best for |
+|---|---|---|
+| `thought_leadership` | Bold claim + insight + question | Establishing expertise |
+| `how_to` | Numbered steps, practical | Getting saves and shares |
+| `story` | Personal narrative arc | Building connection |
+| `list` | "X things I wish I knew" | Easy to consume |
+| `hot_take` | Contrarian + reasoned | Debate and comments |
+| `celebration` | Milestone + journey + lesson | Announcements |
+
+---
+
+## Comment strategy
+
+The agent drafts comments with one of 5 angles:
+
+| Angle | Style |
+|---|---|
+| ⚡ `contrarian` | Respectful pushback with a reason |
+| 👍 `supportive` | Adds data, example, or extends the idea |
+| 💡 `add_value` | Brings a new angle or related insight |
+| ❓ `ask_question` | Genuine curiosity about their experience |
+| 🗣️ `share_experience` | "This reminded me of when I…" |
+
+Rules baked into the prompt: no sycophantic openers, never starts with "I", max 4 sentences, sounds human.
+
+---
+
+## Personalisation
+
+Fill these in `.env` for best results — they're injected into every prompt:
+
+```env
+LINKEDIN_USER_NAME=Raj Patel
+LINKEDIN_USER_ROLE=Founder & CEO at BuildFast
+LINKEDIN_USER_INDUSTRY=B2B SaaS / AI Tools
+LINKEDIN_NICHE_TOPICS=AI agents, developer tools, bootstrapping
+LINKEDIN_WRITING_TONE=direct, slightly contrarian, data-driven
+LINKEDIN_GOAL=reach 5000 followers and get 3 inbound leads/month
+```
+
+---
+
+## Integration with Personal AI OS
+
+```
+01 ✅ Daily Planner Agent
+02 ✅ Email Agent
+03 ✅ Meeting Prep Agent
+04 ✅ End-of-Day Review Agent
+05 ✅ Task Manager Agent
+06 ✅ Research Agent
+07 ✅ Finance Agent
+08 ✅ LinkedIn Agent      ← YOU ARE HERE
+09    Knowledge Agent
+10    Master Orchestrator (Mem0 + LangGraph)
+```

linkedin_agent/data_fetcher.py

@@ -0,0 +1,352 @@
+"""
+data_fetcher.py — LinkedIn Agent
+==================================
+Fetches LinkedIn data via:
+  1. RapidAPI LinkedIn scraper (primary — needs RAPIDAPI_KEY)
+  2. Serper Google search fallback (for public profile info)
+  3. Local mock data for development/testing
+
+Note: LinkedIn blocks direct scraping. This agent uses the
+Fresh LinkedIn Profile Data API on RapidAPI (freemium).
+"""
+
+import os
+import json
+import logging
+import requests
+from datetime import datetime
+from typing import Optional
+from pathlib import Path
+
+logger = logging.getLogger("LinkedInAgent.DataFetcher")
+
+RAPIDAPI_KEY      = os.getenv("RAPIDAPI_KEY", "")
+SERPER_API_KEY    = os.getenv("SERPER_API_KEY", "")
+REQUEST_TIMEOUT   = int(os.getenv("REQUEST_TIMEOUT", "10"))
+MOCK_MODE         = os.getenv("LINKEDIN_MOCK_MODE", "false").lower() == "true"
+
+# RapidAPI LinkedIn endpoints
+RAPIDAPI_HOST_FEED    = "linkedin-data-api.p.rapidapi.com"
+RAPIDAPI_HOST_PROFILE = "fresh-linkedin-profile-data.p.rapidapi.com"
+
+NICHE_TOPICS = os.getenv("LINKEDIN_NICHE_TOPICS", "AI, technology, startups")
+
+
+# ── feed ──────────────────────────────────────────────────────────────────────
+
+def fetch_linkedin_feed(max_posts: int = 20) -> list[dict]:
+    """
+    Fetches recent LinkedIn feed posts.
+    Returns: [{author, role, company, content, likes, comments, url, posted_at}]
+    """
+    if MOCK_MODE:
+        return _mock_feed()
+
+    if RAPIDAPI_KEY:
+        posts = _fetch_feed_rapidapi(max_posts)
+        if posts:
+            return posts
+
+    # Fallback: search for trending LinkedIn posts in user's niche via Serper
+    logger.info("RapidAPI unavailable — using Serper search fallback for feed")
+    return _fetch_feed_via_search()
+
+
+def _fetch_feed_rapidapi(max_posts: int) -> list[dict]:
+    try:
+        resp = requests.get(
+            "https://linkedin-data-api.p.rapidapi.com/get-feed-posts",
+            headers={
+                "X-RapidAPI-Key":  RAPIDAPI_KEY,
+                "X-RapidAPI-Host": RAPIDAPI_HOST_FEED,
+            },
+            params={"count": max_posts},
+            timeout=REQUEST_TIMEOUT,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        posts = []
+        for item in data.get("data", {}).get("items", []):
+            actor = item.get("actor", {})
+            posts.append({
+                "author":     actor.get("name", ""),
+                "role":       actor.get("description", ""),
+                "company":    actor.get("subDescription", ""),
+                "content":    item.get("commentary", {}).get("text", ""),
+                "likes":      item.get("socialDetail", {}).get("totalLikes", 0),
+                "comments":   item.get("socialDetail", {}).get("totalComments", 0),
+                "shares":     item.get("socialDetail", {}).get("totalShares", 0),
+                "url":        item.get("shareUrl", ""),
+                "posted_at":  item.get("postedAt", ""),
+                "post_id":    item.get("entityUrn", ""),
+                "source":     "rapidapi",
+            })
+        return posts
+    except Exception as e:
+        logger.warning(f"RapidAPI feed fetch failed: {e}")
+        return []
+
+
+def _fetch_feed_via_search() -> list[dict]:
+    """Uses Serper to find trending LinkedIn posts in the user's niche."""
+    if not SERPER_API_KEY:
+        logger.warning("No SERPER_API_KEY — returning mock feed")
+        return _mock_feed()
+
+    topics = [t.strip() for t in NICHE_TOPICS.split(",")][:3]
+    posts  = []
+
+    for topic in topics:
+        try:
+            resp = requests.post(
+                "https://google.serper.dev/search",
+                headers={"X-API-KEY": SERPER_API_KEY, "Content-Type": "application/json"},
+                json={"q": f"site:linkedin.com/posts {topic} 2025", "num": 5},
+                timeout=REQUEST_TIMEOUT,
+            )
+            resp.raise_for_status()
+            for item in resp.json().get("organic", []):
+                posts.append({
+                    "author":   "",
+                    "role":     "",
+                    "company":  "",
+                    "content":  item.get("snippet", ""),
+                    "title":    item.get("title", ""),
+                    "likes":    0,
+                    "comments": 0,
+                    "url":      item.get("link", ""),
+                    "posted_at": "",
+                    "topic":    topic,
+                    "source":   "serper",
+                })
+        except Exception as e:
+            logger.warning(f"Serper feed search failed for '{topic}': {e}")
+
+    return posts
+
+
+# ── profile ───────────────────────────────────────────────────────────────────
+
+def fetch_profile_info(name_or_url: str) -> Optional[dict]:
+    """
+    Fetches public LinkedIn profile info for a person.
+    Returns: {name, role, company, about, skills, recent_posts, url}
+    """
+    if MOCK_MODE:
+        return _mock_profile(name_or_url)
+
+    if RAPIDAPI_KEY:
+        return _fetch_profile_rapidapi(name_or_url)
+
+    return _fetch_profile_via_search(name_or_url)
+
+
+def _fetch_profile_rapidapi(name_or_url: str) -> Optional[dict]:
+    try:
+        # If it's not a URL, search for the profile URL first
+        profile_url = name_or_url
+        if "linkedin.com" not in name_or_url:
+            profile_url = _search_profile_url(name_or_url)
+            if not profile_url:
+                return None
+
+        resp = requests.get(
+            "https://fresh-linkedin-profile-data.p.rapidapi.com/get-linkedin-profile",
+            headers={
+                "X-RapidAPI-Key":  RAPIDAPI_KEY,
+                "X-RapidAPI-Host": RAPIDAPI_HOST_PROFILE,
+            },
+            params={"linkedin_url": profile_url, "include_skills": "true"},
+            timeout=REQUEST_TIMEOUT,
+        )
+        resp.raise_for_status()
+        d = resp.json().get("data", {})
+        return {
+            "name":         d.get("full_name", ""),
+            "role":         d.get("headline", ""),
+            "company":      d.get("company", ""),
+            "location":     d.get("location", ""),
+            "about":        d.get("about", "")[:500],
+            "skills":       [s.get("name") for s in d.get("skills", [])[:10]],
+            "connections":  d.get("connections_count", 0),
+            "followers":    d.get("followers_count", 0),
+            "url":          profile_url,
+            "source":       "rapidapi",
+        }
+    except Exception as e:
+        logger.warning(f"RapidAPI profile fetch failed: {e}")
+        return None
+
+
+def _search_profile_url(name: str) -> Optional[str]:
+    """Searches Google for someone's LinkedIn profile URL."""
+    if not SERPER_API_KEY:
+        return None
+    try:
+        resp = requests.post(
+            "https://google.serper.dev/search",
+            headers={"X-API-KEY": SERPER_API_KEY, "Content-Type": "application/json"},
+            json={"q": f"site:linkedin.com/in {name}", "num": 1},
+            timeout=REQUEST_TIMEOUT,
+        )
+        results = resp.json().get("organic", [])
+        if results:
+            return results[0].get("link", "")
+    except Exception as e:
+        logger.warning(f"Profile URL search failed: {e}")
+    return None
+
+
+def _fetch_profile_via_search(name: str) -> Optional[dict]:
+    """Fallback: build profile context from web search snippets."""
+    if not SERPER_API_KEY:
+        return None
+    try:
+        resp = requests.post(
+            "https://google.serper.dev/search",
+            headers={"X-API-KEY": SERPER_API_KEY, "Content-Type": "application/json"},
+            json={"q": f"{name} LinkedIn profile", "num": 3},
+            timeout=REQUEST_TIMEOUT,
+        )
+        results = resp.json().get("organic", [])
+        if not results:
+            return None
+        # Combine snippets as profile context
+        about = " ".join(r.get("snippet", "") for r in results[:2])
+        return {
+            "name":    name,
+            "role":    "",
+            "company": "",
+            "about":   about[:500],
+            "source":  "serper",
+        }
+    except Exception as e:
+        logger.warning(f"Profile search failed: {e}")
+        return None
+
+
+# ── connection suggestions ────────────────────────────────────────────────────
+
+def fetch_connection_suggestions() -> list[dict]:
+    """
+    Returns people worth connecting with.
+    Primary: RapidAPI | Fallback: Serper search for people in niche.
+    """
+    if MOCK_MODE:
+        return _mock_suggestions()
+
+    if RAPIDAPI_KEY:
+        try:
+            resp = requests.get(
+                "https://linkedin-data-api.p.rapidapi.com/get-profile-connections",
+                headers={
+                    "X-RapidAPI-Key":  RAPIDAPI_KEY,
+                    "X-RapidAPI-Host": RAPIDAPI_HOST_FEED,
+                },
+                params={"count": 10},
+                timeout=REQUEST_TIMEOUT,
+            )
+            resp.raise_for_status()
+            data  = resp.json()
+            items = data.get("data", {}).get("items", [])
+            return [
+                {
+                    "name":    item.get("name", ""),
+                    "role":    item.get("headline", ""),
+                    "company": item.get("company", ""),
+                    "url":     item.get("profileUrl", ""),
+                    "mutual":  item.get("mutualConnections", 0),
+                    "source":  "rapidapi",
+                }
+                for item in items
+            ]
+        except Exception as e:
+            logger.warning(f"RapidAPI suggestions failed: {e}")
+
+    # Fallback: search for thought leaders in user's niche
+    return _fetch_suggestions_via_search()
+
+
+def _fetch_suggestions_via_search() -> list[dict]:
+    if not SERPER_API_KEY:
+        return _mock_suggestions()
+    topics = [t.strip() for t in NICHE_TOPICS.split(",")][:2]
+    people = []
+    for topic in topics:
+        try:
+            resp = requests.post(
+                "https://google.serper.dev/search",
+                headers={"X-API-KEY": SERPER_API_KEY, "Content-Type": "application/json"},
+                json={"q": f"LinkedIn {topic} thought leader India 2025", "num": 4},
+                timeout=REQUEST_TIMEOUT,
+            )
+            for item in resp.json().get("organic", []):
+                if "linkedin.com/in/" in item.get("link", ""):
+                    people.append({
+                        "name":    item.get("title", "").split(" - ")[0],
+                        "role":    item.get("title", "").split(" - ")[-1][:80],
+                        "company": "",
+                        "url":     item.get("link", ""),
+                        "snippet": item.get("snippet", ""),
+                        "topic":   topic,
+                        "source":  "serper",
+                    })
+        except Exception as e:
+            logger.warning(f"Suggestion search failed: {e}")
+    return people[:8]
+
+
+def fetch_my_profile() -> dict:
+    """Returns the user's own profile context from .env settings."""
+    return {
+        "name":     os.getenv("LINKEDIN_USER_NAME", ""),
+        "role":     os.getenv("LINKEDIN_USER_ROLE", ""),
+        "industry": os.getenv("LINKEDIN_USER_INDUSTRY", ""),
+        "topics":   os.getenv("LINKEDIN_NICHE_TOPICS", ""),
+        "tone":     os.getenv("LINKEDIN_WRITING_TONE", "professional yet conversational"),
+        "goal":     os.getenv("LINKEDIN_GOAL", "build thought leadership and grow network"),
+    }
+
+
+# ── mock data for dev/testing ──────────────────────────────────────────────────
+
+def _mock_feed() -> list[dict]:
+    return [
+        {
+            "author": "Kunal Shah", "role": "Founder", "company": "CRED",
+            "content": "The best founders I know don't chase funding. They chase clarity. When you're clear on the problem, capital follows. Most pitches fail not because of bad ideas but because of unclear thinking.",
+            "likes": 3420, "comments": 187, "shares": 94,
+            "url": "https://linkedin.com/posts/mock1", "posted_at": "2h", "source": "mock",
+        },
+        {
+            "author": "Ankur Warikoo", "role": "Entrepreneur & Author", "company": "",
+            "content": "I failed 3 businesses before 30. Each one taught me something the previous hadn't. Failure is only permanent if you stop. The best thing you can do after failing is to write down what you learned within 24 hours.",
+            "likes": 5100, "comments": 342, "shares": 201,
+            "url": "https://linkedin.com/posts/mock2", "posted_at": "5h", "source": "mock",
+        },
+        {
+            "author": "Paras Chopra", "role": "Founder", "company": "Wingify",
+            "content": "Hot take: Most AI startups are building features, not businesses. A feature becomes a business only when it creates a switching cost. What's your moat beyond the AI model itself?",
+            "likes": 1890, "comments": 256, "shares": 78,
+            "url": "https://linkedin.com/posts/mock3", "posted_at": "8h", "source": "mock",
+        },
+    ]
+
+
+def _mock_profile(name: str) -> dict:
+    return {
+        "name":    name,
+        "role":    "Senior Product Manager",
+        "company": "Tech Startup",
+        "about":   f"{name} is a product leader with 8 years of experience in B2B SaaS. Previously at Razorpay and Freshworks.",
+        "skills":  ["Product Strategy", "Growth", "AI/ML", "Leadership"],
+        "source":  "mock",
+    }
+
+
+def _mock_suggestions() -> list[dict]:
+    return [
+        {"name": "Nikhil Kamath", "role": "Co-founder", "company": "Zerodha", "mutual": 12, "source": "mock"},
+        {"name": "Sriram Krishnan", "role": "General Partner", "company": "a16z", "mutual": 8, "source": "mock"},
+        {"name": "Ritesh Agarwal", "role": "Founder & CEO", "company": "OYO", "mutual": 5, "source": "mock"},
+    ]

linkedin_agent/delivery.py

@@ -0,0 +1,348 @@
+"""
+delivery.py — LinkedIn Agent
+==============================
+Output channels: Rich HTML email, WhatsApp, Notion, Markdown drafts file.
+"""
+
+import os
+import re
+import smtplib
+import logging
+import requests
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+from datetime import datetime
+from pathlib import Path
+
+logger = logging.getLogger("LinkedInAgent.Delivery")
+
+SMTP_EMAIL     = os.getenv("SMTP_EMAIL", "")
+SMTP_PASSWORD  = os.getenv("SMTP_PASSWORD", "")
+SMTP_HOST      = os.getenv("SMTP_HOST", "smtp.gmail.com")
+SMTP_PORT      = int(os.getenv("SMTP_PORT", "587"))
+
+TWILIO_SID     = os.getenv("TWILIO_ACCOUNT_SID", "")
+TWILIO_AUTH    = os.getenv("TWILIO_AUTH_TOKEN", "")
+TWILIO_WA_FROM = os.getenv("TWILIO_WHATSAPP_FROM", "whatsapp:+14155238886")
+WHATSAPP_TO    = os.getenv("WHATSAPP_TO", "")
+
+NOTION_TOKEN   = os.getenv("NOTION_TOKEN", "")
+NOTION_DB_ID   = os.getenv("NOTION_LINKEDIN_DB_ID", "")
+
+DRAFTS_DIR     = Path(os.getenv("LINKEDIN_DRAFTS_DIR", "linkedin_drafts"))
+
+ANGLE_EMOJI = {
+    "contrarian":       "⚡",
+    "supportive":       "👍",
+    "add_value":        "💡",
+    "ask_question":     "❓",
+    "share_experience": "🗣️",
+}
+
+
+# ── markdown ──────────────────────────────────────────────────────────────────
+
+def save_drafts_to_markdown(report: dict) -> str:
+    DRAFTS_DIR.mkdir(exist_ok=True)
+    ts       = datetime.now().strftime("%Y%m%d_%H%M%S")
+    filename = DRAFTS_DIR / f"linkedin_drafts_{ts}.md"
+    date_str = datetime.now().strftime("%B %d, %Y")
+
+    lines = [f"# LinkedIn Drafts — {date_str}", ""]
+
+    # Post idea
+    post = report.get("post_idea", {})
+    if post.get("content"):
+        lines += [
+            "## ✍️ Post Draft",
+            f"**Type:** {post.get('post_type','')} | "
+            f"**Hook Score:** {post.get('hook_score','?')}/10 | "
+            f"**Best Time:** {post.get('best_time','')}",
+            "",
+            post["content"],
+            "",
+            f"**Hashtags:** {' '.join(post.get('hashtags', []))}",
+            "",
+            "---",
+            "",
+        ]
+
+    # Comments
+    comments = report.get("drafted_comments", [])
+    if comments:
+        lines.append("## 💬 Comments to Post")
+        for c in comments:
+            lines += [
+                f"### {ANGLE_EMOJI.get(c.get('suggested_angle',''), '💬')} {c.get('author', 'Unknown')}",
+                f"*{c.get('role', '')}*",
+                f"**Post summary:** {c.get('content_summary', '')}",
+                f"**Angle:** {c.get('suggested_angle', '')}",
+                "",
+                f"> {c.get('drafted_comment', '')}",
+                "",
+                f"🔗 {c.get('url', '')}",
+                "",
+            ]
+        lines.append("---\n")
+
+    # Connection messages
+    connections = report.get("drafted_connections", [])
+    if connections:
+        lines.append("## 🤝 Connection Requests to Send")
+        for p in connections:
+            lines += [
+                f"### {p.get('name', 'Unknown')}",
+                f"*{p.get('role', '')} @ {p.get('company', '')}*",
+                f"**Why connect:** {p.get('why_connect', '')}",
+                "",
+                f"**Message ({len(p.get('drafted_message',''))} chars):**",
+                f"> {p.get('drafted_message', '')}",
+                "",
+                f"🔗 {p.get('url', '')}",
+                "",
+            ]
+
+    try:
+        filename.write_text("\n".join(lines), encoding="utf-8")
+        return str(filename)
+    except Exception as e:
+        logger.error(f"Could not save markdown: {e}")
+        return ""
+
+
+# ── email ─────────────────────────────────────────────────────────────────────
+
+def send_digest_email(report: dict, recipient: str = "") -> bool:
+    if not SMTP_EMAIL or not SMTP_PASSWORD:
+        logger.warning("SMTP not configured — skipping email")
+        return False
+    recipient = recipient or SMTP_EMAIL
+    date_str  = datetime.now().strftime("%b %d, %Y")
+    subject   = f"🔗 LinkedIn Digest — {date_str}"
+    html      = _build_html(report)
+    plain     = _build_plain(report)
+
+    try:
+        msg = MIMEMultipart("alternative")
+        msg["Subject"] = subject
+        msg["From"]    = SMTP_EMAIL
+        msg["To"]      = recipient
+        msg.attach(MIMEText(plain, "plain"))
+        msg.attach(MIMEText(html, "html"))
+
+        with smtplib.SMTP(SMTP_HOST, SMTP_PORT) as server:
+            server.starttls()
+            server.login(SMTP_EMAIL, SMTP_PASSWORD)
+            server.sendmail(SMTP_EMAIL, recipient, msg.as_string())
+        logger.info(f"Digest email sent to {recipient}")
+        return True
+    except Exception as e:
+        logger.error(f"Email delivery failed: {e}", exc_info=True)
+        return False
+
+
+def _build_plain(report: dict) -> str:
+    post    = report.get("post_idea", {})
+    comments = report.get("drafted_comments", [])
+    connects = report.get("drafted_connections", [])
+    lines = [
+        f"LinkedIn Daily Digest — {datetime.now().strftime('%B %d, %Y')}",
+        "=" * 50,
+        f"Feed posts scanned: {report.get('feed_posts_scanned', 0)}",
+        f"Comment drafts: {len(comments)}",
+        f"Connection drafts: {len(connects)}",
+        "",
+        "POST IDEA:",
+        post.get("content", "None")[:500],
+        "",
+    ]
+    for c in comments:
+        lines += [f"COMMENT → {c.get('author', '')}", c.get("drafted_comment", ""), ""]
+    for p in connects:
+        lines += [f"CONNECT → {p.get('name', '')}", p.get("drafted_message", ""), ""]
+    return "\n".join(lines)
+
+
+def _build_html(report: dict) -> str:
+    post     = report.get("post_idea", {})
+    comments = report.get("drafted_comments", [])
+    connects = report.get("drafted_connections", [])
+    plan     = report.get("engagement_plan", {})
+    analysis = report.get("feed_analysis", {})
+    ts       = datetime.now().strftime("%B %d, %Y %H:%M")
+    scanned  = report.get("feed_posts_scanned", 0)
+
+    # trending topics pills
+    topics_html = "".join(
+        f'<span style="background:#dbeafe;color:#1d4ed8;padding:3px 10px;border-radius:12px;font-size:12px;margin:2px">{t}</span>'
+        for t in analysis.get("trending_topics", [])[:5]
+    )
+
+    # post idea card
+    post_content = post.get("content", "")
+    hook_score   = post.get("hook_score", 0)
+    hook_color   = "#16a34a" if hook_score >= 8 else "#ca8a04" if hook_score >= 6 else "#dc2626"
+    hashtags_str = " ".join(post.get("hashtags", []))
+    post_card = f"""
+    <div style='background:#f0f9ff;border:1px solid #bae6fd;border-radius:8px;padding:16px;margin:12px 0'>
+      <div style='display:flex;justify-content:space-between;align-items:center;margin-bottom:8px'>
+        <strong style='color:#0369a1'>✍️ Today's Post Draft</strong>
+        <span style='background:{hook_color};color:white;padding:2px 8px;border-radius:12px;font-size:12px'>
+          Hook {hook_score}/10
+        </span>
+      </div>
+      <p style='white-space:pre-wrap;font-size:14px;line-height:1.6;margin:0'>{post_content}</p>
+      <p style='margin:8px 0 0;font-size:12px;color:#6b7280'>{hashtags_str} · Best time: {post.get("best_time","")}</p>
+    </div>""" if post_content else ""
+
+    # comment cards
+    comment_cards = ""
+    for c in comments:
+        angle  = c.get("suggested_angle", "add_value")
+        emoji  = ANGLE_EMOJI.get(angle, "💬")
+        url    = c.get("url", "#")
+        comment_cards += f"""
+        <div style='border:1px solid #e2e8f0;border-radius:8px;padding:14px;margin:8px 0'>
+          <div style='font-weight:600;margin-bottom:4px'>{emoji} {c.get("author","")} <span style='font-weight:normal;color:#6b7280;font-size:13px'>— {c.get("role","")}</span></div>
+          <p style='font-size:13px;color:#64748b;margin:4px 0;font-style:italic'>{c.get("content_summary","")}</p>
+          <div style='background:#f8fafc;border-left:3px solid #3b82f6;padding:8px 12px;margin:8px 0;border-radius:0 4px 4px 0'>
+            <p style='margin:0;font-size:14px'>{c.get("drafted_comment","")}</p>
+          </div>
+          <a href='{url}' style='font-size:12px;color:#3b82f6'>View post →</a>
+        </div>"""
+
+    # connection cards
+    connect_cards = ""
+    for p in connects:
+        msg_len = len(p.get("drafted_message", ""))
+        connect_cards += f"""
+        <div style='border:1px solid #e2e8f0;border-radius:8px;padding:14px;margin:8px 0'>
+          <div style='font-weight:600;margin-bottom:2px'>🤝 {p.get("name","")}</div>
+          <div style='font-size:13px;color:#6b7280;margin-bottom:8px'>{p.get("role","")} @ {p.get("company","")}</div>
+          <div style='background:#f0fdf4;border-left:3px solid #16a34a;padding:8px 12px;border-radius:0 4px 4px 0'>
+            <p style='margin:0;font-size:14px'>{p.get("drafted_message","")}</p>
+          </div>
+          <p style='font-size:12px;color:#9ca3af;margin:4px 0'>{msg_len}/300 chars</p>
+        </div>"""
+
+    daily_goal = plan.get("daily_goal", "")
+    est_time   = plan.get("estimated_time_minutes", 15)
+
+    return f"""<!DOCTYPE html><html><body style='font-family:sans-serif;max-width:720px;margin:0 auto;color:#111;font-size:14px'>
+
+<div style='background:#0a66c2;color:white;padding:20px 24px;border-radius:8px 8px 0 0'>
+  <h2 style='margin:0'>🔗 LinkedIn Agent Digest</h2>
+  <p style='margin:4px 0 0;opacity:0.8;font-size:13px'>{ts} · {scanned} posts scanned</p>
+</div>
+
+<div style='padding:16px 24px;background:#f8fafc;border:1px solid #e2e8f0;border-top:none'>
+  <div style='display:flex;gap:16px;flex-wrap:wrap;margin-bottom:12px'>
+    <div style='text-align:center'><strong style='font-size:20px;color:#0a66c2'>{len(comments)}</strong><br><span style='font-size:12px;color:#6b7280'>Comments</span></div>
+    <div style='text-align:center'><strong style='font-size:20px;color:#0a66c2'>{len(connects)}</strong><br><span style='font-size:12px;color:#6b7280'>Connections</span></div>
+    <div style='text-align:center'><strong style='font-size:20px;color:#0a66c2'>{est_time}m</strong><br><span style='font-size:12px;color:#6b7280'>Est. time</span></div>
+  </div>
+  {f'<p style="margin:0;font-size:13px;color:#1d4ed8;font-style:italic">🎯 {daily_goal}</p>' if daily_goal else ''}
+</div>
+
+<div style='padding:16px 24px;background:#fff;border:1px solid #e2e8f0;border-top:none'>
+  <strong style='font-size:13px;color:#64748b'>TRENDING IN YOUR FEED</strong><br>
+  <div style='margin-top:8px'>{topics_html}</div>
+</div>
+
+<div style='padding:16px 24px;background:#fff;border:1px solid #e2e8f0;border-top:none'>
+  {post_card}
+</div>
+
+{"<div style='padding:16px 24px;background:#fff;border:1px solid #e2e8f0;border-top:none'><h3 style='margin:0 0 8px;color:#1e293b'>💬 Comment Drafts</h3>" + comment_cards + "</div>" if comment_cards else ""}
+
+{"<div style='padding:16px 24px;background:#fff;border:1px solid #e2e8f0;border-top:none'><h3 style='margin:0 0 8px;color:#1e293b'>🤝 Connection Drafts</h3>" + connect_cards + "</div>" if connect_cards else ""}
+
+<p style='font-size:11px;color:#9ca3af;padding:8px 24px'>Personal AI OS · LinkedIn Agent</p>
+</body></html>"""
+
+
+# ── whatsapp ──────────────────────────────────────────────────────────────────
+
+def send_whatsapp_alert(report: dict) -> bool:
+    if not all([TWILIO_SID, TWILIO_AUTH, WHATSAPP_TO]):
+        logger.warning("Twilio not configured — skipping WhatsApp")
+        return False
+    try:
+        from twilio.rest import Client
+        comments = report.get("drafted_comments", [])
+        connects = report.get("drafted_connections", [])
+        post     = report.get("post_idea", {})
+        plan     = report.get("engagement_plan", {})
+
+        comment_names = ", ".join(c.get("author", "") for c in comments[:3])
+        connect_names = ", ".join(p.get("name", "") for p in connects[:3])
+
+        body = (
+            f"🔗 *LinkedIn Digest*\n"
+            f"{'─'*28}\n"
+            f"🎯 {plan.get('daily_goal','Engage and grow')}\n\n"
+            f"💬 Comment on: {comment_names or 'none'}\n"
+            f"🤝 Connect with: {connect_names or 'none'}\n"
+            f"✍️ Post idea ({post.get('post_type','')}, score {post.get('hook_score','?')}/10)\n\n"
+            f"_{plan.get('estimated_time_minutes',15)} min total_"
+        )
+
+        client = Client(TWILIO_SID, TWILIO_AUTH)
+        msg    = client.messages.create(
+            from_=TWILIO_WA_FROM, to=f"whatsapp:{WHATSAPP_TO}", body=body,
+        )
+        logger.info(f"WhatsApp sent: {msg.sid}")
+        return True
+    except Exception as e:
+        logger.error(f"WhatsApp failed: {e}", exc_info=True)
+        return False
+
+
+# ── notion ────────────────────────────────────────────────────────────────────
+
+def save_to_notion(report: dict) -> str:
+    if not NOTION_TOKEN or not NOTION_DB_ID:
+        logger.debug("Notion not configured — skipping")
+        return ""
+    try:
+        headers = {
+            "Authorization": f"Bearer {NOTION_TOKEN}",
+            "Notion-Version": "2022-06-28",
+            "Content-Type": "application/json",
+        }
+        date_str  = datetime.now().strftime("%Y-%m-%d")
+        post      = report.get("post_idea", {})
+        comments  = report.get("drafted_comments", [])
+        connects  = report.get("drafted_connections", [])
+
+        payload = {
+            "parent": {"database_id": NOTION_DB_ID},
+            "properties": {
+                "Name": {"title": [{"text": {"content": f"LinkedIn Digest — {date_str}"}}]},
+                "Date": {"date": {"start": date_str}},
+                "Post Type": {"select": {"name": post.get("post_type", "thought_leadership").replace("_", " ").title()}},
+                "Hook Score": {"number": post.get("hook_score", 0)},
+                "Comments Drafted": {"number": len(comments)},
+                "Connections Drafted": {"number": len(connects)},
+                "Trigger": {"rich_text": [{"text": {"content": report.get("trigger", "")}}]},
+            },
+            "children": [
+                {
+                    "object": "block", "type": "heading_2",
+                    "heading_2": {"rich_text": [{"type": "text", "text": {"content": "Post Draft"}}]},
+                },
+                {
+                    "object": "block", "type": "paragraph",
+                    "paragraph": {"rich_text": [{"type": "text", "text": {"content": post.get("content", "")[:2000]}}]},
+                },
+            ],
+        }
+        resp = requests.post(
+            "https://api.notion.com/v1/pages",
+            headers=headers, json=payload, timeout=10,
+        )
+        resp.raise_for_status()
+        return resp.json().get("url", "")
+    except Exception as e:
+        logger.error(f"Notion save failed: {e}", exc_info=True)
+        return ""

linkedin_agent/linkedin_data/drafts.json

@@ -0,0 +1,72 @@
+[
+  {
+    "id": "d04c1500-39b4-4730-90f2-79e9b05dca62",
+    "created_at": "2026-05-14T07:44:35.925500+00:00",
+    "date": "2026-05-14",
+    "comments": [
+      {
+        "author": "Ankur Warikoo",
+        "content_summary": "The author shares his experience of failing 3 businesses before 30 and emphasizes the importance of learning from failures",
+        "url": "https://www.linkedin.com/feed/update/urn:li:activity:1234567890/",
+        "why_comment": "The post is engaging and relevant to startup building, and sharing a personal story can help build thought leadership",
+        "suggested_angle": "share_experience",
+        "drafted_comment": "Having navigated the challenges of building and scaling multiple SaaS companies, it's clear that resilience and adaptability are key to transforming failures into valuable lessons. The ability to analyze and learn from setbacks has been instrumental in shaping our company's growth strategy, allowing us to pivot and refine our approach in response to changing market conditions. What role do you think mentorship and external guidance play in helping entrepreneurs bounce back from failure and apply those lessons to future ventures?"
+      },
+      {
+        "author": "Paras Chopra",
+        "content_summary": "The author argues that most AI startups are building features, not businesses, and emphasizes the need for a moat beyond the AI model",
+        "url": "https://www.linkedin.com/feed/update/urn:li:activity:2345678901/",
+        "why_comment": "The post is thought-provoking and relevant to AI agents, and sharing an example can add value to the conversation",
+        "suggested_angle": "add_value",
+        "drafted_comment": "Building a defensible moat beyond the AI model is crucial for long-term sustainability, and this can be achieved by focusing on the data flywheel effect, where the AI model improves with more data, creating a self-reinforcing cycle. Successful AI startups have also emphasized the importance of integrating their AI models with human workflows, creating a seamless user experience that drives adoption and retention. By doing so, they can create a competitive advantage that goes beyond just the technology itself, what strategies have been most effective in your experience for building this type of moat?"
+      },
+      {
+        "author": "Kunal Shah",
+        "content_summary": "The author emphasizes the importance of clarity in founding a successful startup, rather than just chasing funding",
+        "url": "https://www.linkedin.com/feed/update/urn:li:activity:3456789012/",
+        "why_comment": "The post is engaging and relevant to startup building, and discussing the importance of clarity can help build thought leadership",
+        "suggested_angle": "supportive",
+        "drafted_comment": "Clarity is indeed crucial in the early stages of a startup, as it allows founders to focus on solving a specific problem and build a strong foundation for growth. Many successful SaaS companies have demonstrated that prioritizing clarity over funding can lead to more sustainable and long-term success. For instance, companies like Atlassian and Zoom have achieved remarkable growth by staying true to their core mission and values, what role do you think company culture plays in maintaining this clarity as the organization scales?"
+      }
+    ],
+    "connections": [
+      {
+        "name": "Nikhil Kamath",
+        "role": "Co-founder",
+        "company": "Zerodha",
+        "url": "https://www.linkedin.com/in/nikhilkamath/",
+        "why_connect": "Nikhil Kamath is a relevant connection in the startup space with 12 mutual connections, increasing the likelihood of engagement",
+        "drafted_message": "Nikhil, impressed by Zerodha's innovative approach, I'm reaching out as a fellow startup founder with similar interests in building scalable products."
+      },
+      {
+        "name": "Sriram Krishnan",
+        "role": "General Partner",
+        "company": "a16z",
+        "url": "https://www.linkedin.com/in/sriramkrishnan/",
+        "why_connect": "Sriram Krishnan is a key player in the VC space with 8 mutual connections, and connecting with him can lead to valuable networking opportunities",
+        "drafted_message": "Sriram, impressed by your work at a16z, particularly in areas like startup building and product management, looking forward to learning from your experience and exploring potential synergies."
+      },
+      {
+        "name": "Ritesh Agarwal",
+        "role": "Founder & CEO",
+        "company": "OYO",
+        "url": "https://www.linkedin.com/in/riteshagarwal/",
+        "why_connect": "Ritesh Agarwal is a successful entrepreneur in the startup space with 5 mutual connections, and connecting with him can help build relationships with other founders",
+        "drafted_message": "Impressed by OYO's growth, Ritesh. As a fellow founder and CEO, I'd appreciate learning from your startup building experiences and exploring potential synergies."
+      }
+    ],
+    "post_idea": {
+      "content": "**85% of startups fail within the first three years, often due to poor market timing or lack of product-market fit.**\nThis staggering statistic highlights the importance of careful planning and adaptability in the startup ecosystem.\n\nSuccessful entrepreneurs, such as Steve Jobs and Elon Musk, have demonstrated the ability to pivot and adjust their strategies in response to changing market conditions.\nTheir willingness to take calculated risks and experiment with new approaches has been key to their success.\n\nIn today's fast-paced technology landscape, the use of AI agents is becoming increasingly prevalent, with companies like Salesforce and Microsoft leveraging AI to drive innovation and growth.\nThe ability to effectively integrate AI into business operations will be crucial for startups looking to stay ahead of the curve.\n\nAs the founder of a SaaS company, navigating these challenges is a daily reality.\nWhat strategies have been most effective for you in building a successful startup, and how do you see AI shaping the future of entrepreneurship?",
+      "post_type": "thought_leadership",
+      "hook_score": 8,
+      "hashtags": [
+        "#startups",
+        "#AI",
+        "#entrepreneurship"
+      ],
+      "best_time": "Morning (7-9am) | Lunch (12-1pm) | Evening (6-8pm)",
+      "word_count": 163,
+      "char_count": 1063
+    }
+  }
+]

linkedin_agent/linkedin_data/feed_snapshots.json

@@ -0,0 +1,64 @@
+[
+  {
+    "date": "2026-05-14",
+    "timestamp": "2026-05-14T07:44:35.924598+00:00",
+    "post_count": 3,
+    "engagement_plan": {
+      "comment_targets": [
+        {
+          "author": "Ankur Warikoo",
+          "content_summary": "The author shares his experience of failing 3 businesses before 30 and emphasizes the importance of learning from failures",
+          "url": "https://www.linkedin.com/feed/update/urn:li:activity:1234567890/",
+          "why_comment": "The post is engaging and relevant to startup building, and sharing a personal story can help build thought leadership",
+          "suggested_angle": "share_experience",
+          "drafted_comment": "Having navigated the challenges of building and scaling multiple SaaS companies, it's clear that resilience and adaptability are key to transforming failures into valuable lessons. The ability to analyze and learn from setbacks has been instrumental in shaping our company's growth strategy, allowing us to pivot and refine our approach in response to changing market conditions. What role do you think mentorship and external guidance play in helping entrepreneurs bounce back from failure and apply those lessons to future ventures?"
+        },
+        {
+          "author": "Paras Chopra",
+          "content_summary": "The author argues that most AI startups are building features, not businesses, and emphasizes the need for a moat beyond the AI model",
+          "url": "https://www.linkedin.com/feed/update/urn:li:activity:2345678901/",
+          "why_comment": "The post is thought-provoking and relevant to AI agents, and sharing an example can add value to the conversation",
+          "suggested_angle": "add_value",
+          "drafted_comment": "Building a defensible moat beyond the AI model is crucial for long-term sustainability, and this can be achieved by focusing on the data flywheel effect, where the AI model improves with more data, creating a self-reinforcing cycle. Successful AI startups have also emphasized the importance of integrating their AI models with human workflows, creating a seamless user experience that drives adoption and retention. By doing so, they can create a competitive advantage that goes beyond just the technology itself, what strategies have been most effective in your experience for building this type of moat?"
+        },
+        {
+          "author": "Kunal Shah",
+          "content_summary": "The author emphasizes the importance of clarity in founding a successful startup, rather than just chasing funding",
+          "url": "https://www.linkedin.com/feed/update/urn:li:activity:3456789012/",
+          "why_comment": "The post is engaging and relevant to startup building, and discussing the importance of clarity can help build thought leadership",
+          "suggested_angle": "supportive",
+          "drafted_comment": "Clarity is indeed crucial in the early stages of a startup, as it allows founders to focus on solving a specific problem and build a strong foundation for growth. Many successful SaaS companies have demonstrated that prioritizing clarity over funding can lead to more sustainable and long-term success. For instance, companies like Atlassian and Zoom have achieved remarkable growth by staying true to their core mission and values, what role do you think company culture plays in maintaining this clarity as the organization scales?"
+        }
+      ],
+      "connect_targets": [
+        {
+          "name": "Nikhil Kamath",
+          "role": "Co-founder",
+          "company": "Zerodha",
+          "url": "https://www.linkedin.com/in/nikhilkamath/",
+          "why_connect": "Nikhil Kamath is a relevant connection in the startup space with 12 mutual connections, increasing the likelihood of engagement",
+          "drafted_message": "Nikhil, impressed by Zerodha's innovative approach, I'm reaching out as a fellow startup founder with similar interests in building scalable products."
+        },
+        {
+          "name": "Sriram Krishnan",
+          "role": "General Partner",
+          "company": "a16z",
+          "url": "https://www.linkedin.com/in/sriramkrishnan/",
+          "why_connect": "Sriram Krishnan is a key player in the VC space with 8 mutual connections, and connecting with him can lead to valuable networking opportunities",
+          "drafted_message": "Sriram, impressed by your work at a16z, particularly in areas like startup building and product management, looking forward to learning from your experience and exploring potential synergies."
+        },
+        {
+          "name": "Ritesh Agarwal",
+          "role": "Founder & CEO",
+          "company": "OYO",
+          "url": "https://www.linkedin.com/in/riteshagarwal/",
+          "why_connect": "Ritesh Agarwal is a successful entrepreneur in the startup space with 5 mutual connections, and connecting with him can help build relationships with other founders",
+          "drafted_message": "Impressed by OYO's growth, Ritesh. As a fellow founder and CEO, I'd appreciate learning from your startup building experiences and exploring potential synergies."
+        }
+      ],
+      "daily_goal": "Engage with relevant posts and connect with key players in the startup and AI spaces to build thought leadership and grow the network",
+      "estimated_time_minutes": 15
+    },
+    "trending_topics": []
+  }
+]

linkedin_agent/linkedin_drafts/linkedin_drafts_20260514_131435.md

@@ -0,0 +1,78 @@
+# LinkedIn Drafts — May 14, 2026
+
+## ✍️ Post Draft
+**Type:** thought_leadership | **Hook Score:** 8/10 | **Best Time:** Morning (7-9am) | Lunch (12-1pm) | Evening (6-8pm)
+
+**85% of startups fail within the first three years, often due to poor market timing or lack of product-market fit.**
+This staggering statistic highlights the importance of careful planning and adaptability in the startup ecosystem.
+
+Successful entrepreneurs, such as Steve Jobs and Elon Musk, have demonstrated the ability to pivot and adjust their strategies in response to changing market conditions.
+Their willingness to take calculated risks and experiment with new approaches has been key to their success.
+
+In today's fast-paced technology landscape, the use of AI agents is becoming increasingly prevalent, with companies like Salesforce and Microsoft leveraging AI to drive innovation and growth.
+The ability to effectively integrate AI into business operations will be crucial for startups looking to stay ahead of the curve.
+
+As the founder of a SaaS company, navigating these challenges is a daily reality.
+What strategies have been most effective for you in building a successful startup, and how do you see AI shaping the future of entrepreneurship?
+
+**Hashtags:** #startups #AI #entrepreneurship
+
+---
+
+## 💬 Comments to Post
+### 🗣️ Ankur Warikoo
+**
+**Post summary:** The author shares his experience of failing 3 businesses before 30 and emphasizes the importance of learning from failures
+**Angle:** share_experience
+
+> Having navigated the challenges of building and scaling multiple SaaS companies, it's clear that resilience and adaptability are key to transforming failures into valuable lessons. The ability to analyze and learn from setbacks has been instrumental in shaping our company's growth strategy, allowing us to pivot and refine our approach in response to changing market conditions. What role do you think mentorship and external guidance play in helping entrepreneurs bounce back from failure and apply those lessons to future ventures?
+
+🔗 https://www.linkedin.com/feed/update/urn:li:activity:1234567890/
+
+### 💡 Paras Chopra
+**
+**Post summary:** The author argues that most AI startups are building features, not businesses, and emphasizes the need for a moat beyond the AI model
+**Angle:** add_value
+
+> Building a defensible moat beyond the AI model is crucial for long-term sustainability, and this can be achieved by focusing on the data flywheel effect, where the AI model improves with more data, creating a self-reinforcing cycle. Successful AI startups have also emphasized the importance of integrating their AI models with human workflows, creating a seamless user experience that drives adoption and retention. By doing so, they can create a competitive advantage that goes beyond just the technology itself, what strategies have been most effective in your experience for building this type of moat?
+
+🔗 https://www.linkedin.com/feed/update/urn:li:activity:2345678901/
+
+### 👍 Kunal Shah
+**
+**Post summary:** The author emphasizes the importance of clarity in founding a successful startup, rather than just chasing funding
+**Angle:** supportive
+
+> Clarity is indeed crucial in the early stages of a startup, as it allows founders to focus on solving a specific problem and build a strong foundation for growth. Many successful SaaS companies have demonstrated that prioritizing clarity over funding can lead to more sustainable and long-term success. For instance, companies like Atlassian and Zoom have achieved remarkable growth by staying true to their core mission and values, what role do you think company culture plays in maintaining this clarity as the organization scales?
+
+🔗 https://www.linkedin.com/feed/update/urn:li:activity:3456789012/
+
+---
+
+## 🤝 Connection Requests to Send
+### Nikhil Kamath
+*Co-founder @ Zerodha*
+**Why connect:** Nikhil Kamath is a relevant connection in the startup space with 12 mutual connections, increasing the likelihood of engagement
+
+**Message (150 chars):**
+> Nikhil, impressed by Zerodha's innovative approach, I'm reaching out as a fellow startup founder with similar interests in building scalable products.
+
+🔗 https://www.linkedin.com/in/nikhilkamath/
+
+### Sriram Krishnan
+*General Partner @ a16z*
+**Why connect:** Sriram Krishnan is a key player in the VC space with 8 mutual connections, and connecting with him can lead to valuable networking opportunities
+
+**Message (191 chars):**
+> Sriram, impressed by your work at a16z, particularly in areas like startup building and product management, looking forward to learning from your experience and exploring potential synergies.
+
+🔗 https://www.linkedin.com/in/sriramkrishnan/
+
+### Ritesh Agarwal
+*Founder & CEO @ OYO*
+**Why connect:** Ritesh Agarwal is a successful entrepreneur in the startup space with 5 mutual connections, and connecting with him can help build relationships with other founders
+
+**Message (161 chars):**
+> Impressed by OYO's growth, Ritesh. As a fellow founder and CEO, I'd appreciate learning from your startup building experiences and exploring potential synergies.
+
+🔗 https://www.linkedin.com/in/riteshagarwal/

linkedin_agent/linkedin_store.py

@@ -0,0 +1,158 @@
+"""
+linkedin_store.py — LinkedIn Agent
+=====================================
+Local JSON store for feed snapshots, drafted content,
+posting history, and connection tracking.
+"""
+
+import os
+import json
+import uuid
+import logging
+from datetime import datetime, timezone, timedelta
+from pathlib import Path
+
+logger = logging.getLogger("LinkedInAgent.Store")
+
+STORE_DIR  = Path(os.getenv("LINKEDIN_STORE_DIR", "linkedin_data"))
+DRAFTS_FILE    = STORE_DIR / "drafts.json"
+HISTORY_FILE   = STORE_DIR / "post_history.json"
+CONNECTIONS_FILE = STORE_DIR / "connections.json"
+FEED_FILE      = STORE_DIR / "feed_snapshots.json"
+MAX_RECORDS    = 500
+
+
+class LinkedInStore:
+    def __init__(self):
+        STORE_DIR.mkdir(exist_ok=True)
+        self._drafts      = self._load(DRAFTS_FILE)
+        self._history     = self._load(HISTORY_FILE)
+        self._connections = self._load(CONNECTIONS_FILE)
+        self._feed        = self._load(FEED_FILE)
+
+    def _load(self, path: Path) -> list:
+        if path.exists():
+            try:
+                with open(path) as f:
+                    return json.load(f)
+            except Exception as e:
+                logger.warning(f"Could not load {path}: {e}")
+        return []
+
+    def _save(self, path: Path, data: list):
+        try:
+            with open(path, "w") as f:
+                json.dump(data[-MAX_RECORDS:], f, indent=2, default=str)
+        except Exception as e:
+            logger.error(f"Could not save {path}: {e}")
+
+    # ── drafts ────────────────────────────────────────────────────────────────
+
+    def save_drafts(
+        self,
+        comments: list[dict],
+        connections: list[dict],
+        post_idea: dict,
+    ):
+        entry = {
+            "id":          str(uuid.uuid4()),
+            "created_at":  datetime.now(timezone.utc).isoformat(),
+            "date":        datetime.now().strftime("%Y-%m-%d"),
+            "comments":    comments,
+            "connections": connections,
+            "post_idea":   post_idea,
+        }
+        self._drafts.append(entry)
+        self._save(DRAFTS_FILE, self._drafts)
+
+    def get_todays_drafts(self) -> dict:
+        today = datetime.now().strftime("%Y-%m-%d")
+        for entry in reversed(self._drafts):
+            if entry.get("date") == today:
+                return entry
+        return {}
+
+    def get_all_draft_posts(self) -> list[dict]:
+        posts = []
+        for entry in self._drafts:
+            if entry.get("post_idea", {}).get("content"):
+                posts.append({
+                    "date":      entry["date"],
+                    "content":   entry["post_idea"]["content"],
+                    "post_type": entry["post_idea"].get("post_type", ""),
+                    "hook_score": entry["post_idea"].get("hook_score", 0),
+                    "hashtags":  entry["post_idea"].get("hashtags", []),
+                    "status":    entry["post_idea"].get("status", "draft"),
+                })
+        return posts
+
+    # ── posting history ───────────────────────────────────────────────────────
+
+    def mark_posted(self, post_content: str, post_type: str = "", url: str = ""):
+        entry = {
+            "id":         str(uuid.uuid4()),
+            "posted_at":  datetime.now(timezone.utc).isoformat(),
+            "date":       datetime.now().strftime("%Y-%m-%d"),
+            "content":    post_content[:500],
+            "post_type":  post_type,
+            "url":        url,
+        }
+        self._history.append(entry)
+        self._save(HISTORY_FILE, self._history)
+
+    def get_post_history(self, days: int = 30) -> list[dict]:
+        cutoff = (datetime.now() - timedelta(days=days)).strftime("%Y-%m-%d")
+        return [h for h in self._history if h.get("date", "") >= cutoff]
+
+    def get_topics_posted_recently(self, days: int = 14) -> list[str]:
+        """Returns recently used topics to avoid repetition."""
+        recent = self.get_post_history(days=days)
+        return [r.get("post_type", "") for r in recent]
+
+    # ── connections ───────────────────────────────────────────────────────────
+
+    def save_connection_sent(self, person: dict, message: str):
+        entry = {
+            "id":        str(uuid.uuid4()),
+            "sent_at":   datetime.now(timezone.utc).isoformat(),
+            "date":      datetime.now().strftime("%Y-%m-%d"),
+            "name":      person.get("name", ""),
+            "role":      person.get("role", ""),
+            "company":   person.get("company", ""),
+            "url":       person.get("url", ""),
+            "message":   message,
+            "status":    "sent",
+        }
+        self._connections.append(entry)
+        self._save(CONNECTIONS_FILE, self._connections)
+
+    def get_recent_connections(self, days: int = 7) -> list[dict]:
+        cutoff = (datetime.now() - timedelta(days=days)).strftime("%Y-%m-%d")
+        return [c for c in self._connections if c.get("date", "") >= cutoff]
+
+    # ── feed snapshots ────────────────────────────────────────────────────────
+
+    def save_feed_snapshot(self, posts: list[dict], engagement_plan: dict):
+        entry = {
+            "date":            datetime.now().strftime("%Y-%m-%d"),
+            "timestamp":       datetime.now(timezone.utc).isoformat(),
+            "post_count":      len(posts),
+            "engagement_plan": engagement_plan,
+            "trending_topics": engagement_plan.get("trending_topics", []),
+        }
+        self._feed.append(entry)
+        self._save(FEED_FILE, self._feed)
+
+    def get_recent_feed_snapshots(self, days: int = 7) -> list[dict]:
+        cutoff = (datetime.now() - timedelta(days=days)).strftime("%Y-%m-%d")
+        return [f for f in self._feed if f.get("date", "") >= cutoff]
+
+    # ── stats ─────────────────────────────────────────────────────────────────
+
+    def get_weekly_stats(self) -> dict:
+        return {
+            "posts_drafted":      len(self.get_all_draft_posts()),
+            "posts_published":    len(self.get_post_history(days=7)),
+            "connections_sent":   len(self.get_recent_connections(days=7)),
+            "days_active":        len({f["date"] for f in self.get_recent_feed_snapshots(days=7)}),
+        }

linkedin_agent/llm.py

@@ -0,0 +1,385 @@
+"""
+llm.py — LinkedIn Agent
+=========================
+All Groq (llama-3.3-70b-versatile) calls:
+  - Feed analysis + topic extraction
+  - Engagement plan generation
+  - Comment drafting
+  - Connection message drafting
+  - Post drafting (6 formats)
+  - Post idea scoring
+"""
+
+import os
+import json
+import re
+import logging
+from datetime import datetime
+from dotenv import load_dotenv
+load_dotenv()
+
+from groq import Groq
+
+logger = logging.getLogger("LinkedInAgent.LLM")
+
+client = Groq(api_key=os.getenv("GROQ_API_KEY"))
+MODEL  = os.getenv("GROQ_MODEL", "llama-3.3-70b-versatile")
+TODAY  = datetime.now().strftime("%A, %B %d, %Y")
+
+
+# ── helpers ───────────────────────────────────────────────────────────────────
+
+def _chat(system: str, user: str, temperature: float = 0.6, max_tokens: int = 1500) -> str:
+    resp = client.chat.completions.create(
+        model=MODEL,
+        temperature=temperature,
+        max_tokens=max_tokens,
+        messages=[
+            {"role": "system", "content": system},
+            {"role": "user",   "content": user},
+        ],
+    )
+    return resp.choices[0].message.content.strip()
+
+
+def _safe_json(text: str, fallback=None):
+    text = re.sub(r"```(?:json)?", "", text).strip().rstrip("`")
+    for s, e in [("[", "]"), ("{", "}")]:
+        si, ei = text.find(s), text.rfind(e)
+        if si != -1 and ei != -1:
+            try:
+                return json.loads(text[si: ei + 1])
+            except json.JSONDecodeError:
+                pass
+    return fallback if fallback is not None else {}
+
+
+# ── feed analysis ─────────────────────────────────────────────────────────────
+
+FEED_ANALYSIS_SYSTEM = f"""You are a LinkedIn growth strategist. Today is {TODAY}.
+
+Analyse a LinkedIn feed and return a JSON object with:
+{{
+  "trending_topics": ["topic1", "topic2", "topic3"],
+  "top_posts": [
+    {{
+      "author": "...",
+      "content_summary": "1 sentence summary",
+      "why_engaging": "why this post is getting traction",
+      "engagement_opportunity": "high|medium|low",
+      "suggested_angle": "what angle to take when commenting"
+    }}
+  ],
+  "feed_sentiment": "positive|neutral|mixed|negative",
+  "content_gaps": ["topic not covered that the user could post about"],
+  "best_posting_time": "observation about when posts in the feed were made"
+}}
+
+Focus on posts with high engagement or interesting ideas worth engaging with.
+Return top 5 posts maximum in top_posts."""
+
+
+def analyze_feed(posts: list[dict], user_context: dict) -> dict:
+    if not posts:
+        return {"trending_topics": [], "top_posts": [], "content_gaps": []}
+
+    posts_text = "\n\n".join(
+        f"[POST {i+1}]\nAuthor: {p.get('author','')} ({p.get('role','')} @ {p.get('company','')})\n"
+        f"Likes: {p.get('likes',0)} | Comments: {p.get('comments',0)}\n"
+        f"Content: {p.get('content','')[:400]}"
+        for i, p in enumerate(posts[:15])
+    )
+
+    user_str = (
+        f"User: {user_context.get('name')} | {user_context.get('role')} | "
+        f"Topics: {user_context.get('topics')}"
+    )
+
+    try:
+        raw = _chat(FEED_ANALYSIS_SYSTEM, f"{user_str}\n\nFEED:\n{posts_text}", temperature=0.3)
+        result = _safe_json(raw, {})
+        return result if isinstance(result, dict) else {}
+    except Exception as e:
+        logger.error(f"Feed analysis failed: {e}")
+        return {}
+
+
+# ── engagement plan ───────────────────────────────────────────────────────────
+
+ENGAGEMENT_PLAN_SYSTEM = f"""You are a LinkedIn growth strategist. Today is {TODAY}.
+
+Based on feed analysis and connection suggestions, create a daily engagement plan.
+
+Return JSON:
+{{
+  "comment_targets": [
+    {{
+      "author": "...",
+      "content_summary": "...",
+      "url": "...",
+      "why_comment": "strategic reason",
+      "suggested_angle": "contrarian|supportive|add_value|ask_question|share_experience"
+    }}
+  ],
+  "connect_targets": [
+    {{
+      "name": "...",
+      "role": "...",
+      "company": "...",
+      "url": "...",
+      "why_connect": "strategic reason"
+    }}
+  ],
+  "daily_goal": "one sentence goal for today's LinkedIn activity",
+  "estimated_time_minutes": 15
+}}
+
+Limit: 3 comment targets, 3 connect targets.
+Prioritise people who are active, relevant to the user's niche, and likely to engage back."""
+
+
+def generate_engagement_plan(
+    feed_analysis: dict,
+    suggestions: list[dict],
+    user_context: dict,
+) -> dict:
+    user_str = (
+        f"User: {user_context.get('name')} | {user_context.get('role')} | "
+        f"Goal: {user_context.get('goal', 'grow network and build thought leadership')} | "
+        f"Topics: {user_context.get('topics')}"
+    )
+    feed_str       = json.dumps(feed_analysis.get("top_posts", [])[:5], indent=2)
+    suggestions_str = json.dumps(suggestions[:8], indent=2)
+
+    try:
+        raw = _chat(
+            ENGAGEMENT_PLAN_SYSTEM,
+            f"{user_str}\n\nFEED ANALYSIS:\n{feed_str}\n\nCONNECTION SUGGESTIONS:\n{suggestions_str}",
+            temperature=0.4,
+        )
+        result = _safe_json(raw, {})
+        return result if isinstance(result, dict) else {}
+    except Exception as e:
+        logger.error(f"Engagement plan failed: {e}")
+        return {}
+
+
+# ── comment drafting ──────────────────────────────────────────────────────────
+
+COMMENT_SYSTEM = f"""You are a LinkedIn expert ghostwriter. Today is {TODAY}.
+
+Draft a genuine, high-value LinkedIn comment. Rules:
+- 2-4 sentences maximum
+- Add real value: insight, experience, a question, or a respectful different angle
+- NEVER sycophantic openers ("Great post!", "Love this!", "So true!")
+- Sound human — conversational but professional
+- Match the angle: contrarian=respectful pushback, supportive=add data/example, ask_question=genuine curiosity
+- End with a question only if it flows naturally
+- No hashtags in comments
+- Do not start with "I"
+
+Return ONLY the comment text, nothing else."""
+
+
+def draft_comment(post: dict, user_context: dict) -> str:
+    post_text = (
+        f"Post by {post.get('author','')} ({post.get('role','')}):\n"
+        f"{post.get('content_summary', post.get('content', ''))}\n"
+        f"Angle to take: {post.get('suggested_angle', 'add_value')}"
+    )
+    user_str = (
+        f"Commenter: {user_context.get('name')} | {user_context.get('role')} | "
+        f"Industry: {user_context.get('industry')}"
+    )
+    try:
+        return _chat(COMMENT_SYSTEM, f"{user_str}\n\nPOST:\n{post_text}", temperature=0.7)
+    except Exception as e:
+        logger.error(f"Comment draft failed: {e}")
+        return "Interesting perspective. What's been the biggest challenge in applying this at scale?"
+
+
+# ── connection message drafting ───────────────────────────────────────────────
+
+CONNECTION_SYSTEM = f"""You are a LinkedIn networking expert. Today is {TODAY}.
+
+Draft a LinkedIn connection request note. Hard rules:
+- 300 characters MAXIMUM (LinkedIn limit)
+- Personalised — mention something specific about them
+- Clear why you want to connect (shared interest, mutual goal, their work)
+- No generic lines ("I'd like to add you to my network")
+- Warm but not creepy — professional peer tone
+- No emojis
+- First person, direct
+
+Return ONLY the message text."""
+
+
+def draft_connection_message(person: dict, user_context: dict) -> str:
+    person_str = (
+        f"Connect with: {person.get('name')} | {person.get('role','')} @ {person.get('company','')}\n"
+        f"About them: {person.get('about', person.get('snippet', ''))[:300]}\n"
+        f"Why connecting: {person.get('why_connect', 'shared professional interest')}"
+    )
+    user_str = (
+        f"Sender: {user_context.get('name')} | {user_context.get('role')} | "
+        f"Topics: {user_context.get('topics')}"
+    )
+    try:
+        msg = _chat(CONNECTION_SYSTEM, f"{user_str}\n\n{person_str}", temperature=0.65)
+        # Enforce 300 char limit
+        if len(msg) > 300:
+            msg = msg[:297] + "..."
+        return msg
+    except Exception as e:
+        logger.error(f"Connection message draft failed: {e}")
+        return f"Hi {person.get('name','')}, your work in {person.get('role','')} aligns with what I'm exploring. Would love to connect and exchange perspectives."[:300]
+
+
+# ── post drafting ─────────────────────────────────────────────────────────────
+
+POST_TEMPLATES = {
+    "thought_leadership": """Write a thought leadership LinkedIn post. Structure:
+- Hook: Bold first line that stops the scroll (no question hooks, make a statement or share a number)
+- Body: 3-5 short paragraphs or lines. Share a specific insight, observation, or lesson.
+- CTA: End with a question or invitation to share perspective
+- Use line breaks generously — short paragraphs (1-2 lines each)
+- NO corporate jargon, NO hashtags in the body
+- Aim for 150-250 words""",
+
+    "how_to": """Write a practical how-to LinkedIn post. Structure:
+- Hook: "How to [do X] without [common mistake]" or similar
+- 5-7 numbered actionable steps
+- Each step: 1-2 lines, specific and concrete
+- Closing line: insight or invitation to comment
+- 150-200 words""",
+
+    "story": """Write a personal story LinkedIn post. Structure:
+- Hook: Start in the middle of the action ("I was about to quit...")
+- Setup: Brief context (2-3 lines)
+- Conflict: What went wrong or what you struggled with
+- Resolution: What you learned or did
+- Lesson: 1-2 sentence takeaway
+- 200-280 words. First person. Vulnerable but professional.""",
+
+    "list": """Write a listicle LinkedIn post. Structure:
+- Hook: "X things I wish I knew about [topic]" or similar
+- 5-8 items, each 1-2 lines
+- Items should be specific, non-obvious insights — not generic advice
+- End with a question
+- 150-220 words""",
+
+    "hot_take": """Write a contrarian/hot take LinkedIn post. Structure:
+- Bold opening statement that challenges conventional wisdom
+- 2-3 short paragraphs explaining your reasoning with evidence
+- Acknowledge the counterargument briefly
+- Restate your position with nuance
+- End with a question inviting debate
+- 150-200 words. Confident but not arrogant.""",
+
+    "celebration": """Write a celebration/milestone LinkedIn post. Structure:
+- Share the achievement directly (no false humility)
+- Brief story of the journey
+- Credit people who helped
+- Lesson or insight from the experience
+- Forward-looking closing
+- 150-200 words. Genuine, warm, not braggy.""",
+}
+
+POST_SYSTEM_BASE = f"""You are an expert LinkedIn ghostwriter. Today is {TODAY}.
+
+You write posts that get 1000+ likes — not because they're viral bait,
+but because they're genuinely insightful and human.
+
+Writing rules:
+- Never start with "I" as the first word
+- Short paragraphs (1-3 lines each) with line breaks between them
+- Specific over generic (use numbers, names, timeframes)
+- Conversational but substantive
+- No emojis in the main content
+- Hashtags: 3-5 relevant ones at the very end only
+
+After the post, on a new line write:
+HOOK_SCORE: X/10
+HASHTAGS: #tag1 #tag2 #tag3
+BEST_TIME: Morning (7-9am) | Lunch (12-1pm) | Evening (6-8pm)"""
+
+
+def draft_post(
+    user_context: dict,
+    trending_topics: list[str],
+    post_type: str = "thought_leadership",
+) -> dict:
+    template = POST_TEMPLATES.get(post_type, POST_TEMPLATES["thought_leadership"])
+    topics_str = ", ".join(trending_topics[:3]) if trending_topics else user_context.get("topics", "")
+
+    user_str = (
+        f"Author: {user_context.get('name')} | {user_context.get('role')} | "
+        f"Industry: {user_context.get('industry')}\n"
+        f"Writing tone: {user_context.get('tone', 'professional yet conversational')}\n"
+        f"Goal: {user_context.get('goal', 'build thought leadership')}\n"
+        f"Trending topics to consider: {topics_str}"
+    )
+
+    system = POST_SYSTEM_BASE + "\n\n" + template
+
+    try:
+        raw = _chat(system, user_str, temperature=0.75, max_tokens=800)
+
+        # Parse structured output
+        content = raw
+        hook_score = 7
+        hashtags   = []
+        best_time  = "Morning"
+
+        if "HOOK_SCORE:" in raw:
+            parts    = raw.split("HOOK_SCORE:")
+            content  = parts[0].strip()
+            metadata = parts[1] if len(parts) > 1 else ""
+
+            score_match = re.search(r"(\d+)/10", metadata)
+            if score_match:
+                hook_score = int(score_match.group(1))
+
+            hash_match = re.search(r"HASHTAGS:(.*?)(?:BEST_TIME:|$)", metadata, re.DOTALL)
+            if hash_match:
+                hashtags = re.findall(r"#\w+", hash_match.group(1))
+
+            time_match = re.search(r"BEST_TIME:(.*?)$", metadata, re.DOTALL)
+            if time_match:
+                best_time = time_match.group(1).strip()
+
+        return {
+            "content":    content,
+            "post_type":  post_type,
+            "hook_score": hook_score,
+            "hashtags":   hashtags[:5],
+            "best_time":  best_time,
+            "word_count": len(content.split()),
+            "char_count": len(content),
+        }
+    except Exception as e:
+        logger.error(f"Post draft failed: {e}")
+        return {"content": "", "post_type": post_type, "hook_score": 0, "hashtags": []}
+
+
+# ── post scoring ──────────────────────────────────────────────────────────────
+
+SCORE_SYSTEM = """You are a LinkedIn content expert. Score this post idea on:
+- Hook strength (1-10): Does the first line stop the scroll?
+- Value delivery (1-10): Is there real insight or is it generic?
+- Authenticity (1-10): Does it sound human, not corporate?
+- Engagement potential (1-10): Will people comment?
+
+Return JSON only:
+{"hook": 7, "value": 8, "authenticity": 9, "engagement": 7, "overall": 7.8,
+ "top_strength": "...", "top_weakness": "...", "quick_fix": "..."}"""
+
+
+def score_post_idea(post_content: str) -> dict:
+    try:
+        raw = _chat(SCORE_SYSTEM, f"POST:\n{post_content}", temperature=0.2)
+        result = _safe_json(raw, {})
+        return result if isinstance(result, dict) else {}
+    except Exception as e:
+        logger.error(f"Post scoring failed: {e}")
+        return {}

linkedin_agent/main_agent.py

@@ -0,0 +1,279 @@
+"""
+LinkedIn Agent — Personal AI OS
+=================================
+Monitors your LinkedIn feed, drafts connection messages,
+suggests engagement targets, helps build professional presence.
+
+Triggers:
+  - Daily 9:30 AM feed scan + engagement suggestions
+  - On-demand: draft connection request, comment, post
+  - CLI: python main_agent.py --feed | --draft-post | --connect "Name"
+"""
+
+import os
+import time
+import logging
+import argparse
+import schedule
+from datetime import datetime
+import os as _os
+from dotenv import load_dotenv
+
+from data_fetcher import (
+    fetch_linkedin_feed,
+    fetch_profile_info,
+    fetch_connection_suggestions,
+    fetch_my_profile,
+)
+from llm import (
+    analyze_feed,
+    draft_connection_message,
+    draft_comment,
+    draft_post,
+    generate_engagement_plan,
+    score_post_idea,
+)
+from linkedin_store import LinkedInStore
+from delivery import (
+    send_digest_email,
+    send_whatsapp_alert,
+    save_to_notion,
+    save_drafts_to_markdown,
+)
+
+load_dotenv(_os.path.join(_os.path.dirname(_os.path.abspath(__file__)), "..", ".env"))
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(name)s — %(message)s",
+    handlers=[
+        logging.FileHandler("linkedin_agent.log"),
+        logging.StreamHandler(),
+    ],
+)
+logger = logging.getLogger("LinkedInAgent")
+
+# ── config ────────────────────────────────────────────────────────────────────
+DELIVER_EMAIL    = os.getenv("DELIVER_LINKEDIN_EMAIL", "true").lower() == "true"
+DELIVER_WHATSAPP = os.getenv("DELIVER_LINKEDIN_WHATSAPP", "false").lower() == "true"
+SAVE_NOTION      = os.getenv("SAVE_LINKEDIN_NOTION", "true").lower() == "true"
+SAVE_MARKDOWN    = os.getenv("SAVE_LINKEDIN_MARKDOWN", "true").lower() == "true"
+USER_EMAIL       = os.getenv("USER_EMAIL", "")
+USER_NAME        = os.getenv("LINKEDIN_USER_NAME", "")
+USER_ROLE        = os.getenv("LINKEDIN_USER_ROLE", "")
+USER_INDUSTRY    = os.getenv("LINKEDIN_USER_INDUSTRY", "")
+NICHE_TOPICS     = os.getenv("LINKEDIN_NICHE_TOPICS", "AI, technology, startups")
+
+
+# ── core pipelines ────────────────────────────────────────────────────────────
+
+def run_daily_digest(trigger: str = "daily_930am") -> dict:
+    """
+    Full daily LinkedIn pipeline:
+    feed scan → engagement suggestions → post ideas → delivery
+    """
+    logger.info(f"🔗 LinkedIn Agent pipeline | trigger={trigger}")
+    start = datetime.now()
+    store = LinkedInStore()
+
+    user_context = {
+        "name":     USER_NAME,
+        "role":     USER_ROLE,
+        "industry": USER_INDUSTRY,
+        "topics":   NICHE_TOPICS,
+    }
+
+    # 1. Fetch feed posts
+    logger.info("📰 Fetching LinkedIn feed …")
+    feed_posts = fetch_linkedin_feed()
+    logger.info(f"   Fetched {len(feed_posts)} feed posts")
+
+    # 2. Fetch connection suggestions
+    logger.info("🤝 Fetching connection suggestions …")
+    suggestions = fetch_connection_suggestions()
+    logger.info(f"   Found {len(suggestions)} suggestions")
+
+    # 3. Analyse feed — find posts worth engaging with
+    logger.info("🤖 Analysing feed via Groq …")
+    feed_analysis = analyze_feed(feed_posts, user_context)
+
+    # 4. Generate engagement plan (who to comment on, what to say)
+    logger.info("📋 Generating engagement plan …")
+    engagement_plan = generate_engagement_plan(
+        feed_analysis=feed_analysis,
+        suggestions=suggestions,
+        user_context=user_context,
+    )
+
+    # 5. Draft comments for top engagement targets
+    drafted_comments = []
+    for target in engagement_plan.get("comment_targets", [])[:3]:
+        comment = draft_comment(
+            post=target,
+            user_context=user_context,
+        )
+        target["drafted_comment"] = comment
+        drafted_comments.append(target)
+        logger.info(f"   Drafted comment for: {target.get('author', '?')}")
+
+    # 6. Draft connection messages for top suggestions
+    drafted_connections = []
+    for person in engagement_plan.get("connect_targets", [])[:3]:
+        msg = draft_connection_message(person=person, user_context=user_context)
+        person["drafted_message"] = msg
+        drafted_connections.append(person)
+        logger.info(f"   Drafted connection message for: {person.get('name', '?')}")
+
+    # 7. Generate a post idea for today
+    logger.info("✍️  Generating post idea …")
+    post_idea = draft_post(
+        user_context=user_context,
+        trending_topics=feed_analysis.get("trending_topics", []),
+        post_type="thought_leadership",
+    )
+
+    # 8. Store
+    store.save_feed_snapshot(feed_posts, engagement_plan)
+    store.save_drafts(drafted_comments, drafted_connections, post_idea)
+
+    elapsed = (datetime.now() - start).seconds
+    report = {
+        "trigger":             trigger,
+        "timestamp":           datetime.now().isoformat(),
+        "feed_posts_scanned":  len(feed_posts),
+        "feed_analysis":       feed_analysis,
+        "engagement_plan":     engagement_plan,
+        "drafted_comments":    drafted_comments,
+        "drafted_connections": drafted_connections,
+        "post_idea":           post_idea,
+        "elapsed_seconds":     elapsed,
+    }
+
+    logger.info(f"✅ LinkedIn digest ready in {elapsed}s")
+    _deliver(report)
+    return report
+
+
+def run_connect(name: str, role: str = "", company: str = "") -> str:
+    """Draft a connection request message for a specific person."""
+    logger.info(f"🤝 Drafting connection message for: {name}")
+    user_context = {
+        "name": USER_NAME, "role": USER_ROLE,
+        "industry": USER_INDUSTRY, "topics": NICHE_TOPICS,
+    }
+    person = {"name": name, "role": role, "company": company}
+    profile_info = fetch_profile_info(name)
+    if profile_info:
+        person.update(profile_info)
+
+    message = draft_connection_message(person=person, user_context=user_context)
+    logger.info("   Message drafted")
+    return message
+
+
+def run_draft_post(post_type: str = "thought_leadership", topic: str = "") -> dict:
+    """Draft a LinkedIn post on demand."""
+    logger.info(f"✍️  Drafting post | type={post_type} topic={topic}")
+    user_context = {
+        "name": USER_NAME, "role": USER_ROLE,
+        "industry": USER_INDUSTRY, "topics": NICHE_TOPICS,
+    }
+    post = draft_post(
+        user_context=user_context,
+        trending_topics=[topic] if topic else [],
+        post_type=post_type,
+    )
+    store = LinkedInStore()
+    store.save_drafts([], [], post)
+    return post
+
+
+def _deliver(report: dict):
+    if SAVE_MARKDOWN:
+        path = save_drafts_to_markdown(report)
+        logger.info(f"📄 Drafts saved to {path}")
+
+    if SAVE_NOTION:
+        url = save_to_notion(report)
+        if url:
+            logger.info(f"📓 Saved to Notion: {url}")
+
+    if DELIVER_EMAIL and USER_EMAIL:
+        send_digest_email(report, recipient=USER_EMAIL)
+        logger.info("📧 Digest email sent")
+
+    if DELIVER_WHATSAPP:
+        send_whatsapp_alert(report)
+        logger.info("📱 WhatsApp alert sent")
+
+
+# ── scheduler ─────────────────────────────────────────────────────────────────
+
+def run_scheduler():
+    schedule.every().day.at("09:30").do(
+        lambda: run_daily_digest(trigger="daily_930am")
+    )
+    logger.info("⏰ Daily digest scheduled at 09:30")
+    while True:
+        schedule.run_pending()
+        time.sleep(30)
+
+
+# ── CLI ───────────────────────────────────────────────────────────────────────
+
+def _parse_args():
+    parser = argparse.ArgumentParser(description="LinkedIn Agent — Personal AI OS")
+    parser.add_argument("--feed",        action="store_true", help="Run full daily digest")
+    parser.add_argument("--connect",     type=str,            help="Draft connection message for NAME")
+    parser.add_argument("--role",        type=str, default="", help="Role of person to connect with")
+    parser.add_argument("--company",     type=str, default="", help="Company of person to connect with")
+    parser.add_argument("--draft-post",  action="store_true", help="Draft a LinkedIn post")
+    parser.add_argument("--topic",       type=str, default="", help="Topic for the post")
+    parser.add_argument(
+        "--post-type",
+        choices=["thought_leadership", "how_to", "story", "list", "hot_take", "celebration"],
+        default="thought_leadership",
+    )
+    parser.add_argument("--daemon",      action="store_true", help="Run with daily scheduler")
+    return parser.parse_args()
+
+
+def main():
+    logger.info("=" * 60)
+    logger.info("  LINKEDIN AGENT  — Personal AI OS")
+    logger.info("=" * 60)
+
+    args = _parse_args()
+
+    if args.feed:
+        report = run_daily_digest(trigger="cli_feed")
+        plan   = report.get("engagement_plan", {})
+        print(f"\n📰 Scanned {report['feed_posts_scanned']} posts")
+        print(f"💬 Comment targets: {len(report['drafted_comments'])}")
+        print(f"🤝 Connect targets: {len(report['drafted_connections'])}")
+        print(f"\n✍️  Post idea:\n{report['post_idea'].get('content','')[:300]}")
+
+    elif args.connect:
+        message = run_connect(args.connect, role=args.role, company=args.company)
+        print(f"\n🤝 Connection message for {args.connect}:\n{'-'*40}\n{message}\n{'-'*40}")
+
+    elif args.draft_post:
+        post = run_draft_post(post_type=args.post_type, topic=args.topic)
+        print(f"\n✍️  Draft post ({args.post_type}):\n{'='*50}")
+        print(post.get("content", ""))
+        print(f"\n📊 Hook score: {post.get('hook_score', '?')}/10")
+        print(f"🏷️  Hashtags: {' '.join(post.get('hashtags', []))}")
+
+    elif args.daemon:
+        run_daily_digest(trigger="startup")
+        run_scheduler()
+
+    else:
+        print("Usage:")
+        print("  python main_agent.py --feed")
+        print("  python main_agent.py --connect 'Priya Sharma' --role 'CTO' --company 'Zepto'")
+        print("  python main_agent.py --draft-post --post-type thought_leadership --topic 'AI agents'")
+        print("  python main_agent.py --daemon")
+
+
+if __name__ == "__main__":
+    main()

linkedin_agent/requirements.txt

@@ -0,0 +1,5 @@
+groq>=0.8.0
+requests>=2.31.0
+schedule>=1.2.1
+python-dotenv>=1.0.1
+twilio>=8.13.0

task_manager_agent/README.md

@@ -0,0 +1,130 @@
+# Task Manager Agent — Personal AI OS
+
+Automatically turns emails and meeting notes into prioritized, synced tasks.
+
+## What it does
+
+| Capability | Detail |
+|---|---|
+| **Email → Tasks** | Scans inbox every 15 min, extracts actionable items via Groq |
+| **Meeting → Tasks** | Parses Google Calendar descriptions for action items and follow-ups |
+| **Prioritization** | LLM scores each task 1–10 using urgency + impact + effort |
+| **Deduplication** | Never creates the same task twice |
+| **Sync** | Pushes to Notion DB and/or Todoist |
+| **Digest** | Sends a formatted email + optional WhatsApp summary |
+| **Triggers** | New email detection (polling) + daily 9 AM scheduled sync |
+
+---
+
+## File structure
+
+```
+task_manager_agent/
+├── main_agent.py       # Orchestrator, scheduler, email watcher
+├── data_fetcher.py     # Gmail + Calendar + existing task fetch
+├── llm.py              # Groq extraction + prioritization prompts
+├── task_store.py       # Local JSON persistence + dedup
+├── delivery.py         # Email SMTP, WhatsApp, Notion, Todoist
+├── .env.example        # All env vars with explanations
+├── requirements.txt
+└── README.md
+```
+
+---
+
+## Setup
+
+### 1. Install dependencies
+```bash
+pip install -r requirements.txt
+```
+
+### 2. Configure environment
+```bash
+cp .env.example .env
+# Edit .env with your credentials
+```
+
+### 3. Google credentials
+Share the same `credentials.json` and `token.json` from your earlier agents.
+The agent needs scopes:
+- `gmail.readonly`
+- `calendar.readonly`
+
+### 4. Notion Database setup
+
+Create a Notion database with these properties:
+
+| Property | Type |
+|---|---|
+| Name | Title |
+| Status | Select: `To Do`, `In Progress`, `Done` |
+| Priority | Select: `Critical`, `High`, `Medium`, `Low` |
+| Due Date | Date |
+| Category | Select: `Work`, `Personal`, `Admin`, `Communication`, `Research`, `Finance`, `Health`, `Other` |
+| Source | Rich Text |
+| Priority Score | Number |
+| Notes | Rich Text |
+
+Copy the DB ID from the Notion URL:
+`https://notion.so/your-workspace/`**`THIS-IS-YOUR-DB-ID`**`?v=...`
+
+### 5. Run
+```bash
+python main_agent.py
+```
+
+On startup the agent runs immediately, then enters the continuous loop:
+- Email watcher polls every `EMAIL_POLL_INTERVAL_MINUTES` minutes
+- Full sync fires daily at **09:00**
+
+---
+
+## How prioritization works
+
+The LLM scores each task using four axes:
+
+```
+Priority Score (1-10) = f(urgency, impact, effort, dependencies)
+```
+
+| Score | Label | Example |
+|---|---|---|
+| 9–10 | Critical | "Contract due tomorrow, client blocked" |
+| 7–8 | High | "Respond to investor by Friday" |
+| 5–6 | Medium | "Update project docs" |
+| 1–4 | Low | "Read that article someone forwarded" |
+
+---
+
+## Cron alternative
+
+To run via system cron instead of the built-in scheduler:
+
+```cron
+# Daily 9 AM sync
+0 9 * * * cd /path/to/task_manager_agent && python -c "from main_agent import run_task_extraction_pipeline; run_task_extraction_pipeline('cron_9am')"
+
+# Email polling every 15 min
+*/15 * * * * cd /path/to/task_manager_agent && python -c "from main_agent import run_task_extraction_pipeline; run_task_extraction_pipeline('email_poll')"
+```
+
+---
+
+## Agent position in Personal AI OS
+
+```
+01 ✅ Daily Planner Agent
+02 ✅ Email Agent
+03 ✅ Meeting Prep Agent
+04 ✅ End-of-Day Review Agent
+05 ✅ Task Manager Agent  ← YOU ARE HERE
+06    Research Agent
+07    Finance Agent
+08    LinkedIn Agent
+09    Knowledge Agent
+10    Master Orchestrator (Mem0 + LangGraph)
+```
+
+The Master Orchestrator will call `run_task_extraction_pipeline()` directly
+and read from `TaskStore` to feed task context into other agents.

task_manager_agent/data_fetcher.py

@@ -0,0 +1,243 @@
+"""
+data_fetcher.py — Task Manager Agent
+=====================================
+Pulls raw data from Gmail, Google Calendar, and existing task stores.
+"""
+
+import os
+import base64
+import logging
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+
+from google.oauth2.credentials import Credentials
+from google.auth.transport.requests import Request
+from google_auth_oauthlib.flow import InstalledAppFlow
+from googleapiclient.discovery import build
+
+logger = logging.getLogger("TaskManagerAgent.DataFetcher")
+
+SCOPES = [
+    "https://www.googleapis.com/auth/gmail.readonly",
+    "https://www.googleapis.com/auth/calendar.readonly",
+]
+
+CREDENTIALS_FILE = os.getenv("GOOGLE_CREDENTIALS_FILE")
+TOKEN_FILE = os.getenv("GOOGLE_TOKEN_FILE")
+
+# Labels that signal actionable emails (expand as needed)
+ACTIONABLE_LABELS = {"INBOX", "IMPORTANT", "STARRED"}
+
+
+# ── Google auth ───────────────────────────────────────────────────────────────
+
+def _get_google_creds() -> Credentials:
+    creds = None
+    if os.path.exists(TOKEN_FILE):
+        creds = Credentials.from_authorized_user_file(TOKEN_FILE, SCOPES)
+    if not creds or not creds.valid:
+        if creds and creds.expired and creds.refresh_token:
+            creds.refresh(Request())
+        else:
+            flow = InstalledAppFlow.from_client_secrets_file(CREDENTIALS_FILE, SCOPES)
+            creds = flow.run_local_server(port=0)
+        with open(TOKEN_FILE, "w") as f:
+            f.write(creds.to_json())
+    return creds
+
+
+def _gmail_service():
+    return build("gmail", "v1", credentials=_get_google_creds())
+
+
+def _calendar_service():
+    return build("calendar", "v3", credentials=_get_google_creds())
+
+
+# ── Gmail ─────────────────────────────────────────────────────────────────────
+
+def fetch_recent_emails(
+    max_results: int = 20,
+    hours_back: int = 24,
+    since_id: Optional[str] = None,
+) -> list[dict]:
+    """
+    Returns list of dicts with keys:
+      id, subject, sender, date, snippet, body (plain text, truncated)
+    """
+    try:
+        service = _gmail_service()
+        after_ts = int((datetime.now(timezone.utc) - timedelta(hours=hours_back)).timestamp())
+        query = f"after:{after_ts} -category:promotions -category:social"
+
+        result = service.users().messages().list(
+            userId="me", q=query, maxResults=max_results
+        ).execute()
+        messages = result.get("messages", [])
+
+        emails = []
+        for msg_ref in messages:
+            if since_id and msg_ref["id"] == since_id:
+                break
+            try:
+                msg = service.users().messages().get(
+                    userId="me", id=msg_ref["id"], format="full"
+                ).execute()
+                emails.append(_parse_email(msg))
+            except Exception as e:
+                logger.warning(f"Could not fetch message {msg_ref['id']}: {e}")
+
+        logger.debug(f"Fetched {len(emails)} emails")
+        return emails
+
+    except Exception as e:
+        logger.error(f"Gmail fetch error: {e}", exc_info=True)
+        return []
+
+
+def _parse_email(msg: dict) -> dict:
+    headers = {h["name"]: h["value"] for h in msg["payload"].get("headers", [])}
+    body = _extract_body(msg["payload"])
+    return {
+        "id": msg["id"],
+        "thread_id": msg.get("threadId", ""),
+        "subject": headers.get("Subject", "(no subject)"),
+        "sender": headers.get("From", ""),
+        "to": headers.get("To", ""),
+        "date": headers.get("Date", ""),
+        "snippet": msg.get("snippet", ""),
+        "body": body[:3000],   # cap at 3k chars
+        "labels": msg.get("labelIds", []),
+    }
+
+
+def _extract_body(payload: dict) -> str:
+    """Recursively extracts plain-text body from MIME payload."""
+    if payload.get("mimeType") == "text/plain":
+        data = payload.get("body", {}).get("data", "")
+        if data:
+            return base64.urlsafe_b64decode(data).decode("utf-8", errors="replace")
+    for part in payload.get("parts", []):
+        text = _extract_body(part)
+        if text:
+            return text
+    return ""
+
+
+# ── Google Calendar ───────────────────────────────────────────────────────────
+
+def fetch_calendar_meetings(
+    days_back: int = 1,
+    days_ahead: int = 0,
+    calendar_id: str = "primary",
+) -> list[dict]:
+    """
+    Returns meetings from [now - days_back, now + days_ahead].
+    Each dict: id, title, start, end, attendees, description, location
+    """
+    try:
+        service = _calendar_service()
+        now = datetime.now(timezone.utc)
+        time_min = (now - timedelta(days=days_back)).isoformat()
+        time_max = (now + timedelta(days=days_ahead + 1)).isoformat()
+
+        events_result = service.events().list(
+            calendarId=calendar_id,
+            timeMin=time_min,
+            timeMax=time_max,
+            maxResults=50,
+            singleEvents=True,
+            orderBy="startTime",
+        ).execute()
+        events = events_result.get("items", [])
+
+        meetings = []
+        for e in events:
+            if e.get("status") == "cancelled":
+                continue
+            meetings.append({
+                "id": e.get("id", ""),
+                "title": e.get("summary", "(untitled)"),
+                "start": e.get("start", {}).get("dateTime", e.get("start", {}).get("date", "")),
+                "end": e.get("end", {}).get("dateTime", e.get("end", {}).get("date", "")),
+                "attendees": [
+                    a.get("email", "") for a in e.get("attendees", [])
+                ],
+                "description": e.get("description", "")[:2000],
+                "location": e.get("location", ""),
+            })
+
+        logger.debug(f"Fetched {len(meetings)} meetings")
+        return meetings
+
+    except Exception as e:
+        logger.error(f"Calendar fetch error: {e}", exc_info=True)
+        return []
+
+
+# ── Existing tasks (local store read) ─────────────────────────────────────────
+
+def fetch_existing_tasks() -> list[dict]:
+    """Loads tasks from local task store + Notion for deduplication context."""
+    tasks = []
+
+    # local
+    local_path = os.getenv("LOCAL_TASKS_FILE", "tasks.json")
+    if os.path.exists(local_path):
+        import json
+        try:
+            with open(local_path) as f:
+                tasks.extend(json.load(f))
+            logger.debug(f"Loaded {len(tasks)} local tasks")
+        except Exception as e:
+            logger.warning(f"Could not load local tasks: {e}")
+
+    return tasks
+
+
+def fetch_notion_tasks() -> list[dict]:
+    """Fetches open tasks from Notion DB."""
+    import requests
+
+    notion_token = os.getenv("NOTION_TOKEN")
+    db_id = os.getenv("NOTION_TASKS_DB_ID")
+    if not notion_token or not db_id:
+        logger.debug("Notion credentials not set — skipping Notion task fetch")
+        return []
+
+    try:
+        headers = {
+            "Authorization": f"Bearer {notion_token}",
+            "Notion-Version": "2022-06-28",
+            "Content-Type": "application/json",
+        }
+        payload = {
+            "filter": {
+                "property": "Status",
+                "select": {"does_not_equal": "Done"},
+            }
+        }
+        resp = requests.post(
+            f"https://api.notion.com/v1/databases/{db_id}/query",
+            headers=headers, json=payload, timeout=10,
+        )
+        resp.raise_for_status()
+        results = resp.json().get("results", [])
+
+        tasks = []
+        for page in results:
+            props = page.get("properties", {})
+            title_prop = props.get("Name", {}).get("title", [])
+            title = title_prop[0]["plain_text"] if title_prop else "(no title)"
+            tasks.append({
+                "id": page["id"],
+                "title": title,
+                "source": "notion",
+                "url": page.get("url", ""),
+            })
+        logger.debug(f"Fetched {len(tasks)} tasks from Notion")
+        return tasks
+
+    except Exception as e:
+        logger.error(f"Notion fetch error: {e}", exc_info=True)
+        return []

task_manager_agent/delivery.py

@@ -0,0 +1,362 @@
+"""
+delivery.py — Task Manager Agent
+=================================
+Handles all delivery methods for task digests:
+  - Email (Gmail SMTP)
+  - WhatsApp (Twilio)
+  - Notion sync
+  - Todoist sync
+"""
+
+import os
+import json
+import logging
+import smtplib
+from email.mime.text import MIMEText
+from email.mime.multipart import MIMEMultipart
+from datetime import datetime
+from typing import Optional
+
+from dotenv import load_dotenv
+load_dotenv()
+
+logger = logging.getLogger("TaskManagerAgent.Delivery")
+
+# ── Config ────────────────────────────────────────────────────────────────────
+GMAIL_ADDRESS       = os.getenv("GMAIL_ADDRESS", "")
+GMAIL_APP_PASSWORD  = os.getenv("GMAIL_APP_PASSWORD", "")
+TWILIO_SID          = os.getenv("TWILIO_ACCOUNT_SID", "")
+TWILIO_TOKEN        = os.getenv("TWILIO_AUTH_TOKEN", "")
+TWILIO_FROM         = os.getenv("TWILIO_WHATSAPP_FROM", "")
+WHATSAPP_TO         = os.getenv("WHATSAPP_TO_NUMBER", "")
+NOTION_API_KEY      = os.getenv("NOTION_API_KEY", "")
+NOTION_DATABASE_ID  = os.getenv("NOTION_DATABASE_ID", "")
+TODOIST_API_KEY     = os.getenv("TODOIST_API_KEY", "")
+
+
+# ── Formatters ────────────────────────────────────────────────────────────────
+
+def _format_task_digest_text(tasks: list[dict], trigger: str = "scheduled") -> str:
+    """Format tasks into a plain-text digest."""
+    now   = datetime.now().strftime("%A, %d %b %Y %H:%M")
+    lines = [
+        f"TASK DIGEST — {now}",
+        f"Trigger: {trigger}",
+        f"Total new tasks: {len(tasks)}",
+        "=" * 50,
+    ]
+    for i, task in enumerate(tasks, 1):
+        title    = task.get("title", "Untitled")
+        priority = task.get("priority", "medium")
+        deadline = task.get("deadline", "No deadline")
+        category = task.get("category", "general")
+        source   = task.get("source", "unknown")
+        lines.append(
+            f"\n{i}. [{priority.upper()}] {title}\n"
+            f"   Category : {category}\n"
+            f"   Deadline : {deadline}\n"
+            f"   Source   : {source}"
+        )
+    lines.append("\n" + "=" * 50)
+    return "\n".join(lines)
+
+
+def _format_task_digest_html(tasks: list[dict], trigger: str = "scheduled") -> str:
+    """Format tasks into an HTML email digest."""
+    now = datetime.now().strftime("%A, %d %b %Y %H:%M")
+
+    priority_colors = {
+        "high":   "#ef4444",
+        "medium": "#f59e0b",
+        "low":    "#22c55e",
+    }
+
+    rows = ""
+    for i, task in enumerate(tasks, 1):
+        title    = task.get("title", "Untitled")
+        priority = task.get("priority", "medium").lower()
+        deadline = task.get("deadline", "No deadline")
+        category = task.get("category", "general")
+        source   = task.get("source", "unknown")
+        color    = priority_colors.get(priority, "#f59e0b")
+        rows += f"""
+        <tr>
+            <td style="padding:10px;border-bottom:1px solid #1e2840;color:#c8d6f0">{i}</td>
+            <td style="padding:10px;border-bottom:1px solid #1e2840;color:#e8f0ff;font-weight:600">{title}</td>
+            <td style="padding:10px;border-bottom:1px solid #1e2840">
+                <span style="background:{color}22;color:{color};padding:2px 8px;border-radius:12px;font-size:12px;border:1px solid {color}44">
+                    {priority.upper()}
+                </span>
+            </td>
+            <td style="padding:10px;border-bottom:1px solid #1e2840;color:#8aaccc">{deadline}</td>
+            <td style="padding:10px;border-bottom:1px solid #1e2840;color:#6b8ab0">{category}</td>
+            <td style="padding:10px;border-bottom:1px solid #1e2840;color:#4a6a90">{source}</td>
+        </tr>"""
+
+    return f"""
+    <html><body style="background:#0a0e1a;color:#c8d6f0;font-family:sans-serif;padding:24px">
+        <h2 style="color:#e8f0ff">📋 Task Digest</h2>
+        <p style="color:#6b8ab0">{now} &nbsp;·&nbsp; Trigger: {trigger} &nbsp;·&nbsp; {len(tasks)} new tasks</p>
+        <table style="width:100%;border-collapse:collapse;background:#0d1220;border-radius:10px;overflow:hidden">
+            <thead>
+                <tr style="background:#111827">
+                    <th style="padding:10px;text-align:left;color:#4a6a90;font-size:12px">#</th>
+                    <th style="padding:10px;text-align:left;color:#4a6a90;font-size:12px">TASK</th>
+                    <th style="padding:10px;text-align:left;color:#4a6a90;font-size:12px">PRIORITY</th>
+                    <th style="padding:10px;text-align:left;color:#4a6a90;font-size:12px">DEADLINE</th>
+                    <th style="padding:10px;text-align:left;color:#4a6a90;font-size:12px">CATEGORY</th>
+                    <th style="padding:10px;text-align:left;color:#4a6a90;font-size:12px">SOURCE</th>
+                </tr>
+            </thead>
+            <tbody>{rows}</tbody>
+        </table>
+        <p style="color:#3a5070;font-size:12px;margin-top:16px">Personal AI OS — Task Manager Agent</p>
+    </body></html>"""
+
+
+# ── Email delivery ────────────────────────────────────────────────────────────
+
+def send_task_digest_email(
+    tasks: list[dict],
+    trigger: str = "scheduled",
+    recipient: str = "",
+) -> bool:
+    """
+    Send task digest via Gmail SMTP.
+
+    Args:
+        tasks:     List of task dicts.
+        trigger:   What triggered this run (for subject line).
+        recipient: Email address to send to.
+
+    Returns:
+        True if sent successfully, False otherwise.
+    """
+    if not GMAIL_ADDRESS or not GMAIL_APP_PASSWORD:
+        logger.warning("Email delivery skipped — GMAIL_ADDRESS or GMAIL_APP_PASSWORD not set")
+        return False
+
+    to_addr = recipient or GMAIL_ADDRESS
+
+    try:
+        msg                  = MIMEMultipart("alternative")
+        msg["Subject"]       = f"📋 Task Digest — {len(tasks)} new tasks ({trigger})"
+        msg["From"]          = GMAIL_ADDRESS
+        msg["To"]            = to_addr
+
+        text_part = MIMEText(_format_task_digest_text(tasks, trigger), "plain")
+        html_part = MIMEText(_format_task_digest_html(tasks, trigger), "html")
+        msg.attach(text_part)
+        msg.attach(html_part)
+
+        with smtplib.SMTP_SSL("smtp.gmail.com", 465) as server:
+            server.login(GMAIL_ADDRESS, GMAIL_APP_PASSWORD)
+            server.sendmail(GMAIL_ADDRESS, to_addr, msg.as_string())
+
+        logger.info(f"✓ Task digest email sent to {to_addr}")
+        return True
+
+    except Exception as e:
+        logger.error(f"✗ Email delivery failed: {e}")
+        return False
+
+
+# ── WhatsApp delivery ─────────────────────────────────────────────────────────
+
+def send_task_digest_whatsapp(
+    tasks: list[dict],
+    trigger: str = "scheduled",
+) -> bool:
+    """
+    Send task digest via Twilio WhatsApp.
+
+    Returns:
+        True if sent successfully, False otherwise.
+    """
+    if not TWILIO_SID or not TWILIO_TOKEN or not TWILIO_FROM or not WHATSAPP_TO:
+        logger.warning("WhatsApp delivery skipped — Twilio credentials not set")
+        return False
+
+    try:
+        from twilio.rest import Client
+        client = Client(TWILIO_SID, TWILIO_TOKEN)
+
+        # Build compact WhatsApp message
+        now   = datetime.now().strftime("%d %b %H:%M")
+        lines = [f"📋 *Task Digest* — {now}", f"_{trigger} · {len(tasks)} new tasks_\n"]
+
+        for i, task in enumerate(tasks[:10], 1):   # cap at 10 for WhatsApp
+            pri   = task.get("priority", "medium").upper()
+            title = task.get("title", "Untitled")
+            dl    = task.get("deadline", "")
+            dl_str = f" · {dl}" if dl and dl != "No deadline" else ""
+            lines.append(f"{i}. [{pri}] {title}{dl_str}")
+
+        if len(tasks) > 10:
+            lines.append(f"\n_...and {len(tasks) - 10} more tasks_")
+
+        message = "\n".join(lines)
+
+        client.messages.create(
+            from_=f"whatsapp:{TWILIO_FROM}",
+            to=f"whatsapp:{WHATSAPP_TO}",
+            body=message,
+        )
+
+        logger.info(f"✓ Task digest WhatsApp sent to {WHATSAPP_TO}")
+        return True
+
+    except Exception as e:
+        logger.error(f"✗ WhatsApp delivery failed: {e}")
+        return False
+
+
+# ── Notion sync ───────────────────────────────────────────────────────────────
+
+def sync_to_notion(tasks: list[dict]) -> int:
+    """
+    Sync tasks to a Notion database.
+
+    Each task becomes a Notion page with:
+      - Title, Priority, Deadline, Category, Source, Status properties.
+
+    Returns:
+        Number of tasks successfully synced.
+    """
+    if not NOTION_API_KEY or not NOTION_DATABASE_ID:
+        logger.warning("Notion sync skipped — NOTION_API_KEY or NOTION_DATABASE_ID not set")
+        return 0
+
+    try:
+        import requests
+
+        headers = {
+            "Authorization":  f"Bearer {NOTION_API_KEY}",
+            "Content-Type":   "application/json",
+            "Notion-Version": "2022-06-28",
+        }
+
+        synced = 0
+        for task in tasks:
+            title    = task.get("title", "Untitled Task")
+            priority = task.get("priority", "medium").capitalize()
+            deadline = task.get("deadline", "")
+            category = task.get("category", "General")
+            source   = task.get("source", "AI OS")
+
+            properties = {
+                "Name": {
+                    "title": [{"text": {"content": title}}]
+                },
+                "Priority": {
+                    "select": {"name": priority}
+                },
+                "Category": {
+                    "select": {"name": category}
+                },
+                "Source": {
+                    "rich_text": [{"text": {"content": source}}]
+                },
+                "Status": {
+                    "select": {"name": "To Do"}
+                },
+            }
+
+            # Only add deadline if it's a valid date string
+            if deadline and deadline not in ("No deadline", "none", ""):
+                try:
+                    # Try to parse common date formats
+                    for fmt in ("%Y-%m-%d", "%d %b %Y", "%B %d, %Y"):
+                        try:
+                            parsed = datetime.strptime(deadline, fmt)
+                            properties["Deadline"] = {
+                                "date": {"start": parsed.strftime("%Y-%m-%d")}
+                            }
+                            break
+                        except ValueError:
+                            continue
+                except Exception:
+                    pass
+
+            payload = {
+                "parent":     {"database_id": NOTION_DATABASE_ID},
+                "properties": properties,
+            }
+
+            response = requests.post(
+                "https://api.notion.com/v1/pages",
+                headers=headers,
+                json=payload,
+                timeout=10,
+            )
+
+            if response.status_code in (200, 201):
+                synced += 1
+                logger.debug(f"  ✓ Notion: {title}")
+            else:
+                logger.warning(f"  ✗ Notion failed for '{title}': {response.text[:200]}")
+
+        logger.info(f"✓ Synced {synced}/{len(tasks)} tasks to Notion")
+        return synced
+
+    except Exception as e:
+        logger.error(f"✗ Notion sync failed: {e}")
+        return 0
+
+
+# ── Todoist sync ──────────────────────────────────────────────────────────────
+
+def sync_to_todoist(tasks: list[dict]) -> int:
+    """
+    Sync tasks to Todoist via REST API v2.
+
+    Returns:
+        Number of tasks successfully synced.
+    """
+    if not TODOIST_API_KEY:
+        logger.warning("Todoist sync skipped — TODOIST_API_KEY not set")
+        return 0
+
+    try:
+        import requests
+
+        headers = {
+            "Authorization": f"Bearer {TODOIST_API_KEY}",
+            "Content-Type":  "application/json",
+        }
+
+        priority_map = {"high": 4, "medium": 3, "low": 2}
+        synced = 0
+
+        for task in tasks:
+            title    = task.get("title", "Untitled Task")
+            priority = priority_map.get(task.get("priority", "medium").lower(), 3)
+            deadline = task.get("deadline", "")
+
+            payload: dict = {
+                "content":  title,
+                "priority": priority,
+            }
+
+            if deadline and deadline not in ("No deadline", "none", ""):
+                payload["due_string"] = deadline
+
+            response = requests.post(
+                "https://api.todoist.com/rest/v2/tasks",
+                headers=headers,
+                json=payload,
+                timeout=10,
+            )
+
+            if response.status_code in (200, 204):
+                synced += 1
+                logger.debug(f"  ✓ Todoist: {title}")
+            else:
+                logger.warning(f"  ✗ Todoist failed for '{title}': {response.text[:200]}")
+
+        logger.info(f"✓ Synced {synced}/{len(tasks)} tasks to Todoist")
+        return synced
+
+    except Exception as e:
+        logger.error(f"✗ Todoist sync failed: {e}")
+        return 0

task_manager_agent/llm.py

@@ -0,0 +1,303 @@
+"""
+llm.py — Task Manager Agent
+=============================
+All Groq (llama-3.3-70b-versatile) calls:
+  - extract tasks from emails
+  - extract tasks from meeting notes
+  - prioritize + enrich tasks
+"""
+
+import os
+import json
+import logging
+import re
+from datetime import datetime
+from typing import Any
+
+from groq import Groq
+from dotenv import load_dotenv
+load_dotenv()
+
+logger = logging.getLogger("TaskManagerAgent.LLM")
+
+client = Groq(api_key=os.getenv("GROQ_API_KEY"))
+MODEL = os.getenv("GROQ_MODEL", "llama-3.3-70b-versatile")
+TODAY = datetime.now().strftime("%A, %B %d, %Y")
+
+
+# ── helpers ───────────────────────────────────────────────────────────────────
+
+def _chat(system: str, user: str, temperature: float = 0.3) -> str:
+    resp = client.chat.completions.create(
+        model=MODEL,
+        temperature=temperature,
+        messages=[
+            {"role": "system", "content": system},
+            {"role": "user",   "content": user},
+        ],
+    )
+    return resp.choices[0].message.content.strip()
+
+
+def _safe_json(text: str) -> Any:
+    """Extract and parse first JSON block from LLM output."""
+    # Strip markdown fences
+    text = re.sub(r"```(?:json)?", "", text).strip().rstrip("`")
+    # Find outermost array or object
+    for start_char, end_char in [("[", "]"), ("{", "}")]:
+        start = text.find(start_char)
+        end = text.rfind(end_char)
+        if start != -1 and end != -1:
+            try:
+                return json.loads(text[start : end + 1])
+            except json.JSONDecodeError:
+                pass
+    logger.warning("Could not parse JSON from LLM response")
+    return []
+
+
+# ── email task extraction ─────────────────────────────────────────────────────
+
+EXTRACT_EMAIL_SYSTEM = f"""You are an expert executive assistant AI.
+Today is {TODAY}.
+
+Your job is to read emails and extract ACTIONABLE tasks — things the user must DO.
+Focus on:
+- Direct requests or assignments ("Please send me…", "Can you prepare…", "I need you to…")
+- Commitments the user made ("I'll get back to you", "Will share by Friday")
+- Deadlines or follow-ups buried in email threads
+- Approvals, decisions, or reviews required
+
+Return ONLY a JSON array of task objects. Each task object must have:
+{{
+  "title":       "short imperative action (verb + object)",
+  "description": "1-2 sentence context from the email",
+  "source":      "email",
+  "source_ref":  "<email subject>",
+  "sender":      "<from address>",
+  "deadline":    "YYYY-MM-DD or null",
+  "deadline_confidence": "high|medium|low",
+  "estimated_minutes": <number or null>,
+  "tags":        ["tag1", "tag2"],
+  "priority_raw": "urgent|high|medium|low"
+}}
+
+Return [] if no actionable tasks are found.
+Do NOT include tasks that are just FYI, news, or promotions.
+Do NOT duplicate tasks already in the existing list."""
+
+
+def extract_tasks_from_emails(
+    emails: list[dict],
+    existing_tasks: list[dict],
+) -> list[dict]:
+    if not emails:
+        return []
+
+    existing_titles = [t.get("title", "") for t in existing_tasks]
+    existing_context = "\n".join(f"- {t}" for t in existing_titles[:30]) if existing_titles else "None"
+
+    email_blocks = []
+    for i, e in enumerate(emails, 1):
+        email_blocks.append(
+            f"=== EMAIL {i} ===\n"
+            f"From: {e['sender']}\n"
+            f"Subject: {e['subject']}\n"
+            f"Date: {e['date']}\n"
+            f"Body:\n{e['body']}\n"
+        )
+
+    user_prompt = (
+        f"EXISTING TASKS (do not duplicate):\n{existing_context}\n\n"
+        f"EMAILS TO ANALYSE:\n{''.join(email_blocks)}"
+    )
+
+    try:
+        raw = _chat(EXTRACT_EMAIL_SYSTEM, user_prompt)
+        tasks = _safe_json(raw)
+        if not isinstance(tasks, list):
+            tasks = []
+        logger.info(f"Email extraction: {len(tasks)} tasks found")
+        return tasks
+    except Exception as e:
+        logger.error(f"Email task extraction failed: {e}", exc_info=True)
+        return []
+
+
+# ── meeting task extraction ───────────────────────────────────────────────────
+
+EXTRACT_MEETING_SYSTEM = f"""You are an expert executive assistant AI.
+Today is {TODAY}.
+
+Your job is to extract ACTIONABLE tasks from meeting descriptions and calendar events.
+Look for:
+- Action items mentioned in descriptions ("Action: …", "TODO:", "Next steps:")
+- Implied follow-ups (prep materials, send recap, schedule next meeting)
+- Deadlines or deliverables tied to the meeting
+
+Return ONLY a JSON array of task objects. Each must have:
+{{
+  "title":       "short imperative action",
+  "description": "context from the meeting",
+  "source":      "meeting",
+  "source_ref":  "<meeting title>",
+  "sender":      null,
+  "deadline":    "YYYY-MM-DD or null",
+  "deadline_confidence": "high|medium|low",
+  "estimated_minutes": <number or null>,
+  "tags":        ["tag1", "tag2"],
+  "priority_raw": "urgent|high|medium|low"
+}}
+
+Return [] if nothing actionable found.
+Do NOT duplicate tasks already in the existing list."""
+
+
+def extract_tasks_from_meeting_notes(
+    meetings: list[dict],
+    existing_tasks: list[dict],
+) -> list[dict]:
+    if not meetings:
+        return []
+
+    existing_titles = [t.get("title", "") for t in existing_tasks]
+    existing_context = "\n".join(f"- {t}" for t in existing_titles[:30]) if existing_titles else "None"
+
+    meeting_blocks = []
+    for i, m in enumerate(meetings, 1):
+        attendees = ", ".join(m.get("attendees", [])[:5]) or "N/A"
+        meeting_blocks.append(
+            f"=== MEETING {i} ===\n"
+            f"Title: {m['title']}\n"
+            f"When: {m['start']} → {m['end']}\n"
+            f"Attendees: {attendees}\n"
+            f"Description:\n{m.get('description', '(none)')}\n"
+        )
+
+    user_prompt = (
+        f"EXISTING TASKS (do not duplicate):\n{existing_context}\n\n"
+        f"MEETINGS TO ANALYSE:\n{''.join(meeting_blocks)}"
+    )
+
+    try:
+        raw = _chat(EXTRACT_MEETING_SYSTEM, user_prompt)
+        tasks = _safe_json(raw)
+        if not isinstance(tasks, list):
+            tasks = []
+        logger.info(f"Meeting extraction: {len(tasks)} tasks found")
+        return tasks
+    except Exception as e:
+        logger.error(f"Meeting task extraction failed: {e}", exc_info=True)
+        return []
+
+
+# ── prioritization ────────────────────────────────────────────────────────────
+
+PRIORITIZE_SYSTEM = f"""You are a world-class productivity coach and AI assistant.
+Today is {TODAY}.
+
+You will receive a list of raw tasks. Your job is to:
+1. Score each task's PRIORITY on a 1-10 scale using these criteria:
+   - Urgency (deadline proximity)
+   - Impact (business / personal significance)
+   - Effort required (lower effort = slightly higher priority, all else equal)
+   - Dependencies (if others are blocked, bump up)
+
+2. Assign a CATEGORY from: [work, personal, admin, communication, research, finance, health, other]
+
+3. Suggest a DUE DATE if none exists (or confirm/adjust if one does).
+
+4. Write a SHORT "why_urgent" note (1 sentence) for tasks scored 7+.
+
+Return ONLY a JSON array. Each object must include ALL original fields PLUS:
+{{
+  ...original fields...,
+  "priority_score": <1-10>,
+  "priority_label": "critical|high|medium|low",
+  "category": "<category>",
+  "suggested_due_date": "YYYY-MM-DD or null",
+  "why_urgent": "one sentence or null",
+  "order": <integer starting from 1, lowest = highest priority>
+}}
+
+Sort the array by priority_score descending (order 1 = most important)."""
+
+
+def prioritize_tasks(
+    new_tasks: list[dict],
+    all_context_tasks: list[dict],
+) -> list[dict]:
+    if not new_tasks:
+        return []
+
+    # Give the LLM context about the full task landscape
+    context_summary = []
+    for t in all_context_tasks[:20]:
+        context_summary.append(
+            f"- [{t.get('priority_raw', '?')}] {t.get('title', '?')} "
+            f"(deadline: {t.get('deadline', 'none')})"
+        )
+    context_str = "\n".join(context_summary) if context_summary else "No existing tasks"
+
+    user_prompt = (
+        f"FULL TASK CONTEXT (existing + new):\n{context_str}\n\n"
+        f"TASKS TO PRIORITIZE:\n{json.dumps(new_tasks, indent=2)}"
+    )
+
+    try:
+        raw = _chat(PRIORITIZE_SYSTEM, user_prompt, temperature=0.2)
+        tasks = _safe_json(raw)
+        if not isinstance(tasks, list) or not tasks:
+            # Fallback: return original tasks with default priority
+            logger.warning("Prioritization returned empty — using defaults")
+            return _apply_default_priority(new_tasks)
+        logger.info(f"Prioritized {len(tasks)} tasks")
+        return tasks
+    except Exception as e:
+        logger.error(f"Prioritization failed: {e}", exc_info=True)
+        return _apply_default_priority(new_tasks)
+
+
+def _apply_default_priority(tasks: list[dict]) -> list[dict]:
+    priority_map = {"urgent": 9, "high": 7, "medium": 5, "low": 3}
+    for i, t in enumerate(tasks):
+        score = priority_map.get(t.get("priority_raw", "medium"), 5)
+        t["priority_score"] = score
+        t["priority_label"] = t.get("priority_raw", "medium")
+        t["category"] = "work"
+        t["suggested_due_date"] = t.get("deadline")
+        t["why_urgent"] = None
+        t["order"] = i + 1
+    return sorted(tasks, key=lambda x: x["priority_score"], reverse=True)
+
+
+# ── daily digest summary ──────────────────────────────────────────────────────
+
+DIGEST_SYSTEM = f"""You are a sharp, concise executive assistant.
+Today is {TODAY}.
+
+Write a crisp task digest. Structure:
+1. One-line headline ("You have N high-priority tasks today")
+2. Top 3 critical tasks with a one-line action each
+3. Quick summary of remaining tasks grouped by category
+4. One motivational closing line
+
+Keep the total under 250 words. Use bullet points sparingly — prefer clean paragraphs.
+Do NOT use emoji."""
+
+
+def generate_digest_summary(tasks: list[dict]) -> str:
+    if not tasks:
+        return "No new tasks extracted today. Your slate is clean."
+    try:
+        task_list = json.dumps(
+            [{"title": t.get("title"), "priority_score": t.get("priority_score"),
+              "deadline": t.get("deadline") or t.get("suggested_due_date"),
+              "category": t.get("category"), "why_urgent": t.get("why_urgent")}
+             for t in tasks[:15]],
+            indent=2
+        )
+        return _chat(DIGEST_SYSTEM, f"TASKS:\n{task_list}", temperature=0.5)
+    except Exception as e:
+        logger.error(f"Digest generation failed: {e}")
+        return f"{len(tasks)} new tasks extracted and prioritized."

task_manager_agent/main_agent.py

@@ -0,0 +1,204 @@
+"""
+Task Manager Agent
+==================
+Turns emails + meeting notes into tasks automatically.
+Prioritizes by deadline and impact.
+Syncs with Notion or Todoist.
+Triggers: new email arrival + daily 9 AM sync.
+"""
+
+import os
+import time
+import logging
+import schedule
+import threading
+from datetime import datetime
+import os as _os
+from dotenv import load_dotenv
+
+from data_fetcher import (
+    fetch_recent_emails,
+    fetch_calendar_meetings,
+    fetch_existing_tasks,
+    fetch_notion_tasks,
+)
+from llm import extract_tasks_from_emails, extract_tasks_from_meeting_notes, prioritize_tasks
+from task_store import TaskStore
+import sys, os
+sys.path.insert(0, os.path.dirname(__file__))
+from delivery import (
+    send_task_digest_email,
+    send_task_digest_whatsapp,
+    sync_to_notion,
+    sync_to_todoist,
+)
+
+load_dotenv(_os.path.join(_os.path.dirname(_os.path.abspath(__file__)), "..", ".env"))
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(name)s — %(message)s",
+    handlers=[
+        logging.FileHandler("task_manager.log"),
+        logging.StreamHandler(),
+    ],
+)
+logger = logging.getLogger("TaskManagerAgent")
+
+# ── config ────────────────────────────────────────────────────────────────────
+EMAIL_POLL_INTERVAL_MINUTES = int(os.getenv("EMAIL_POLL_INTERVAL_MINUTES", "15"))
+SYNC_BACKEND = os.getenv("TASK_SYNC_BACKEND", "notion")   # "notion" | "todoist" | "both"
+DELIVER_EMAIL = os.getenv("DELIVER_TASK_EMAIL", "true").lower() == "true"
+DELIVER_WHATSAPP = os.getenv("DELIVER_TASK_WHATSAPP", "false").lower() == "true"
+MAX_EMAILS_TO_SCAN = int(os.getenv("MAX_EMAILS_TO_SCAN", "20"))
+USER_EMAIL = os.getenv("USER_EMAIL", "")
+
+
+# ── core pipeline ─────────────────────────────────────────────────────────────
+
+def run_task_extraction_pipeline(trigger: str = "scheduled") -> dict:
+    """Full pipeline: fetch → extract → prioritize → sync → deliver."""
+    logger.info(f"🚀 Task Manager pipeline started (trigger={trigger})")
+    start = datetime.now()
+    results = {"new_tasks": [], "updated_tasks": [], "errors": []}
+
+    try:
+        # 1. Fetch inputs
+        logger.info("📥 Fetching recent emails …")
+        emails = fetch_recent_emails(max_results=MAX_EMAILS_TO_SCAN)
+        logger.info(f"   Found {len(emails)} emails to analyse")
+
+        logger.info("📅 Fetching today's meetings for context …")
+        meetings = fetch_calendar_meetings(days_back=1, days_ahead=0)
+        logger.info(f"   Found {len(meetings)} recent meetings")
+
+        logger.info("📋 Fetching existing tasks to avoid duplicates …")
+        existing_tasks = fetch_existing_tasks()
+
+        # 2. Extract tasks from emails
+        if emails:
+            logger.info("🤖 Extracting tasks from emails via Groq …")
+            email_tasks = extract_tasks_from_emails(emails, existing_tasks)
+            logger.info(f"   Extracted {len(email_tasks)} tasks from emails")
+            results["new_tasks"].extend(email_tasks)
+
+        # 3. Extract tasks from meeting notes / descriptions
+        if meetings:
+            logger.info("🤖 Extracting tasks from meeting context …")
+            meeting_tasks = extract_tasks_from_meeting_notes(meetings, existing_tasks)
+            logger.info(f"   Extracted {len(meeting_tasks)} tasks from meetings")
+            results["new_tasks"].extend(meeting_tasks)
+
+        if not results["new_tasks"]:
+            logger.info("✅ No new tasks found — nothing to sync")
+            return results
+
+        # 4. Prioritize all new tasks together
+        logger.info("🎯 Prioritizing tasks …")
+        all_existing = existing_tasks + results["new_tasks"]
+        prioritized = prioritize_tasks(results["new_tasks"], all_existing)
+        results["new_tasks"] = prioritized
+
+        # 5. Persist locally
+        store = TaskStore()
+        saved_count = store.save_tasks(prioritized)
+        logger.info(f"💾 Saved {saved_count} tasks to local store")
+
+        # 6. Sync to external backend(s)
+        if SYNC_BACKEND in ("notion", "both"):
+            logger.info("🔄 Syncing to Notion …")
+            synced = sync_to_notion(prioritized)
+            logger.info(f"   Synced {synced} tasks to Notion")
+
+        if SYNC_BACKEND in ("todoist", "both"):
+            logger.info("🔄 Syncing to Todoist …")
+            synced = sync_to_todoist(prioritized)
+            logger.info(f"   Synced {synced} tasks to Todoist")
+
+        # 7. Deliver digest
+        if DELIVER_EMAIL and USER_EMAIL:
+            logger.info("📧 Sending task digest email …")
+            send_task_digest_email(prioritized, trigger=trigger, recipient=USER_EMAIL)
+
+        if DELIVER_WHATSAPP:
+            logger.info("📱 Sending WhatsApp digest …")
+            send_task_digest_whatsapp(prioritized, trigger=trigger)
+
+        elapsed = (datetime.now() - start).seconds
+        logger.info(f"✅ Pipeline complete in {elapsed}s — {len(prioritized)} tasks processed")
+
+    except Exception as e:
+        logger.error(f"❌ Pipeline error: {e}", exc_info=True)
+        results["errors"].append(str(e))
+
+    return results
+
+
+# ── email-trigger watcher ─────────────────────────────────────────────────────
+
+class EmailWatcher(threading.Thread):
+    """Polls Gmail every N minutes; fires pipeline when new actionable emails arrive."""
+
+    def __init__(self):
+        super().__init__(daemon=True)
+        self._stop_event = threading.Event()
+        self._last_email_id: str | None = None
+
+    def run(self):
+        logger.info(f"👁️  EmailWatcher started (polling every {EMAIL_POLL_INTERVAL_MINUTES} min)")
+        while not self._stop_event.is_set():
+            try:
+                self._check_for_new_emails()
+            except Exception as e:
+                logger.warning(f"EmailWatcher error: {e}")
+            self._stop_event.wait(EMAIL_POLL_INTERVAL_MINUTES * 60)
+
+    def _check_for_new_emails(self):
+        emails = fetch_recent_emails(max_results=5, since_id=self._last_email_id)
+        if emails:
+            newest_id = emails[0].get("id")
+            if newest_id != self._last_email_id:
+                logger.info(f"📬 {len(emails)} new email(s) detected — triggering extraction")
+                self._last_email_id = newest_id
+                run_task_extraction_pipeline(trigger="email_trigger")
+
+    def stop(self):
+        self._stop_event.set()
+
+
+# ── scheduler ─────────────────────────────────────────────────────────────────
+
+def schedule_daily_sync():
+    schedule.every().day.at("09:00").do(
+        lambda: run_task_extraction_pipeline(trigger="daily_9am")
+    )
+    logger.info("⏰ Daily sync scheduled at 09:00")
+
+
+def run_scheduler():
+    logger.info("🗓️  Scheduler running …")
+    while True:
+        schedule.run_pending()
+        time.sleep(30)
+
+
+# ── entry point ───────────────────────────────────────────────────────────────
+
+def main():
+    logger.info("=" * 60)
+    logger.info("  TASK MANAGER AGENT  — Personal AI OS")
+    logger.info("=" * 60)
+
+    # Immediate run on startup
+    run_task_extraction_pipeline(trigger="startup")
+
+    # Continuous email watcher
+    watcher = EmailWatcher()
+    watcher.start()
+
+    # Daily 9 AM scheduled sync
+    schedule_daily_sync()
+    run_scheduler()   # blocks
+
+
+if __name__ == "__main__":
+    main()

task_manager_agent/requirements.txt

@@ -0,0 +1,9 @@
+groq>=0.8.0
+google-auth>=2.28.0
+google-auth-oauthlib>=1.2.0
+google-auth-httplib2>=0.2.0
+google-api-python-client>=2.120.0
+schedule>=1.2.1
+python-dotenv>=1.0.1
+requests>=2.31.0
+twilio>=8.13.0

task_manager_agent/task_store.py

@@ -0,0 +1,97 @@
+"""
+task_store.py — Task Manager Agent
+=====================================
+Local JSON-based task store with deduplication, status tracking,
+and a simple query interface.
+"""
+
+import json
+import os
+import uuid
+import logging
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger("TaskManagerAgent.TaskStore")
+
+TASKS_FILE = os.getenv("LOCAL_TASKS_FILE", "tasks.json")
+MAX_LOCAL_TASKS = 500   # rotate after this many
+
+
+class TaskStore:
+    def __init__(self, filepath: str = TASKS_FILE):
+        self.path = Path(filepath)
+        self._tasks: list[dict] = self._load()
+
+    # ── I/O ──────────────────────────────────────────────────────────────────
+
+    def _load(self) -> list[dict]:
+        if self.path.exists():
+            try:
+                with open(self.path) as f:
+                    data = json.load(f)
+                    return data if isinstance(data, list) else []
+            except Exception as e:
+                logger.warning(f"Could not load tasks file: {e}")
+        return []
+
+    def _persist(self):
+        try:
+            with open(self.path, "w") as f:
+                json.dump(self._tasks[-MAX_LOCAL_TASKS:], f, indent=2, default=str)
+        except Exception as e:
+            logger.error(f"Could not persist tasks: {e}")
+
+    # ── public API ────────────────────────────────────────────────────────────
+
+    def save_tasks(self, tasks: list[dict]) -> int:
+        """Upsert tasks by title similarity. Returns count of new tasks added."""
+        existing_titles = {t.get("title", "").lower().strip() for t in self._tasks}
+        added = 0
+        for task in tasks:
+            title_key = task.get("title", "").lower().strip()
+            if title_key in existing_titles:
+                logger.debug(f"Skipping duplicate task: {task.get('title')}")
+                continue
+            task["id"] = task.get("id") or str(uuid.uuid4())
+            task["created_at"] = datetime.now(timezone.utc).isoformat()
+            task["status"] = task.get("status", "todo")
+            self._tasks.append(task)
+            existing_titles.add(title_key)
+            added += 1
+
+        if added:
+            self._persist()
+        return added
+
+    def get_tasks(
+        self,
+        status: Optional[str] = None,
+        category: Optional[str] = None,
+        priority_min: int = 0,
+    ) -> list[dict]:
+        result = self._tasks
+        if status:
+            result = [t for t in result if t.get("status") == status]
+        if category:
+            result = [t for t in result if t.get("category") == category]
+        if priority_min:
+            result = [t for t in result if (t.get("priority_score") or 0) >= priority_min]
+        return sorted(result, key=lambda x: x.get("priority_score", 0), reverse=True)
+
+    def mark_done(self, task_id: str) -> bool:
+        for t in self._tasks:
+            if t.get("id") == task_id:
+                t["status"] = "done"
+                t["completed_at"] = datetime.now(timezone.utc).isoformat()
+                self._persist()
+                return True
+        return False
+
+    def get_open_count(self) -> int:
+        return sum(1 for t in self._tasks if t.get("status") == "todo")
+
+    def all_as_context(self) -> list[dict]:
+        """Lightweight list for LLM context / dedup checks."""
+        return [{"title": t.get("title"), "status": t.get("status")} for t in self._tasks]

task_manager_agent/token.json

@@ -0,0 +1 @@
+{"token": "ya29.a0AQvPyIM5ItOxxVnGPnWfIzXS7aQpCYvu09vLmS42BhjeV2p4Z0V2Q3bYPiub9yY0UkU09AvuIX75cyfS7nxn2oFEW49QLvPcHZU5PzDiNrvitPB6C4LS75CxQUjR63OLP8hpELr07zgEM594L7m0D0BV3GBdayxJqiIF_X4rt_fg0-raP4suW4sSW_FoX-8IYCCkdBEaCgYKAcgSARUSFQHGX2MiAHBi0PWVvembfcbAGKUFSg0206", "refresh_token": "1//0gpNfTgwl7MUnCgYIARAAGBASNwF-L9IrcTUaFCTszG_Z0BLQZw-RC4pZaXl0B1m8AjuP0dnEaOdZDUIIK-2EOh7WndaHl-X4fiQ", "token_uri": "https://oauth2.googleapis.com/token", "client_id": "426626406279-ib9ps1kchej0eqt4ot2l7mbng7gaac5m.apps.googleusercontent.com", "client_secret": "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", "scopes": ["https://www.googleapis.com/auth/gmail.readonly", "https://www.googleapis.com/auth/calendar.readonly"], "universe_domain": "googleapis.com", "account": "", "expiry": "2026-05-17T20:40:05Z"}