Update README.md

README.md

@@ -7,246 +7,84 @@ sdk: gradio
 pinned: false
 short_description: A simple Gradio app that greets users by name
 ---
-# StrategyStack Recovery/Enrichment Agent
+# StrategyStack Recovery/Enrichment & Outreach Agents
 
-## Overview
-This repository contains a modular recovery/enrichment agent capable of prioritized multi-source enrichment, live queue handoff, browser automation fallback, and human-in-the-loop escalation. All actions, outcomes, and escalations are logged for full audit and compliance.
+(...existing content above remains unchanged...)
 
-## Key Features
-- Configurable prioritized enrichment sources, rate limits, and retry logic: see [`docs/configs/enrichment_config.json`](./docs/configs/enrichment_config.json).
-- Simulated queue handoff to enrichment agent, with browser agent fallback and human review escalation: see [`docs/enrichment_handoff_simulation.py`](./docs/enrichment_handoff_simulation.py).
-- Activity logging for all agent actions, outcome, errors, and escalations in [`activity_log.csv`](./activity_log.csv).
-- Modular integration: Upstream and downstream agent handoff (query_search_agent, validation_agent, etc.) supported for live flows.
-
-## Human Validation Agent Module
-
-The Human Validation Agent module provides comprehensive functionality for manual review and validation of leads that require human intervention. This module is fully integrated with the lead queue system and provides robust validation, feedback, and handoff capabilities.
+---
+## Outreach Automation & Personalization Agent: `outreach_agent.py`
+### Overview
+The `outreach_agent.py` module provides advanced, high-fidelity outbound engagement with:
+- Extensive lead enrichment and validation
+- Context-specific message tailoring with maximal personalization
+- Fully pluggable multi-channel delivery (Email, LinkedIn, SMS, Browser/Agent automation)
+- Support for rich variables: context snippets, recent posts, complaints, industry hooks, urgency cues
+- Automated browser-based social actions (connect, DM, comment, like, milestone)
+- Robust error handling, analytics, engagement feedback loop, and lead asset state update
 
 ### Key Features
