Update README.md

README.md

@@ -5,86 +5,112 @@ colorFrom: blue
 colorTo: purple
 sdk: gradio
 pinned: false
-short_description: A simple Gradio app that greets users by name
+short_description: A simple Gradio app
 ---
-# StrategyStack Recovery/Enrichment & Outreach Agents
 
-(...existing content above remains unchanged...)
+# StrategyStack Recovery, Enrichment & Outreach Platform
+
+**Modular pipeline for automated asset enrichment, engagement, analytics, and agent/handoff orchestration—including API, UI, test logic, upgrade/migration, and troubleshooting.**
+
+---
+
+## Pipeline Workflow
+
+1. **Input/Asset Ingestion** (`activity_ingestion.py`):
+   - Receives assets or lead lists (CSV, API, UI submission).
+   - Validates schema (see `schema_registry.py`).
+   - Logs activity (`activity_log.csv`).
+2. **Automated Enrichment** (`recovery_enrichment_agent.py`):
+   - Fills gaps: persona, recent posts, complaints, engagement metrics.
+   - Invokes external APIs as needed or generates synthetic context.
+   - Handoff to validation agent if enrichment uncertain.
+3. **Human/Machine Validation** (`human_validation_agent.py`):
+   - Receives enriched assets where automated logic lacks confidence.
+   - Interactive review and correction (UI or API endpoint).
+   - Returns enriched/validated assets to pipeline.
+4. **Outreach/Engagement** (`outreach_agent.py`):
+   - Selects template, personalizes using context fields.
+   - Delivers via pluggable channels: email, LinkedIn, SMS, browser automation.
+   - Supports automated social actions and feedback.
+5. **Analytics & Reporting** (`analytics_agent.py`):
+   - Logs all asset/channel outcomes, engagement stats.
+   - Computes dashboards, actionable feedback, and improvement triggers.
+6. **Research/Search Integration** (`research_agent.py`, `query_search_agent.py`):
+   - Supplements enrichment with web or corpus search, updates context/data.
+   - Used by outreach for deep personalization or compliance needs.
+
+---
+
+## API Endpoints
+
+- `/ingest` (**POST**): Upload asset batch (CSV/JSON), triggers validation & enrichment.
+- `/validate` (**POST**): Human/machine validation of asset content.
+- `/enrich` (**POST**): Force re-enrichment or supplemental context fill.
+- `/outreach` (**POST**): Initiates personalized outreach actions; returns status/transcript.
+- `/analytics` (**GET**): Fetch per-asset, per-campaign, or global reports/statistics.
+- **Authentication/Authorization**: All endpoints respect granular role controls, see config in `docs/configs/`.
+
+---
+
+## UI Dashboard Features
+
+- Asset ingestion/upload table with schema/state indicators.
+- Visualization of validation/enrichment status, gaps, and overrides (human/manual call-outs).
+- Outreach composer: preview, edit, and dispatch personalized messages across channels.
+- Live stats: engagement rates, delivery status, trigger diagnostics, per-asset and per-campaign.
+- Agent handoff log: view/trace enrichment, validation, and outreach chain per asset.
+
+---
+
+## Test Case Logic
+
+- Test scripts: `test_schema_tools.py`, `test_validation.py` (unit tests for all schema/enrichment/validation logic).
+- CI-friendly: All test scripts runnable standalone or via `pytest`, support fixtures for human/machine edge cases.
+- Example cases cover incomplete asset, fuzzy enrichment, validation override, pipeline/integration chain.
+
+---
+
+## Agent & Asset Wiring
+
+- Each module is pluggable: you can sub in new enrichment, validation, or channel handler without altering others.
+- Agent handoff: all context (original, intermediate states) passes via in-memory or file-based serialization; reference logic in `enrichment_handoff_simulation.py` (`docs/`).
+- Asset state maintained through pipeline, logging all hops. Schemas upgradable (see `SCHEMA_VERSIONING.md`).
+
+---
+
+## Upgrade & Migration Guide
+
+- **Schema Versioning**: Asset, enrichment, and analytics schema tracked with incremental migrations (`SCHEMA_VERSIONING.md`).
+- **Future DB Integration**: Swap out CSV with SQL/NoSQL backend by implementing new state store hooks in `app.py` and updating config in `docs/configs/`.
+- Migration scripts: Provided for legacy log/asset conversion.
+
+---
+
+## Best Practices: Setup, Usage, Troubleshooting
+
+- **Setup**: `pip install -r requirements.txt`; run `app.py` to launch UI and API.
+- **Usage**: Ingest assets via UI or API, follow pipeline in dashboard, manually validate flagged inputs.
+- **Troubleshooting**:
+  - Logs/errors to console and CSV.
+  - Validation steps highlight schema mismatches.
+  - Check agent handoff logs for stuck or dropped assets.
+  - Update configs/schemas via `docs/configs/` for custom needs.
 
 ---
-## 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. **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 outreach_agent import OutreachAgent, email_handler, linkedin_handler, sms_handler
-
-# Initialize agent with pluggable channel handlers
-agent = OutreachAgent(channel_handlers={
-    "email": email_handler,
-    "linkedin": linkedin_handler,
-    "sms": sms_handler
-})
-
-# 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."
-})
-# 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)
-```
-
-### 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
-
-### Channel Handler Example
-- Add your own channel support by implementing a handler function:
-```python
-def whatsapp_handler(profile, message):
-    # Send WhatsApp message here
-    return {"status": "sent_via_whatsapp", "recipient": profile.get("phone", "n/a"), "message": message}
-```
-
-### 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
+
+## Module, Config, Script, and Logic Reference
+
+- **Core Modules**: 
+  - `activity_ingestion.py`, `outreach_agent.py`, `recovery_enrichment_agent.py`, `analytics_agent.py`, `research_agent.py`, `human_validation_agent.py`, `query_search_agent.py`
+- **Config Files**:
+  - All YAML/JSON in `docs/configs/`, plus channel/handler settings in each agent.
+- **Schema & Versioning**:
+  - `schema_registry.py`, `SCHEMA_VERSIONING.md`
+- **Test Scripts**:
+  - `test_schema_tools.py`, `test_validation.py`
+- **Agent Handoff Logic**:
+  - `docs/enrichment_handoff_simulation.py`
 
 ---
+
+For further explanation, workflows, and custom case studies—see full documentation and module-level docstrings.