agent-os-kernel 1.1.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

modules/caas/docs/SLIDING_WINDOW.md

@@ -0,0 +1,387 @@
+# Sliding Window Conversation Management
+
+**The Brutal Squeeze: Chopping > Summarizing**
+
+## The Problem
+
+Traditional conversation management systems face a critical problem: **context window overflow**. When conversations get too long, they try to solve it by asking an AI to summarize the history.
+
+### The Naive Approach
+
+> "The context is too long. Let's ask an AI to summarize the conversation history to save space."
+
+This seems logical, but it's a trap.
+
+## The Engineering Reality
+
+Summarization is **expensive and lossy**:
+
+### Cost Problem
+- Every summary costs money (e.g., $0.01 per GPT-4o call)
+- For 1000 conversations with 20 turns each → $20 in summarization costs
+- Annual cost: $240 (just for conversation management!)
+
+### Information Loss Problem
+```
+Original Turn:
+"I tried calling /api/users/123 and got error code 500. 
+The exact error is: 'Connection timeout to db.example.com:5432'. 
+Check config.py line 45."
+
+After Summarization:
+"User encountered API error. System provided troubleshooting steps."
+
+❌ LOST:
+- Error code: 500
+- Endpoint: /api/users/123
+- Database host: db.example.com:5432
+- File reference: config.py line 45
+```
+
+The specific details that users actually need are **gone**.
+
+## My Philosophy: Chopping > Summarizing
+
+Instead of summarization, we use a **brutal "Sliding Window"** approach:
+
+### The Sliding Window (FIFO)
+
+1. **Keep the last N turns perfectly intact** (default: 10 turns)
+2. **Delete turn N+1** (First In, First Out)
+3. **No summarization** = **No AI cost** = **No information loss**
+
+### Why This Works
+
+**Users rarely refer back to what they said 20 minutes ago.**
+
+**But they constantly refer to the exact code snippet they pasted 30 seconds ago.**
+
+#### Key Insight
+
+- **Summary = Lossy Compression** (loses error codes, exact wording, file paths)
+- **Chopping = Lossless Compression** (of the recent past)
+- **Recent Precision > Vague History**
+
+In a frugal architecture, we value precision where it matters most: **the recent past**.
+
+## Implementation
+
+### Python API
+
+```python
+from caas.conversation import ConversationManager
+
+# Create manager with sliding window of 10 turns
+manager = ConversationManager(max_turns=10)
+
+# Add conversation turns
+turn_id = manager.add_turn(
+    user_message="I'm getting error 500 when calling /api/users/123",
+    ai_response="That's a database connection issue. Check config.py line 45."
+)
+
+# Get conversation history (last 10 turns, perfectly intact)
+history = manager.get_conversation_history(format_as_text=False)
+
+# Get recent N turns
+recent = manager.get_recent_turns(n=5)
+
+# Get statistics
+stats = manager.get_statistics()
+print(f"Current turns: {stats['current_turns']}")
+print(f"Total ever: {stats['total_turns_ever']}")
+print(f"Deleted: {stats['deleted_turns']}")
+
+# Update AI response for a turn (useful for streaming responses)
+manager.update_turn_response(turn_id, "Updated response")
+
+# Clear conversation
+manager.clear_conversation()
+```
+
+### REST API
+
+#### Add a Conversation Turn
+
+```bash
+POST /conversation/turn
+```
+
+**Request:**
+```json
+{
+  "user_message": "How do I fix error 500?",
+  "ai_response": "Check your database connection...",
+  "metadata": {
+    "source": "chat",
+    "session_id": "abc123"
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "turn_id": "def456",
+  "message": "Conversation turn added successfully",
+  "statistics": {
+    "current_turns": 8,
+    "max_turns": 10,
+    "total_turns_ever": 15,
+    "deleted_turns": 7
+  }
+}
+```
+
+#### Get Conversation History
+
+```bash
+GET /conversation?format_text=false&include_metadata=true
+```
+
+**Response:**
+```json
+{
+  "turns": [
+    {
+      "id": "abc123",
+      "user_message": "How do I fix error 500?",
+      "ai_response": "Check your database connection...",
+      "timestamp": "2024-01-03T14:23:45.123Z",
+      "metadata": {}
+    }
+  ],
+  "total_turns": 10,
+  "max_turns": 10,
+  "total_turns_ever": 25,
+  "oldest_turn_timestamp": "2024-01-03T14:15:00.000Z",
+  "newest_turn_timestamp": "2024-01-03T14:25:00.000Z"
+}
+```
+
+#### Get Conversation Statistics
+
+```bash
+GET /conversation/stats
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "statistics": {
+    "current_turns": 10,
+    "max_turns": 10,
+    "total_turns_ever": 47,
+    "deleted_turns": 37,
+    "oldest_turn": "2024-01-03T14:15:00.000Z",
+    "newest_turn": "2024-01-03T14:25:00.000Z"
+  },
+  "sliding_window_info": {
+    "max_turns": 10,
+    "policy": "FIFO (First In First Out)",
+    "philosophy": "Chopping > Summarizing",
+    "benefits": [
+      "Recent precision: Last N turns perfectly intact",
+      "Zero AI cost: No summarization needed",
+      "No information loss: Lossless compression of recent past",
+      "Predictable: Always know what's in context"
+    ]
+  }
+}
+```
+
+#### Get Recent Turns
+
+```bash
+GET /conversation/recent?n=5
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "recent_turns": [
+    {
+      "id": "xyz789",
+      "user_message": "What about error 404?",
+      "ai_response": "That's a not found error...",
+      "timestamp": "2024-01-03T14:24:00.000Z",
+      "metadata": {}
+    }
+  ],
+  "count": 5,
+  "requested": 5
+}
+```
+
+#### Update Turn Response
+
+```bash
+PATCH /conversation/turn/{turn_id}?ai_response=Updated response text
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "turn_id": "abc123",
+  "message": "AI response updated successfully"
+}
+```
+
+#### Clear Conversation
+
+```bash
+DELETE /conversation
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "message": "Conversation history cleared",
+  "total_turns_ever": 47
+}
+```
+
+## Cost Comparison
+
+### Scenario: 1000 Conversations, 20 Turns Each
+
+#### Summarization Approach ❌
+
+- Summarize every 10 turns
+- Cost per summary: $0.01 (GPT-4o call)
+- Summaries needed: 1,000 conversations × 2 summaries = 2,000
+- **Total cost: $20.00**
+- **Information loss: ⚠️ HIGH** (loses error codes, exact wording, file paths)
+
+#### Sliding Window Approach ✅
+
+- Keep last 10 turns intact
+- Delete older turns (FIFO)
+- Cost per conversation: $0.00 (no AI calls)
+- **Total cost: $0.00**
+- **Information loss: ✅ ZERO** (what's kept is perfect)
+
+### Savings
+
+- **Monthly savings**: $20.00
+- **Annual savings**: $240.00
+- **Per 10K conversations**: $200.00
+
+## FIFO Behavior Example
+
+```
+Window size: 3 turns
+
+Step 1: Add turn 1
+  Current: [Turn 1]
+
+Step 2: Add turn 2
+  Current: [Turn 1, Turn 2]
+
+Step 3: Add turn 3
+  Current: [Turn 1, Turn 2, Turn 3]
+
+Step 4: Add turn 4 (WINDOW FULL!)
+  🗑️  Delete Turn 1 (FIFO)
+  Current: [Turn 2, Turn 3, Turn 4]
+
+Step 5: Add turn 5
+  🗑️  Delete Turn 2 (FIFO)
+  Current: [Turn 3, Turn 4, Turn 5]
+```
+
+**Notice:** Turns are deleted in FIFO order (oldest first), but recent turns are kept PERFECTLY intact.
+
+## Real-World Example: Debugging Session
+
+```python
+manager = ConversationManager(max_turns=5)
+
+# Debugging conversation
+manager.add_turn(
+    "I'm debugging a function",
+    "Let me help you with that"
+)
+
+manager.add_turn(
+    "Here's my code: def process_data(items):",
+    "I see the function signature"
+)
+
+manager.add_turn(
+    "    for item in items:",
+    "You're iterating over items"
+)
+
+manager.add_turn(
+    "        result = item.value * 2",
+    "You're doubling the value"
+)
+
+manager.add_turn(
+    "        print(result)",
+    "You're printing the result"
+)
+
+# Critical insight (turn 6 - triggers deletion of turn 1)
+manager.add_turn(
+    "Wait, I just realized the bug! Line 4 should be item.value * 3 not * 2",
+    "Ah! So the multiplication factor is wrong. Change line 4 to multiply by 3."
+)
+
+# Get recent 3 turns
+recent = manager.get_recent_turns(n=3)
+# Returns turns 4, 5, and 6 with EXACT details about the bug fix
+```
+
+**Key Point:** The user can see the EXACT fix ("line 4 should be item.value * 3 not * 2") instead of a vague summary like "User identified a calculation issue."
+
+## Why This Matters
+
+### Traditional Systems
+1. **Cost money** ($0.01+ per summary)
+2. **Lose critical details** (error codes, file paths, exact wording)
+3. **Create vague summaries** that aren't actionable
+
+### Our Sliding Window
+1. **Costs $0** (no AI calls)
+2. **Keeps recent turns PERFECTLY intact** (lossless)
+3. **Provides exact details** users actually need
+
+## Philosophy
+
+In a frugal architecture:
+- **Recent Precision > Vague History**
+- **Chopping > Summarizing**
+- **Lossless (recent) > Lossy (summary)**
+
+Users care about what happened 30 seconds ago, not 20 minutes ago. The sliding window ensures they always have access to the recent, precise details they need.
+
+## Testing
+
+Run the test suite:
+```bash
+python test_conversation_manager.py
+```
+
+Run the demo:
+```bash
+python demo_conversation_manager.py
+```
+
+## Key Takeaways
+
+1. ✅ **Sliding Window keeps recent turns PERFECTLY intact**
+2. ✅ **No AI cost for context management**
+3. ✅ **No information loss** (what's kept is lossless)
+4. ✅ **Users care about recent details, not old summaries**
+5. ✅ **Recent Precision > Vague History**
+
+---
+
+**The Brutal Squeeze: In a frugal architecture, we chop old data instead of compressing it. What we keep, we keep perfectly. What we don't need, we delete. No middle ground, no lossy summaries.**

modules/caas/docs/STRUCTURE_AWARE_INDEXING.md

@@ -0,0 +1,158 @@
+# Structure-Aware Indexing Implementation Summary
+
+## Problem Statement
+The "Flat Chunk Fallacy" - traditional context extraction systems treat all content equally, splitting documents every N words and treating each chunk the same. This means a random paragraph on page 50 has the same weight as critical API definitions on page 1, leading to poor search results.
+
+## Solution Implemented
+Implemented a three-tier hierarchical structure-aware indexing system that assigns weights based on content importance, not just semantic similarity.
+
+## Architecture
+
+### Three Tiers of Content Classification
+
+#### Tier 1 - High Value Content (2.0x base weight)
+- Class Definitions and Interfaces
+- API Contracts and Endpoints
+- Main Headers (H1, H2)
+- Critical Sections (Definitions, Authentication, Authorization)
+- Abstract, Introduction, Conclusion in papers
+
+#### Tier 2 - Medium Value Content (1.0x base weight)
+- Body text and paragraphs
+- Function implementations
+- Method descriptions
+- Standard documentation sections
+
+#### Tier 3 - Low Value Content (0.5x base weight)
+- Comments and inline documentation
+- TODO/FIXME/HACK markers
+- Footnotes and disclaimers
+- Acknowledgments and copyright notices
+
+## Implementation Details
+
+### Files Created/Modified
+
+1. **caas/models.py**
+   - Added `ContentTier` enum with three tiers
+   - Updated `Section` model to include `tier` field
+
+2. **caas/ingestion/structure_parser.py** (NEW)
+   - `StructureParser` class that analyzes content and assigns tiers
+   - Document-type-aware pattern matching
+   - Supports source code, documentation, legal contracts, research papers
+
+3. **caas/tuning/tuner.py**
+   - Updated `WeightTuner` to use tier-based weights
+   - Changed from multiplicative to additive keyword boosts (prevents excessive amplification)
+   - Integrates structure parser in the tuning pipeline
+
+4. **caas/storage/store.py**
+   - Enhanced `ContextExtractor` to include tier information in metadata
+   - Maintains tier-based prioritization during retrieval
+
+5. **test_structure_aware_indexing.py** (NEW)
+   - Comprehensive tests for tier classification
+   - Tests for tier-based retrieval prioritization
+   - Validates that tiers work even when semantic similarity is equal
+
+6. **demo_structure_aware.py** (NEW)
+   - Interactive demonstration of the feature
+   - Shows real-world example with source code
+
+7. **README.md**
+   - Added detailed explanation of structure-aware indexing
+   - Updated features list, problem statement, and architecture diagrams
+
+## Key Results
+
+### Before (Flat Chunk Approach)
+```
+Section: "public class Authentication"  → 1.0x weight
+Section: "// TODO: fix this later"      → 1.0x weight
+Result: Poor search quality
+```
+
+### After (Structure-Aware Approach)
+```
+Section: "public class Authentication" → 3.95x weight (Tier 1)
+Section: "// TODO: fix this later"     → 0.5x weight (Tier 3)
+Result: High-value content prioritized 8x over low-value
+```
+
+## Test Results
+
+✅ **All Original Tests Pass** - Backward compatible, no breaking changes
+✅ **New Tests Pass** - 4/4 structure-aware indexing tests pass
+✅ **Security Scan Clean** - CodeQL: 0 alerts
+✅ **Code Review Completed** - All feedback addressed
+
+### Test Coverage
+- Tier base weight validation
+- Content classification into tiers
+- Tier-based retrieval prioritization
+- Semantic similarity with tier boosting (key feature!)
+- Integration with existing pipeline
+
+## Technical Highlights
+
+1. **Document Type Awareness**: Different patterns for different document types (source code vs documentation vs legal contracts)
+
+2. **Intelligent Pattern Matching**: Uses regex patterns to identify:
+   - Class/interface definitions
+   - API endpoints (GET/POST/PUT/DELETE)
+   - Critical sections by title
+   - Comment markers (TODO, FIXME, etc.)
+
+3. **Balanced Weight Calculation**: 
+   - Tier provides base weight
+   - Keyword boosts are additive (not multiplicative) to prevent excessive amplification
+   - Additional content analysis (definitions, code examples, important markers)
+   - Position-based adjustments (first/last sections)
+
+4. **Query Boosting**: Matching sections get 50% boost, but tier hierarchy is maintained
+
+## Example Use Case
+
+### Source Code Indexing
+```python
+# Input: Python authentication module
+class Authentication:           # Tier 1 → 3.95x weight
+    def login(self, ...):       # Tier 2 → ~1.5x weight
+        # TODO: rate limit      # Tier 3 → 0.5x weight
+
+# Query: "authentication"
+# Result Order:
+# 1. Class Authentication (Tier 1, highest weight)
+# 2. login method (Tier 2, medium weight)
+# 3. TODO comment (Tier 3, lowest weight)
+```
+
+### API Documentation
+```markdown
+# Authentication API           # Tier 1 → High weight
+POST /authenticate             # Tier 1 → High weight
+Implementation details         # Tier 2 → Medium weight
+Footnotes and disclaimers     # Tier 3 → Low weight
+```
+
+## Impact
+
+1. **Better Search Results**: Critical content surfaces first
+2. **Automatic Optimization**: No manual weight configuration needed
+3. **Context Quality**: AI gets the right information, not just similar text
+4. **Scalable**: Works across document types and formats
+5. **Backward Compatible**: Existing functionality unchanged
+
+## Future Enhancements
+
+Potential improvements (not in scope for this PR):
+- Machine learning-based tier classification
+- User feedback loop for tier adjustments
+- Custom tier definitions per organization
+- Tier visualization in API responses
+- Performance optimization for large documents
+
+## Conclusion
+
+Successfully implemented structure-aware indexing that solves the "Flat Chunk Fallacy". The system now intelligently prioritizes high-value content (class definitions, API contracts) over low-value content (comments, TODOs) based on hierarchical structure, not just semantic similarity. This fundamental improvement ensures better context extraction and search quality across all document types.