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

modules/caas/docs/TESTING.md

@@ -0,0 +1,259 @@
+# Testing Guide
+
+This guide explains how to test the Context-as-a-Service codebase.
+
+## Quick Start
+
+Run all tests:
+
+```bash
+python run_tests.py
+```
+
+Run a specific test:
+
+```bash
+python -m tests.test_functionality
+```
+
+## Test Organization
+
+Tests are organized in the `tests/` directory:
+
+```
+tests/
+├── __init__.py
+├── conftest.py                      # pytest configuration
+├── test_functionality.py            # Basic functionality tests
+├── test_structure_aware_indexing.py # Structure-aware indexing tests
+├── test_metadata_injection.py       # Metadata enrichment tests
+├── test_time_decay.py              # Time-based decay tests
+├── test_context_triad.py           # Context Triad (Hot/Warm/Cold) tests
+├── test_pragmatic_truth.py         # Pragmatic Truth (source tracking) tests
+├── test_heuristic_router.py        # Heuristic Router tests
+├── test_conversation_manager.py    # Conversation Manager tests
+└── test_trust_gateway.py           # Trust Gateway tests
+```
+
+## Test Coverage
+
+### Core Functionality
+- **test_functionality.py**: Tests basic document processing, detection, and tuning
+- **test_structure_aware_indexing.py**: Tests 3-tier content classification (High/Medium/Low)
+
+### Advanced Features
+- **test_metadata_injection.py**: Tests metadata enrichment for context preservation
+- **test_time_decay.py**: Tests time-based relevance decay ("The Half-Life of Truth")
+- **test_context_triad.py**: Tests Hot/Warm/Cold context management
+- **test_pragmatic_truth.py**: Tests source tracking and conflict detection
+- **test_heuristic_router.py**: Tests deterministic query routing (Speed > Smarts)
+- **test_conversation_manager.py**: Tests sliding window conversation management (FIFO)
+- **test_trust_gateway.py**: Tests enterprise security gateway
+
+## Running Tests
+
+### All Tests
+```bash
+python run_tests.py
+```
+
+### Individual Module Tests
+```bash
+python -m tests.test_functionality
+python -m tests.test_heuristic_router
+python -m tests.test_trust_gateway
+```
+
+### Using pytest (optional)
+If you have pytest installed:
+
+```bash
+pytest tests/
+pytest tests/test_functionality.py
+pytest tests/ -v  # verbose output
+pytest tests/ -k "decay"  # run tests matching "decay"
+```
+
+## Test Structure
+
+Each test file follows a similar structure:
+
+```python
+"""
+Test description
+"""
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from caas.module import Component
+
+
+def test_feature():
+    """Test a specific feature."""
+    print("\n=== Testing Feature ===")
+    
+    # Setup
+    component = Component()
+    
+    # Execute
+    result = component.do_something()
+    
+    # Assert
+    assert result is not None
+    print("✓ Feature working correctly")
+
+
+if __name__ == "__main__":
+    print("=" * 60)
+    print("Module Tests")
+    print("=" * 60)
+    
+    try:
+        test_feature()
+        # ... more tests ...
+        
+        print("\n" + "=" * 60)
+        print("✅ All tests passed!")
+        print("=" * 60)
+    except Exception as e:
+        print(f"\n❌ Test failed: {e}")
+        import traceback
+        traceback.print_exc()
+        sys.exit(1)
+```
+
+## Example Agents
+
+The `examples/agents/` directory contains sample agents that demonstrate how to use multiple modules together:
+
+### Intelligent Document Analyzer
+Demonstrates using 6+ modules together:
+- Structure-aware indexing
+- Metadata enrichment
+- Time-based decay
+- Heuristic routing
+- Conversation management
+- Pragmatic truth tracking
+
+```bash
+PYTHONPATH=. python examples/agents/intelligent_document_analyzer.py
+```
+
+### Enterprise Security Agent
+Demonstrates security-focused usage:
+- Trust Gateway (on-prem deployment)
+- Data classification
+- Audit trail
+- Compliance reporting
+- Secure conversation management
+
+```bash
+PYTHONPATH=. python examples/agents/enterprise_security_agent.py
+```
+
+## Continuous Integration
+
+To set up CI testing, add this to your `.github/workflows/test.yml`:
+
+```yaml
+name: Tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+        with:
+          python-version: '3.8'
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+      - name: Run tests
+        run: python run_tests.py
+```
+
+## Writing New Tests
+
+When adding new functionality:
+
+1. Create a test file in `tests/test_<module>.py`
+2. Import your module with the path fix:
+   ```python
+   import sys
+   from pathlib import Path
+   sys.path.insert(0, str(Path(__file__).parent.parent))
+   ```
+3. Write test functions with descriptive names
+4. Use print statements for clear output
+5. Assert expected behavior
+6. Add to `run_tests.py` TEST_FILES list
+
+## Best Practices
+
+- **Test naming**: Use descriptive names like `test_decay_calculation()` not `test1()`
+- **Print output**: Use `print()` statements to show what's being tested
+- **Assertions**: Always include assertions to verify correctness
+- **Documentation**: Add docstrings explaining what each test verifies
+- **Independence**: Tests should not depend on other tests
+- **Cleanup**: Clean up any resources (files, connections) after tests
+
+## Troubleshooting
+
+### Import Errors
+If you get `ModuleNotFoundError: No module named 'caas'`:
+
+```bash
+# Use module syntax
+python -m tests.test_functionality
+
+# Or set PYTHONPATH
+PYTHONPATH=. python tests/test_functionality.py
+```
+
+### Test Timeout
+Tests have a 60-second timeout. If a test times out:
+- Check for infinite loops
+- Verify external dependencies are available
+- Consider breaking into smaller tests
+
+## Demo Files
+
+The `examples/` directory contains demonstration scripts:
+
+```bash
+PYTHONPATH=. python examples/demo_time_decay.py
+PYTHONPATH=. python examples/demo_heuristic_router.py
+PYTHONPATH=. python examples/demo_trust_gateway.py
+```
+
+These demos show real-world usage examples and can serve as integration tests.
+
+## Code Coverage (Optional)
+
+To measure code coverage:
+
+```bash
+pip install coverage
+coverage run run_tests.py
+coverage report
+coverage html  # generates htmlcov/index.html
+```
+
+## Performance Testing
+
+For performance testing:
+
+```bash
+pip install pytest-benchmark
+pytest tests/ --benchmark-only
+```
+
+## Questions?
+
+For questions about testing, see:
+- [CONTRIBUTING.md](CONTRIBUTING.md) - Contribution guidelines
+- [README.md](README.md) - Project overview
+- GitHub Issues - Report bugs or ask questions

