README.md

metadata

title: README
emoji: 🚀
colorFrom: blue
colorTo: purple
sdk: gradio
pinned: false
short_description: A simple Gradio app

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.

---

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.