Update README.md

README.md

@@ -7,216 +7,45 @@ 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.**
-
----
-
-## Runtime Error Diagnostic & Remediation (Nov 2025)
-
-### Problem Identified
-The Space experienced a `ModuleNotFoundError: No module named 'transformers'` runtime error at startup. The error traceback showed:
-```
-File "/app/app.py", line 2, in <module>
-    from lead_scoring_agent import LeadScoringAgent
-File "/app/lead_scoring_agent.py", line 13, in <module>
-    from transformers import pipeline
-ModuleNotFoundError: No module named 'transformers'
-```
-
-### Root Cause
-The `lead_scoring_agent.py` module imports `from transformers import pipeline` (line 13), which is required for HuggingFace model-based lead scoring functionality. However, the `transformers` library dependency was commented out in `requirements.txt` (line 16: `# transformers>=4.35.0  # Uncomment if using HuggingFace models`).
-
-### Remediation
-**Action taken:** Uncommented the `transformers>=4.35.0` dependency in `requirements.txt` (commit 2812a465d20a511d453648b52e546bbba1d87532).
-
-**Explanation:** The `transformers` library is essential for the lead scoring agent's NLP-based analysis capabilities. With the dependency now active, the Space container can install the required package during build, resolving the import error.
-
-**Verification:** After the fix, the Space should rebuild automatically and transition from "Runtime error" to "Running" state. Monitor build logs to confirm successful installation of transformers and dependencies.
-
-### Best Practices Going Forward
-- **Dependency Audit:** When adding new agent modules that import external libraries, ensure all dependencies are declared in `requirements.txt`.
-- **Import Testing:** Run local imports or CI checks before deploying to catch missing dependencies early.
-- **Documentation Alignment:** Keep inline comments in `requirements.txt` synchronized with actual code imports to prevent confusion.
-
----
-
-## Pipeline Workflow
+## Granular UI Features (Nov 2025)
+### New Compliance, Audit, Branching & Diagnostics Widgets
 
-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`).
+#### 1. Consent/Event Audit Panel
+Shows all consent events, opt-outs, and compliance flags per contact and batch. 
+- **Backend mapping:** Receives list of consent events (JSON, e.g. {contact_id, event_type, opt_out, compliance_flag}) per contact or batch.
+- **UI mapping:** Gradio panel renders event history per contact, batch aggregation, flags out-of-policy events.
+- **State schema:** See /docs/configs/compliance_schema.json.
 
-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.
+#### 2. Dynamic Cadence Branching Composer
+Visual builder for editing & previewing cadence sequences (multi-step outreach flows with conditional logic)
+- **Backend mapping:** Mirrored to cadence state JSON (see cadence_agent.py / docs/configs/cadence_tree.json)
+- **UI mapping:** Interactive tabular/tree UI shows each step, transition, and condition (see new app.py logic).
+- **Inline code:** Each logic widget/function takes the backend structure as argument.
 
-3. **Lead Scoring** (`lead_scoring_agent.py`) - NEW:
-   - Scores lead profiles based on firmographic, behavioral, and engagement signals.
-   - Enriches profiles with scoring metadata and rationale.
-   - Integrated into validation workflow at action start for each lead review.
+#### 3. Live Diagnostics Panel (Incidents/Health)
+Shows real-time and historical such as error, warning, info events for cadence or batch operations.
+- **Backend mapping:** List of incidents/events from backend diagnostics state (event objects: {timestamp, type, message, level})
+- **UI mapping:** Gradio Markdown log renders type/level/message per event.
+- **Config:** Event/incident schema in docs/configs/diagnostics_schema.json
 
-4. **Human/Machine Validation** (`human_validation_agent.py`):
-   - Receives enriched assets where automated logic lacks confidence.
-   - **NEW:** Scores each lead profile at action start using `lead_scoring_agent`.
-   - **NEW:** Passes scoring results and enrichment data to downstream handlers.
-   - Interactive review and correction (UI or API endpoint).
-   - Returns enriched/validated/scored assets to pipeline.
-
-5. **Outreach/Engagement** (`outreach_agent.py`):
-   - Selects template, personalizes using context fields and scoring signals.
-   - Delivers via pluggable channels: email, LinkedIn, SMS, browser automation.
-   - Supports automated social actions and feedback.
-
-6. **Analytics & Reporting** (`analytics_agent.py`):
-   - Logs all asset/channel outcomes, engagement stats, and scoring performance.
-   - Computes dashboards, actionable feedback, and improvement triggers.
-
-7. **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 with lead scoring.
-- `/score` (**POST**) - NEW: Score lead profiles using lead_scoring_agent; returns scoring metadata.
-- `/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 and scoring status.
-- Visualization of validation/enrichment status, gaps, overrides (human/manual call-outs), and lead scores.
-- Outreach composer: preview, edit, and dispatch personalized messages across channels using scoring signals.
-- Live stats: engagement rates, delivery status, trigger diagnostics, scoring performance metrics, per-asset and per-campaign.
-- Agent handoff log: view/trace enrichment, validation, scoring, and outreach chain per asset.
-
----
+#### 4. Exportable Audit Trail (Compliance/Debug)
+CSV/text export of event history (compliance and debug records)
+- **Backend mapping:** Batch history as list of per-event dicts, same as consent_audit schema.
+- **UI mapping:** Text/csv box (downloadable) shows organized history—maps to regulatory & support request export needs.
 
