Federated from workspace · PRD-001 · Dental Clinic Revenue Operating System/docs/technical/ZAIXOS_AGENT_LEARNING_DATASET_PLATFORM.md Do not edit canonical truth here — update the source repo, then re-run npm run docs:sync.

---

ZAIXOS Agent Learning Dataset Platform

Status: Implemented (2026-07-05)
Authority: App\Modules\AI\Application\Learning
Ownership: Platform (authority: platform) — not product-owned

What this is

The Learning Dataset is ZAIXOS's enterprise ground-truth asset for agent quality. It is:

Is	Is NOT
Ground truth for evaluation	Runtime memory
Human-approved learning records	Conversation history dump
Benchmark input after approval	RAG knowledge base
Versioned, auditable asset	Auto-modifying production config

Architecture (additive)

Production Conversation
        ↓
Trace + Pipeline Evaluation
        ↓
PL-004 Analysis Bridge (recommendations only)
        ↓
Learning Dataset Candidate (pending_review)
        ↓
Human Review (mandatory)
        ↓
ai_learning_dataset_records (approved ground truth)
        ↓
Phrase Clustering (evaluation only)
        ↓
Benchmark Sync → ai:dataset:benchmark

Frozen: PL-003 planner/orchestrator, PL-005, PL-006 — unchanged.
PL-004: Analyzes via Pl004LearningAnalysisBridge — recommendations stored, never auto-applied.

Ground truth record schema

See AgentLearningDatasetRecordData — all fields from spec including expected/actual pipeline outputs, failure category, PL-004 recommendation, human approval, version, source trace.

Dataset sources

AgentLearningDatasetSource enum:

• production_conversation
• qa_team
• internal_testing
• acceptance_lab
• synthetic_llm
• imported_public
• clinic_staff
• customer_feedback
• benchmark_seed

Every record stores source + optional source_trace_id.

CLI

# Seed ground truth from benchmark factory
php artisan ai:dataset:import --seed

# Import production conversations → review queue
php artisan ai:dataset:import --limit=50

# Human approve / reject
php artisan ai:dataset:approve {candidate-uuid} --reviewer=moomen
php artisan ai:dataset:approve {candidate-uuid} --reject --reviewer=moomen

# Export ground truth JSON
php artisan ai:dataset:export

# Analytics
php artisan ai:dataset:statistics
php artisan ai:dataset:statistics --json
php artisan ai:dataset:coverage
php artisan ai:dataset:report
php artisan ai:dataset:failures --pending

# Run benchmark on approved dataset
php artisan ai:dataset:benchmark --sync

Legacy benchmark commands (ai:benchmark*) remain for evaluation-only workflows.

Phrase clustering

AgentLearningPhraseClusterer groups by intent key (intent:daily_report) — not regex, not runtime catalogs. Used for coverage analysis and learning analytics only.

Synthetic generation

AgentLearningSyntheticPhraseGenerator creates variation candidates (formal/casual/short/long, EN/AR/TR templates). All synthetic phrases enter pending review — never runtime.

Governance

Rule	Enforcement
Platform owns dataset	authority = platform on all records
Human approval required	AgentLearningApprovalService
Versioned changes	ai_learning_dataset_audit_log
PL-004 recommendations only	ai_learning_pl004_recommendations.status = pending_approval
No runtime routing from dataset	Isolation tests
Approved → benchmark	Sync on approve via AgentLearningApprovalService

Enterprise workflow

Production → Conversation → Trace → Evaluation
    → PL-004 Pattern Mining (bridge)
    → Recommendation (pending)
    → Acceptance Lab / Human Review
    → Dataset Update (approved)
    → Benchmark
    → Release Candidate
    → Production

Learning is always human-supervised. Production behavior is never self-modified.

Configuration

AI_LEARNING_DATASET_ENABLED=true
AI_LEARNING_PRODUCT=prd-001
AI_LEARNING_VERSION=1.0.0
AI_LEARNING_PL004_BRIDGE=true

Tests

php artisan test app/Modules/AI/Tests/Unit/AgentLearningDatasetTest.php
php artisan test app/Modules/AI/Tests/Unit/ClinicAgentBenchmarkRunnerTest.php

Related

• ZAIXOS_AGENT_BENCHMARK_PLATFORM.md
• ZAIXOS_AGENT_LEARNING_CERTIFICATION_REPORT.md