SignalIQ: AI Personalized Outreach Assistant

SignalIQ is an agentic, full-stack workflow application designed to automate prospect research, extract high-relevance personalization opportunities ("signals"), score and rank those hooks, draft targeted sales emails under 120 words, and present them in a premium dashboard for human review.

The application leverages LangGraph for multi-agent coordination, Pydantic for structured output generation, and is optimized for zero-cost, open-source execution.

---

Architecture & Frameworks

1. Backend (FastAPI + LangGraph)

• Multi-Agent State Graph: Built using LangGraph, routing state across 5 specialized agents (Research, Extraction, Ranking, Copywriter, and QA Reviewer).
• Self-Correction Loopback: If the QA Reviewer Agent flags quality or factual issues in the generated email, it routes back to the copywriter with critique feedback for revision (capped at 2 attempts).
• Open-Source Scraper: Searches using the free duckduckgo_search library (no API key required), parses with BeautifulSoup, and reduces noise to clean Markdown with markdownify.
• Real-Time SSE Streaming: Emits live log states from the background agent pipeline directly to the UI using Server-Sent Events.

2. Frontend (Next.js 16 + React 19 + Tailwind CSS)

• Dashboard: Track key metrics (Total Prospects, Approval Rates, Average Signal Scores) and search/filter historical campaigns.
• Review Workstation: Interactive live console displaying real-time agent step steppers and log streams, transitioning into a dual review pane presenting:
  • Scored signals matrix with categories and confidence levels.
  • Form editing sandbox to modify, approve, or reject generated subjects/bodies/CTAs.

---

Setup & Installation

Prerequisites

• Python 3.12+
• Node.js 18+ or 24+
• (Optional) Ollama running locally with llama3.1 pulled:

  ollama pull llama3.1

---

Step 1: Backend Setup

1. Navigate to the backend/ directory:

   cd backend

2. Create and activate a Python virtual environment:

   python -m venv .venv
   # Windows PowerShell
   .\.venv\Scripts\Activate.ps1
   # Linux/macOS
   source .venv/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

4. Create your .env configuration file:

   cp .env.example .env

Connection Configurations in .env:

• For SQLite:

  DATABASE_URL=sqlite:///./signal_iq.db

• For PostgreSQL & pgAdmin: Install pgAdmin and create a PostgreSQL database. Set the environment variable:

  DATABASE_URL=postgresql://username:password@localhost:5432/dbname

• LLM Failover Setup (Gemini → Ollama): Provide a Google Gemini API Key. If the API is rate-limited or fails, the orchestrator automatically redirects structured validation prompts to your local Ollama server.

  LLM_PROVIDER=gemini
  GEMINI_API_KEY=your_gemini_key_here
  OLLAMA_BASE_URL=http://localhost:11434
  OLLAMA_MODEL=llama3.1

5. Launch the FastAPI server:

   python -m uvicorn app.main:app --reload

   The backend API will run on http://127.0.0.1:8000.

---

Step 2: Frontend Setup

1. Navigate to the frontend/ directory:

   cd ../frontend

2. Install Node packages:

   npm install

3. Start the Next.js dev server:

   npm run dev

4. Open http://localhost:3000 in your browser.

---

System Workflow

               Prospect Input Form
                       │
                       ▼
         Research Agent (DuckDuckGo + BS4)
                       │
                       ▼
       Signal Extraction Agent (Pydantic Output)
                       │
                       ▼
        Signal Ranking Agent (Hook Selection)
                       │
                       ▼
            ┌──► Copywriter Agent
            │          │
            │          ▼
            │     QA Review Agent
            │          │
            └──────────┴──────────► Approved Outreach Draft (Human Review Workstation)
                    (Max 2 Loops)