docs: Add test script and documentation for EpistemicState and Cost-Benefit Logic

anhmtk · anhmtk · commit 73d722ff6c99 · 2025-11-28T14:42:38.000+07:00
1. Created test script (scripts/test_epistemic_state.py)
   - 8 test cases covering all epistemic states
   - Tests KNOWN, UNCERTAIN, UNKNOWN scenarios
   - Tests edge cases (None values, fallback, critical failures)
   - All tests passing

2. Created documentation (docs/EPISTEMIC_STATE.md)
   - Overview of epistemic state classification
   - Classification rules and examples
   - Implementation details and configuration
   - Use cases and future enhancements

3. Created documentation (docs/COST_BENEFIT_REWRITE.md)
   - Overview of cost-benefit logic for RewriteLLM
   - Self-correction modes (off/light/aggressive)
   - Quality thresholds and rewrite decision logic
   - Configuration and logging

4. Updated README.md
   - Added Cost-Benefit Logic and EpistemicState to Features section
   - Added links to new documentation in Documentation section
   - Kept updates concise and professional

5. Fixed format string errors in epistemic_state.py
   - Fixed f-string conditional formatting issues
   - Fixed Unicode encoding in test script (Windows compatibility)
diff --git a/README.md b/README.md
@@ -226,8 +226,12 @@ See `env.example` for full list.
 - ✅ Post-Processing System - Quality enhancement and variation
   - Quality evaluator - Rule-based quality assessment (0 token cost)
   - Rewrite engine - LLM-based answer refinement with retry mechanism
+  - Cost-benefit logic - Intelligent rewrite decisions (prevents unnecessary rewrites)
   - Style sanitizer - Removes anthropomorphic language
   - Honesty handler - Specialized processing for transparency questions
+- ✅ Epistemic State Classification - Response certainty indicators
+  - KNOWN/UNCERTAIN/UNKNOWN states - Transparent knowledge classification
+  - Rule-based classifier - Based on citations, confidence, and validation results
 - ✅ Philosophical Question Processor - 3-layer system for consciousness/emotion questions
   - Intent classification (consciousness, emotion, understanding, mixed)
   - Sub-type detection (paradox, epistemic, meta, definitional, direct)
@@ -417,6 +421,8 @@ We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed se
 **Features:**
 - [`docs/SPICE_ARCHITECTURE.md`](docs/SPICE_ARCHITECTURE.md) - SPICE framework
 - [`docs/CONFIDENCE_AND_FALLBACK.md`](docs/CONFIDENCE_AND_FALLBACK.md) - Validation system
+- [`docs/COST_BENEFIT_REWRITE.md`](docs/COST_BENEFIT_REWRITE.md) - Cost-benefit logic for RewriteLLM
+- [`docs/EPISTEMIC_STATE.md`](docs/EPISTEMIC_STATE.md) - Epistemic state classification (KNOWN/UNCERTAIN/UNKNOWN)
 
 ## ⚠️ Known Limitations & Improvements
 
diff --git a/backend/core/epistemic_state.py b/backend/core/epistemic_state.py
@@ -162,10 +162,11 @@ def calculate_epistemic_state(
         (conf_score is None or conf_score >= 0.7) and
         not has_warnings
     ):
+        conf_display = f"{conf_score:.2f}" if conf_score is not None else "N/A"
         logger.debug(
             f"EpistemicState: KNOWN "
             f"(passed={validation_passed}, citations={has_citations}, "
-            f"ctx_docs={ctx_docs_count}, confidence={conf_score:.2f if conf_score else 'N/A'})"
+            f"ctx_docs={ctx_docs_count}, confidence={conf_display})"
         )
         return EpistemicState.KNOWN
     
@@ -189,10 +190,11 @@ def calculate_epistemic_state(
         (validation_passed and has_warnings) or
         (has_citations and ctx_docs_count == 0)  # Citations but no context (general knowledge)
     ):
+        conf_display = f"{conf_score:.2f}" if conf_score is not None else "N/A"
         logger.debug(
             f"EpistemicState: UNCERTAIN "
             f"(citations={has_citations}, ctx_docs={ctx_docs_count}, "
-            f"confidence={conf_score:.2f if conf_score else 'N/A'}, warnings={has_warnings})"
+            f"confidence={conf_display}, warnings={has_warnings})"
         )
         return EpistemicState.UNCERTAIN
     