-
-1. **Queue Integration**
-   - Automatically pulls leads marked with `needs_human_review` flag from the queue
-   - Supports configurable batch sizes for efficient review workflows
-   - Filters by status (`pending_review`, `flagged`) for targeted processing
-
-2. **Batch Review Interface**
-   - Process multiple leads in a single batch operation
-   - Four resolution options:
-     - **Approve**: Move lead to approved queue for downstream processing
-     - **Edit**: Update lead data and move to approved queue
-     - **Hold**: Keep in review queue with hold status for retry
-     - **Scrub**: Archive lead with documented reason
-
-3. **Schema Validation**
-   - Pydantic-based schema validation for all review actions
-   - Business rule validation (e.g., required fields for edit actions)
-   - Reason validation for hold and scrub actions (minimum 10 characters)
-   - Real-time validation feedback with user-friendly error messages
-
-4. **Feedback & Guardrails**
-   - Invalid actions are rejected with clear, actionable feedback
-   - Comprehensive error handling and logging
-   - Validation error tracking for audit purposes
-   - Success rate statistics and review analytics
-
-5. **Resolution & Handoff**
-   - **Approved leads**: Routed to `approved_leads` queue for downstream processing
-   - **Edited leads**: Updated data validated and routed to `approved_leads` queue
-   - **Held leads**: Maintained in `on_hold` queue with documented reason
-   - **Scrubbed leads**: Archived to `scrubbed_leads` queue with reason
-
-### API Interface
-
+1. **Lead Intake & Validation**: Accepts, validates, and enriches leads for personalized messaging. Can auto-resolve incomplete fields and flags for missing persona or channel fit.
+2. **Template Selection & Personalization**: Chooses and dynamically adapts outreach templates leveraging persona, pain/opportunity, buyer signals, historical engagement, and channel fit. Supports deep mapping of all relevant profile details.
+3. **Rich Variables Support**: Message logic can use highly granular fields—contextual snippets, recent social or product posts, customer complaints, competitor/industry hooks, urgency/trigger events, and custom tags.
+4. **Omnichannel Delivery**: Channel handlers for Email, LinkedIn, SMS, or direct browser-agent control. Pluggable dispatch for easy integration of new channels.
+5. **Social Automation**: If browser-agent/capabilities available, automates connect, DM, comment, like, and milestone outreach on supported social platforms.
+6. **Error Handling & Feedback Loop**: Comprehensive try/except with logging per-action and per-lead. Delivered message and social actions update lead analytics and asset state. Feedback methods enable continuous learning loop.
+7. **Engagement Analytics & Traceability**: Per-lead transcript, channel actions, engagement results and context mapping are stored and can be queried for real-time stats or compliance reporting.
+8. **Easy Integration**: Fully modular—custom channel handlers, callback hooks, and analytics sinks can be swapped in as business needs evolve.
+
+### Example Usage
 ```python
-from human_validation_agent import HumanValidationAgent, create_review_interface
-
-# Initialize agent
-agent = HumanValidationAgent(queue_connection=your_queue_connection)
+from outreach_agent import OutreachAgent, email_handler, linkedin_handler, sms_handler
 
-# Create interface
-interface = create_review_interface(agent)
-
-# Get pending reviews
-pending_leads = interface["get_pending_reviews"](limit=50)
-
-# Submit single review
-review_result = interface["submit_review"]({
-    "lead_id": "lead_001",
-    "action": "approve",
-    "reviewer_id": "reviewer_123"
+# Initialize agent with pluggable channel handlers
+agent = OutreachAgent(channel_handlers={
+    "email": email_handler,
+    "linkedin": linkedin_handler,
+    "sms": sms_handler
 })
 
-# Submit batch review
-batch_result = interface["submit_batch_review"]({
-    "reviews": [
-        {
-            "lead_id": "lead_001",
-            "action": "approve",
-            "reviewer_id": "reviewer_123"
-        },
-        {
-            "lead_id": "lead_002",
-            "action": "edit",
-            "edited_data": {
-                "name": "Updated Name",
-                "email": "updated@email.com",
-                "company": "Updated Corp"
-            },
-            "reviewer_id": "reviewer_123"
-        },
-        {
-            "lead_id": "lead_003",
-            "action": "scrub",
-            "reason": "Lead is a competitor and not a valid prospect",
-            "reviewer_id": "reviewer_123"
-        }
-    ]
+# Intake enriched lead
+lead = agent.intake_lead({
+    "id": "lead_42",
+    "name": "Sam Patel",
+    "persona": "Operations Manager",
+    "pain_opportunity": "reducing manual workload by 30%",
+    "buyer_signals": ["asked for automation demo", "visited pricing"],
+    "channel_fit": "linkedin",
+    "recent_posts": ["Looking for workflow improvement ideas"],
+    "context_snippets": "Their company just merged with a large provider.",
+    "customer_complaint_tags": ["integration delays"],
+    "competitor_industry_hooks": ["AcmeSoft success story"],
+    "urgency_triggers": "Budget cycle renews in 2 weeks."
 })
-
-# Get statistics
-stats = interface["get_stats"]()
-
-# Export history
-interface["export_history"]("review_history.json")
+# Select template and personalize
+template = agent.select_template(lead)
+personalized = agent.tailor_message(lead, template)
+# Deliver via chosen channel
+delivery_result = agent.deliver(lead, personalized, channel="linkedin")
+# Automate a milestone outreach if desired
+soc_result = agent.browser_social_actions(lead, "connect")
+# Capture feedback and stats
+agent.feedback_loop(lead, feedback="Lead asked for more details.")
+transcript = agent.get_transcript("lead_42")
+print(transcript)
 ```
 
-### Schema Definitions
+### System & Integration Points
+- Integrates upstream from enrichment agent, downstream to analytics and customer asset store
+- Can be used stand-alone or in orchestration/chain with search, validation, or queue agents
+- Add custom channel or context processors as new channels emerge
 
-#### LeadReview Schema
+### Channel Handler Example
+- Add your own channel support by implementing a handler function:
 ```python
-{
-    "lead_id": str,                    # Required: Unique lead identifier
-    "action": str,                     # Required: "approve", "edit", "hold", or "scrub"
-    "reason": str | None,              # Required for "hold" and "scrub" actions
-    "edited_data": dict | None,        # Required for "edit" action
-    "reviewer_id": str,                # Required: Reviewer identifier
-    "reviewed_at": datetime            # Auto-generated timestamp
-}
+def whatsapp_handler(profile, message):
+    # Send WhatsApp message here
+    return {"status": "sent_via_whatsapp", "recipient": profile.get("phone", "n/a"), "message": message}
 ```
 