-## Lead Scoring Integration (NEW)
-
-### Overview
-The `lead_scoring_agent` module scores lead profiles based on multiple signals and enriches them with contextual metadata. The `human_validation_agent` integrates lead scoring at the point of action start—each lead review now includes:
-- Score result (numeric or categorical)
-- Scoring rationale and signal breakdown
-- Enriched profile data
-- Scoring metadata for downstream use
-
-### Key Features
-- **Import & Initialization**: `human_validation_agent` imports `LeadScoringAgent` and initializes it on instantiation.
-- **Action-Start Scoring**: `process_review_action()` scores the lead profile before action execution.
-- **Schema Updates**: `LeadReview` schema extended with `scoring_result` and `enrichment_data` fields.
-- **Batch Scoring**: `process_batch_review()` scores all leads in the batch, passing metadata downstream.
-- **History Export**: Review history JSON export includes scoring metadata for each review.
-- **Error Handling**: Scoring failures logged and tracked without blocking review actions.
-
-### Integration Points
-- **LeadReview Schema**: New optional fields: `scoring_result` (Dict), `enrichment_data` (Dict).
-- **HumanValidationAgent.score_lead_profile()**: Calls `lead_scoring_agent.score_lead()` and retrieves enrichment data.
-- **HumanValidationAgent.process_review_action()**: Scores profile at action start; stores metadata with review.
-- **HumanValidationAgent.process_batch_review()**: Iterates batch reviews, scoring each and collecting results.
-- **API & UI**: `/validate` endpoint receives and returns scoring metadata; dashboard displays scores and rationale.
-
-### Example Usage
-```python
-from human_validation_agent import HumanValidationAgent, BatchReviewRequest
-
-agent = HumanValidationAgent()
-
-# Single review with scoring
-review_data = {
-    "lead_id": "lead_001",
-    "action": "approve",
-    "reviewer_id": "reviewer_123"
-}
-result = agent.process_review_action(LeadReview(**review_data))
-print(result)  # Includes scoring_metadata with score_result and enrichment_data
-
-# Batch review with scoring for each lead
-batch_request = BatchReviewRequest(
-    reviews=[
-        LeadReview(lead_id="lead_001", action="approve", reviewer_id="reviewer_123"),
-        LeadReview(lead_id="lead_002", action="edit", edited_data={...}, reviewer_id="reviewer_123"),
-        LeadReview(lead_id="lead_003", action="scrub", reason="competitor", reviewer_id="reviewer_123")
-    ]
-)
-results = agent.process_batch_review(batch_request)
-print(results)  # All results include scoring metadata
-```
-
----
-
-## Test Case Logic
-
-- Test scripts: `test_schema_tools.py`, `test_validation.py` (unit tests for all schema/enrichment/validation logic).
-- **NEW**: Test lead scoring integration in `test_validation.py`; verify scoring metadata in reviews.
-- 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, lead scoring, pipeline/integration chain.
-
----
-
-## Agent & Asset Wiring
-
-- Each module is pluggable: you can sub in new enrichment, validation, scoring, or channel handler without altering others.
-- **NEW**: Lead scoring agent decoupled from validation—can be swapped or augmented independently.
-- Agent handoff: all context (original, intermediate states, **scoring metadata**) passes via in-memory or file-based serialization; reference logic in `enrichment_handoff_simulation.py` (`docs/`).
-- Asset state maintained through pipeline, logging all hops including scoring. Schemas upgradable (see `SCHEMA_VERSIONING.md`).
-
----
-
-## Upgrade & Migration Guide
-
-- **Schema Versioning**: Asset, enrichment, and analytics schema tracked with incremental migrations (`SCHEMA_VERSIONING.md`).
-  - **NEW**: `LeadReview` schema v2 includes `scoring_result` and `enrichment_data` fields (backward compatible).
-- **Lead Scoring Integration**: Ensure `lead_scoring_agent.py` is available in the same namespace; import validated on `HumanValidationAgent` instantiation.
-- **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, review and score leads, 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.
-  - **NEW**: If scoring fails, error logged in `validation_errors`; review continues without score.
-  - Verify `lead_scoring_agent` module is importable; check namespace and dependencies.
-  - Update configs/schemas via `docs/configs/` for custom needs.
-
----
+#### Usage & API Mapping
+- All widgets assume backend compliance/cadence events via standardized JSON from respective APIs (see /api/diagnostics, /api/cadence, /api/compliance, etc).
+- See app.py for inline documentation on each panel/component; argument signatures require the backend state JSON (typically list[dict]).
 
-## Module, Config, Script, and Logic Reference
+#### Inline Documentation Examples (app.py)
+- Each widget (audit, diagnostics, branching, export) is documented inline for both UI and state/JSON structure.
+- You can customize backend structure via docs/configs/ files and panel logic will adopt new schemas as format evolves.
 
-- **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`
-  - **NEW**: `lead_scoring_agent.py` (lead profile scoring and enrichment)
-- **Config Files**:
-  - All YAML/JSON in `docs/configs/`, plus channel/handler settings in each agent.
-  - **NEW**: Lead scoring configuration in `docs/configs/scoring_config.yaml` (signal weights, thresholds, etc.)
-- **Schema & Versioning**:
-  - `schema_registry.py`, `SCHEMA_VERSIONING.md`
-  - **NEW**: Updated `LeadReview` schema with scoring fields in v2
-- **Test Scripts**:
-  - `test_schema_tools.py`, `test_validation.py`
-  - **NEW**: Lead scoring integration tests in `test_validation.py`
-- **Agent Handoff Logic**:
-  - `docs/enrichment_handoff_simulation.py`
-  - **NEW**: Scoring metadata passed through handoff chain
+## Example Panel Usage
+Example construction is provided in app.py showing default data structures and rendering each widget in a Gradio tab.
 
 ---
+(legacy platform and API docs retained below)
 
-For further explanation, workflows, and custom case studies—see full documentation and module-level docstrings.