diff --git a/docs/COST_BENEFIT_REWRITE.md b/docs/COST_BENEFIT_REWRITE.md
@@ -0,0 +1,107 @@
+# Cost-Benefit Logic for RewriteLLM
+
+## Overview
+
+StillMe implements a **cost-benefit policy** for the RewriteLLM system to intelligently decide when to rewrite responses for quality improvement. This prevents unnecessary rewrites that waste tokens and increase latency while ensuring critical quality issues are addressed.
+
+## Self-Correction Modes
+
+The system supports three modes (configurable via `SELF_CORRECTION_MODE` environment variable):
+
+- **`off`**: No rewrites (disable self-correction)
+- **`light`**: Conservative (max 1 rewrite for medium quality, max 2 for low quality)
+- **`aggressive`**: More rewrites (max 2 for medium quality, max 2 for low quality)
+
+**Default**: `light` (balanced cost and quality)
+
+## Quality Thresholds
+
+### High Quality (>= 0.8)
+- **Action**: No rewrite
+- **Reason**: Quality is already good enough
+
+### Medium Quality (0.5 - 0.8)
+- **Light mode**: Max 1 rewrite (only if critical issues present)
+- **Aggressive mode**: Max 2 rewrites
+- **Condition**: Only rewrite if critical issues or aggressive mode enabled
+
+### Low Quality (< 0.5)
+- **Action**: Max 2 rewrites allowed
+- **Stop condition**: Stop if quality doesn't improve after rewrite
+
+## Rewrite Decision Logic
+
+### Initial Decision (`should_rewrite()`)
+
+The system decides whether to rewrite based on:
+
+1. **Quality score** from QualityEvaluator
+2. **Critical issues** (anthropomorphic language, missing citations, template-like responses, topic drift)
+3. **Current rewrite count** (prevents excessive rewrites)
+4. **Self-correction mode** (off/light/aggressive)
+
+### Continue Decision (`should_continue_rewrite()`)
+
+After each rewrite, the system decides whether to continue:
+
+- **Continue if**: Quality improved significantly (>= 0.2) but still below threshold
+- **Stop if**: 
+  - Quality reached threshold (>= 0.8)
+  - Max attempts reached
+  - Quality not improving (< 0.1 improvement) and still low
+
+## Configuration
+
+### Environment Variable
+
+```bash
+SELF_CORRECTION_MODE=light  # Options: off, light, aggressive
+```
+
+### Code Configuration
+
+Thresholds can be adjusted in `RewriteDecisionPolicy.__init__()`:
+
+```python
+self.high_quality_threshold = 0.8  # No rewrite if >= this
+self.medium_quality_threshold = 0.5  # Conditional rewrite if 0.5-0.8
+self.max_attempts_light_medium = 1  # Light mode: max 1 for medium
+self.max_attempts_aggressive_medium = 2  # Aggressive mode: max 2 for medium
+self.max_attempts_low_quality = 2  # Low quality: max 2 attempts
+```
+
+## Logging
+
+The system logs detailed metrics for monitoring:
+
+```
+🔄 Cost-Benefit: Rewrite decision - {reason}, quality_before={score:.2f}, rewrite_count={count}/{max}, mode={mode}
+📊 Rewrite metrics (attempt {n}): quality_before={before:.2f}, quality_after={after:.2f}, improvement={improvement:+.2f}
+✅ Rewrite loop complete: initial_quality={init:.2f}, final_quality={final:.2f}, total_rewrites={count}
+```
+
+## Benefits
+
+1. **Cost Reduction**: Prevents unnecessary rewrites for already-good responses
+2. **Latency Optimization**: Reduces response time by skipping redundant rewrites
+3. **Quality Assurance**: Still addresses critical quality issues when needed
+4. **Configurable**: Easy to adjust thresholds and modes based on requirements
+
+## Architecture
+
+- **Module**: `backend/postprocessing/rewrite_decision_policy.py`
+- **Integration**: Used by `PostProcessingOptimizer.should_rewrite()`
+- **Pipeline**: Integrated into `chat_router.py` rewrite loop
+
+## Future Enhancements
+
+- **ML-based Classifier**: Upgrade from rule-based to ML-based for more nuanced decisions
+- **Token Cost Tracking**: Track actual token costs for each rewrite
+- **Adaptive Thresholds**: Automatically adjust thresholds based on performance metrics
+
+## See Also
+
+- [Epistemic State Classification](EPISTEMIC_STATE.md)
+- [Validation Chain Documentation](VALIDATION_CHAIN.md)
+- [StillMe Architecture](../README.md)
+
diff --git a/docs/EPISTEMIC_STATE.md b/docs/EPISTEMIC_STATE.md
@@ -0,0 +1,128 @@
+# Epistemic State Classification
+
+## Overview
+
+StillMe classifies each response into one of three **epistemic states** to indicate the system's level of certainty about the information provided:
+
+- **KNOWN**: Clear evidence, good citations, validators pass
+- **UNCERTAIN**: Some information but thin, or validators warn
+- **UNKNOWN**: System truly doesn't know / insufficient data
+
+This classification helps users understand the reliability of StillMe's responses and aligns with StillMe's philosophy of transparency and anti-hallucination.
+
+## Classification Rules
+
+### KNOWN State
+
+A response is classified as **KNOWN** when:
+
+- ✅ Validation passed (`validation_passed = True`)
+- ✅ Has valid citations (e.g., `[1]`, `[2]`, `[general knowledge]`)
+- ✅ Has RAG context (`context_docs_count > 0`)
+- ✅ High confidence (`confidence_score >= 0.7`)
+- ✅ No critical warnings from validators
+
+**Example:**
+```
+Response: "According to [1] and [2], the capital of France is Paris."
+- Citations: [1], [2]
+- Context docs: 3
+- Confidence: 0.85
+- Validation: Passed
+→ State: KNOWN
+```
+
+### UNCERTAIN State
+
+A response is classified as **UNCERTAIN** when:
+
+- Has some information (citations or context) but:
+  - Medium confidence (`0.4 <= confidence_score < 0.7`), or
+  - Has warnings from validators (non-critical), or
+  - Has citations but no RAG context (general knowledge only)
+
+**Example:**
+```
+Response: "Based on [1], the answer might be X. However, there is some uncertainty."
+- Citations: [1]
+- Context docs: 1
+- Confidence: 0.55
+- Validation: Passed with warnings
+→ State: UNCERTAIN
+```
+
+### UNKNOWN State
+
+A response is classified as **UNKNOWN** when:
+
+- ❌ Fallback triggered (`used_fallback = True`), or
+- ❌ No context and low confidence (`context_docs_count = 0` and `confidence_score < 0.5`), or
+- ❌ Critical validation failures (e.g., `factual_hallucination`, `missing_citation`, `explicit_fake_entity`)
+
+**Example:**
+```
+Response: "I don't have sufficient information to answer this question accurately."
+- Citations: None
+- Context docs: 0
+- Confidence: 0.2
+- Fallback: True
+→ State: UNKNOWN
+```
+
+## Implementation
+
+### Location
+
+- **Module**: `backend/core/epistemic_state.py`
+- **Function**: `calculate_epistemic_state()`
+- **Integration**: Calculated after validation, before returning `ChatResponse`
+
+### API Response
+
+The `epistemic_state` field is included in the `ChatResponse` JSON:
+
+```json
+{
+  "response": "...",
+  "confidence_score": 0.85,
+  "validation_info": {...},
+  "epistemic_state": "KNOWN"
+}
+```
+
+### Configuration
+
+Thresholds can be adjusted in `calculate_epistemic_state()`:
+
+- **KNOWN threshold**: `confidence_score >= 0.7` (line ~100)
+- **UNCERTAIN range**: `0.4 <= confidence_score < 0.7` (line ~120)
+- **Citation patterns**: Regex patterns for detecting citations (line ~60)
+- **Critical failures**: List of critical validation failure patterns (line ~75)
+
+## Use Cases
+
+1. **User Transparency**: Users can see at a glance how confident StillMe is about each response
+2. **Quality Monitoring**: Track the distribution of epistemic states across responses
+3. **Fallback Detection**: Identify when StillMe is using fallback responses
+4. **Citation Quality**: Distinguish between responses with RAG context vs. general knowledge
+
+## Future Enhancements
+
+- **ML-based Classification**: Upgrade from rule-based to ML-based classifier for more nuanced classification
+- **Citation Quality Scoring**: Consider citation relevance and source quality, not just presence
+- **Confidence Calibration**: Fine-tune confidence thresholds based on evaluation results
+- **Dashboard Integration**: Display epistemic state badges in the dashboard UI
+
+## Related Features
+
+- **Validation Chain**: Epistemic state relies on validation results from the validator chain
+- **Confidence Scoring**: Uses `confidence_score` calculated from context quality and validation results
+- **Fallback Mechanism**: UNKNOWN state is triggered when fallback responses are used
+- **Citation System**: KNOWN state requires valid citations from RAG context
+
+## See Also
+
+- [Validation Chain Documentation](VALIDATION_CHAIN.md)
+- [Cost-Benefit Logic for RewriteLLM](COST_BENEFIT_REWRITE.md)
+- [StillMe Architecture](../README.md)
+
diff --git a/scripts/test_epistemic_state.py b/scripts/test_epistemic_state.py
