Update README.md

DOC: Add lead_scoring_agent integration documentation to README

- Add new Pipeline Workflow step 3: Lead Scoring (lead_scoring_agent.py)
- Document scoring integration in Human/Machine Validation step
- Add /score API endpoint documentation
- Document scoring features in UI Dashboard
- Add comprehensive "Lead Scoring Integration (NEW)" section with:
* Overview of scoring features and metadata
* Key features and integration points
* Example usage showing single review and batch review scoring
- Update schema versioning section with LeadReview v2 fields
- Add troubleshooting guidance for scoring failures and module import
- Reference lead_scoring_agent.py in Core Modules section
- Document scoring configuration reference in docs/configs/
- Update Test Case Logic with lead scoring integration tests
- Document scoring metadata passing through agent handoff chain

README.md

@@ -7,15 +7,11 @@ 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`).
@@ -24,93 +20,147 @@ short_description: A simple Gradio app
    - 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`):
+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.
+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 assets to pipeline.
-4. **Outreach/Engagement** (`outreach_agent.py`):
-   - Selects template, personalizes using context fields.
+   - 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.
-5. **Analytics & Reporting** (`analytics_agent.py`):
-   - Logs all asset/channel outcomes, engagement stats.
+6. **Analytics & Reporting** (`analytics_agent.py`):
+   - Logs all asset/channel outcomes, engagement stats, and scoring performance.
    - Computes dashboards, actionable feedback, and improvement triggers.
-6. **Research/Search Integration** (`research_agent.py`, `query_search_agent.py`):
+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.
+- `/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.
-- 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.
+- 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.
 
 ---
+## 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, pipeline/integration chain.
+- 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, 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`).
+- 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, manually validate flagged inputs.
+- **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.
 
 ---
-
 ## 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`
+  - **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
 
 ---
-
 For further explanation, workflows, and custom case studies—see full documentation and module-level docstrings.