Changes for page POC1 API & Schemas Specification

Last modified by Robert Schaub on 2025/12/24 20:16

From version 2.2

edited by Robert Schaub
on 2025/12/24 20:16

Change comment: Update document after refactoring.

To version 1.1

edited by Robert Schaub
on 2025/12/24 19:45

Change comment: Imported from XAR

Raw
Rendered

Summary

Page properties (2 modified, 0 added, 0 removed)

Details

Page properties

Parent

@@ -1,1 +1,1 @@
--Test.FactHarbor V0\.9\.105.Specification.POC.WebHome
++Test.FactHarbor.Specification.POC.WebHome

Content

@@ -58,7 +58,7 @@
  * **Input:** Article text
  * **Output:** 5 canonical claims (normalized, deduplicated)
--* **Model:** Claude Haiku 4.5.5 (default, configurable via LLM abstraction layer)
++* **Model:** Claude Haiku 4 (default, configurable via LLM abstraction layer)
  * **Cost:** $0.003 per article
  * **Cache strategy:** No caching (article-specific)
@@ -66,7 +66,7 @@
  * **Input:** Single canonical claim
  * **Output:** Scenarios + Evidence + Verdicts
--* **Model:** Claude Sonnet 4.5 (default, configurable via LLM abstraction layer)
++* **Model:** Claude Sonnet 3.5 (default, configurable via LLM abstraction layer)
  * **Cost:** $0.081 per NEW claim
  * **Cache strategy:** Redis, 90-day TTL
  * **Cache key:** claim:v1norm1:{language}:{sha256(canonical_claim)}
@@ -75,7 +75,7 @@
  * **Input:** Article + Claim verdicts (from cache or Stage 2)
  * **Output:** Article verdict + Fallacies + Logic quality
--* **Model:** Claude Sonnet 4.5 (default, configurable via LLM abstraction layer)
++* **Model:** Claude Sonnet 3.5 (default, configurable via LLM abstraction layer)
  * **Cost:** $0.030 per article
  * **Cache strategy:** No caching (article-specific)
@@ -115,336 +115,6 @@
  When free users reach their $10 monthly limit, they enter **Cache-Only Mode**:
--
--
--==== Stage 3: Holistic Assessment - Complete Specification ====
--
--===== 3.3.1 Overview =====
--
--**Purpose:** Synthesize individual claim analyses into an overall article assessment, identifying logical fallacies, reasoning quality, and publication readiness.
--
--**Approach:** **Single-Pass Holistic Analysis** (Approach 1 from Comparison Matrix)
--
--**Why This Approach for POC1:**
--* ✅ **1 API call** (vs 2 for Two-Pass or Judge)
--* ✅ **Low cost** ($0.030 per article)
--* ✅ **Fast** (4-6 seconds)
--* ✅ **Low complexity** (simple implementation)
--* ⚠️ **Medium reliability** (acceptable for POC1, will improve in POC2/Production)
--
--**Alternative Approaches Considered:**
--
--|= Approach |= API Calls |= Cost |= Speed |= Complexity |= Reliability |= Best For
--| **1. Single-Pass** ⭐ | 1 | 💰 Low | ⚡ Fast | 🟢 Low | ⚠️ Medium | **POC1**
--| 2. Two-Pass | 2 | 💰💰 Med | 🐢 Slow | 🟡 Med | ✅ High | POC2/Prod
--| 3. Structured | 1 | 💰 Low | ⚡ Fast | 🟡 Med | ✅ High | POC1 (alternative)
--| 4. Weighted | 1 | 💰 Low | ⚡ Fast | 🟢 Low | ⚠️ Medium | POC1 (alternative)
--| 5. Heuristics | 1 | 💰 Lowest | ⚡⚡ Fastest | 🟡 Med | ⚠️ Medium | Any
--| 6. Hybrid | 1 | 💰 Low | ⚡ Fast | 🔴 Med-High | ✅ High | POC2
--| 7. Judge | 2 | 💰💰 Med | 🐢 Slow | 🟡 Med | ✅ High | Production
--
--**POC1 Choice:** Approach 1 (Single-Pass) for speed and simplicity. Will upgrade to Approach 2 (Two-Pass) or 6 (Hybrid) in POC2 for higher reliability.
--
--===== 3.3.2 What Stage 3 Evaluates =====
--
--Stage 3 performs **integrated holistic analysis** considering:
--
--**1. Claim-Level Aggregation:**
--* Verdict distribution (how many TRUE vs FALSE vs DISPUTED)
--* Average confidence across all claims
--* Claim interdependencies (do claims support/contradict each other?)
--* Critical claim identification (which claims are most important?)
--
--**2. Contextual Factors:**
--* **Source credibility**: Is the article from a reputable publisher?
--* **Author expertise**: Does the author have relevant credentials?
--* **Publication date**: Is information current or outdated?
--* **Claim coherence**: Do claims form a logical narrative?
--* **Missing context**: Are important caveats or qualifications missing?
--
--**3. Logical Fallacies:**
--* **Cherry-picking**: Selective evidence presentation
--* **False equivalence**: Treating unequal things as equal
--* **Straw man**: Misrepresenting opposing arguments
--* **Ad hominem**: Attacking person instead of argument
--* **Slippery slope**: Assuming extreme consequences without justification
--* **Circular reasoning**: Conclusion assumes premise
--* **False dichotomy**: Presenting only two options when more exist
--
--**4. Reasoning Quality:**
--* **Evidence strength**: Quality and quantity of supporting evidence
--* **Logical coherence**: Arguments follow logically
--* **Transparency**: Assumptions and limitations acknowledged
--* **Nuance**: Complexity and uncertainty appropriately addressed
--
--**5. Publication Readiness:**
--* **Risk tier assignment**: A (high risk), B (medium), or C (low risk)
--* **Publication mode**: DRAFT_ONLY, AI_GENERATED, or HUMAN_REVIEWED
--* **Required disclaimers**: What warnings should accompany this content?
--
--===== 3.3.3 Implementation: Single-Pass Approach =====
--
--**Input:**
--* Original article text (full content)
--* Stage 2 claim analyses (array of ClaimAnalysis objects)
--* Article metadata (URL, title, author, date, source)
--
--**Processing:**
--
--{{code language="python"}}
--# Pseudo-code for Stage 3 (Single-Pass)
--
--def stage3_holistic_assessment(article, claim_analyses, metadata):
--    """
--    Single-pass holistic assessment using Claude Sonnet 4.5.
--
--    Approach 1: One comprehensive prompt that asks the LLM to:
--    1. Review all claim verdicts
--    2. Identify patterns and dependencies
--    3. Detect logical fallacies
--    4. Assess reasoning quality
--    5. Determine credibility score and risk tier
--    6. Generate publication recommendations
--    """
--
--    # Construct comprehensive prompt
--    prompt = f"""
--You are analyzing an article for factual accuracy and logical reasoning.
--
--ARTICLE METADATA:
--- Title: {metadata['title']}
--- Source: {metadata['source']}
--- Date: {metadata['date']}
--- Author: {metadata['author']}
--
--ARTICLE TEXT:
--{article}
--
--INDIVIDUAL CLAIM ANALYSES:
--{format_claim_analyses(claim_analyses)}
--
--YOUR TASK:
--Perform a holistic assessment considering:
--
--1. CLAIM AGGREGATION:
--   - Review the verdict for each claim
--   - Identify any interdependencies between claims
--   - Determine which claims are most critical to the article's thesis
--
--2. CONTEXTUAL EVALUATION:
--   - Assess source credibility
--   - Evaluate author expertise
--   - Consider publication timeliness
--   - Identify missing context or important caveats
--
--3. LOGICAL FALLACIES:
--   - Identify any logical fallacies present
--   - For each fallacy, provide:
--     * Type of fallacy
--     * Where it occurs in the article
--     * Why it's problematic
--     * Severity (minor/moderate/severe)
--
--4. REASONING QUALITY:
--   - Evaluate evidence strength
--   - Assess logical coherence
--   - Check for transparency in assumptions
--   - Evaluate handling of nuance and uncertainty
--
--5. CREDIBILITY SCORING:
--   - Calculate overall credibility score (0.0-1.0)
--   - Assign risk tier:
--     * A (high risk): ≤0.5 credibility OR severe fallacies
--     * B (medium risk): 0.5-0.8 credibility OR moderate issues
--     * C (low risk): >0.8 credibility AND no significant issues
--
--6. PUBLICATION RECOMMENDATIONS:
--   - Determine publication mode:
--     * DRAFT_ONLY: Tier A, multiple severe issues
--     * AI_GENERATED: Tier B/C, acceptable quality with disclaimers
--     * HUMAN_REVIEWED: Complex or borderline cases
--   - List required disclaimers
--   - Explain decision rationale
--
--OUTPUT FORMAT:
--Return a JSON object matching the ArticleAssessment schema.
--"""
--
--    # Call LLM
--    response = llm_client.complete(
--        model="claude-sonnet-4-5-20250929",
--        prompt=prompt,
--        max_tokens=4000,
--        response_format="json"
--    )
--
--    # Parse and validate response
--    assessment = parse_json(response.content)
--    validate_article_assessment_schema(assessment)
--
--    return assessment
--{{/code}}
--
--**Prompt Engineering Notes:**
--
--1. **Structured Instructions**: Break down task into 6 clear sections
--2. **Context-Rich**: Provide article + all claim analyses + metadata
--3. **Explicit Criteria**: Define credibility scoring and risk tiers precisely
--4. **JSON Schema**: Request structured output matching ArticleAssessment schema
--5. **Examples** (in production): Include 2-3 example assessments for consistency
--
--===== 3.3.4 Credibility Scoring Algorithm =====
--
--**Base Score Calculation:**
--
--{{code language="python"}}
--def calculate_credibility_score(claim_analyses, fallacies, contextual_factors):
--    """
--    Calculate overall credibility score (0.0-1.0).
--
--    This is a GUIDELINE for the LLM, not strict code.
--    The LLM has flexibility to adjust based on context.
--    """
--
--    # 1. Claim Verdict Score (60% weight)
--    verdict_weights = {
--        "TRUE": 1.0,
--        "PARTIALLY_TRUE": 0.7,
--        "DISPUTED": 0.5,
--        "UNSUPPORTED": 0.3,
--        "FALSE": 0.0,
--        "UNVERIFIABLE": 0.4
--    }
--
--    claim_scores = [
--        verdict_weights[c.verdict.label] * c.verdict.confidence
--        for c in claim_analyses
--    ]
--    avg_claim_score = sum(claim_scores) / len(claim_scores)
--    claim_component = avg_claim_score * 0.6
--
--    # 2. Fallacy Penalty (20% weight)
--    fallacy_penalties = {
--        "minor": -0.05,
--        "moderate": -0.15,
--        "severe": -0.30
--    }
--
--    fallacy_score = 1.0
--    for fallacy in fallacies:
--        fallacy_score += fallacy_penalties[fallacy.severity]
--
--    fallacy_score = max(0.0, min(1.0, fallacy_score))
--    fallacy_component = fallacy_score * 0.2
--
--    # 3. Contextual Factors (20% weight)
--    context_adjustments = {
--        "source_credibility": {"positive": +0.1, "neutral": 0, "negative": -0.1},
--        "author_expertise": {"positive": +0.1, "neutral": 0, "negative": -0.1},
--        "timeliness": {"positive": +0.05, "neutral": 0, "negative": -0.05},
--        "transparency": {"positive": +0.05, "neutral": 0, "negative": -0.05}
--    }
--
--    context_score = 1.0
--    for factor in contextual_factors:
--        adjustment = context_adjustments.get(factor.factor, {}).get(factor.impact, 0)
--        context_score += adjustment
--
--    context_score = max(0.0, min(1.0, context_score))
--    context_component = context_score * 0.2
--
--    # 4. Combine components
--    final_score = claim_component + fallacy_component + context_component
--
--    # 5. Apply confidence modifier
--    avg_confidence = sum(c.verdict.confidence for c in claim_analyses) / len(claim_analyses)
--    final_score = final_score * (0.8 + 0.2 * avg_confidence)
--
--    return max(0.0, min(1.0, final_score))
--{{/code}}
--
--**Note:** This algorithm is a **guideline** provided to the LLM in the system prompt. The LLM has flexibility to adjust based on specific article context, but should generally follow this structure for consistency.
--
--===== 3.3.5 Risk Tier Assignment =====
--
--**Automatic Risk Tier Rules:**
--
--{{code}}
--Risk Tier A (High Risk - Requires Review):
--- Credibility score ≤ 0.5, OR
--- Any severe fallacies detected, OR
--- Multiple (3+) moderate fallacies, OR
--- 50%+ of claims are FALSE or UNSUPPORTED
--
--Risk Tier B (Medium Risk - May Publish with Disclaimers):
--- Credibility score 0.5-0.8, OR
--- 1-2 moderate fallacies, OR
--- 20-49% of claims are DISPUTED or PARTIALLY_TRUE
--
--Risk Tier C (Low Risk - Safe to Publish):
--- Credibility score > 0.8, AND
--- No severe or moderate fallacies, AND
--- <20% disputed/problematic claims, AND
--- No critical missing context
--{{/code}}
--
--===== 3.3.6 Output: ArticleAssessment Schema =====
--
--(See Stage 3 Output Schema section above for complete JSON schema)
--
--===== 3.3.7 Performance Metrics =====
--
--**POC1 Targets:**
--* **Processing time**: 4-6 seconds per article
--* **Cost**: $0.030 per article (Sonnet 4.5 tokens)
--* **Quality**: 70-80% agreement with human reviewers (acceptable for POC)
--* **API calls**: 1 per article
--
--**Future Improvements (POC2/Production):**
--* Upgrade to Two-Pass (Approach 2): +15% accuracy, +$0.020 cost
--* Add human review sampling: 10% of Tier B articles
--* Implement Judge approach (Approach 7) for Tier A: Highest quality
--
--===== 3.3.8 Example Stage 3 Execution =====
--
--**Input:**
--* Article: "Biden won the 2020 election"
--* Claim analyses: [{claim: "Biden won", verdict: "TRUE", confidence: 0.95}]
--
--**Stage 3 Processing:**
--1. Analyzes single claim with high confidence
--2. Checks for contextual factors (source credibility)
--3. Searches for logical fallacies (none found)
--4. Calculates credibility: 0.6 * 0.95 + 0.2 * 1.0 + 0.2 * 1.0 = 0.97
--5. Assigns risk tier: C (low risk)
--6. Recommends: AI_GENERATED publication mode
--
--**Output:**
--```json
--{
--  "article_id": "a1",
--  "overall_assessment": {
--    "credibility_score": 0.97,
--    "risk_tier": "C",
--    "summary": "Article makes single verifiable claim with strong evidence support",
--    "confidence": 0.95
--  },
--  "claim_aggregation": {
--    "total_claims": 1,
--    "verdict_distribution": {"TRUE": 1},
--    "avg_confidence": 0.95
--  },
--  "contextual_factors": [
--    {"factor": "source_credibility", "impact": "positive", "description": "Reputable news source"}
--  ],
--  "recommendations": {
--    "publication_mode": "AI_GENERATED",
--    "requires_review": false,
--    "suggested_disclaimers": []
--  }
--}
--```
--
  ==== What Cache-Only Mode Provides: ====
  ✅ **Claim Extraction (Platform-Funded):**