-#### BatchReviewRequest Schema
-```python
-{
-    "reviews": List[LeadReview],       # Required: List of review objects
-    "batch_id": str | None             # Optional: Batch identifier
-}
-```
-
-### Validation Rules
-
-1. **Approve Action**: No additional fields required
-2. **Edit Action**: Must include `edited_data` with required fields (`name`, `email`, `company`)
-3. **Hold Action**: Must include `reason` (minimum 10 characters)
-4. **Scrub Action**: Must include `reason` (minimum 10 characters)
-
-### Response Format
-
-#### Batch Review Response
-```json
-{
-  "batch_id": "batch_1730832123.456",
-  "total_reviews": 3,
-  "successful": 2,
-  "failed": 1,
-  "results": [
-    {
-      "lead_id": "lead_001",
-      "action": "approve",
-      "status": "approved",
-      "next_queue": "approved_leads",
-      "timestamp": "2025-11-05T13:23:00"
-    }
-  ],
-  "errors": [
-    {
-      "lead_id": "lead_002",
-      "error": "Missing required field in edited_data: email",
-      "feedback": "Edited lead data must include all required fields: name, email, and company."
-    }
-  ]
-}
-```
-
-### Statistics & Reporting
-
-The agent tracks comprehensive statistics:
-- Total reviews processed
-- Reviews by action type (approve, edit, hold, scrub)
-- Validation error count
-- Success rate calculation
-- Full history export to JSON
-
-### Integration Points
-
-1. **Upstream**: Receives leads from enrichment agent or browser agent
-2. **Queue Connection**: Queries and updates lead queue system
-3. **Downstream**: Routes to appropriate queues based on action:
-   - `approved_leads` → Next processing stage
-   - `on_hold` → Temporary hold for retry
-   - `scrubbed_leads` → Archived/removed from pipeline
-
-### Error Handling
-
-- Schema validation errors return detailed feedback
-- Business rule violations provide actionable guidance
-- All errors logged with timestamps for audit
-- Failed reviews don't block successful reviews in batch operations
-
-### Audit Trail
-
-All review activities are logged with:
-- Lead ID and action taken
-- Reviewer ID and timestamp
-- Reason for hold/scrub actions
-- Updated fields for edit actions
-- Validation errors and feedback
-- Export capability for compliance reporting
+### Logging & Feedback
+- Comprehensive action/error/info logging using standard Python logging to file/console
+- All actions update per-lead asset and engagement analytics in real time
 
 ---
-
-## Usage
-
-1. **Configure enrichment sources:**
-   Edit `docs/configs/enrichment_config.json` to set source order, rate limits, retry policies, and handoff rules.
-
-2. **Run simulation or queue handoff:**
-   Execute `docs/enrichment_handoff_simulation.py` to simulate a queue item enrichment with browser fallback and human escalation.
-
-3. **Human validation workflow:**
-   Use `human_validation_agent.py` to pull and review leads requiring manual intervention.
-
-4. **Audit log review:**
-   Inspect `activity_log.csv` for all enrichment, handoff, error, and escalation events (timestamped and detailed).
-
-## Example Config
-
-```json
-{
-  "enrichment_sources": {
-    "priority_order": ["crunchbase_api", "clearbit_api", "linkedin_browser"],
-    "source_configs": {
-      "crunchbase_api": {"rate_limit": {"requests_per_minute": 60}, "retry_policy": {"max_retries": 3}},
-      "linkedin_browser": {"requires_human_validation": true, "fallback_to_browser_agent": true}
-    }
-  },
-  "agent_handoff": {
-    "human_validation": {"enabled": true, "confidence_threshold": 0.75}
-  }
-}
-```
-
-## Live Integration
-
-- **Upstream:** Receives items from ingest/query queue.
-- **Enrichment:** Prioritized API calls with fallback if rates/quality unmet.
-- **Browser Agent:** Triggered if API unavailable, rate-limited, or data quality insufficient.
-- **Human Validation:** Escalates for manual review if confidence/compliance requires human-in-the-loop.
-- **Audit Trail:** Complete log of actions, fallback, escalations in CSV.
-
-## Preparing for Next Agent
-
-- Extend `docs/configs/enrichment_config.json` to add sources or escalation criteria.
-- Integrate additional downstream agents via `integration` section of config.
-- Full audit log available for compliance/modules handoff.
-
----