Spaces:
Sleeping
Sleeping
File size: 5,124 Bytes
f0e28a4 e9fa71b f0e28a4 91ad377 f0e28a4 87173c6 91ad377 87173c6 e663164 91ad377 59b4838 91ad377 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 | ---
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. |