Changes for page POC1 API & Schemas Specification

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

From 2.1 to 2.2

From version 1.1

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

Change comment: Imported from XAR

To version 2.1

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

Change comment: Imported from XAR

Raw
Rendered

Summary

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

Details

Page properties

Content

@@ -58,7 +58,7 @@
  * **Input:** Article text
  * **Output:** 5 canonical claims (normalized, deduplicated)
--* **Model:** Claude Haiku 4 (default, configurable via LLM abstraction layer)
++* **Model:** Claude Haiku 4.5.5 (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 3.5 (default, configurable via LLM abstraction layer)
++* **Model:** Claude Sonnet 4.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 3.5 (default, configurable via LLM abstraction layer)
++* **Model:** Claude Sonnet 4.5 (default, configurable via LLM abstraction layer)
  * **Cost:** $0.030 per article
  * **Cache strategy:** No caching (article-specific)
@@ -115,6 +115,336 @@
  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):**
@@ -236,7 +236,7 @@
  **Primary Provider (Default):**
  * **Anthropic Claude API**
--  * Models: Claude Haiku 4, Claude Sonnet 3.5, Claude Opus 4
++  * Models: Claude Haiku 4.5, Claude Sonnet 4.5, Claude Opus 4
    * Used by default in POC1
    * Best quality for holistic analysis
@@ -273,9 +273,9 @@
  LLM_STAGE1_PROVIDER=anthropic
  LLM_STAGE1_MODEL=claude-haiku-4
  LLM_STAGE2_PROVIDER=anthropic
--LLM_STAGE2_MODEL=claude-sonnet-3-5
++LLM_STAGE2_MODEL=claude-sonnet-4-5-20250929
  LLM_STAGE3_PROVIDER=anthropic
--LLM_STAGE3_MODEL=claude-sonnet-3-5
++LLM_STAGE3_MODEL=claude-sonnet-4-5-20250929
  # Cost limits
  LLM_MAX_COST_PER_REQUEST=1.00
@@ -302,19 +302,19 @@
    "stage_config": {
      "stage1": {
        "provider": "anthropic",
--      "model": "claude-haiku-4",
++      "model": "claude-haiku-4-5-20251001",
        "max_tokens": 4096,
        "temperature": 0.0
      },
      "stage2": {
        "provider": "anthropic",
--      "model": "claude-sonnet-3-5",
++      "model": "claude-sonnet-4-5-20250929",
        "max_tokens": 16384,
        "temperature": 0.3
      },
      "stage3": {
        "provider": "anthropic",
--      "model": "claude-sonnet-3-5",
++      "model": "claude-sonnet-4-5-20250929",
        "max_tokens": 8192,
        "temperature": 0.2
      }
@@ -328,7 +328,7 @@
  **Stage 1: Claim Extraction**
--* **Default:** Anthropic Claude Haiku 4
++* **Default:** Anthropic Claude Haiku 4.5
  * **Alternative:** OpenAI GPT-4o-mini, Google Gemini 1.5 Flash
  * **Rationale:** Fast, cheap, simple task
  * **Cost:** ~$0.003 per article
@@ -335,7 +335,7 @@
  **Stage 2: Claim Analysis** (CACHEABLE)
--* **Default:** Anthropic Claude Sonnet 3.5
++* **Default:** Anthropic Claude Sonnet 4.5
  * **Alternative:** OpenAI GPT-4o, Google Gemini 1.5 Pro
  * **Rationale:** High-quality analysis, cached 90 days
  * **Cost:** ~$0.081 per NEW claim
@@ -342,7 +342,7 @@
  **Stage 3: Holistic Assessment**
--* **Default:** Anthropic Claude Sonnet 3.5
++* **Default:** Anthropic Claude Sonnet 4.5
  * **Alternative:** OpenAI GPT-4o, Claude Opus 4 (for high-stakes)
  * **Rationale:** Complex reasoning, logical fallacy detection
  * **Cost:** ~$0.030 per article
@@ -350,9 +350,9 @@
  **Cost Comparison (Example):**
  |=Stage|=Anthropic (Default)|=OpenAI Alternative|=Google Alternative
--|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)
++|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)
  |**Total (0% cache)**|**$0.114**|**$0.065**|**$0.072**
  **Note:** POC1 uses Anthropic exclusively for consistency. Multi-provider support planned for POC2.
@@ -413,7 +413,7 @@
    "stage": "stage2",
    "previous": {
      "provider": "anthropic",
--    "model": "claude-sonnet-3-5"
++    "model": "claude-sonnet-4-5-20250929"
    },
    "current": {
      "provider": "openai",
@@ -439,17 +439,17 @@
    "stages": {
      "stage1": {
        "provider": "anthropic",
--      "model": "claude-haiku-4",
++      "model": "claude-haiku-4-5-20251001",
        "cost_per_request": 0.003
      },
      "stage2": {
        "provider": "anthropic",
--      "model": "claude-sonnet-3-5",
++      "model": "claude-sonnet-4-5-20250929",
        "cost_per_new_claim": 0.081
      },
      "stage3": {
        "provider": "anthropic",
--      "model": "claude-sonnet-3-5",
++      "model": "claude-sonnet-4-5-20250929",
        "cost_per_request": 0.030
      }
    }
@@ -466,7 +466,7 @@
  class AnthropicProvider implements LLMProvider {
    async complete(prompt: string, options: CompletionOptions) {
      const response = await anthropic.messages.create({
--      model: options.model || 'claude-sonnet-3-5',
++      model: options.model || 'claude-sonnet-4-5-20250929',
        max_tokens: options.maxTokens || 4096,
        messages: [{ role: 'user', content: prompt }],
        system: options.systemPrompt
@@ -532,6 +532,178 @@
  ----
++
++
++==== 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
@@ -583,6 +583,20 @@
   "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
@@ -770,80 +770,78 @@
  **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
--# Version identifier (include in cache namespace)
--CANONICALIZER_VERSION = "v1norm1"
--}}}
++**Normative Algorithm:**
--**Cache Key Formula (Updated):**
++{{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}}
--{{{language = "en"
--canonical = normalize_claim_v1(claim_text, language)
--cache_key = f"claim:{CANONICALIZER_VERSION}:{language}:{sha256(canonical)}"
++**Normalization Examples:**
--Example:
-- claim: "COVID-19 vaccines are 95% effective"
-- canonical: "covid vaccines are 95 percent effective"
-- sha256: abc123...def456
-- key: "claim:v1norm1:en:abc123...def456"
--}}}
++|= 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}}
--**Cache Metadata MUST Include:**
++**Versioning:** Algorithm version is {{code}}v1norm1{{/code}}. Changes to the algorithm require a new version identifier.
--{{{{
-- "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?