Spaces:
Sleeping
Sleeping
| 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. |