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

modules/caas/CONTRIBUTING.md

@@ -0,0 +1,346 @@
+# Contributing to Context-as-a-Service
+
+Thank you for your interest in contributing! This document provides guidelines for contributing to the project.
+
+## Code of Conduct
+
+Be respectful, inclusive, and collaborative. We're here to build something great together.
+
+## Getting Started
+
+### 1. Fork and Clone
+
+```bash
+git clone https://github.com/<your-username>/context-as-a-service.git
+cd context-as-a-service
+```
+
+### 2. Install Dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+### 3. Run Tests
+
+```bash
+python run_tests.py
+```
+
+## Project Structure
+
+```
+context-as-a-service/
+├── caas/                    # Main package
+│   ├── __init__.py
+│   ├── models.py           # Data models
+│   ├── cli.py              # CLI tool
+│   ├── api/                # REST API
+│   ├── ingestion/          # Document processors
+│   ├── detection/          # Type detection
+│   ├── tuning/             # Weight tuning
+│   ├── storage/            # Document storage
+│   ├── enrichment.py       # Metadata enrichment
+│   ├── decay.py            # Time-based decay
+│   ├── triad.py            # Context Triad (Hot/Warm/Cold)
+│   ├── pragmatic_truth.py  # Source tracking
+│   ├── routing/            # Heuristic routing
+│   ├── conversation.py     # Conversation management
+│   └── gateway/            # Trust Gateway
+├── tests/                  # Test suite
+├── examples/               # Example usage
+│   ├── agents/            # Sample agent implementations
+│   └── *.py               # Demo scripts
+├── docs/                   # Documentation (markdown files)
+├── run_tests.py           # Test runner
+├── TESTING.md             # Testing guide
+├── CONTRIBUTING.md        # This file
+└── README.md              # Project overview
+```
+
+## Development Workflow
+
+### 1. Create a Branch
+
+```bash
+git checkout -b feature/your-feature-name
+```
+
+### 2. Make Changes
+
+- Write clear, documented code
+- Follow existing code style
+- Add docstrings to functions and classes
+- Use type hints where appropriate
+
+### 3. Add Tests
+
+For any new functionality, add tests in `tests/`:
+
+```python
+"""
+Test description.
+"""
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from caas.module import NewFeature
+
+
+def test_new_feature():
+    """Test the new feature."""
+    print("\n=== Testing New Feature ===")
+    
+    feature = NewFeature()
+    result = feature.do_something()
+    
+    assert result is not None
+    print("✓ Feature working correctly")
+```
+
+### 4. Run Tests
+
+```bash
+python run_tests.py
+```
+
+### 5. Commit Changes
+
+Use clear, descriptive commit messages:
+
+```bash
+git add .
+git commit -m "Add feature: brief description
+
+- Detailed point 1
+- Detailed point 2
+- Closes #123"
+```
+
+### 6. Push and Create PR
+
+```bash
+git push origin feature/your-feature-name
+```
+
+Then create a Pull Request on GitHub.
+
+## Coding Standards
+
+### Python Style
+
+- Follow PEP 8 style guide
+- Use 4 spaces for indentation
+- Maximum line length: 100 characters
+- Use descriptive variable names
+
+### Docstrings
+
+Use Google-style docstrings:
+
+```python
+def extract_context(document_id: str, query: str, max_tokens: int = 2000) -> Tuple[str, Dict]:
+    """
+    Extract context from a document.
+    
+    Args:
+        document_id: ID of document to extract from
+        query: Search query
+        max_tokens: Maximum tokens to extract
+        
+    Returns:
+        Tuple of (context_string, metadata_dict)
+        
+    Raises:
+        ValueError: If document not found
+        
+    Example:
+        >>> context, metadata = extractor.extract_context("doc-123", "authentication")
+        >>> print(len(context))
+        1847
+    """
+    # Implementation
+```
+
+### Type Hints
+
+Use type hints for function signatures:
+
+```python
+from typing import List, Dict, Optional
+
+def process_documents(
+    docs: List[Document],
+    max_count: Optional[int] = None
+) -> Dict[str, Any]:
+    ...
+```
+
+## Testing Guidelines
+
+### Test Coverage
+
+- Write tests for all new features
+- Test edge cases and error conditions
+- Aim for clear, readable test code
+
+### Test Structure
+
+```python
+def test_feature_name():
+    """Test description."""
+    print("\n=== Testing Feature ===")
+    
+    # Setup
+    component = Component()
+    
+    # Execute
+    result = component.method()
+    
+    # Assert
+    assert result == expected_value
+    print("✓ Test passed")
+```
+
+### Running Tests
+
+```bash
+# All tests
+python run_tests.py
+
+# Specific test
+python -m tests.test_module_name
+```
+
+## Areas for Contribution
+
+### High Priority
+
+1. **Additional Document Processors**
+   - Support for more file formats (DOCX, Markdown, etc.)
+   - Better code language support
+   - Improved structure detection
+
+2. **Enhanced Detection**
+   - Better document type classification
+   - More sophisticated pattern matching
+   - Machine learning-based detection
+
+3. **Performance Optimization**
+   - Faster document processing
+   - Efficient storage mechanisms
+   - Caching strategies
+
+### Medium Priority
+
+4. **API Enhancements**
+   - Additional endpoints
+   - WebSocket support for real-time updates
+   - GraphQL API option
+
+5. **CLI Improvements**
+   - Interactive mode
+   - Better output formatting
+   - Progress indicators
+
+6. **Documentation**
+   - More examples
+   - Tutorials
+   - Video guides
+
+### Lower Priority
+
+7. **UI/Dashboard**
+   - Web-based interface
+   - Visualization of document structures
+   - Analytics dashboard
+
+8. **Integrations**
+   - Slack bot
+   - VS Code extension
+   - Zapier integration
+
+## Module-Specific Guidelines
+
+### Ingestion Module (`caas/ingestion/`)
+
+When adding new processors:
+- Inherit from base `Processor` class
+- Implement `process()` method
+- Track document hierarchy
+- Extract meaningful sections
+
+### Detection Module (`caas/detection/`)
+
+When adding detection patterns:
+- Add patterns to appropriate category
+- Test with diverse documents
+- Consider false positives/negatives
+
+### Tuning Module (`caas/tuning/`)
+
+When adding tuning rules:
+- Add to `TYPE_SPECIFIC_WEIGHTS`
+- Document reasoning
+- Test with real documents
+
+## Documentation
+
+### Inline Documentation
+
+- Add docstrings to all public functions/classes
+- Include examples in docstrings
+- Explain complex algorithms
+
+### README Updates
+
+Update README.md when:
+- Adding new features
+- Changing API
+- Updating installation process
+
+### Architecture Documentation
+
+Document architectural decisions in:
+- Code comments for complex logic
+- Separate docs for major changes
+- Examples for new patterns
+
+## Pull Request Process
+
+1. **Before Submitting**
+   - Run all tests
+   - Update documentation
+   - Add examples if needed
+   - Rebase on latest main
+
+2. **PR Description**
+   - Describe what and why
+   - Link related issues
+   - Show before/after examples
+   - List breaking changes
+
+3. **Review Process**
+   - Address review comments
+   - Keep discussions focused
+   - Be open to suggestions
+
+4. **After Merge**
+   - Delete your branch
+   - Update your fork
+   - Celebrate! 🎉
+
+## Questions or Issues?
+
+- **Bug reports**: Open an issue with reproduction steps
+- **Feature requests**: Open an issue with use case description
+- **Questions**: Start a discussion or open an issue
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
+
+---
+
+Thank you for contributing to Context-as-a-Service! 🚀

