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

modules/caas/experiments/README.md

@@ -0,0 +1,42 @@
+# Experiments Directory
+
+This folder contains reproducibility scripts for the CaaS paper.
+
+## Quick Start
+
+```bash
+# Run the main reproducibility script
+python experiments/reproduce_results.py
+
+# Run with custom seed
+python experiments/reproduce_results.py --seed 42 --output experiments/results.json
+```
+
+## Files
+
+- `reproduce_results.py` - Main reproducibility script for paper claims
+- `results.json` - Output results (generated after running)
+
+## Full Benchmarks
+
+For comprehensive benchmarks including the full corpus evaluation, see:
+
+```bash
+python benchmarks/run_evaluation.py --corpus benchmarks/data/sample_corpus/
+```
+
+## Paper Claims
+
+The reproducibility script validates the following claims from the paper:
+
+| Claim | Metric | Expected |
+|-------|--------|----------|
+| Sub-millisecond routing | Router latency | < 0.01 ms |
+| High routing accuracy | Heuristic accuracy | > 90% |
+| Fast context operations | Triad add operations | < 0.1 ms/item |
+
+## Requirements
+
+```bash
+pip install caas-core numpy
+```

modules/caas/experiments/reproduce_results.py

@@ -0,0 +1,462 @@
+#!/usr/bin/env python3
+"""
+CaaS Reproducibility Script.
+
+This script provides a simple, reproducible way to run the CaaS benchmarks
+and verify the results reported in the paper.
+
+Usage:
+    python experiments/reproduce_results.py
+    python experiments/reproduce_results.py --seed 42 --output results.json
+
+The script will:
+    1. Set up a controlled environment with fixed random seed
+    2. Run the core CaaS components against sample inputs
+    3. Measure metrics (latency, accuracy, token efficiency)
+    4. Save results to experiments/results.json
+
+For full benchmark evaluation, see: benchmarks/run_evaluation.py
+
+Requirements:
+    pip install caas-core numpy
+
+Author: Imran Siddique
+License: MIT
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import random
+import sys
+import time
+from dataclasses import asdict, dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import numpy as np
+
+# Add parent directory for imports if running as script
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+try:
+    from caas import __version__ as CAAS_VERSION
+    from caas.routing.heuristic_router import HeuristicRouter
+    from caas.triad import ContextTriadManager
+    from caas.decay import TimeDecayCalculator
+    from caas.models import ModelTier
+
+    CAAS_AVAILABLE = True
+except ImportError as e:
+    CAAS_AVAILABLE = False
+    CAAS_VERSION = "unknown"
+    print(f"Warning: CaaS not fully available ({e}). Running in demo mode.")
+
+
+# ============================================================================
+# Configuration
+# ============================================================================
+
+DEFAULT_SEED = 42
+DEFAULT_OUTPUT = "experiments/results.json"
+
+# Sample queries for routing benchmark
+SAMPLE_QUERIES = [
+    # Greetings (should route to CANNED)
+    "Hi",
+    "Hello there",
+    "Thanks!",
+    "Ok",
+    # Short queries (should route to FAST)
+    "What is RAG?",
+    "Define context window",
+    "List the files",
+    # Complex queries (should route to SMART)
+    "Summarize the architecture of this system and explain the tradeoffs",
+    "Analyze the performance implications of using vector similarity search",
+    "Compare the Context Triad approach with traditional RAG systems",
+    "Please provide a comprehensive review of the code structure",
+]
+
+# Expected routing results for accuracy calculation
+EXPECTED_ROUTING = {
+    "Hi": ModelTier.CANNED,
+    "Hello there": ModelTier.CANNED,
+    "Thanks!": ModelTier.CANNED,
+    "Ok": ModelTier.CANNED,
+    "What is RAG?": ModelTier.FAST,
+    "Define context window": ModelTier.FAST,
+    "List the files": ModelTier.FAST,
+    "Summarize the architecture of this system and explain the tradeoffs": ModelTier.SMART,
+    "Analyze the performance implications of using vector similarity search": ModelTier.SMART,
+    "Compare the Context Triad approach with traditional RAG systems": ModelTier.SMART,
+    "Please provide a comprehensive review of the code structure": ModelTier.SMART,
+}
+
+
+# ============================================================================
+# Data Classes
+# ============================================================================
+
+
+@dataclass
+class BenchmarkConfig:
+    """Configuration for the benchmark run."""
+
+    seed: int = DEFAULT_SEED
+    n_iterations: int = 100
+    warmup_iterations: int = 10
+
+
+@dataclass
+class MetricResult:
+    """A single metric measurement."""
+
+    name: str
+    value: float
+    std: Optional[float] = None
+    unit: str = ""
+    n_samples: int = 1
+
+
+@dataclass
+class ExperimentResults:
+    """Complete experiment results."""
+
+    timestamp: str
+    caas_version: str
+    python_version: str
+    seed: int
+    metrics: Dict[str, Any]
+    config: Dict[str, Any]
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "timestamp": self.timestamp,
+            "caas_version": self.caas_version,
+            "python_version": self.python_version,
+            "seed": self.seed,
+            "metrics": self.metrics,
+            "config": self.config,
+        }
+
+
+# ============================================================================
+# Benchmark Functions
+# ============================================================================
+
+
+def set_seed(seed: int) -> None:
+    """Set random seed for reproducibility.
+
+    Args:
+        seed: Random seed value.
+    """
+    random.seed(seed)
+    np.random.seed(seed)
+
+
+def benchmark_router_latency(
+    router: HeuristicRouter,
+    queries: List[str],
+    n_iterations: int = 100,
+    warmup: int = 10,
+) -> MetricResult:
+    """Benchmark the heuristic router latency.
+
+    Args:
+        router: The HeuristicRouter instance.
+        queries: List of queries to route.
+        n_iterations: Number of timing iterations.
+        warmup: Number of warmup iterations.
+
+    Returns:
+        MetricResult with latency statistics.
+    """
+    # Warmup
+    for _ in range(warmup):
+        for query in queries:
+            router.route(query)
+
+    # Timed iterations
+    latencies = []
+    for _ in range(n_iterations):
+        for query in queries:
+            start = time.perf_counter()
+            router.route(query)
+            end = time.perf_counter()
+            latencies.append((end - start) * 1000)  # Convert to ms
+
+    latencies_arr = np.array(latencies)
+
+    return MetricResult(
+        name="router_latency",
+        value=float(np.mean(latencies_arr)),
+        std=float(np.std(latencies_arr)),
+        unit="ms",
+        n_samples=len(latencies),
+    )
+
+
+def benchmark_router_accuracy(
+    router: HeuristicRouter,
+    queries: List[str],
+    expected: Dict[str, ModelTier],
+) -> MetricResult:
+    """Benchmark the heuristic router accuracy.
+
+    Args:
+        router: The HeuristicRouter instance.
+        queries: List of queries to route.
+        expected: Dictionary mapping queries to expected ModelTier.
+
+    Returns:
+        MetricResult with accuracy percentage.
+    """
+    correct = 0
+    total = 0
+
+    for query in queries:
+        if query in expected:
+            decision = router.route(query)
+            if decision.model_tier == expected[query]:
+                correct += 1
+            total += 1
+
+    accuracy = (correct / total * 100) if total > 0 else 0.0
+
+    return MetricResult(
+        name="router_accuracy",
+        value=accuracy,
+        unit="%",
+        n_samples=total,
+    )
+
+
+def benchmark_context_triad(
+    n_items: int = 100,
+) -> Dict[str, MetricResult]:
+    """Benchmark Context Triad operations.
+
+    Args:
+        n_items: Number of context items to add.
+
+    Returns:
+        Dictionary of MetricResults for various operations.
+    """
+    triad = ContextTriadManager()
+    results = {}
+
+    # Benchmark add_hot_context
+    start = time.perf_counter()
+    for i in range(n_items):
+        triad.add_hot_context(f"Hot context item {i}", metadata={"index": i})
+    hot_time = (time.perf_counter() - start) * 1000
+
+    results["add_hot_context"] = MetricResult(
+        name="add_hot_context",
+        value=hot_time / n_items,
+        unit="ms/item",
+        n_samples=n_items,
+    )
+
+    # Benchmark add_warm_context
+    start = time.perf_counter()
+    for i in range(n_items):
+        triad.add_warm_context(f"Warm context item {i}", metadata={"index": i})
+    warm_time = (time.perf_counter() - start) * 1000
+
+    results["add_warm_context"] = MetricResult(
+        name="add_warm_context",
+        value=warm_time / n_items,
+        unit="ms/item",
+        n_samples=n_items,
+    )
+
+    # Benchmark add_cold_context
+    start = time.perf_counter()
+    for i in range(n_items):
+        triad.add_cold_context(f"Cold context item {i}", metadata={"index": i})
+    cold_time = (time.perf_counter() - start) * 1000
+
+    results["add_cold_context"] = MetricResult(
+        name="add_cold_context",
+        value=cold_time / n_items,
+        unit="ms/item",
+        n_samples=n_items,
+    )
+
+    return results
+
+
+def benchmark_decay_calculator(
+    n_items: int = 1000,
+) -> MetricResult:
+    """Benchmark time decay calculations.
+
+    Args:
+        n_items: Number of decay calculations.
+
+    Returns:
+        MetricResult with timing statistics.
+    """
+    calculator = TimeDecayCalculator()
+
+    # Generate random ages (in hours)
+    ages = np.random.exponential(scale=24, size=n_items)
+
+    start = time.perf_counter()
+    for age in ages:
+        calculator.calculate_decay(float(age))
+    elapsed = (time.perf_counter() - start) * 1000
+
+    return MetricResult(
+        name="decay_calculation",
+        value=elapsed / n_items,
+        unit="ms/calculation",
+        n_samples=n_items,
+    )
+
+
+# ============================================================================
+# Main
+# ============================================================================
+
+
+def run_experiments(config: BenchmarkConfig) -> ExperimentResults:
+    """Run all benchmark experiments.
+
+    Args:
+        config: Benchmark configuration.
+
+    Returns:
+        ExperimentResults with all metrics.
+    """
+    print(f"Setting random seed: {config.seed}")
+    set_seed(config.seed)
+
+    metrics: Dict[str, Any] = {}
+
+    if not CAAS_AVAILABLE:
+        print("CaaS not available. Returning empty results.")
+        return ExperimentResults(
+            timestamp=datetime.utcnow().isoformat(),
+            caas_version=CAAS_VERSION,
+            python_version=f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}",
+            seed=config.seed,
+            metrics={},
+            config=asdict(config),
+        )
+
+    # 1. Router benchmarks
+    print("\n[1/4] Benchmarking Heuristic Router...")
+    router = HeuristicRouter()
+
+    latency_result = benchmark_router_latency(
+        router,
+        SAMPLE_QUERIES,
+        n_iterations=config.n_iterations,
+        warmup=config.warmup_iterations,
+    )
+    metrics["router_latency_ms"] = latency_result.value
+    metrics["router_latency_std"] = latency_result.std
+    print(f"  - Latency: {latency_result.value:.4f} ± {latency_result.std:.4f} ms")
+
+    accuracy_result = benchmark_router_accuracy(router, SAMPLE_QUERIES, EXPECTED_ROUTING)
+    metrics["router_accuracy_pct"] = accuracy_result.value
+    print(f"  - Accuracy: {accuracy_result.value:.1f}%")
+
+    # 2. Context Triad benchmarks
+    print("\n[2/4] Benchmarking Context Triad...")
+    triad_results = benchmark_context_triad(n_items=100)
+    for name, result in triad_results.items():
+        metrics[f"triad_{name}_ms"] = result.value
+        print(f"  - {name}: {result.value:.4f} {result.unit}")
+
+    # 3. Decay calculator benchmarks
+    print("\n[3/4] Benchmarking Time Decay Calculator...")
+    decay_result = benchmark_decay_calculator(n_items=1000)
+    metrics["decay_calculation_ms"] = decay_result.value
+    print(f"  - Decay calculation: {decay_result.value:.6f} {decay_result.unit}")
+
+    # 4. Summary statistics
+    print("\n[4/4] Computing summary statistics...")
+    metrics["total_queries_tested"] = len(SAMPLE_QUERIES)
+    metrics["n_iterations"] = config.n_iterations
+
+    return ExperimentResults(
+        timestamp=datetime.utcnow().isoformat(),
+        caas_version=CAAS_VERSION,
+        python_version=f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}",
+        seed=config.seed,
+        metrics=metrics,
+        config=asdict(config),
+    )
+
+
+def main() -> None:
+    """Main entry point."""
+    parser = argparse.ArgumentParser(
+        description="CaaS Reproducibility Script",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__,
+    )
+    parser.add_argument(
+        "--seed",
+        type=int,
+        default=DEFAULT_SEED,
+        help=f"Random seed (default: {DEFAULT_SEED})",
+    )
+    parser.add_argument(
+        "--output",
+        type=str,
+        default=DEFAULT_OUTPUT,
+        help=f"Output file path (default: {DEFAULT_OUTPUT})",
+    )
+    parser.add_argument(
+        "--iterations",
+        type=int,
+        default=100,
+        help="Number of timing iterations (default: 100)",
+    )
+
+    args = parser.parse_args()
+
+    print("=" * 60)
+    print("CaaS Reproducibility Benchmark")
+    print("=" * 60)
+    print(f"CaaS Version: {CAAS_VERSION}")
+    print(f"Python Version: {sys.version}")
+    print(f"Timestamp: {datetime.utcnow().isoformat()}")
+
+    config = BenchmarkConfig(
+        seed=args.seed,
+        n_iterations=args.iterations,
+    )
+
+    results = run_experiments(config)
+
+    # Ensure output directory exists
+    output_path = Path(args.output)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Save results
+    with open(output_path, "w", encoding="utf-8") as f:
+        json.dump(results.to_dict(), f, indent=2)
+
+    print("\n" + "=" * 60)
+    print(f"Results saved to: {output_path}")
+    print("=" * 60)
+
+    # Print summary
+    print("\nSummary:")
+    print(f"  - Router latency: {results.metrics.get('router_latency_ms', 'N/A'):.4f} ms")
+    print(f"  - Router accuracy: {results.metrics.get('router_accuracy_pct', 'N/A'):.1f}%")
+    print(f"  - Seed: {results.seed}")
+
+
+if __name__ == "__main__":
+    main()

modules/caas/paper/ARXIV_METADATA.md

@@ -0,0 +1,145 @@
+# arXiv Submission Metadata
+
+**Submission Package**: `arxiv_submission.tar` (399 KB)  
+**Generated**: January 22, 2026
+
+---
+
+## Required Metadata Fields
+
+### Title
+```
+Context-as-a-Service: A Principled Architecture for Enterprise RAG Systems
+```
+
+### Authors
+```
+Imran Siddique
+Microsoft
+imran.siddique@microsoft.com
+```
+
+### Abstract
+```
+Retrieval-Augmented Generation (RAG) systems have become essential for grounding LLM outputs in factual content. However, production deployments face seven critical fallacies that current frameworks fail to address: (1) the Flat Chunk Fallacy, treating all content equally regardless of structural importance; (2) Context Amnesia, losing metadata when chunks are extracted; (3) Time-Blind Retrieval, ignoring content freshness; (4) Flat Context, lacking priority tiers for different context types; (5) Official Truth Fallacy, favoring documentation over practical knowledge; (6) Brutal Squeeze, using lossy summarization instead of precision truncation; and (7) the Middleware Gap, trusting third-party routers with sensitive data.
+
+We present Context-as-a-Service (CaaS), an open-source framework that systematically addresses these challenges through five novel components: (a) Structure-Aware Indexing with three-tier value hierarchies; (b) Context Triad for Hot/Warm/Cold intimacy-based prioritization; (c) Pragmatic Truth tracking that surfaces practical knowledge alongside official sources; (d) Heuristic Router for zero-latency deterministic query routing; and (e) Trust Gateway for enterprise-grade on-premises deployment.
+
+We evaluate CaaS on a new benchmark corpus of 16 enterprise documents spanning code, legal, HR, and engineering domains. Our experiments demonstrate 28.1% improvement in Precision@5 and 27.9% improvement in NDCG@10 over flat-chunk baselines, with sub-millisecond routing latency (0.003ms) and only 18.4% latency overhead for the full pipeline. CaaS is available as an open-source Python package with MIT license, Docker support, and a public Hugging Face dataset for reproducibility.
+```
+
+### Categories
+
+**Primary Category**:
+```
+cs.AI - Artificial Intelligence
+```
+
+**Cross-list Categories** (select all that apply):
+```
+cs.CL - Computation and Language
+cs.IR - Information Retrieval
+cs.SE - Software Engineering
+```
+
+### Comments Field
+```
+Code: https://github.com/imran-siddique/context-as-a-service
+PyPI: https://pypi.org/project/context-as-a-service/
+Dataset: https://huggingface.co/datasets/imran-siddique/context-as-a-service
+12 pages, 4 figures, 9 tables
+```
+
+### License
+```
+CC BY 4.0 (Creative Commons Attribution 4.0 International)
+```
+
+### ACM Classification (optional)
+```
+I.2.7 Natural Language Processing
+H.3.3 Information Search and Retrieval
+```
+
+### Keywords (for discoverability)
+```
+Retrieval-Augmented Generation, RAG, Enterprise AI, Context Management, LLM, Large Language Models, Information Retrieval, Context Window, Document Indexing, Accumulation Paradox
+```
+
+---
+
+## Submission Checklist
+
+### Before Submission
+- [x] Update author names and affiliations in `main.tex` (line ~52)
+- [x] Update email addresses in `main.tex`
+- [ ] Verify all figures render correctly
+- [ ] Verify all citations compile without errors
+- [ ] Run spell check on abstract and paper
+- [ ] Verify URLs in Comments field are accessible
+
+### Package Contents
+- [x] `main.tex` - Main LaTeX source (20.7 KB)
+- [x] `references.bib` - BibTeX bibliography with 17 entries (6.2 KB)
+- [x] `figures/fig1_system_architecture.png` - System architecture (105 KB)
+- [x] `figures/fig2_context_triad.png` - Context Triad diagram (115 KB)
+- [x] `figures/fig3_ablation_results.png` - Ablation study (83 KB)
+- [x] `figures/fig4_routing_latency.png` - Routing latency (72 KB)
+
+**Total Package Size**: 399 KB (well under arXiv's 10 MB limit)
+
+### Compilation Instructions
+```bash
+pdflatex main.tex
+bibtex main
+pdflatex main.tex
+pdflatex main.tex
+```
+
+---
+
+## Key References Added (Accumulation Paradox)
+
+The following verified citations were added to support the Accumulation Paradox concept:
+
+1. **Liu et al. (2023)** - "Lost in the Middle: How Language Models Use Long Contexts"
+   - Venue: TACL
+   - arXiv: 2307.03172
+   - Key contribution: U-shaped performance curve in long contexts
+
+2. **Xiao et al. (2024)** - "Efficient Streaming Language Models with Attention Sinks"
+   - Venue: ICLR 2024
+   - arXiv: 2309.17453
+   - Key contribution: Attention sink phenomenon
+
+3. **Li et al. (2024)** - "Long-context LLMs Struggle with Long In-context Learning"
+   - Venue: arXiv preprint
+   - arXiv: 2404.02060
+   - Key contribution: Performance degradation with accumulated context
+
+4. **Packer et al. (2023)** - "MemGPT: Towards LLMs as Operating Systems"
+   - Venue: arXiv preprint
+   - arXiv: 2310.08560
+   - Key contribution: Virtual context management for agentic AI
+
+---
+
+## arXiv Submission Steps
+
+1. Go to: https://arxiv.org/submit
+2. Sign in or create an arXiv account
+3. Click "Start New Submission"
+4. Select primary category: **cs.AI**
+5. Add cross-list categories: **cs.CL**, **cs.IR**
+6. Fill in metadata from fields above
+7. Upload `arxiv_submission.tar`
+8. Select license: **CC BY 4.0**
+9. Add comments with code/data URLs
+10. Preview PDF compilation
+11. Submit for moderation
+
+**Expected Processing Time**: 1-2 business days for moderation
+
+---
+
+*All citations in this submission are verified as real and accurate.*

modules/caas/paper/ARXIV_README.md

@@ -0,0 +1,47 @@
+# arXiv Submission Package
+
+## Contents
+
+```
+arxiv_submission.zip
+├── main.tex           # Main LaTeX source file
+├── references.bib     # BibTeX bibliography
+└── figures/
+    ├── fig1_system_architecture.png  # System architecture diagram
+    ├── fig2_context_triad.png        # Context Triad visualization
+    ├── fig3_ablation_results.png     # Ablation study bar chart
+    └── fig4_routing_latency.png      # Routing latency comparison
+```
+
+## Compilation
+
+```bash
+pdflatex main.tex
+bibtex main
+pdflatex main.tex
+pdflatex main.tex
+```
+
+## arXiv Submission Steps
+
+1. Go to: https://arxiv.org/submit
+2. Sign in (or create account)
+3. Start new submission
+4. Fill in metadata:
+   - **Primary Category**: `cs.AI` (Artificial Intelligence)
+   - **Cross-list**: `cs.CL` (Computation and Language), `cs.IR` (Information Retrieval)
+   - **Title**: Context-as-a-Service: A Principled Architecture for Enterprise RAG Systems
+   - **License**: CC BY 4.0
+5. Upload `arxiv_submission.zip`
+6. In **Comments** field, add:
+   ```
+   Code: https://github.com/imran-siddique/context-as-a-service
+   PyPI: https://pypi.org/project/context-as-a-service/
+   Dataset: https://huggingface.co/datasets/imran-siddique/context-as-a-service
+   ```
+7. Preview and submit
+
+## Package Size
+
+- Total: ~363 KB
+- Within arXiv's 10MB limit ✓