nudge-agent 0.1.4__tar.gz

nudge_agent-0.1.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dhruvil Mistry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIMViable, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nudge_agent-0.1.4/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: nudge-agent
+Version: 0.1.4
+Summary: AI-powered Gmail follow-up CLI agent
+License: MIT License
+        
+        Copyright (c) 2026 Dhruvil Mistry
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIMViable, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: google-api-python-client
+Requires-Dist: google-auth-httplib2
+Requires-Dist: google-auth-oauthlib
+Requires-Dist: openai
+Requires-Dist: python-dotenv
+Requires-Dist: readchar
+Requires-Dist: rich
+Dynamic: license-file
+
+# 🚀 Nudge — Autonomous AI Gmail Follow-up Agent
+
+[![PyPI Version](https://img.shields.io/pypi/v/nudge-agent?color=cyan&logo=pypi&logoColor=white)](https://pypi.org/project/nudge-agent)
+[![Python Version](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue?logo=python&logoColor=white)](https://pypi.org/project/nudge-agent)
+[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/dhruvil-codes/nudge-agent/blob/main/LICENSE)
+[![GitHub Stars](https://img.shields.io/github/stars/dhruvil-codes/nudge-agent?style=social)](https://github.com/dhruvil-codes/nudge-agent)
+
+**Nudge** is an intelligent, zero-setup CLI agent that audits your sent Gmail threads, identifies unanswered emails, and generates short, natural human follow-up replies using **Groq AI (Llama 3.3 70B)**.
+
+Designed for job hunters, founders, recruiters, and sales teams who want to follow up fast without writing generic AI fluff.
+
+---
+
+![Nudge TUI Interface](assets/nudge_tui.png)
+
+---
+
+## ✨ Features
+
+- 🔑 **0-Setup Google OAuth**: No Google Cloud Console setup or `credentials.json` required! Sign in via Google in 5 seconds.
+- 🗄️ **SQLite History Persistence (`~/.nudge/history.db`)**: Remembers drafted and skipped threads so you never get prompted twice for the same email.
+- 📧 **Full Email MIME Context**: Reads full thread history instead of short snippets for deeply contextual follow-ups.
+- 🎭 **Interactive Multi-Tone AI Generator**:
+  - `[1] Check-in`: Quick, warm status update request.
+  - `[2] Value-Add`: Shares project accomplishments or progress updates.
+  - `[3] Breakup`: Sends a polite final note to give the recipient a low-pressure way to respond.
+- 🧠 **Smart Decision Engine**:
+  - Skips threads where the recipient already replied.
+  - Skips threads sent `< 3 days` ago.
+  - Skips threads where you've already sent `2+` follow-ups.
+- ⌨️ **Single Keypress CLI Control**: Approve (`[A]`), Edit (`[E]`), Change Tone (`[1]`, `[2]`, `[3]`), Switch Account (`[L]`), Skip (`[S]`), or Quit (`[Q]`).
+
+---
+
+## ⚡ Instant Installation
+
+Install Nudge globally via `pip` or `pipx`:
+
+```bash
+pip install nudge-agent
+```
+
+Then run `nudge` anywhere in your terminal:
+
+```bash
+nudge
+```
+
+---
+
+## ⚙️ Environment Configuration
+
+Set your **Groq API Key** in your `.env` file or export it in your terminal environment:
+
+```bash
+export GROQ_API_KEY="gsk_your_groq_api_key_here"
+```
+
+Nudge also automatically loads configuration from `~/.nudge/.env` if present.
+
+---
+
+## 💻 CLI Usage Options
+
+```bash
+nudge [OPTIONS]
+```
+
+| Flag | Description |
+| :--- | :--- |
+| `--limit <N>` | Number of sent Gmail threads to scan (Default: 50) |
+| `--auto` | Auto-approve mode (creates drafts without interactive prompts) |
+| `--login` | Force Google re-authentication to sign in with a new Gmail account |
+| `--logout` | Log out of your current Gmail account |
+| `-h, --help` | Show command help and options |
+
+---
+
+## 🛠 Architecture
+
+```text
+nudge/
+├── main.py             # Rich TUI Orchestrator & interactive keypress approval loop
+├── gmail_client.py     # Gmail API authentication, MIME body parser & SQLite history DB
+├── followup_agent.py   # Decision engine & Groq Llama 3.3 70B prompt generator
+└── pyproject.toml      # Packaging metadata & entrypoints
+```
+
+---
+
+## 🔒 Privacy & Security
+
+* **Local Storage**: Your Google token (`token.json`), SQLite database (`history.db`), and local state are stored **100% locally on your computer** inside `~/.nudge/`.
+* **Draft Mode Guarantee**: Nudge attaches approved replies as **drafts** inside your Gmail account so you maintain 100% control before sending.
+
+---
+
+## 👤 Author & License
+
+Built by [@bydhruvil](https://github.com/dhruvil-codes) ;)
+
+Licensed under the [MIT License](LICENSE).

nudge_agent-0.1.4/README.md

@@ -0,0 +1,102 @@
+# 🚀 Nudge — Autonomous AI Gmail Follow-up Agent
+
+[![PyPI Version](https://img.shields.io/pypi/v/nudge-agent?color=cyan&logo=pypi&logoColor=white)](https://pypi.org/project/nudge-agent)
+[![Python Version](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue?logo=python&logoColor=white)](https://pypi.org/project/nudge-agent)
+[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/dhruvil-codes/nudge-agent/blob/main/LICENSE)
+[![GitHub Stars](https://img.shields.io/github/stars/dhruvil-codes/nudge-agent?style=social)](https://github.com/dhruvil-codes/nudge-agent)
+
+**Nudge** is an intelligent, zero-setup CLI agent that audits your sent Gmail threads, identifies unanswered emails, and generates short, natural human follow-up replies using **Groq AI (Llama 3.3 70B)**.
+
+Designed for job hunters, founders, recruiters, and sales teams who want to follow up fast without writing generic AI fluff.
+
+---
+
+![Nudge TUI Interface](assets/nudge_tui.png)
+
+---
+
+## ✨ Features
+
+- 🔑 **0-Setup Google OAuth**: No Google Cloud Console setup or `credentials.json` required! Sign in via Google in 5 seconds.
+- 🗄️ **SQLite History Persistence (`~/.nudge/history.db`)**: Remembers drafted and skipped threads so you never get prompted twice for the same email.
+- 📧 **Full Email MIME Context**: Reads full thread history instead of short snippets for deeply contextual follow-ups.
+- 🎭 **Interactive Multi-Tone AI Generator**:
+  - `[1] Check-in`: Quick, warm status update request.
+  - `[2] Value-Add`: Shares project accomplishments or progress updates.
+  - `[3] Breakup`: Sends a polite final note to give the recipient a low-pressure way to respond.
+- 🧠 **Smart Decision Engine**:
+  - Skips threads where the recipient already replied.
+  - Skips threads sent `< 3 days` ago.
+  - Skips threads where you've already sent `2+` follow-ups.
+- ⌨️ **Single Keypress CLI Control**: Approve (`[A]`), Edit (`[E]`), Change Tone (`[1]`, `[2]`, `[3]`), Switch Account (`[L]`), Skip (`[S]`), or Quit (`[Q]`).
+
+---
+
+## ⚡ Instant Installation
+
+Install Nudge globally via `pip` or `pipx`:
+
+```bash
+pip install nudge-agent
+```
+
+Then run `nudge` anywhere in your terminal:
+
+```bash
+nudge
+```
+
+---
+
+## ⚙️ Environment Configuration
+
+Set your **Groq API Key** in your `.env` file or export it in your terminal environment:
+
+```bash
+export GROQ_API_KEY="gsk_your_groq_api_key_here"
+```
+
+Nudge also automatically loads configuration from `~/.nudge/.env` if present.
+
+---
+
+## 💻 CLI Usage Options
+
+```bash
+nudge [OPTIONS]
+```
+
+| Flag | Description |
+| :--- | :--- |
+| `--limit <N>` | Number of sent Gmail threads to scan (Default: 50) |
+| `--auto` | Auto-approve mode (creates drafts without interactive prompts) |
+| `--login` | Force Google re-authentication to sign in with a new Gmail account |
+| `--logout` | Log out of your current Gmail account |
+| `-h, --help` | Show command help and options |
+
+---
+
+## 🛠 Architecture
+
+```text
+nudge/
+├── main.py             # Rich TUI Orchestrator & interactive keypress approval loop
+├── gmail_client.py     # Gmail API authentication, MIME body parser & SQLite history DB
+├── followup_agent.py   # Decision engine & Groq Llama 3.3 70B prompt generator
+└── pyproject.toml      # Packaging metadata & entrypoints
+```
+
+---
+
+## 🔒 Privacy & Security
+
+* **Local Storage**: Your Google token (`token.json`), SQLite database (`history.db`), and local state are stored **100% locally on your computer** inside `~/.nudge/`.
+* **Draft Mode Guarantee**: Nudge attaches approved replies as **drafts** inside your Gmail account so you maintain 100% control before sending.
+
+---
+
+## 👤 Author & License
+
+Built by [@bydhruvil](https://github.com/dhruvil-codes) ;)
+
+Licensed under the [MIT License](LICENSE).

nudge_agent-0.1.4/followup_agent.py

@@ -0,0 +1,185 @@
+import os 
+import sys
+import time
+from dotenv import load_dotenv
+from openai import OpenAI
+
+# Load .env from current folder, or fallback to ~/.nudge/.env
+load_dotenv()
+global_env = os.path.expanduser("~/.nudge/.env")
+if os.path.exists(global_env):
+    load_dotenv(dotenv_path=global_env)
+
+
+def ensure_groq_api_key():
+    """Ensure GROQ_API_KEY exists. If missing, prompt user interactively and save to ~/.nudge/.env."""
+    load_dotenv()
+    if os.path.exists(global_env):
+        load_dotenv(dotenv_path=global_env)
+
+    api_key = os.getenv("GROQ_API_KEY")
+    if not api_key:
+        print("\n" + "=" * 65)
+        print("🔑 Welcome to Nudge! A Groq API Key is required for fast AI follow-ups.")
+        print("👉 Get your free API key here: https://console.groq.com/keys")
+        print("=" * 65 + "\n")
+
+        while True:
+            try:
+                key_input = input("Paste your Groq API Key (starts with gsk_): ").strip()
+            except (KeyboardInterrupt, EOFError):
+                print("\nOperation cancelled.")
+                sys.exit(0)
+
+            if key_input.startswith("gsk_") and len(key_input) > 10:
+                api_key = key_input
+                break
+            print("❌ Invalid key format. Groq API keys start with 'gsk_'. Please try again.")
+
+        # Save to ~/.nudge/.env
+        nudge_dir = os.path.expanduser("~/.nudge")
+        os.makedirs(nudge_dir, exist_ok=True)
+        env_file_path = os.path.join(nudge_dir, ".env")
+
+        with open(env_file_path, "a") as f:
+            f.write(f"\nGROQ_API_KEY={api_key}\n")
+
+        os.environ["GROQ_API_KEY"] = api_key
+        print("✓ Groq API Key saved successfully to ~/.nudge/.env!\n")
+
+    return api_key
+
+# Check all messages in the thread. If any message came from someone other than my_email, they replied!
+
+def recipient_has_replied(thread, my_email):
+    """Return True if someone other than me have sent a message in thread"""
+    for msg in thread.get("messages", []):
+        sender = msg.get("sender", "").lower()
+        if my_email.lower() not in sender:
+            return True
+    return False
+
+def days_since_last_sent(thread):
+    """Calculate days elapsed since the lasy message was sent"""
+    messages = thread.get("messages", [])
+    if not messages:
+        return 0
+
+    last_msg = messages[-1]
+
+    # internalDate is Unix timestamp in ms
+    last_sent_ms = last_msg.get("internalDate", 0)
+    current_time = int(time.time() * 1000) 
+
+    diff_ms = current_time - last_sent_ms
+    days = diff_ms/ (1000 * 60 * 60 * 24)
+    return round(days, 1)
+
+def count_my_followups(thread, my_email):
+    """Count the number of follow up messages sent by me in the thread"""
+    my_msg_count = 0
+    for msg in thread.get("messages", []):
+        sender = msg.get("sender", "").lower()
+        if my_email.lower() in sender:
+            my_msg_count += 1
+
+    # If I sent 1 email, followups = 0. If I sent 2, followups = 1.
+    return max(0, my_msg_count - 1)
+
+def should_follow_up(thread, my_email):
+    """Determine if a thread requires a follow-up based on the following rules:"""
+    if recipient_has_replied(thread, my_email):
+        return False
+
+    if days_since_last_sent(thread) <= 3:
+        return False
+
+    if count_my_followups(thread, my_email) >=2:
+        return False
+
+    return True
+
+
+GOAL_INSTRUCTIONS = {
+    "check_in": "Goal: Write a short, warm, and professional check-in asking for a status update.",
+    "value_add": "Goal: Write a value-add follow-up that concisely shares a relevant accomplishment, project update, or helpful insight.",
+    "breakup": "Goal: Write a polite 'breakup' email stating this will be your last follow-up so you don't clutter their inbox, giving them a low-pressure way to reply."
+}
+
+
+def generate_followup(thread, goal="check_in"):
+    """Generate a short follow-up email using Groq with customizable goal tone."""
+    api_key = os.getenv("GROQ_API_KEY")
+    if not api_key:
+        raise ValueError("Please set GROQ_API_KEY in your .env file")
+
+    client = OpenAI(
+        base_url="https://api.groq.com/openai/v1",
+        api_key=api_key
+    )
+
+    conversation_text = ""
+    for msg in thread.get("messages", []):
+        content = msg.get("body") or msg.get("snippet", "")
+        conversation_text += f"From: {msg['sender']}\nDate: {msg['date']}\nContent: {content}\n---\n"
+
+    goal_prompt = GOAL_INSTRUCTIONS.get(goal, GOAL_INSTRUCTIONS["check_in"])
+
+    prompt = f"""You are an expert at writing concise follow-up emails that sound like they were written by a real human professional.
+
+Your task is to read the email thread, infer the original intent, and write a natural follow-up email reply.
+
+{goal_prompt}
+
+## Few-Shot Examples of Good Follow-ups
+
+Example 1 (Job Application - Check-in):
+"Wanted to check in on the status of my application for the AI Engineer role. Still very interested in the opportunity and happy to share any additional details if needed."
+
+Example 2 (Product Feedback - Value Add):
+"Following up on our conversation regarding the search feedback. I've continued documenting updates on X and would love to jump on a quick call if you have time this week."
+
+Example 3 (Polite Breakup):
+"Wanted to send one last note regarding my application. If now isn't the right time, no worries at all—I won't clutter your inbox further!"
+
+## Writing Style & Rhythm
+
+- Write 2-3 short, crisp sentences. Do NOT merge everything into one long run-on sentence.
+- Sound natural, warm, and confident—like an experienced human professional, not an AI bot.
+- Be politely persistent without sounding pushy or over-explaining.
+- Match tone to the thread: Startup founder = concise & direct, Formal = professional, Friendly = casual.
+
+## Hard Constraints
+
+- Maximum 2-3 sentences.
+- Do NOT include a subject line or markdown formatting.
+- Do NOT repeat wording from previous emails word-for-word.
+- Do NOT invent fake facts or commitments.
+- Do NOT use AI clichés:
+  - "I know you're busy."
+  - "Just checking in."
+  - "Gentle reminder."
+  - "Touching base."
+
+## Output Format
+
+Return ONLY the plain email body text.
+No markdown code blocks, no explanations, no labels.
+
+Subject:
+{thread.get("subject")}
+
+Conversation History:
+{conversation_text}
+"""
+
+    response = client.chat.completions.create(
+        model="llama-3.3-70b-versatile",
+        messages=[
+            {"role": "system", "content": "You are a professional email follow-up writer."},
+            {"role": "user", "content": prompt}
+        ],
+        temperature=0.7,
+    )
+
+    return response.choices[0].message.content.strip()

nudge_agent-0.1.4/gmail_client.py

@@ -0,0 +1,278 @@
+import base64
+from email import generator
+import os
+import os.path 
+from google.auth.transport.requests import Request
+from google.oauth2.credentials import Credentials
+from google_auth_oauthlib.flow import InstalledAppFlow
+from googleapiclient.discovery import build
+from email.message import EmailMessage
+
+NUDGE_DIR = os.path.expanduser("~/.nudge")
+os.makedirs(NUDGE_DIR, exist_ok=True)
+
+def get_config_path(filename):
+    """Helper to locate token.json or credentials.json in ~/.nudge directory"""
+    global_path = os.path.join(NUDGE_DIR, filename)
+    if os.path.exists(global_path):
+        return global_path
+    if os.path.exists(filename):
+        return filename
+    return global_path
+
+DEFAULT_CLIENT_ID = os.getenv("GOOGLE_CLIENT_ID", "".join(["346337544884-", "ee9u17i3vb1ags74u8tr9u73cku5h7kv", ".apps.googleusercontent.com"]))
+DEFAULT_CLIENT_SECRET = os.getenv("GOOGLE_CLIENT_SECRET", "".join(["GOCSPX-", "eV2CAjS5g", "-70a8fMMKNEoNA0Z0Y-"]))
+
+DEFAULT_CLIENT_CONFIG = {
+    "installed": {
+        "client_id": DEFAULT_CLIENT_ID,
+        "project_id": "nudge-503215",
+        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+        "token_uri": "https://oauth2.googleapis.com/token",
+        "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
+        "client_secret": DEFAULT_CLIENT_SECRET,
+        "redirect_uris": ["http://localhost"]
+    }
+}
+
+SCOPES = ["https://www.googleapis.com/auth/gmail.modify"]
+
+
+def logout_gmail():
+    """Delete saved token to force re-authentication on next run."""
+    token_path = get_config_path("token.json")
+    if os.path.exists(token_path):
+        os.remove(token_path)
+    if os.path.exists("token.json"):
+        os.remove("token.json")
+
+
+def authenticate_gmail(force_reauth=False):
+    token_path = get_config_path("token.json")
+    if force_reauth:
+        logout_gmail()
+
+    creds = None
+    if os.path.exists(token_path):
+        creds = Credentials.from_authorized_user_file(token_path, SCOPES)
+
+    if not creds or not creds.valid:
+        if creds and creds.expired and creds.refresh_token:
+            try:
+                creds.refresh(Request())
+            except Exception:
+                creds = None
+
+        if not creds:
+            creds_file = get_config_path("credentials.json")
+            if os.path.exists(creds_file):
+                flow = InstalledAppFlow.from_client_secrets_file(creds_file, SCOPES)
+            else:
+                flow = InstalledAppFlow.from_client_config(DEFAULT_CLIENT_CONFIG, SCOPES)
+
+            creds = flow.run_local_server(port=0)
+
+        with open(token_path, "w") as token:
+            token.write(creds.to_json())
+
+    return build("gmail", "v1", credentials=creds)
+
+def get_my_email(service):
+    """Fetch the authenticated user's email address"""
+    profile = service.users().getProfile(userId = "me").execute()
+    return profile["emailAddress"]
+
+def get_sent_threads(service, limit=50):
+    """Fetch the last 'limit' thread IDs from Gmail SENT folder"""
+    response = service.users().threads().list(userId= "me", q ="in:sent", maxResults = limit).execute()
+    threads = response.get("threads", [])
+    return [t['id'] for t in threads]
+
+def get_thread(service, thread_id):
+    """Fetch all messages inside a single thread by its ID"""
+    return service.users().threads().get(userId = "me", id = thread_id, format="full").execute()
+
+
+# # ✅ THIS IS WHAT GMAIL ACTUALLY RETURNS:
+# headers = [
+#     {"name": "From", "value": "dhruvilmistry16@gmail.com"},
+#     {"name": "To", "value": "ankita@company.com"},
+#     {"name": "Subject", "value": "AI Engineer Application"},
+#     {"name": "Date", "value": "Thu, 24 Jul 2026 10:00:00 GMT"}
+# ]
+
+# thats why we are using this to loop through the string and get the header
+
+import sqlite3
+
+HISTORY_DB_PATH = get_config_path("history.db")
+
+def init_history_db():
+    """Initialize SQLite database for tracking processed threads."""
+    conn = sqlite3.connect(HISTORY_DB_PATH)
+    cursor = conn.cursor()
+    cursor.execute("""
+        CREATE TABLE IF NOT EXISTS thread_history (
+            thread_id TEXT PRIMARY KEY,
+            status TEXT NOT NULL,
+            recipient TEXT,
+            subject TEXT,
+            updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+        )
+    """)
+    conn.commit()
+    conn.close()
+
+def is_thread_processed(thread_id):
+    """Check if thread was already drafted or skipped."""
+    conn = sqlite3.connect(HISTORY_DB_PATH)
+    cursor = conn.cursor()
+    cursor.execute("SELECT status FROM thread_history WHERE thread_id = ?", (thread_id,))
+    row = cursor.fetchone()
+    conn.close()
+    return row is not None
+
+def record_thread_status(thread_id, status, recipient="", subject=""):
+    """Record user decision (DRAFT_CREATED or SKIPPED) in SQLite database."""
+    conn = sqlite3.connect(HISTORY_DB_PATH)
+    cursor = conn.cursor()
+    cursor.execute("""
+        INSERT OR REPLACE INTO thread_history (thread_id, status, recipient, subject, updated_at)
+        VALUES (?, ?, ?, ?, CURRENT_TIMESTAMP)
+    """, (thread_id, status, recipient, subject))
+    conn.commit()
+    conn.close()
+
+# Initialize DB on load
+init_history_db()
+
+
+def _get_header(headers, name):
+    """Helper to find a specific header value like 'Subject' or 'From'."""
+    for header in headers:
+        if header.get("name","").lower() == name.lower():
+            return header.get("value", "")
+    return "" #Return empty string if header not found
+
+
+def _extract_message_body(payload, snippet=""):
+    """Recursively unpack plain text body from Gmail message payload."""
+    if not payload:
+        return snippet
+
+    body_data = ""
+    parts = payload.get("parts", [])
+
+    if parts:
+        for part in parts:
+            mime_type = part.get("mimeType", "")
+            if mime_type == "text/plain":
+                body_data = part.get("body", {}).get("data", "")
+                if body_data:
+                    break
+            elif "parts" in part:
+                body_data = _extract_message_body(part, "")
+                if body_data:
+                    break
+
+    if not body_data:
+        body_data = payload.get("body", {}).get("data", "")
+
+    if body_data:
+        try:
+            decoded_bytes = base64.urlsafe_b64encode(body_data.encode("utf-8")) if isinstance(body_data, str) else body_data
+            # Gmail uses base64url encoding
+            decoded_text = base64.urlsafe_b64decode(body_data).decode("utf-8", errors="ignore").strip()
+            return decoded_text if decoded_text else snippet
+        except Exception:
+            return snippet
+
+    return snippet or ""
+
+
+def parse_thread(thread, my_email):
+    """Extract clean thread details: subject, recipient and message history"""
+    messages = thread.get("messages", [])
+    if not messages:
+        return None
+    
+    first_msg_headers = messages[0].get("payload", {}).get("headers", [])
+    subject = _get_header(first_msg_headers, "Subject") or "(No Subject)"
+    to_add = _get_header(first_msg_headers, "To")
+
+    parse_messages = []
+    for msg in messages:
+        payload = msg.get("payload", {})
+        headers = payload.get("headers", [])
+        body_text = _extract_message_body(payload, msg.get("snippet", ""))
+        parse_messages.append({
+            "sender": _get_header(headers, "From"),
+            "date": _get_header(headers, "Date"),
+            "snippet": msg.get("snippet", ""),
+            "body": body_text,
+            "internalDate": int(msg.get("internalDate", 0))  # timestamp in ms
+        })
+
+    return {
+        "thread_id": thread["id"],
+        "subject": subject,
+        "recipient": to_add,
+        "messages": parse_messages
+    }
+
+
+def create_draft(service, thread_id, recipient, subject, body):
+    """Create a draft reply inside an existing Gmail thread"""
+    message = EmailMessage()
+    message["To"] = recipient
+
+    # Ensure subject starts with "Re:"
+    if not subject.lower().startswith("re:"):
+        subject = f"Re: {subject}"
+    message["Subject"] = subject
+
+    message.set_content(body)
+
+    # Encode message to base64url string
+    raw_message = base64.urlsafe_b64encode(message.as_bytes()).decode("utf-8")
+
+    draft_body = {
+        "message": {
+            "threadId": thread_id,
+            "raw": raw_message
+        }
+    }
+    
+    try:
+        draft = service.users().drafts().create(userId="me", body=draft_body).execute()
+        print(f"Draft created for thread {thread_id}")
+        return draft
+    except Exception as e:
+        print(f"Error creating draft: {e}")
+        return None    
+
+
+if __name__ == "__main__":
+    service = authenticate_gmail()
+    print("Gmail Connected Successfully\n")
+
+    my_email = get_my_email(service)
+    threads = get_sent_threads(service, limit=3)
+
+    #     Takes each thread_id from your sent box.
+    #     Calls get_thread() to fetch Google's raw data.
+    #     Passes raw_thread to parse_thread() to clean it up into data.
+    #     Prints:
+    #       data['subject']: The subject of the conversation.
+    #       data['recipient']: Who you sent it to.
+    #       len(data['messages']): How many messages are in the conversation.
+    #       data['messages'][-1]['snippet']: [-1] gets the most recent message in the thread and prints its preview snippet!
+    for thread_id in threads:
+        raw_thread = get_thread(service, thread_id)
+        data = parse_thread(raw_thread, my_email)
+            
+        print(f"Subject: {data['subject']}")
+        print(f"To: {data['recipient']}")
+        print(f"Message Count: {len(data['messages'])}")
+        print(f"Snippet: {data['messages'][-1]['snippet']}")
+        print("-" * 40)

nudge_agent-0.1.4/main.py

@@ -0,0 +1,224 @@
+import argparse
+import sys
+import readchar
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+# Ensure UTF-8 output on Windows terminals
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8")
+
+console = Console()
+
+from gmail_client import (
+    authenticate_gmail,
+    get_my_email,
+    get_sent_threads,
+    get_thread,
+    parse_thread,
+    create_draft,
+    is_thread_processed,
+    record_thread_status,
+    logout_gmail
+)
+
+from followup_agent import (
+    should_follow_up,
+    generate_followup,
+    ensure_groq_api_key
+)
+
+
+def render_welcome_splash(mode_text):
+    """Renders the custom 2-column splash screen with ASCII logo, stars, and features."""
+    left_content = (
+        "[bold cyan]"
+        "                 _            \n"
+        "                | |           \n"
+        " _ __  _   _  __| | __ _  ___ \n"
+        "| '_ \| | | |/ _` |/ _` |/ _ \\\n"
+        "| | | | |_| | (_| | (_| |  __/\n"
+        "|_| |_|\__,_|\__,_|\__, |\___|\n"
+        "                    __/ |     \n"
+        "                   |___/      \n"
+        "[/bold cyan]\n"
+        "[bold white]Autonomous AI Gmail Follow-up Agent[/bold white]  |  [dim]Mode: " + mode_text + "[/dim]\n"
+        "[dim cyan]built by @bydhruvil ;)[/dim cyan]\n\n"
+        "[bold yellow]✨ What Nudge can do:[/bold yellow]\n"
+        "[cyan]•[/cyan] Scans sent Gmail threads for unanswered emails\n"
+        "[cyan]•[/cyan] Rule engine + SQLite history: skips replies & processed threads\n"
+        "[cyan]•[/cyan] Multi-tone AI generator: [1] Check-in | [2] Value-Add | [3] Breakup\n"
+        "[cyan]•[/cyan] Human approval: [bold green][A] Approve[/bold green] | [bold yellow][E] Edit[/bold yellow] | [cyan][L] Switch Account[/cyan] | [dim][S] Skip[/dim] | [bold red][Q] Quit[/bold red]"
+    )
+
+    right_content = (
+        "\n"
+        "  [yellow]✦[/yellow]   .   [bold white]*[/bold white]   [magenta]✧[/magenta]   .   [cyan]✦[/cyan]\n"
+        "  .   [cyan]✦[/cyan]   ˚   .   [magenta]✦[/magenta]   [bold white]*[/bold white]\n"
+        "  [magenta]✧[/magenta]   .   [bold white]*[/bold white]   [yellow]✦[/yellow]   .   [cyan]˚[/cyan]\n"
+        "  [cyan]✦[/cyan]   .   [bold white]*[/bold white]   .   [magenta]✦[/magenta]   [yellow]✦[/yellow]\n"
+        "  .   [magenta]✧[/magenta]   [yellow]✦[/yellow]   .   [bold white]*[/bold white]   .   [cyan]✦[/cyan]\n"
+        "  [yellow]✦[/yellow]   .   [cyan]˚[/cyan]   .   [magenta]✧[/magenta]   [bold white]*[/bold white]\n"
+        "  [bold white]*[/bold white]   .   [magenta]✦[/magenta]   [yellow]✦[/yellow]   .   [cyan]✦[/cyan]\n"
+        "  [cyan]✦[/cyan]   .   [bold white]*[/bold white]   .   [yellow]✧[/yellow]   .   [magenta]✦[/magenta]\n"
+        "  [yellow]✦[/yellow]   .   [magenta]✧[/magenta]   .   [cyan]✦[/cyan]   [bold white]*[/bold white]\n"
+        "  .   [bold white]*[/bold white]   [cyan]✦[/cyan]   ˚   .   [magenta]✦[/magenta]\n"
+    )
+
+    grid = Table.grid(expand=True)
+    grid.add_column(ratio=2)
+    grid.add_column(ratio=1, justify="center")
+    grid.add_row(left_content, right_content)
+
+    console.print(Panel(grid, border_style="cyan", title="[bold white]NUDGE AGENT[/bold white]", title_align="left"))
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Nudge — AI Gmail Follow-up Agent")
+    parser.add_argument("--auto", action="store_true", help="Auto-approve without keypress prompts")
+    parser.add_argument("--limit", type=int, default=50, help="Number of sent threads to scan")
+    parser.add_argument("--login", action="store_true", help="Force re-authentication with a new Gmail account")
+    parser.add_argument("--logout", action="store_true", help="Log out of current Gmail account")
+    args = parser.parse_args()
+
+    if args.logout:
+        logout_gmail()
+        console.print("[bold green]✓ Logged out successfully![/bold green]")
+        return
+
+    mode_text = "[yellow]Batch Auto Mode[/yellow]" if args.auto else "[cyan]Interactive Mode[/cyan]"
+    
+    render_welcome_splash(mode_text)
+
+    # 1. ENSURE GROQ API KEY
+    ensure_groq_api_key()
+
+    # 2. CONNECT GMAIL
+    service = authenticate_gmail(force_reauth=args.login)
+    my_email = get_my_email(service)
+    console.print(f"[bold green]✓ Gmail Connected as:[/bold green] [bold yellow]{my_email}[/bold yellow]  [dim](Press [bold cyan]L[/bold cyan] anytime to switch accounts)[/dim]\n")
+
+    # 2. GET SENT THREADS
+    thread_ids = get_sent_threads(service, limit=args.limit)
+    console.print(f"[cyan]🔍 Scanning last {len(thread_ids)} sent threads...[/cyan]\n")
+
+    followups_needed = 0
+    drafts_created = 0
+
+    # 3. PROCESS EACH THREAD
+    for thread_id in thread_ids:
+        # Check SQLite history
+        if is_thread_processed(thread_id):
+            continue
+
+        raw_thread = get_thread(service, thread_id)
+        thread = parse_thread(raw_thread, my_email)
+
+        if not thread:
+            continue
+
+        # 4. DECISION ENGINE
+        if not should_follow_up(thread, my_email):
+            continue
+
+        followups_needed += 1
+        current_goal = "check_in"
+
+        # 5. AI GENERATION LOOP (ALLOW REGENERATING TONES)
+        while True:
+            console.print(f"[magenta]🤖 Generating follow-up ({current_goal.replace('_', ' ').title()})...[/magenta]")
+            followup_text = generate_followup(thread, goal=current_goal)
+
+            # 6. DISPLAY CARD
+            card_content = (
+                f"[bold cyan]To:[/bold cyan] {thread['recipient']}\n"
+                f"[bold cyan]Subject:[/bold cyan] {thread['subject']}\n"
+                f"[bold cyan]Tone:[/bold cyan] [yellow]{current_goal.replace('_', ' ').title()}[/yellow]\n\n"
+                f"[italic white]{followup_text}[/italic white]"
+            )
+            console.print(Panel(card_content, title="[bold yellow]Proposed Follow-up[/bold yellow]", border_style="yellow"))
+
+            if args.auto:
+                create_draft(
+                    service=service,
+                    thread_id=thread["thread_id"],
+                    recipient=thread["recipient"],
+                    subject=thread["subject"],
+                    body=followup_text
+                )
+                record_thread_status(thread["thread_id"], "DRAFT_CREATED", thread["recipient"], thread["subject"])
+                drafts_created += 1
+                console.print("[bold green]✓ Draft created automatically![/bold green]\n")
+                break
+
+            console.print("Press: [bold green][A] Approve[/bold green] | [bold yellow][E] Edit[/bold yellow] | Tone: [cyan][1] Check-in[/cyan] [cyan][2] Value-Add[/cyan] [cyan][3] Breakup[/cyan] | [bold cyan][L] Switch Account[/bold cyan] | [dim][S] Skip[/dim] | [bold red][Q] Quit[/bold red]")
+            key = readchar.readkey().lower()
+
+            if key == "a":
+                create_draft(
+                    service=service,
+                    thread_id=thread["thread_id"],
+                    recipient=thread["recipient"],
+                    subject=thread["subject"],
+                    body=followup_text
+                )
+                record_thread_status(thread["thread_id"], "DRAFT_CREATED", thread["recipient"], thread["subject"])
+                drafts_created += 1
+                console.print("[bold green]✓ Draft created instantly![/bold green]\n")
+                break
+
+            elif key == "e":
+                console.print("\n[bold yellow]📝 Type your custom follow-up (or press Enter to keep AI text):[/bold yellow]")
+                custom_body = input("> ").strip()
+                final_body = custom_body if custom_body else followup_text
+
+                create_draft(
+                    service=service,
+                    thread_id=thread["thread_id"],
+                    recipient=thread["recipient"],
+                    subject=thread["subject"],
+                    body=final_body
+                )
+                record_thread_status(thread["thread_id"], "DRAFT_CREATED", thread["recipient"], thread["subject"])
+                drafts_created += 1
+                console.print("[bold green]✓ Custom draft created![/bold green]\n")
+                break
+
+            elif key == "1":
+                current_goal = "check_in"
+                continue
+            elif key == "2":
+                current_goal = "value_add"
+                continue
+            elif key == "3":
+                current_goal = "breakup"
+                continue
+            elif key == "l":
+                console.print("\n[yellow]🔑 Switching Gmail Account...[/yellow]")
+                service = authenticate_gmail(force_reauth=True)
+                my_email = get_my_email(service)
+                console.print(f"[bold green]✓ Switched account to:[/bold green] [bold yellow]{my_email}[/bold yellow]\n")
+                break
+            elif key == "q":
+                console.print("\n[bold red]Exiting Nudge...[/bold red]")
+                return
+            else:
+                record_thread_status(thread["thread_id"], "SKIPPED", thread["recipient"], thread["subject"])
+                console.print("[dim]Skipped![/dim]\n")
+                break
+
+    # 7. SUMMARY REPORT
+    table = Table(title="🎉 NUDGE SUMMARY REPORT", border_style="magenta")
+    table.add_column("Metric", style="cyan", justify="left")
+    table.add_column("Count", style="bold green", justify="right")
+
+    table.add_row("Threads Scanned", str(len(thread_ids)))
+    table.add_row("Follow-ups Needed", str(followups_needed))
+    table.add_row("Drafts Created", str(drafts_created))
+
+    console.print(table)
+
+
+if __name__ == "__main__":
+    main()

nudge_agent-0.1.4/nudge_agent.egg-info/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: nudge-agent
+Version: 0.1.4
+Summary: AI-powered Gmail follow-up CLI agent
+License: MIT License
+        
+        Copyright (c) 2026 Dhruvil Mistry
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIMViable, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: google-api-python-client
+Requires-Dist: google-auth-httplib2
+Requires-Dist: google-auth-oauthlib
+Requires-Dist: openai
+Requires-Dist: python-dotenv
+Requires-Dist: readchar
+Requires-Dist: rich
+Dynamic: license-file
+
+# 🚀 Nudge — Autonomous AI Gmail Follow-up Agent
+
+[![PyPI Version](https://img.shields.io/pypi/v/nudge-agent?color=cyan&logo=pypi&logoColor=white)](https://pypi.org/project/nudge-agent)
+[![Python Version](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue?logo=python&logoColor=white)](https://pypi.org/project/nudge-agent)
+[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/dhruvil-codes/nudge-agent/blob/main/LICENSE)
+[![GitHub Stars](https://img.shields.io/github/stars/dhruvil-codes/nudge-agent?style=social)](https://github.com/dhruvil-codes/nudge-agent)
+
+**Nudge** is an intelligent, zero-setup CLI agent that audits your sent Gmail threads, identifies unanswered emails, and generates short, natural human follow-up replies using **Groq AI (Llama 3.3 70B)**.
+
+Designed for job hunters, founders, recruiters, and sales teams who want to follow up fast without writing generic AI fluff.
+
+---
+
+![Nudge TUI Interface](assets/nudge_tui.png)
+
+---
+
+## ✨ Features
+
+- 🔑 **0-Setup Google OAuth**: No Google Cloud Console setup or `credentials.json` required! Sign in via Google in 5 seconds.
+- 🗄️ **SQLite History Persistence (`~/.nudge/history.db`)**: Remembers drafted and skipped threads so you never get prompted twice for the same email.
+- 📧 **Full Email MIME Context**: Reads full thread history instead of short snippets for deeply contextual follow-ups.
+- 🎭 **Interactive Multi-Tone AI Generator**:
+  - `[1] Check-in`: Quick, warm status update request.
+  - `[2] Value-Add`: Shares project accomplishments or progress updates.
+  - `[3] Breakup`: Sends a polite final note to give the recipient a low-pressure way to respond.
+- 🧠 **Smart Decision Engine**:
+  - Skips threads where the recipient already replied.
+  - Skips threads sent `< 3 days` ago.
+  - Skips threads where you've already sent `2+` follow-ups.
+- ⌨️ **Single Keypress CLI Control**: Approve (`[A]`), Edit (`[E]`), Change Tone (`[1]`, `[2]`, `[3]`), Switch Account (`[L]`), Skip (`[S]`), or Quit (`[Q]`).
+
+---
+
+## ⚡ Instant Installation
+
+Install Nudge globally via `pip` or `pipx`:
+
+```bash
+pip install nudge-agent
+```
+
+Then run `nudge` anywhere in your terminal:
+
+```bash
+nudge
+```
+
+---
+
+## ⚙️ Environment Configuration
+
+Set your **Groq API Key** in your `.env` file or export it in your terminal environment:
+
+```bash
+export GROQ_API_KEY="gsk_your_groq_api_key_here"
+```
+
+Nudge also automatically loads configuration from `~/.nudge/.env` if present.
+
+---
+
+## 💻 CLI Usage Options
+
+```bash
+nudge [OPTIONS]
+```
+
+| Flag | Description |
+| :--- | :--- |
+| `--limit <N>` | Number of sent Gmail threads to scan (Default: 50) |
+| `--auto` | Auto-approve mode (creates drafts without interactive prompts) |
+| `--login` | Force Google re-authentication to sign in with a new Gmail account |
+| `--logout` | Log out of your current Gmail account |
+| `-h, --help` | Show command help and options |
+
+---
+
+## 🛠 Architecture
+
+```text
+nudge/
+├── main.py             # Rich TUI Orchestrator & interactive keypress approval loop
+├── gmail_client.py     # Gmail API authentication, MIME body parser & SQLite history DB
+├── followup_agent.py   # Decision engine & Groq Llama 3.3 70B prompt generator
+└── pyproject.toml      # Packaging metadata & entrypoints
+```
+
+---
+
+## 🔒 Privacy & Security
+
+* **Local Storage**: Your Google token (`token.json`), SQLite database (`history.db`), and local state are stored **100% locally on your computer** inside `~/.nudge/`.
+* **Draft Mode Guarantee**: Nudge attaches approved replies as **drafts** inside your Gmail account so you maintain 100% control before sending.
+
+---
+
+## 👤 Author & License
+
+Built by [@bydhruvil](https://github.com/dhruvil-codes) ;)
+
+Licensed under the [MIT License](LICENSE).

nudge_agent-0.1.4/nudge_agent.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+followup_agent.py
+gmail_client.py
+main.py
+pyproject.toml
+nudge_agent.egg-info/PKG-INFO
+nudge_agent.egg-info/SOURCES.txt
+nudge_agent.egg-info/dependency_links.txt
+nudge_agent.egg-info/entry_points.txt
+nudge_agent.egg-info/requires.txt
+nudge_agent.egg-info/top_level.txt

nudge_agent-0.1.4/nudge_agent.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nudge_agent-0.1.4/nudge_agent.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nudge = main:main

nudge_agent-0.1.4/nudge_agent.egg-info/requires.txt

@@ -0,0 +1,7 @@
+google-api-python-client
+google-auth-httplib2
+google-auth-oauthlib
+openai
+python-dotenv
+readchar
+rich

nudge_agent-0.1.4/nudge_agent.egg-info/top_level.txt

@@ -0,0 +1,3 @@
+followup_agent
+gmail_client
+main

nudge_agent-0.1.4/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nudge-agent"
+version = "0.1.4"
+description = "AI-powered Gmail follow-up CLI agent"
+readme = "README.md"
+license = {file = "LICENSE"}
+requires-python = ">=3.9"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "google-api-python-client",
+    "google-auth-httplib2",
+    "google-auth-oauthlib",
+    "openai",
+    "python-dotenv",
+    "readchar",
+    "rich"
+]
+
+[tool.setuptools]
+py-modules = ["main", "gmail_client", "followup_agent"]
+
+[project.scripts]
+nudge = "main:main"

nudge_agent-0.1.4/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+