Update README with comprehensive Human Validation Agent documentation

README.md

@@ -7,7 +7,6 @@ sdk: gradio
 pinned: false
 short_description: A simple Gradio app that greets users by name
 ---
-
 # StrategyStack Recovery/Enrichment Agent
 
 ## Overview
@@ -19,15 +18,208 @@ This repository contains a modular recovery/enrichment agent capable of prioriti
 - Activity logging for all agent actions, outcome, errors, and escalations in [`activity_log.csv`](./activity_log.csv).
 - Modular integration: Upstream and downstream agent handoff (query_search_agent, validation_agent, etc.) supported for live flows.
 
+## Human Validation Agent Module
+
+The Human Validation Agent module provides comprehensive functionality for manual review and validation of leads that require human intervention. This module is fully integrated with the lead queue system and provides robust validation, feedback, and handoff capabilities.
+
+### Key Features
+
+1. **Queue Integration**
+   - Automatically pulls leads marked with `needs_human_review` flag from the queue
+   - Supports configurable batch sizes for efficient review workflows
+   - Filters by status (`pending_review`, `flagged`) for targeted processing
+
+2. **Batch Review Interface**
+   - Process multiple leads in a single batch operation
+   - Four resolution options:
+     - **Approve**: Move lead to approved queue for downstream processing
+     - **Edit**: Update lead data and move to approved queue
+     - **Hold**: Keep in review queue with hold status for retry
+     - **Scrub**: Archive lead with documented reason
+
+3. **Schema Validation**
+   - Pydantic-based schema validation for all review actions
+   - Business rule validation (e.g., required fields for edit actions)
+   - Reason validation for hold and scrub actions (minimum 10 characters)
+   - Real-time validation feedback with user-friendly error messages
+
+4. **Feedback & Guardrails**
+   - Invalid actions are rejected with clear, actionable feedback
+   - Comprehensive error handling and logging
+   - Validation error tracking for audit purposes
+   - Success rate statistics and review analytics
+
+5. **Resolution & Handoff**
+   - **Approved leads**: Routed to `approved_leads` queue for downstream processing
+   - **Edited leads**: Updated data validated and routed to `approved_leads` queue
+   - **Held leads**: Maintained in `on_hold` queue with documented reason
+   - **Scrubbed leads**: Archived to `scrubbed_leads` queue with reason
+
+### API Interface
+
+```python
+from human_validation_agent import HumanValidationAgent, create_review_interface
+
+# Initialize agent
+agent = HumanValidationAgent(queue_connection=your_queue_connection)
+
+# Create interface
+interface = create_review_interface(agent)
+
+# Get pending reviews
+pending_leads = interface["get_pending_reviews"](limit=50)
+
+# Submit single review
+review_result = interface["submit_review"]({
+    "lead_id": "lead_001",
+    "action": "approve",
+    "reviewer_id": "reviewer_123"
+})
+
+# Submit batch review
+batch_result = interface["submit_batch_review"]({
+    "reviews": [
+        {
+            "lead_id": "lead_001",
+            "action": "approve",
+            "reviewer_id": "reviewer_123"
+        },
+        {
+            "lead_id": "lead_002",
+            "action": "edit",
+            "edited_data": {
+                "name": "Updated Name",
+                "email": "updated@email.com",
+                "company": "Updated Corp"
+            },
+            "reviewer_id": "reviewer_123"
+        },
+        {
+            "lead_id": "lead_003",
+            "action": "scrub",
+            "reason": "Lead is a competitor and not a valid prospect",
+            "reviewer_id": "reviewer_123"
+        }
+    ]
+})
+
+# Get statistics
+stats = interface["get_stats"]()
+
+# Export history
+interface["export_history"]("review_history.json")
+```
+
+### Schema Definitions
+
+#### LeadReview Schema
+```python
+{
+    "lead_id": str,                    # Required: Unique lead identifier
+    "action": str,                     # Required: "approve", "edit", "hold", or "scrub"
+    "reason": str | None,              # Required for "hold" and "scrub" actions
+    "edited_data": dict | None,        # Required for "edit" action
+    "reviewer_id": str,                # Required: Reviewer identifier
+    "reviewed_at": datetime            # Auto-generated timestamp
+}
+```
+
+#### BatchReviewRequest Schema
+```python
+{
+    "reviews": List[LeadReview],       # Required: List of review objects
+    "batch_id": str | None             # Optional: Batch identifier
+}
+```
+
+### Validation Rules
+
+1. **Approve Action**: No additional fields required
+2. **Edit Action**: Must include `edited_data` with required fields (`name`, `email`, `company`)
+3. **Hold Action**: Must include `reason` (minimum 10 characters)
+4. **Scrub Action**: Must include `reason` (minimum 10 characters)
+
+### Response Format
+
+#### Batch Review Response
+```json
+{
+  "batch_id": "batch_1730832123.456",
+  "total_reviews": 3,
+  "successful": 2,
+  "failed": 1,
+  "results": [
+    {
+      "lead_id": "lead_001",
+      "action": "approve",
+      "status": "approved",
+      "next_queue": "approved_leads",
+      "timestamp": "2025-11-05T13:23:00"
+    }
+  ],
+  "errors": [
+    {
+      "lead_id": "lead_002",
+      "error": "Missing required field in edited_data: email",
+      "feedback": "Edited lead data must include all required fields: name, email, and company."
+    }
+  ]
+}
+```
+
+### Statistics & Reporting
+
+The agent tracks comprehensive statistics:
+- Total reviews processed
+- Reviews by action type (approve, edit, hold, scrub)
+- Validation error count
+- Success rate calculation
+- Full history export to JSON
+
+### Integration Points
+
+1. **Upstream**: Receives leads from enrichment agent or browser agent
+2. **Queue Connection**: Queries and updates lead queue system
+3. **Downstream**: Routes to appropriate queues based on action:
+   - `approved_leads` → Next processing stage
+   - `on_hold` → Temporary hold for retry
+   - `scrubbed_leads` → Archived/removed from pipeline
+
+### Error Handling
+
+- Schema validation errors return detailed feedback
+- Business rule violations provide actionable guidance
+- All errors logged with timestamps for audit
+- Failed reviews don't block successful reviews in batch operations
+
+### Audit Trail
+
+All review activities are logged with:
+- Lead ID and action taken
+- Reviewer ID and timestamp
+- Reason for hold/scrub actions
+- Updated fields for edit actions
+- Validation errors and feedback
+- Export capability for compliance reporting
+
+---
+
 ## Usage
