caas-core 0.3.0

A pure, logic-only library for routing context, handling RAG fallacies, and managing context windows. Layer 1 Primitive - no agent dependencies.

Context-as-a-Service (CaaS)

Stateless context management primitive for RAG systems. Part of the Agent OS ecosystem.

---

Philosophy: Why CaaS Exists

RAG systems fail because they treat context as a flat stream. Documents lose structure. Time becomes meaningless. Official docs conflict with reality. LLMs waste tokens on stale data.

We built CaaS to subtract these problems. No agent frameworks. No middleware dependencies. Just pure context logic that routes, prioritizes, and filters data based on deterministic rules.

Scale by Subtraction: Remove the coupling between context management and agent execution. CaaS processes text and metadata—nothing more. This constraint forces clarity and enables reuse across any agent system.

---

Installation

pip install caas-core

---

Quick Start

from caas import ContextTriadManager, HeuristicRouter, DocumentStore

store = DocumentStore()
store.add_document({"content": "API auth uses JWT", "timestamp": "2025-01-15"})
router = HeuristicRouter()
decision = router.route("How does authentication work?")  # Returns ModelTier.FAST

CaaS provides stateless functions. You control storage, agents, and orchestration.

---

Core Features

1. Virtual File System (Project State)

A lightweight in-memory file system that maintains project state shared across multiple SDLC agents.

from caas import VirtualFileSystem

# Create shared VFS
vfs = VirtualFileSystem()

# Agent 1 creates a file
vfs.create_file("/project/main.py", "print('hello')", agent_id="agent-1")

# Agent 2 reads and updates the file
content = vfs.read_file("/project/main.py")
vfs.update_file("/project/main.py", "print('world')", agent_id="agent-2")

# View edit history
history = vfs.get_file_history("/project/main.py")
# Shows edits from both agents

Why VFS? SDLC agents don't just chat—they edit files. The VFS ensures all agents see each other's changes, enabling true multi-agent collaboration on codebases.

2. Context Management

---

Architecture

CaaS sits in Layer 1: Primitives of the Agent OS.

• Layer 1 (Primitives): caas (Context), cmvk (Verification), emk (Memory)
• Layer 2 (Infrastructure): iatp (Trust Protocol), amb (Message Bus), atr (Tool Registry)
• Layer 3 (Framework): agent-control-plane (Core), scak (Self-Correction)

CaaS does not import iatp or agent-control-plane. It returns structured data that upper layers consume. This decoupling is intentional.

Example: The ContextTriadManager produces a ContextTriadState object. The amb message bus transports it. The agent-control-plane interprets it. Each layer operates independently.

---

Key Features

🗂️ Virtual File System (Project State)

• Multi-agent collaboration: All agents see each other's file edits in real-time
• Edit history: Track who changed what and when
• In-memory performance: Fast operations with optional disk persistence
• Path normalization: Consistent file paths across agents
• Use case: SDLC agents collaboratively editing codebases

🎯 Context Routing & Management

• Heuristic Router: Zero-latency query routing to appropriate model tiers
• Context Triad: Hot/Warm/Cold context layers for optimal retrieval
• Time Decay: Prioritize recent information with configurable decay
• Structure-aware: Preserve document hierarchy and relationships

🔒 Enterprise Features

• Trust Gateway: On-premises deployment with security policies
• Audit logging: Complete audit trail of all operations
• Conflict detection: Identify conflicts between official docs and practical reality
• Source citations: Transparent provenance for all information

---

The Ecosystem Map

CaaS is one component in a modular Agent Operating System. Related projects:

Primitives (Layer 1)

• caas — Context routing, triad management, RAG fallacy solutions
• cmvk — Cryptographic verification for agent messages (planned)
• emk — Episodic memory with time-decay and retrieval policies (planned)

Infrastructure (Layer 2)

• iatp — Inter-Agent Trust Protocol for authenticated message exchange (planned)
• amb — Agent Message Bus for decentralized pub/sub (planned)
• atr — Agent Tool Registry with sandboxed execution (planned)

Framework (Layer 3)

• agent-control-plane — Supervisor, orchestration, and failure handling (planned)
• scak — Self-Correction Agent Kernel for adaptive refinement (planned)

CaaS is production-ready. Other components are in design or alpha stages.

---

Citation

@software{caas2026,
  title        = {Context-as-a-Service: Stateless Primitives for RAG Systems},
  author       = {Siddique, Imran},
  year         = {2026},
  version      = {0.2.0},
  url          = {https://github.com/imran-siddique/context-as-a-service},
  note         = {Part of the Agent Operating System project}
}

---

Contributing

See CONTRIBUTING.md for development setup and guidelines.

---

License

MIT License — see LICENSE for details.