modules/caas/Dockerfile

@@ -0,0 +1,41 @@
+# Use Python 3.11 slim image
+FROM python:3.11-slim
+
+# Set working directory
+WORKDIR /app
+
+# Set environment variables
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1
+
+# Install system dependencies
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+    build-essential \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy the application
+COPY . .
+
+# Install the package in development mode
+RUN pip install -e .
+
+# Create directory for document storage
+RUN mkdir -p /app/data/documents /app/data/storage
+
+# Expose the API port
+EXPOSE 8000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Run the API server
+CMD ["uvicorn", "caas.api.main:app", "--host", "0.0.0.0", "--port", "8000"]

modules/caas/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Context-as-a-Service Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

modules/caas/MANIFEST.in

@@ -0,0 +1,11 @@
+include README.md
+include LICENSE
+include requirements.txt
+include pyproject.toml
+recursive-include src/caas *.py
+recursive-include docs *.md
+recursive-include examples *.py *.html
+recursive-include tests *.py
+global-exclude __pycache__
+global-exclude *.py[co]
+global-exclude .DS_Store

modules/caas/README.md

@@ -0,0 +1,158 @@
+# Context-as-a-Service (CaaS)
+
+> **Part of [Agent OS](https://github.com/imran-siddique/agent-os)** - Kernel-level governance for AI agents
+
+[![PyPI](https://img.shields.io/pypi/v/caas-core.svg)](https://pypi.org/project/caas-core/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/imran-siddique/context-as-a-service/actions/workflows/ci.yml/badge.svg)](https://github.com/imran-siddique/context-as-a-service/actions/workflows/ci.yml)
+
+**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
+
+```bash
+pip install caas-core
+```
+
+---
+
+## Quick Start
+
+```python
+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.
+
+```python
+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](https://github.com/imran-siddique/context-as-a-service)** — 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
+
+```bibtex
+@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](CONTRIBUTING.md) for development setup and guidelines.
+
+---
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.