+
 1. **Configure enrichment sources:**
    Edit `docs/configs/enrichment_config.json` to set source order, rate limits, retry policies, and handoff rules.
+
 2. **Run simulation or queue handoff:**
    Execute `docs/enrichment_handoff_simulation.py` to simulate a queue item enrichment with browser fallback and human escalation.
-3. **Audit log review:**
+
+3. **Human validation workflow:**
+   Use `human_validation_agent.py` to pull and review leads requiring manual intervention.
+
+4. **Audit log review:**
    Inspect `activity_log.csv` for all enrichment, handoff, error, and escalation events (timestamped and detailed).
 
 ## Example Config
+
 ```json
 {
   "enrichment_sources": {
@@ -44,6 +236,7 @@ This repository contains a modular recovery/enrichment agent capable of prioriti
 ```
 
 ## Live Integration
+
 - **Upstream:** Receives items from ingest/query queue.
 - **Enrichment:** Prioritized API calls with fallback if rates/quality unmet.
 - **Browser Agent:** Triggered if API unavailable, rate-limited, or data quality insufficient.
@@ -51,8 +244,9 @@ This repository contains a modular recovery/enrichment agent capable of prioriti
 - **Audit Trail:** Complete log of actions, fallback, escalations in CSV.
 
 ## Preparing for Next Agent
+
 - Extend `docs/configs/enrichment_config.json` to add sources or escalation criteria.
 - Integrate additional downstream agents via `integration` section of config.
 - Full audit log available for compliance/modules handoff.
 
----
+---