modules/caas/docs/THREAT_MODEL.md

@@ -0,0 +1,247 @@
+# Threat Model and Security Considerations
+
+## Overview
+
+Context-as-a-Service (CaaS) is designed with enterprise security and privacy as core principles. This document outlines the threat model, security considerations, and mitigation strategies implemented in the system.
+
+## Trust Gateway Architecture
+
+The Trust Gateway is the cornerstone of CaaS security, designed to prevent data leakage and enable deployment in sensitive environments.
+
+### Key Security Properties
+
+1. **Zero Data Leakage**: All processing can occur on-premises or in air-gapped environments
+2. **No External Dependencies**: No required calls to third-party APIs for core functionality
+3. **Local Processing**: All document analysis, context extraction, and routing occur locally
+4. **Transparent Routing**: Heuristic-based routing provides deterministic, auditable decisions
+
+## Threat Categories
+
+### 1. Data Confidentiality Threats
+
+#### Threat: Document Content Exposure
+- **Description**: Sensitive documents could be exposed to unauthorized parties through API calls or third-party services
+- **Likelihood**: High (if using external RAG services)
+- **Impact**: Critical (confidential data breach)
+- **Mitigation**:
+  - Trust Gateway enables on-premises deployment
+  - No external API calls required for document processing
+  - Air-gapped deployment support
+  - Local vector storage options
+  - Encryption at rest and in transit
+
+#### Threat: Context Window Leakage
+- **Description**: Conversation context could be exposed through logging or external LLM calls
+- **Likelihood**: Medium
+- **Impact**: High (conversation privacy breach)
+- **Mitigation**:
+  - Sliding window management keeps only recent context
+  - Configurable context retention policies
+  - Local conversation storage
+  - No automatic transmission to external services
+  - Audit logging of context access
+
+#### Threat: Metadata Exposure
+- **Description**: Document metadata (structure, sources, timestamps) could reveal sensitive information
+- **Likelihood**: Medium
+- **Impact**: Medium (organizational intelligence)
+- **Mitigation**:
+  - Metadata stored locally
+  - Access control on metadata endpoints
+  - Configurable metadata retention
+  - Option to anonymize source information
+
+### 2. Data Integrity Threats
+
+#### Threat: Document Tampering
+- **Description**: Malicious actors could modify ingested documents
+- **Likelihood**: Low (with proper access controls)
+- **Impact**: High (poisoned context)
+- **Mitigation**:
+  - Document ingestion checksums
+  - Immutable document storage option
+  - Audit trail of all ingestion operations
+  - Document verification before serving
+
+#### Threat: Weight Manipulation
+- **Description**: Auto-tuned weights could be manipulated to prioritize/deprioritize content
+- **Likelihood**: Low
+- **Impact**: Medium (biased context serving)
+- **Mitigation**:
+  - Weight calculation transparency
+  - Audit logs of weight changes
+  - Configurable weight bounds
+  - Manual weight override capabilities
+
+### 3. Availability Threats
+
+#### Threat: Resource Exhaustion
+- **Description**: Large document ingestion could exhaust system resources
+- **Likelihood**: Medium
+- **Impact**: Medium (service degradation)
+- **Mitigation**:
+  - Configurable resource limits
+  - Rate limiting on ingestion endpoints
+  - Async processing with queues
+  - Monitoring and alerting
+
+#### Threat: Adversarial Queries
+- **Description**: Malicious queries designed to extract maximum context or cause slowdowns
+- **Likelihood**: Medium
+- **Impact**: Medium (performance degradation)
+- **Mitigation**:
+  - Query rate limiting
+  - Maximum context token limits
+  - Query complexity analysis
+  - Request authentication
+
+### 4. Privacy Threats
+
+#### Threat: Source Attribution Linking
+- **Description**: Source citations could reveal private information about document origins
+- **Likelihood**: Medium
+- **Impact**: Medium (privacy breach)
+- **Mitigation**:
+  - Configurable source anonymization
+  - Source access controls
+  - Option to disable source tracking
+  - Redaction capabilities
+
+#### Threat: Temporal Analysis
+- **Description**: Time decay patterns could reveal when sensitive documents were created
+- **Likelihood**: Low
+- **Impact**: Low (temporal intelligence)
+- **Mitigation**:
+  - Configurable decay parameters
+  - Option to disable time-based ranking
+  - Timestamp anonymization options
+
+## Deployment Models
+
+### On-Premises Deployment (Recommended for Enterprise)
+- **Security Level**: Maximum
+- **Data Location**: Customer infrastructure
+- **Network Requirements**: None (can be air-gapped)
+- **Use Cases**: Financial services, healthcare, government, defense
+
+### Private Cloud Deployment
+- **Security Level**: High
+- **Data Location**: Customer's private cloud (AWS VPC, Azure VNet, etc.)
+- **Network Requirements**: Private network only
+- **Use Cases**: Enterprise SaaS, medium-to-large businesses
+
+### Hybrid Deployment
+- **Security Level**: Medium-High
+- **Data Location**: Sensitive data on-prem, non-sensitive in cloud
+- **Network Requirements**: Secure tunnels for hybrid communication
+- **Use Cases**: Organizations with mixed sensitivity requirements
+
+### Public Cloud Deployment (Development/Testing Only)
+- **Security Level**: Basic
+- **Data Location**: Public cloud infrastructure
+- **Network Requirements**: Internet accessible
+- **Use Cases**: Development, testing, non-sensitive applications
+
+## Security Best Practices
+
+### 1. Authentication & Authorization
+- Implement strong authentication for all API endpoints
+- Use role-based access control (RBAC) for different operations
+- Separate read/write permissions for documents and contexts
+- Regular credential rotation
+
+### 2. Network Security
+- Deploy behind firewalls and VPNs in production
+- Use HTTPS/TLS for all API communications
+- Consider mTLS for service-to-service communication
+- Network segmentation for different sensitivity levels
+
+### 3. Data Protection
+- Encrypt documents at rest using AES-256 or equivalent
+- Encrypt all network traffic with TLS 1.3+
+- Implement secure key management (KMS, HSM)
+- Regular security audits of storage systems
+
+### 4. Logging & Monitoring
+- Comprehensive audit logging of all operations
+- Monitor for anomalous access patterns
+- Alert on suspicious activities
+- Log retention policies aligned with compliance requirements
+
+### 5. Secure Configuration
+- Change all default credentials
+- Disable unnecessary features and endpoints
+- Use secure defaults for all configurations
+- Regular security configuration reviews
+
+## Compliance Considerations
+
+### GDPR (General Data Protection Regulation)
+- **Right to be forgotten**: Document deletion capabilities
+- **Data minimization**: Configurable retention policies
+- **Data portability**: Export capabilities
+- **Consent management**: Explicit document ingestion tracking
+
+### HIPAA (Health Insurance Portability and Accountability Act)
+- **PHI Protection**: On-premises deployment option
+- **Access Controls**: RBAC implementation
+- **Audit Trails**: Comprehensive logging
+- **Encryption**: At rest and in transit
+
+### SOC 2 Type II
+- **Security**: Trust Gateway architecture
+- **Availability**: Resource management and monitoring
+- **Confidentiality**: Encryption and access controls
+- **Privacy**: Anonymization and retention policies
+
+## Incident Response
+
+### Security Incident Categories
+1. **Data Breach**: Unauthorized access to documents or contexts
+2. **Service Disruption**: DoS or resource exhaustion
+3. **Configuration Error**: Misconfigurations exposing data
+4. **Third-Party Compromise**: If external integrations are used
+
+### Response Procedures
+1. **Detection**: Monitoring alerts or user reports
+2. **Containment**: Isolate affected components
+3. **Eradication**: Remove the threat
+4. **Recovery**: Restore normal operations
+5. **Post-Incident**: Review and improve
+
+## Known Limitations
+
+### Current Version (0.1.0)
+- No built-in authentication (must be added at infrastructure layer)
+- No built-in encryption at rest (relies on filesystem/OS encryption)
+- No built-in rate limiting (must be added at reverse proxy/API gateway)
+- Limited audit logging (basic operation logs only)
+
+### Planned Improvements
+- Built-in authentication/authorization middleware
+- Native encryption at rest options
+- Advanced rate limiting and quota management
+- Enhanced audit logging with correlation IDs
+- Security scanning integration
+- Automated security testing in CI/CD
+
+## Security Reporting
+
+If you discover a security vulnerability in Context-as-a-Service, please report it responsibly:
+
+1. **Do not** open a public GitHub issue
+2. Email security concerns to: [security@your-domain.com] (to be configured)
+3. Include:
+   - Description of the vulnerability
+   - Steps to reproduce
+   - Potential impact
+   - Suggested fixes (if any)
+
+We will respond within 48 hours and provide updates on the resolution timeline.
+
+## References
+
+- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
+- [NIST Cybersecurity Framework](https://www.nist.gov/cyberframework)
+- [Cloud Security Alliance Guidelines](https://cloudsecurityalliance.org/)
+- [Zero Trust Architecture](https://www.nist.gov/publications/zero-trust-architecture)