---
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.