How noor-fatima-afzal/cold-email-automation works
Project Type and Purpose
• This is an AI-driven automation tool for faculty data scraping and personalized email campaigns.
• It’s not a traditional web app but a Python-based pipeline/orchestration project leveraging LangChain and Groq LLMs.
• Two execution modes:
• Agent-based (autonomous, LangChain agent)
• Sequential (step-by-step pipeline)
File Structure Analysis
• Top level:
• main.py – entrypoint, parses args, kicks off workflows
• config.py – configuration (endpoints, credentials, test mode flags)
• llm_setup.py – initializes Groq LLM & LangChain client
• tools/: domain helpers
• email_campaign.py – templates + SMTP/test inbox logic
• faculty_scraper.py – HTTP requests + HTML parsing + CSV output
• workflows/: orchestration
• agent_workflow.py – LangChain Agent setup + autonomous loop
• sequential_workflow.py – linear pipeline steps
Key Components
• User/CLI: triggers main.py with mode flag
• Config Module: centralizes API keys, SMTP settings, test flags
• LLM Layer: groq “gemma2-9b-it” via LangChain client
• Scraper Tool: fetch & parse university site → CSV
• Email Tool: generate email bodies via LLM → send via SMTP/test inbox
• Workflows:
• Agent Workflow: Agent interacts with scraper/email tools autonomously
• Sequential Workflow: Controller invokes scraper → LLM → email in series
• External Systems:
• University Website (HTTP)
• SMTP Server or Test Inbox
• Groq LLM API
Relationships & Data Flows
• main.py → loads config.py & llm_setup.py
• main.py → selects and invokes either agent_workflow or sequential_workflow
• Workflow → calls faculty_scraper (outputs CSV)
• Workflow → calls email_campaign (pulls CSV, generates emails via LLM, dispatches)
• LLM setup (llm_setup.py) is injected into both workflows and tools
• Tools depend on config for endpoints, credentials, test mode
Architectural Patterns & Principles
• Modular layering:
• Orchestration layer (workflows)
• Tool/domain logic layer (tools)
• Infrastructure/configuration layer (config & llm_setup)
• Dependency Injection: workflows and tools receive LLM client and config
• Two modes illustrate:
• Agent pattern (LangChain agent loop)
• Sequential pipeline