@@ -566,7 +566,7 @@
  **Primary Provider (Default):**
  * **Anthropic Claude API**
--  * Models: Claude Haiku 4.5, Claude Sonnet 4.5, Claude Opus 4
++  * Models: Claude Haiku 4, Claude Sonnet 3.5, Claude Opus 4
    * Used by default in POC1
    * Best quality for holistic analysis
@@ -603,9 +603,9 @@
  LLM_STAGE1_PROVIDER=anthropic
  LLM_STAGE1_MODEL=claude-haiku-4
  LLM_STAGE2_PROVIDER=anthropic
--LLM_STAGE2_MODEL=claude-sonnet-4-5-20250929
++LLM_STAGE2_MODEL=claude-sonnet-3-5
  LLM_STAGE3_PROVIDER=anthropic
--LLM_STAGE3_MODEL=claude-sonnet-4-5-20250929
++LLM_STAGE3_MODEL=claude-sonnet-3-5
  # Cost limits
  LLM_MAX_COST_PER_REQUEST=1.00
@@ -632,19 +632,19 @@
    "stage_config": {
      "stage1": {
        "provider": "anthropic",
--      "model": "claude-haiku-4-5-20251001",
++      "model": "claude-haiku-4",
        "max_tokens": 4096,
        "temperature": 0.0
      },
      "stage2": {
        "provider": "anthropic",
--      "model": "claude-sonnet-4-5-20250929",
++      "model": "claude-sonnet-3-5",
        "max_tokens": 16384,
        "temperature": 0.3
      },
      "stage3": {
        "provider": "anthropic",
--      "model": "claude-sonnet-4-5-20250929",
++      "model": "claude-sonnet-3-5",
        "max_tokens": 8192,
        "temperature": 0.2
      }
@@ -658,7 +658,7 @@
  **Stage 1: Claim Extraction**
--* **Default:** Anthropic Claude Haiku 4.5
++* **Default:** Anthropic Claude Haiku 4
  * **Alternative:** OpenAI GPT-4o-mini, Google Gemini 1.5 Flash
  * **Rationale:** Fast, cheap, simple task
  * **Cost:** ~$0.003 per article
@@ -665,7 +665,7 @@
  **Stage 2: Claim Analysis** (CACHEABLE)
--* **Default:** Anthropic Claude Sonnet 4.5
++* **Default:** Anthropic Claude Sonnet 3.5
  * **Alternative:** OpenAI GPT-4o, Google Gemini 1.5 Pro
  * **Rationale:** High-quality analysis, cached 90 days
  * **Cost:** ~$0.081 per NEW claim
@@ -672,7 +672,7 @@
  **Stage 3: Holistic Assessment**
--* **Default:** Anthropic Claude Sonnet 4.5
++* **Default:** Anthropic Claude Sonnet 3.5
  * **Alternative:** OpenAI GPT-4o, Claude Opus 4 (for high-stakes)
  * **Rationale:** Complex reasoning, logical fallacy detection
  * **Cost:** ~$0.030 per article
@@ -680,9 +680,9 @@
  **Cost Comparison (Example):**
  |=Stage|=Anthropic (Default)|=OpenAI Alternative|=Google Alternative
--|Stage 1|Claude Haiku 4.5.5 ($0.003)|GPT-4o-mini ($0.002)|Gemini Flash ($0.002)
--|Stage 2|Claude Sonnet 4.5 ($0.081)|GPT-4o ($0.045)|Gemini Pro ($0.050)
--|Stage 3|Claude Sonnet 4.5 ($0.030)|GPT-4o ($0.018)|Gemini Pro ($0.020)
++|Stage 1|Claude Haiku 4 ($0.003)|GPT-4o-mini ($0.002)|Gemini Flash ($0.002)
++|Stage 2|Claude Sonnet 3.5 ($0.081)|GPT-4o ($0.045)|Gemini Pro ($0.050)
++|Stage 3|Claude Sonnet 3.5 ($0.030)|GPT-4o ($0.018)|Gemini Pro ($0.020)
  |**Total (0% cache)**|**$0.114**|**$0.065**|**$0.072**
  **Note:** POC1 uses Anthropic exclusively for consistency. Multi-provider support planned for POC2.
@@ -743,7 +743,7 @@
    "stage": "stage2",
    "previous": {
      "provider": "anthropic",
--    "model": "claude-sonnet-4-5-20250929"
++    "model": "claude-sonnet-3-5"
    },
    "current": {
      "provider": "openai",
@@ -769,17 +769,17 @@
    "stages": {
      "stage1": {
        "provider": "anthropic",
--      "model": "claude-haiku-4-5-20251001",
++      "model": "claude-haiku-4",
        "cost_per_request": 0.003
      },
      "stage2": {
        "provider": "anthropic",
--      "model": "claude-sonnet-4-5-20250929",
++      "model": "claude-sonnet-3-5",
        "cost_per_new_claim": 0.081
      },
      "stage3": {
        "provider": "anthropic",
--      "model": "claude-sonnet-4-5-20250929",
++      "model": "claude-sonnet-3-5",
        "cost_per_request": 0.030
      }
    }
@@ -796,7 +796,7 @@
  class AnthropicProvider implements LLMProvider {
    async complete(prompt: string, options: CompletionOptions) {
      const response = await anthropic.messages.create({
--      model: options.model || 'claude-sonnet-4-5-20250929',
++      model: options.model || 'claude-sonnet-3-5',
        max_tokens: options.maxTokens || 4096,
        messages: [{ role: 'user', content: prompt }],
        system: options.systemPrompt
@@ -862,178 +862,6 @@
  ----
--
--
--==== Stage 2 Output Schema: ClaimAnalysis ====
--
--**Complete schema for each claim's analysis result:**
--
--{{code language="json"}}
--{
--  "claim_id": "claim_abc123",
--  "claim_text": "Biden won the 2020 election",
--  "scenarios": [
--    {
--      "scenario_id": "scenario_1",
--      "description": "Interpreting 'won' as Electoral College victory",
--      "verdict": {
--        "label": "TRUE",
--        "confidence": 0.95,
--        "explanation": "Joe Biden won 306 electoral votes vs Trump's 232"
--      },
--      "evidence": {
--        "supporting": [
--          {
--            "text": "Biden certified with 306 electoral votes",
--            "source_url": "https://www.archives.gov/electoral-college/2020",
--            "source_title": "2020 Electoral College Results",
--            "credibility_score": 0.98
--          }
--        ],
--        "opposing": []
--      }
--    }
--  ],
--  "recommended_scenario": "scenario_1",
--  "metadata": {
--    "analysis_timestamp": "2024-12-24T18:00:00Z",
--    "model_used": "claude-sonnet-4-5-20250929",
--    "processing_time_seconds": 8.5
--  }
--}
--{{/code}}
--
--**Required Fields:**
--* **claim_id**: Unique identifier matching Stage 1 output
--* **claim_text**: The exact claim being analyzed
--* **scenarios**: Array of interpretation scenarios (minimum 1)
-- * **scenario_id**: Unique ID for this scenario
-- * **description**: Clear interpretation of the claim
-- * **verdict**: Verdict object with label, confidence, explanation
-- * **evidence**: Supporting and opposing evidence arrays
--* **recommended_scenario**: ID of the primary/recommended scenario
--* **metadata**: Processing metadata (timestamp, model, timing)
--
--**Optional Fields:**
--* Additional context, warnings, or quality scores
--
--**Minimum Viable Example:**
--
--{{code language="json"}}
--{
--  "claim_id": "c1",
--  "claim_text": "The sky is blue",
--  "scenarios": [{
--    "scenario_id": "s1",
--    "description": "Under clear daytime conditions",
--    "verdict": {"label": "TRUE", "confidence": 0.99, "explanation": "Rayleigh scattering"},
--    "evidence": {"supporting": [], "opposing": []}
--  }],
--  "recommended_scenario": "s1",
--  "metadata": {"analysis_timestamp": "2024-12-24T18:00:00Z"}
--}
--{{/code}}
--
--
--
--==== Stage 3 Output Schema: ArticleAssessment ====
--
--**Complete schema for holistic article-level assessment:**
--
--{{code language="json"}}
--{
--  "article_id": "article_xyz789",
--  "overall_assessment": {
--    "credibility_score": 0.72,
--    "risk_tier": "B",
--    "summary": "Article contains mostly accurate claims with one disputed claim requiring expert review",
--    "confidence": 0.85
--  },
--  "claim_aggregation": {
--    "total_claims": 5,
--    "verdict_distribution": {
--      "TRUE": 3,
--      "PARTIALLY_TRUE": 1,
--      "DISPUTED": 1,
--      "FALSE": 0,
--      "UNSUPPORTED": 0,
--      "UNVERIFIABLE": 0
--    },
--    "avg_confidence": 0.82
--  },
--  "contextual_factors": [
--    {
--      "factor": "Source credibility",
--      "impact": "positive",
--      "description": "Published by reputable news organization"
--    },
--    {
--      "factor": "Claim interdependence",
--      "impact": "neutral",
--      "description": "Claims are independent; no logical chains"
--    }
--  ],
--  "recommendations": {
--    "publication_mode": "AI_GENERATED",
--    "requires_review": false,
--    "review_reason": null,
--    "suggested_disclaimers": [
--      "One claim (Claim 4) has conflicting expert opinions"
--    ]
--  },
--  "metadata": {
--    "holistic_timestamp": "2024-12-24T18:00:10Z",
--    "model_used": "claude-sonnet-4-5-20250929",
--    "processing_time_seconds": 4.2,
--    "cache_used": false
--  }
--}
--{{/code}}
--
--**Required Fields:**
--* **article_id**: Unique identifier for this article
--* **overall_assessment**: Top-level assessment
-- * **credibility_score**: 0.0-1.0 composite score
-- * **risk_tier**: A, B, or C (per AKEL quality gates)
-- * **summary**: Human-readable assessment
-- * **confidence**: How confident the holistic assessment is
--* **claim_aggregation**: Statistics across all claims
-- * **total_claims**: Count of claims analyzed
-- * **verdict_distribution**: Count per verdict label
-- * **avg_confidence**: Average confidence across verdicts
--* **contextual_factors**: Array of contextual considerations
--* **recommendations**: Publication decision support
-- * **publication_mode**: DRAFT_ONLY, AI_GENERATED, or HUMAN_REVIEWED
-- * **requires_review**: Boolean flag
-- * **suggested_disclaimers**: Array of disclaimer texts
--* **metadata**: Processing metadata
--
--**Minimum Viable Example:**
--
--{{code language="json"}}
--{
--  "article_id": "a1",
--  "overall_assessment": {
--    "credibility_score": 0.95,
--    "risk_tier": "C",
--    "summary": "All claims verified as true",
--    "confidence": 0.98
--  },
--  "claim_aggregation": {
--    "total_claims": 1,
--    "verdict_distribution": {"TRUE": 1},
--    "avg_confidence": 0.99
--  },
--  "contextual_factors": [],
--  "recommendations": {
--    "publication_mode": "AI_GENERATED",
--    "requires_review": false,
--    "suggested_disclaimers": []
--  },
--  "metadata": {"holistic_timestamp": "2024-12-24T18:00:00Z"}
--}
--{{/code}}
--
  === 3.2 Create Analysis Job (3-Stage) ===
  **Endpoint:** POST /v1/analyze
@@ -1085,20 +1085,6 @@
   "browsing": "on",
   "depth": "standard",
   "max_claims": 5,
--
--* **cache_preference** (optional): Cache usage preference
-- * **Type:** string
-- * **Enum:** {{code}}["prefer_cache", "allow_partial", "skip_cache"]{{/code}}
-- * **Default:** {{code}}"prefer_cache"{{/code}}
-- * **Semantics:**
--  * {{code}}"prefer_cache"{{/code}}: Use full cache if available, otherwise run all stages
--  * {{code}}"allow_partial"{{/code}}: Use cached Stage 2 results if available, rerun only Stage 3
--  * {{code}}"skip_cache"{{/code}}: Always rerun all stages (ignore cache)
-- * **Behavior:** When set to {{code}}"allow_partial"{{/code}} and Stage 2 cached results exist:
--  * Stage 1 & 2 are skipped
--  * Stage 3 (holistic assessment) runs fresh with cached claim analyses
--  * Response includes {{code}}"cache_used": true{{/code}} and {{code}}"stages_cached": ["stage1", "stage2"]{{/code}}
--
   "scenarios_per_claim": 2,
   "max_evidence_per_scenario": 6,
   "context_aware_analysis": true
@@ -1286,78 +1286,80 @@
  **Algorithm: Canonical Claim Normalization v1**
++{{{def normalize_claim_v1(claim_text: str, language: str) -> str:
++ """
++ Normalizes claim to canonical form for cache key generation.
++ Version: v1norm1 (POC1)
++ """
++ import re
++ import unicodedata
++
++ # Step 1: Unicode normalization (NFC)
++ text = unicodedata.normalize('NFC', claim_text)
++
++ # Step 2: Lowercase
++ text = text.lower()
++
++ # Step 3: Remove punctuation (except hyphens in words)
++ text = re.sub(r'[^\w\s-]', '', text)
++
++ # Step 4: Normalize whitespace (collapse multiple spaces)
++ text = re.sub(r'\s+', ' ', text).strip()
++
++ # Step 5: Numeric normalization
++ text = text.replace('%', ' percent')
++ # Spell out single-digit numbers
++ num_to_word = {'0':'zero', '1':'one', '2':'two', '3':'three',
++ '4':'four', '5':'five', '6':'six', '7':'seven',
++ '8':'eight', '9':'nine'}
++ for num, word in num_to_word.items():
++ text = re.sub(rf'\b{num}\b', word, text)
++
++ # Step 6: Common abbreviations (English only in v1)
++ if language == 'en':
++ text = text.replace('covid-19', 'covid')
++ text = text.replace('u.s.', 'us')
++ text = text.replace('u.k.', 'uk')
++
++ # Step 7: NO entity normalization in v1
++ # (Trump vs Donald Trump vs President Trump remain distinct)
++
++ return text
--**Normative Algorithm:**
++# Version identifier (include in cache namespace)
++CANONICALIZER_VERSION = "v1norm1"
++}}}
--{{code language="python"}}
--def normalize_claim(text: str) -> str:
--    """
--    Canonical claim normalization for deduplication.
--    MUST follow this algorithm exactly.
--
--    Version: v1norm1
--    """
--    import re
--    import unicodedata
--
--    # 1. Unicode normalization (NFD)
--    text = unicodedata.normalize('NFD', text)
--
--    # 2. Lowercase
--    text = text.lower()
--
--    # 3. Remove diacritics
--    text = ''.join(c for c in text if unicodedata.category(c) != 'Mn')
--
--    # 4. Normalize whitespace
--    text = re.sub(r'\s+', ' ', text)
--    text = text.strip()
--
--    # 5. Remove punctuation except apostrophes in contractions
--    text = re.sub(r"[^\w\s']", '', text)
--
--    # 6. Normalize common contractions
--    contractions = {
--        "don't": "do not",
--        "doesn't": "does not",
--        "didn't": "did not",
--        "can't": "cannot",
--        "won't": "will not",
--        "shouldn't": "should not",
--        "wouldn't": "would not",
--        "isn't": "is not",
--        "aren't": "are not",
--        "wasn't": "was not",
--        "weren't": "were not",
--        "haven't": "have not",
--        "hasn't": "has not",
--        "hadn't": "had not"
--    }
--
--    for contraction, expansion in contractions.items():
--        text = re.sub(r'\b' + contraction + r'\b', expansion, text)
--
--    # 7. Remove remaining apostrophes
--    text = text.replace("'", "")
--
--    # 8. Final whitespace normalization
--    text = re.sub(r'\s+', ' ', text)
--    text = text.strip()
--
--    return text
--{{/code}}
++**Cache Key Formula (Updated):**
--**Normalization Examples:**
++{{{language = "en"
++canonical = normalize_claim_v1(claim_text, language)
++cache_key = f"claim:{CANONICALIZER_VERSION}:{language}:{sha256(canonical)}"
--|= Input |= Normalized Output
--| "Biden won the 2020 election" | {{code}}biden won the 2020 election{{/code}}
--| "Biden won the 2020 election!" | {{code}}biden won the 2020 election{{/code}}
--| "Biden  won   the 2020  election" | {{code}}biden won the 2020 election{{/code}}
--| "Biden didn't win the 2020 election" | {{code}}biden did not win the 2020 election{{/code}}
--| "BIDEN WON THE 2020 ELECTION" | {{code}}biden won the 2020 election{{/code}}
++Example:
++ claim: "COVID-19 vaccines are 95% effective"
++ canonical: "covid vaccines are 95 percent effective"
++ sha256: abc123...def456
++ key: "claim:v1norm1:en:abc123...def456"
++}}}
--**Versioning:** Algorithm version is {{code}}v1norm1{{/code}}. Changes to the algorithm require a new version identifier.
++**Cache Metadata MUST Include:**
++{{{{
++ "canonical_claim": "covid vaccines are 95 percent effective",
++ "canonicalizer_version": "v1norm1",
++ "language": "en",
++ "original_claim_samples": ["COVID-19 vaccines are 95% effective"]
++}
++}}}
++
++**Version Upgrade Path:**
++
++* v1norm1 → v1norm2: Cache namespace changes, old keys remain valid until TTL
++* v1normN → v2norm1: Major version bump, invalidate all v1 caches
++
++----
++
  === 5.1.2 Copyright & Data Retention Policy ===
  **Evidence Excerpt Storage:**

Changes for page POC1 API & Schemas Specification

Summary

Details

Applications

Navigation

Need help?