Wiki source code of POC1: Core Workflow with Quality Gates
Version 1.2 by Robert Schaub on 2025/12/22 14:32
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | = POC1: Core Workflow with Quality Gates = **Phase Goal:** Prove AKEL can produce credible, quality outputs without manual intervention **Success Metric:** <10% hallucination rate, quality gates prevent low-confidence publications == 1. Overview == POC1 validates that the core AKEL workflow (Article → Claims → Verdicts) can produce trustworthy fact-checking analyses automatically. This phase implements **2 critical quality gates** to prevent low-quality outputs from being published. **Key Innovation:** Quality validation BEFORE publication, not after **What We're Proving:** | ||
| 2 | * AKEL can reliably extract factual claims from articles | ||
| 3 | * AKEL can generate credible verdicts with proper evidence | ||
| 4 | * Quality gates prevent hallucinations and low-confidence outputs | ||
| 5 | * Fully automated approach is viable == 2. Scope == === In Scope === * Core AKEL workflow (claim extraction, verdict generation) | ||
| 6 | * **Gate 1:** Claim Validation (factual vs. opinion/prediction) | ||
| 7 | * **Gate 4:** Verdict Confidence Assessment (minimum 2 sources, quality thresholds) | ||
| 8 | * Basic UI to display results | ||
| 9 | * Manual quality tracking === Out of Scope (Deferred to POC2+) === * User accounts / authentication | ||
| 10 | * Corrections system | ||
| 11 | * Search engine optimization (ClaimReview schema) | ||
| 12 | * Image verification | ||
| 13 | * API endpoints | ||
| 14 | * Archive.org integration | ||
| 15 | * Security hardening | ||
| 16 | * A/B testing | ||
| 17 | * Gates 2 & 3 (Evidence relevance, Scenario coherence) == 3. Requirements == === 3.1 NFR11: Quality Assurance Framework (POC1 Lite Version) === **Priority:** CRITICAL - Core POC1 Requirement **Fulfills:** AI safety, credibility, prevents embarrassing failures **Specification:** AKEL must validate outputs before displaying to users. POC1 implements a **2-gate subset** of the full NFR11 framework. ==== Gate 1: Claim Validation ==== **Purpose:** Ensure extracted claims are factual assertions, not opinions or predictions **Validation Checks:** | ||
| 18 | 1. **Factual Statement Test:** Can this be verified with evidence? | ||
| 19 | 2. **Opinion Detection:** Contains hedging language? ("I think", "probably", "best", "worst") | ||
| 20 | 3. **Specificity Score:** Contains concrete details? (names, numbers, dates, locations) | ||
| 21 | 4. **Future Prediction Test:** Makes claims about future events? **Pass Criteria:** | ||
| 22 | {{code}} | ||
| 23 | - isFactual: true | ||
| 24 | - opinionScore: ≤ 0.3 | ||
| 25 | - specificityScore: ≥ 0.3 | ||
| 26 | - claimType: FACTUAL | ||
| 27 | {{/code}} **Action if Failed:** | ||
| 28 | * Flag as "Non-verifiable: Opinion/Prediction/Ambiguous" | ||
| 29 | * Do NOT generate scenarios or verdicts | ||
| 30 | * Display explanation to user **Target:** 0% opinion statements processed as facts ==== Gate 4: Verdict Confidence Assessment ==== **Purpose:** Only publish verdicts with sufficient evidence and confidence **Validation Checks:** | ||
| 31 | 1. **Evidence Count:** Minimum 2 independent sources | ||
| 32 | 2. **Source Quality:** Average reliability ≥ 0.6 (on 0-1 scale) | ||
| 33 | 3. **Evidence Agreement:** % supporting vs. contradicting ≥ 0.6 | ||
| 34 | 4. **Uncertainty Factors:** Count of hedging statements in reasoning **Confidence Tiers:** | ||
| 35 | {{code}} | ||
| 36 | HIGH (80-100%): - ≥3 sources - ≥0.7 average quality - ≥80% agreement MEDIUM (50-79%): - ≥2 sources - ≥0.6 average quality - ≥60% agreement LOW (0-49%): - ≥2 sources BUT low quality/agreement INSUFFICIENT: - <2 sources → DO NOT PUBLISH | ||
| 37 | {{/code}} **POC1 Publication Rule:** | ||
| 38 | * Minimum **MEDIUM** confidence required | ||
| 39 | * Blocked verdicts show "Insufficient Evidence" message **Target:** 0% verdicts published with <2 sources === 3.2 Modified FR7: Automated Verdicts (Enhanced) === **Enhancement for POC1:** After AKEL generates a verdict, it must pass through the quality validation pipeline: {{code}} | ||
| 40 | AKEL Workflow (POC1): 1. Extract claims from article ↓ | ||
| 41 | 2. [GATE 1] Validate each claim is fact-checkable ↓ (pass claims only) | ||
| 42 | 3. Generate verdicts for each claim ↓ | ||
| 43 | 4. [GATE 4] Validate verdict has sufficient evidence ↓ (pass verdicts only) | ||
| 44 | 5. Display to user Failed claims/verdicts: | ||
| 45 | - Store in database with failure reason | ||
| 46 | - Display explanatory message to user | ||
| 47 | - Log for quality metrics tracking | ||
| 48 | {{/code}} **Updated Verdict States:** | ||
| 49 | * PUBLISHED - Passed all gates | ||
| 50 | * INSUFFICIENT_EVIDENCE - Failed Gate 4 | ||
| 51 | * NON_FACTUAL_CLAIM - Failed Gate 1 | ||
| 52 | * PROCESSING - In progress | ||
| 53 | * ERROR - System failure === 3.3 Modified FR4: Analysis Summary (Enhanced) === **Enhancement for POC1:** Analysis Summary must now display quality metadata: {{code}} | ||
| 54 | Analysis Summary: Total Claims Found: 5 Verifiable Claims: 3 Non-verifiable (Opinion): 1 Non-verifiable (Prediction): 1 Verdicts Generated: 3 High Confidence: 1 Medium Confidence: 2 Insufficient Evidence: 0 Evidence Sources: 12 total Average Source Quality: 0.73 Quality Score: 8.5/10 | ||
| 55 | {{/code}} == 4. Success Criteria == POC1 is considered **SUCCESSFUL** if: **✅ Functional:** | ||
| 56 | * Processes diverse test articles without crashes | ||
| 57 | * Generates verdicts for all factual claims | ||
| 58 | * Blocks all non-factual claims (0% pass through) | ||
| 59 | * Blocks all insufficient-evidence verdicts (0% with <2 sources) **✅ Quality:** | ||
| 60 | * Hallucination rate <10% (manual verification) | ||
| 61 | * 0 verdicts with <2 sources published | ||
| 62 | * 0 opinion statements published as facts | ||
| 63 | * Average quality score ≥7.0/10 **✅ Performance:** | ||
| 64 | * Processing time reasonable for POC demonstration | ||
| 65 | * Quality gates execute efficiently | ||
| 66 | * UI displays results clearly **✅ Learnings:** | ||
| 67 | * Identified prompt engineering improvements | ||
| 68 | * Documented AKEL strengths/weaknesses | ||
| 69 | * Validated threshold values | ||
| 70 | * Clear path to POC2 defined == 5. Decision Gates == **POC1 → POC2 Decision:** * **IF** hallucination rate >10% → Pause, improve prompts before POC2 | ||
| 71 | * **IF** majority of claims non-processable → Rethink claim extraction approach | ||
| 72 | * **IF** quality gates too strict (excessive blocking) → Adjust thresholds | ||
| 73 | * **IF** quality gates too loose (hallucinations pass) → Tighten criteria **Only proceed to POC2 if all success criteria met** == 6. Architecture Notes == **POC1 Simplified Architecture:** {{code}} | ||
| 74 | User Input → AKEL Processing → Quality Gates → Display (claim extraction (Gates 1 & 4) + verdicts) | ||
| 75 | {{/code}} **vs. Full System (Future):** {{code}} | ||
| 76 | Input → Claim Extractor → Scenario Generator → Evidence Linker → Verdict Generator → All 4 Gates → Review Queue → Publication | ||
| 77 | {{/code}} **POC1 Acceptable Simplifications:** | ||
| 78 | * Single AKEL call (not multi-component pipeline) | ||
| 79 | * No scenarios (implicit in verdicts) | ||
| 80 | * Basic evidence linking | ||
| 81 | * 2 gates instead of 4 | ||
| 82 | * No review queue **See:** [[Architecture>>Test.FactHarbor.Specification.Architecture.WebHome]] for details == Related Pages == * [[Roadmap Overview>>Test.FactHarbor.Roadmap.WebHome]] - All phases | ||
| 83 | * [[POC2 Requirements>>Test.FactHarbor.Roadmap.POC2.WebHome]] - Next phase | ||
| 84 | * [[Requirements>>Test.FactHarbor.Specification.Requirements.WebHome]] - Full system requirements | ||
| 85 | * [[Architecture>>Test.FactHarbor.Specification.Architecture.WebHome]] - System architecture | ||
| 86 | * [[NFR11 Full Specification>>Test.FactHarbor.Specification.Requirements.WebHome#NFR11]] - Complete quality framework **Document Status:** ✅ POC1 Specification Complete - Ready for Implementation **Version:** V0.9.70 |