agent_os_kernel 3.1.0__py3-none-any.whl

caas/cli.py

@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Command-line interface for Context-as-a-Service.
+"""
+
+import sys
+import json
+from pathlib import Path
+
+from caas.models import ContentFormat
+from caas.ingestion import ProcessorFactory
+from caas.detection import DocumentTypeDetector, StructureAnalyzer
+from caas.tuning import WeightTuner
+from caas.storage import DocumentStore, ContextExtractor
+
+
+def main():
+    """Main CLI entry point."""
+    if len(sys.argv) < 2:
+        print_usage()
+        return
+    
+    command = sys.argv[1]
+    
+    if command == "ingest":
+        ingest_command()
+    elif command == "analyze":
+        analyze_command()
+    elif command == "context":
+        context_command()
+    elif command == "list":
+        list_command()
+    else:
+        print(f"Unknown command: {command}")
+        print_usage()
+
+
+def print_usage():
+    """Print CLI usage information."""
+    print("""
+Context-as-a-Service CLI
+
+Usage:
+    caas ingest <file> <format> [title]    Ingest a document
+    caas analyze <document_id>             Analyze a document
+    caas context <document_id> [query]     Extract context
+    caas list                              List all documents
+
+Formats: pdf, html, code
+
+Examples:
+    caas ingest contract.pdf pdf "Employment Contract"
+    caas analyze abc-123
+    caas context abc-123 "termination clause"
+    """)
+
+
+def ingest_command():
+    """Handle ingest command."""
+    if len(sys.argv) < 4:
+        print("Usage: caas ingest <file> <format> [title]")
+        return
+    
+    file_path = Path(sys.argv[2])
+    format_str = sys.argv[3]
+    title = sys.argv[4] if len(sys.argv) > 4 else file_path.stem
+    
+    if not file_path.exists():
+        print(f"Error: File not found: {file_path}")
+        return
+    
+    # Map format string to enum
+    format_map = {
+        "pdf": ContentFormat.PDF,
+        "html": ContentFormat.HTML,
+        "code": ContentFormat.CODE,
+    }
+    
+    format_enum = format_map.get(format_str.lower())
+    if not format_enum:
+        print(f"Error: Invalid format: {format_str}")
+        print("Valid formats: pdf, html, code")
+        return
+    
+    # Process document
+    print(f"Ingesting {file_path}...")
+    
+    content = file_path.read_bytes()
+    processor = ProcessorFactory.get_processor(format_enum)
+    
+    import uuid
+    doc_id = str(uuid.uuid4())
+    
+    metadata = {
+        "id": doc_id,
+        "title": title,
+        "filename": file_path.name,
+    }
+    
+    document = processor.process(content, metadata)
+    
+    # Auto-detect and tune
+    detector = DocumentTypeDetector()
+    document.detected_type = detector.detect(document)
+    
+    tuner = WeightTuner()
+    document = tuner.tune(document)
+    
+    # Store
+    store = DocumentStore("caas_data.json")
+    store.add(document)
+    
+    print(f"\n✓ Document ingested successfully!")
+    print(f"  ID: {document.id}")
+    print(f"  Title: {document.title}")
+    print(f"  Detected Type: {document.detected_type}")
+    print(f"  Sections: {len(document.sections)}")
+    print(f"\nTop weighted sections:")
+    sorted_sections = sorted(document.sections, key=lambda s: s.weight, reverse=True)
+    for section in sorted_sections[:5]:
+        print(f"  - {section.title}: {section.weight}x")
+
+
+def analyze_command():
+    """Handle analyze command."""
+    if len(sys.argv) < 3:
+        print("Usage: caas analyze <document_id>")
+        return
+    
+    doc_id = sys.argv[2]
+    
+    store = DocumentStore("caas_data.json")
+    document = store.get(doc_id)
+    
+    if not document:
+        print(f"Error: Document not found: {doc_id}")
+        return
+    
+    analyzer = StructureAnalyzer()
+    detector = DocumentTypeDetector()
+    
+    structure = detector.detect_structure(document)
+    analysis = analyzer.analyze(document)
+    
+    print(f"\n=== Document Analysis ===")
+    print(f"ID: {document.id}")
+    print(f"Title: {document.title}")
+    print(f"Type: {document.detected_type}")
+    print(f"\nStructure:")
+    print(f"  Sections: {structure['section_count']}")
+    print(f"  Clear Structure: {'Yes' if structure['has_clear_sections'] else 'No'}")
+    print(f"  Quality: {analysis['structure_quality']}")
+    print(f"\nKey Sections:")
+    for section in structure['key_sections']:
+        print(f"  - {section}")
+
+
+def context_command():
+    """Handle context command."""
+    if len(sys.argv) < 3:
+        print("Usage: caas context <document_id> [query]")
+        return
+    
+    doc_id = sys.argv[2]
+    query = sys.argv[3] if len(sys.argv) > 3 else ""
+    
+    store = DocumentStore("caas_data.json")
+    document = store.get(doc_id)
+    
+    if not document:
+        print(f"Error: Document not found: {doc_id}")
+        return
+    
+    extractor = ContextExtractor(store)
+    context, metadata = extractor.extract_context(doc_id, query, max_tokens=500)
+    
+    print(f"\n=== Context Extraction ===")
+    print(f"Document: {document.title}")
+    print(f"Type: {document.detected_type}")
+    if query:
+        print(f"Query: {query}")
+    print(f"\nSections used: {len(metadata['sections_used'])}/{metadata['total_sections']}")
+    for section in metadata['sections_used']:
+        print(f"  - {section}")
+    print(f"\n--- Context ---")
+    print(context[:1000] + ("..." if len(context) > 1000 else ""))
+
+
+def list_command():
+    """Handle list command."""
+    store = DocumentStore("caas_data.json")
+    documents = store.list_all()
+    
+    if not documents:
+        print("No documents found.")
+        return
+    
+    print(f"\n=== Documents ({len(documents)}) ===")
+    for doc in documents:
+        print(f"\n{doc.id}")
+        print(f"  Title: {doc.title}")
+        print(f"  Type: {doc.detected_type}")
+        print(f"  Format: {doc.format}")
+        print(f"  Sections: {len(doc.sections)}")
+
+
+if __name__ == "__main__":
+    main()

caas/conversation.py

@@ -0,0 +1,223 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Conversation Manager for Sliding Window (FIFO) history management.
+
+The Brutal Squeeze Philosophy:
+"Chopping > Summarizing"
+
+Instead of asking an AI to summarize conversation history (which costs money and loses nuance),
+we use a brutal "Sliding Window" approach:
+- Keep the last 10 turns perfectly intact
+- Delete turn 11 (FIFO - First In First Out)
+- No summarization = No lossy compression
+- Recent Precision over Vague History
+
+Why this works:
+- Users rarely refer back to what they said 20 minutes ago
+- They constantly refer to the exact code snippet they pasted 30 seconds ago
+- Summary = Lossy Compression (loses specific error codes, exact wording)
+- Chopping = Lossless Compression (of the recent past)
+
+Example:
+Turn 1: "I tried X and it failed with error code 500"
+With Summarization: "User attempted troubleshooting" (ERROR CODE LOST!)
+With Chopping: After 10 new turns, this is deleted entirely
+                But turns 2-11 are perfectly intact with all details
+"""
+
+from typing import Dict, List, Optional, Any, Union
+from datetime import datetime, timezone
+import uuid
+import logging
+
+from caas.models import ConversationTurn, ConversationState
+
+# Set up logger
+logger = logging.getLogger(__name__)
+
+
+class ConversationManager:
+    """
+    Manages conversation history using a Sliding Window (FIFO) approach.
+    
+    The Sliding Window ensures:
+    1. Recent precision: Last N turns are perfectly intact
+    2. Zero summarization cost: No AI calls needed
+    3. No information loss: What's kept is lossless
+    4. Predictable behavior: Always know what's in context
+    
+    Philosophy:
+    In a frugal architecture, we value Recent Precision over Vague History.
+    """
+    
+    def __init__(self, max_turns: int = 10):
+        """
+        Initialize the conversation manager.
+        
+        Args:
+            max_turns: Maximum number of turns to keep (default: 10)
+        """
+        self.state = ConversationState(max_turns=max_turns)
+    
+    def add_turn(
+        self, 
+        user_message: str,
+        ai_response: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> str:
+        """
+        Add a conversation turn to the history.
+        
+        This implements the FIFO Sliding Window:
+        - If we have < max_turns, just add the turn
+        - If we have = max_turns, delete the oldest turn and add the new one
+        - No summarization, no compression, just brutal chopping
+        
+        Args:
+            user_message: The user's message
+            ai_response: The AI's response (optional)
+            metadata: Optional metadata for the turn
+            
+        Returns:
+            The ID of the created turn
+        """
+        turn_id = str(uuid.uuid4())
+        turn = ConversationTurn(
+            id=turn_id,
+            user_message=user_message,
+            ai_response=ai_response,
+            timestamp=datetime.now(timezone.utc).isoformat(),
+            metadata=metadata or {}
+        )
+        
+        # FIFO: If we're at max capacity, delete the oldest turn
+        if len(self.state.turns) >= self.state.max_turns:
+            deleted_turn = self.state.turns.pop(0)  # Remove first (oldest) turn
+            logger.debug(f"FIFO: Deleted oldest turn (ID: {deleted_turn.id[:8]}...) to make room")
+        
+        # Add the new turn at the end
+        self.state.turns.append(turn)
+        self.state.total_turns_ever += 1
+        
+        return turn_id
+    
+    def update_turn_response(self, turn_id: str, ai_response: str) -> bool:
+        """
+        Update the AI response for a specific turn.
+        
+        Useful when you add a turn with just the user message
+        and want to update it with the AI response later.
+        
+        Args:
+            turn_id: The ID of the turn to update
+            ai_response: The AI response to add
+            
+        Returns:
+            True if turn was found and updated, False otherwise
+        """
+        for turn in self.state.turns:
+            if turn.id == turn_id:
+                turn.ai_response = ai_response
+                return True
+        return False
+    
+    def get_conversation_history(
+        self, 
+        include_metadata: bool = False,
+        format_as_text: bool = True
+    ) -> Union[List[ConversationTurn], str]:
+        """
+        Get the conversation history (last N turns).
+        
+        Returns the history in FIFO order (oldest to newest).
+        All turns are perfectly intact - no summarization, no loss.
+        
+        Args:
+            include_metadata: Whether to include metadata in text format
+            format_as_text: If True, return formatted text; if False, return list of turns
+            
+        Returns:
+            Formatted conversation history or list of turns
+        """
+        if not format_as_text:
+            return self.state.turns
+        
+        if not self.state.turns:
+            return "No conversation history."
+        
+        # Format as text
+        parts = ["# Conversation History (Sliding Window)\n"]
+        parts.append(f"_Keeping last {self.state.max_turns} turns intact (no summarization)_\n")
+        parts.append(f"_Total turns ever: {self.state.total_turns_ever}_\n\n")
+        
+        for i, turn in enumerate(self.state.turns, 1):
+            parts.append(f"## Turn {i}\n")
+            parts.append(f"**User**: {turn.user_message}\n")
+            if turn.ai_response:
+                parts.append(f"**AI**: {turn.ai_response}\n")
+            if include_metadata and turn.metadata:
+                parts.append(f"_Metadata: {turn.metadata}_\n")
+            parts.append("\n")
+        
+        return "".join(parts)
+    
+    def get_recent_turns(self, n: int = 5) -> List[ConversationTurn]:
+        """
+        Get the N most recent turns.
+        
+        Args:
+            n: Number of recent turns to get
+            
+        Returns:
+            List of recent turns (newest last)
+        """
+        return self.state.turns[-n:] if len(self.state.turns) > n else self.state.turns
+    
+    def clear_conversation(self):
+        """Clear all conversation history."""
+        self.state.turns = []
+    
+    def get_state(self) -> ConversationState:
+        """
+        Get the current conversation state.
+        
+        Returns:
+            The current conversation state
+        """
+        return self.state
+    
+    def set_state(self, state: ConversationState):
+        """
+        Set the conversation state.
+        
+        Args:
+            state: The new conversation state
+        """
+        self.state = state
+    
+    def get_statistics(self) -> Dict[str, Any]:
+        """
+        Get statistics about the conversation.
+        
+        Returns:
+            Dictionary with statistics
+        """
+        if not self.state.turns:
+            return {
+                "current_turns": 0,
+                "max_turns": self.state.max_turns,
+                "total_turns_ever": self.state.total_turns_ever,
+                "deleted_turns": self.state.total_turns_ever,
+                "oldest_turn": None,
+                "newest_turn": None,
+            }
+        
+        return {
+            "current_turns": len(self.state.turns),
+            "max_turns": self.state.max_turns,
+            "total_turns_ever": self.state.total_turns_ever,
+            "deleted_turns": self.state.total_turns_ever - len(self.state.turns),
+            "oldest_turn": self.state.turns[0].timestamp if self.state.turns else None,
+            "newest_turn": self.state.turns[-1].timestamp if self.state.turns else None,
+        }

caas/decay.py

@@ -0,0 +1,72 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# Public Preview — basic context/memory management
+"""
+Simple TTL-based decay for document relevance scoring.
+
+Returns 1.0 if within TTL, 0.0 if expired, with linear interpolation between.
+"""
+
+from datetime import datetime, timezone
+from typing import Optional
+
+# Default TTL in days
+_DEFAULT_TTL_DAYS = 30.0
+
+
+def calculate_decay_factor(
+    ingestion_timestamp: Optional[str],
+    reference_time: Optional[datetime] = None,
+    decay_rate: float = 1.0,
+) -> float:
+    """
+    Calculate a simple TTL-based decay factor.
+
+    Returns 1.0 when the document is brand-new and linearly decays to 0.0
+    at ``_DEFAULT_TTL_DAYS / decay_rate`` days old.
+
+    Args:
+        ingestion_timestamp: ISO-format timestamp of document ingestion.
+        reference_time: Time to measure from (defaults to now).
+        decay_rate: Higher values shorten the effective TTL.
+
+    Returns:
+        Decay factor between 0.0 and 1.0.
+    """
+    if not ingestion_timestamp:
+        return 0.0
+
+    try:
+        ingestion_dt = datetime.fromisoformat(
+            ingestion_timestamp.replace("Z", "+00:00")
+        )
+        if reference_time is None:
+            reference_time = datetime.now(timezone.utc)
+
+        days_elapsed = max(
+            0.0, (reference_time - ingestion_dt).total_seconds() / 86400.0
+        )
+        ttl = _DEFAULT_TTL_DAYS / max(decay_rate, 0.001)
+        if days_elapsed >= ttl:
+            return 0.0
+        return 1.0 - (days_elapsed / ttl)
+    except (ValueError, AttributeError, TypeError):
+        return 0.0
+
+
+def apply_decay_to_score(base_score: float, decay_factor: float) -> float:
+    """Apply *decay_factor* to *base_score*."""
+    return base_score * decay_factor
+
+
+def get_time_weighted_score(
+    base_score: float,
+    ingestion_timestamp: Optional[str],
+    reference_time: Optional[datetime] = None,
+    decay_rate: float = 1.0,
+) -> float:
+    """Convenience: compute time-weighted score in one call."""
+    return apply_decay_to_score(
+        base_score,
+        calculate_decay_factor(ingestion_timestamp, reference_time, decay_rate),
+    )

caas/detection/__init__.py

@@ -0,0 +1,9 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Detection module initialization.
+"""
+
+from caas.detection.detector import DocumentTypeDetector, StructureAnalyzer
+
+__all__ = ["DocumentTypeDetector", "StructureAnalyzer"]