Social-to-Lead Agentic Workflow

Production-ready Python project skeleton for a conversational AI workflow that classifies user intent, answers product inquiries via local RAG, and captures qualified leads only after required details are collected.

Folder Structure

project_root/
│── app.py
│── config/
│   ├── __init__.py
│   ├── app_config.json
│   ├── providers.py
│   └── settings.py
│── agent/
│   ├── __init__.py
│   ├── intent_classifier.py
│   └── workflow.py
│── rag/
│   ├── __init__.py
│   ├── knowledge_base.py
│   ├── pipeline.py
│   └── retriever.py
│── tools/
│   ├── __init__.py
│   └── lead_capture.py
│── memory/
│   ├── __init__.py
│   └── conversation_memory.py
│── utils/
│   ├── __init__.py
│   ├── json_utils.py
│   └── validators.py
│── data/
│   └── knowledge_base.json
│── tests/
│   ├── test_agent_flow.py
│   ├── test_intent_classifier.py
│   └── test_rag_pipeline.py
│── requirements.txt
│── README.md

Setup

1. Create and activate a Python 3.9+ virtual environment.
2. Install dependencies:

pip install -r requirements.txt

3. Optional: configure provider and model in environment variables (or config/app_config.json):

• LLM_PROVIDER = mock | openai | gemini | claude
• LLM_MODEL = model name for chosen provider
• OPENAI_API_KEY, GOOGLE_API_KEY, ANTHROPIC_API_KEY as needed

Run Locally

python app.py

Run Tests

pytest -q

Architecture (Overview)

This project uses a modular agentic architecture centered on a LangGraph workflow. Each user turn enters the graph at intent classification, where an LLM-based classifier returns structured JSON (greeting, product_inquiry, or high_intent_lead). For product inquiries, the system uses a local RAG pipeline: JSON knowledge is loaded into a lightweight document model, then a keyword retriever scores and returns top matches, and the LLM produces a grounded answer from those retrieved snippets. For high-intent interactions, the workflow enters a lead collection path that accumulates name, email, and platform in stateful memory before tool execution. The lead capture tool is protected by a strict readiness check so it runs only when all required fields are available. Memory is intentionally separated from the workflow and stores bounded multi-turn history (default 6 turns), active intent, and progressive lead fields. Provider abstraction is isolated in config/providers.py, allowing runtime switching between OpenAI, Gemini, Claude, and a deterministic mock provider for local development and tests.

WhatsApp Webhook Integration (How to Extend)

To integrate with WhatsApp, add a lightweight web server (e.g., FastAPI/Flask) with a webhook endpoint that receives inbound messages from the WhatsApp Business API provider. Parse sender ID and message text, then map each sender to a persistent SocialLeadAgent instance (or persistent memory store keyed by sender). Pass message text to agent.process_turn(...) and send the returned response back through WhatsApp's outbound message API. For production, replace in-memory lead storage with a database and add signature verification, retry handling, idempotency keys, and structured logging. This repo is already organized so webhook transport logic can be added without changing core agent, RAG, or tool modules.