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

modules/caas/docs/VFS.md

@@ -0,0 +1,298 @@
+# Virtual File System (VFS)
+
+## Overview
+
+The Virtual File System (VFS) is a lightweight in-memory file system designed for multi-agent SDLC collaboration. It maintains project state that all agents can share, allowing Agent A to see Agent B's edits in real-time.
+
+## Why VFS?
+
+SDLC agents don't just chat—they edit files. Traditional approaches where each agent has its own isolated file view lead to:
+
+- **Inconsistency**: Agents have different views of the project
+- **Lost work**: Edits by one agent aren't visible to others
+- **No history**: Can't track who changed what and when
+- **Coordination overhead**: Manual synchronization required
+
+The VFS solves these problems by providing a **shared, versioned file system** that all agents access.
+
+## Key Features
+
+### 1. Shared Project State
+All agents work on the same VFS instance, seeing changes immediately:
+
+```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 can immediately read it
+content = vfs.read_file("/project/main.py")  # "print('hello')"
+```
+
+### 2. Edit History Tracking
+Every change is tracked with agent ID, timestamp, and optional message:
+
+```python
+# Agent 2 updates the file
+vfs.update_file(
+    "/project/main.py",
+    "print('world')",
+    agent_id="agent-2",
+    message="Changed greeting"
+)
+
+# View complete history
+history = vfs.get_file_history("/project/main.py")
+for edit in history:
+    print(f"{edit.agent_id} at {edit.timestamp}: {edit.message}")
+```
+
+### 3. Directory Support
+Automatic parent directory creation and tree structure:
+
+```python
+# No need to create directories manually
+vfs.create_file("/deep/nested/path/file.txt", "content", "agent-1")
+
+# List directory contents
+files = vfs.list_files("/deep", recursive=True)
+```
+
+### 4. Path Normalization
+Consistent path handling across agents:
+
+```python
+# These all refer to the same file
+vfs.read_file("/project/file.txt")
+vfs.read_file("project/file.txt")
+vfs.read_file("//project//file.txt")
+```
+
+### 5. Optional Persistence
+Save/load VFS state to/from disk:
+
+```python
+# VFS with persistence
+vfs = VirtualFileSystem(storage_path="/tmp/vfs_state.json")
+
+# Changes are automatically saved
+vfs.create_file("/data.txt", "content", "agent-1")
+
+# Load on next initialization
+vfs2 = VirtualFileSystem(storage_path="/tmp/vfs_state.json")
+# File is already there
+```
+
+## API Reference
+
+### Core Operations
+
+#### Create File
+```python
+file_node = vfs.create_file(
+    path="/project/main.py",
+    content="print('hello')",
+    agent_id="agent-1",
+    metadata={"language": "python"}
+)
+```
+
+**Parameters:**
+- `path` (str): File path (normalized automatically)
+- `content` (str): Initial file content
+- `agent_id` (str): ID of agent creating the file
+- `metadata` (dict, optional): Additional metadata
+
+**Returns:** `FileNode` object
+
+**Raises:**
+- `ValueError`: If file already exists
+
+#### Read File
+```python
+content = vfs.read_file("/project/main.py")
+```
+
+**Parameters:**
+- `path` (str): File path to read
+
+**Returns:** File content as string
+
+**Raises:**
+- `FileNotFoundError`: If file doesn't exist
+- `ValueError`: If path is a directory
+
+#### Update File
+```python
+file_node = vfs.update_file(
+    path="/project/main.py",
+    content="print('world')",
+    agent_id="agent-2",
+    message="Update greeting"
+)
+```
+
+**Parameters:**
+- `path` (str): File path to update
+- `content` (str): New content
+- `agent_id` (str): ID of agent making update
+- `message` (str, optional): Commit-like message
+
+**Returns:** Updated `FileNode` object
+
+**Raises:**
+- `FileNotFoundError`: If file doesn't exist
+- `ValueError`: If path is a directory
+
+#### Delete File
+```python
+result = vfs.delete_file("/project/main.py", agent_id="agent-1")
+```
+
+**Parameters:**
+- `path` (str): File path to delete
+- `agent_id` (str): ID of agent deleting file
+
+**Returns:** `True` if successful
+
+**Raises:**
+- `FileNotFoundError`: If file doesn't exist
+- `ValueError`: If directory is not empty
+
+#### List Files
+```python
+files = vfs.list_files("/project", recursive=True)
+```
+
+**Parameters:**
+- `path` (str): Directory path
+- `recursive` (bool): Include subdirectories
+
+**Returns:** `FileListResponse` with list of files
+
+#### Get File History
+```python
+history = vfs.get_file_history("/project/main.py")
+```
+
+**Parameters:**
+- `path` (str): File path
+
+**Returns:** List of `FileEdit` objects
+
+## REST API Endpoints
+
+The VFS is also exposed via REST API:
+
+### POST /vfs/files
+Create a new file
+
+**Request body:**
+```json
+{
+  "path": "/project/main.py",
+  "content": "print('hello')",
+  "agent_id": "agent-1",
+  "metadata": {"language": "python"}
+}
+```
+
+### GET /vfs/files?path=/project/main.py
+Read a file
+
+### PUT /vfs/files
+Update a file
+
+**Request body:**
+```json
+{
+  "path": "/project/main.py",
+  "content": "print('world')",
+  "agent_id": "agent-2",
+  "message": "Update greeting"
+}
+```
+
+### DELETE /vfs/files?path=/project/main.py&agent_id=agent-1
+Delete a file
+
+### GET /vfs/list?path=/project&recursive=true
+List files in directory
+
+### GET /vfs/history?path=/project/main.py
+Get file edit history
+
+### GET /vfs/state
+Get complete VFS state
+
+## Multi-Agent Example
+
+See `examples/multi_agent/vfs_collaboration.py` for a complete example showing:
+
+- **Developer Agent**: Creates initial code
+- **Reviewer Agent**: Reviews and improves code
+- **Documenter Agent**: Adds documentation
+- **Tester Agent**: Creates tests
+
+All agents work on the shared VFS, demonstrating real multi-agent collaboration.
+
+## Use Cases
+
+### 1. Collaborative Code Generation
+Multiple agents work together to build a complete application:
+- One agent writes the main logic
+- Another adds error handling
+- A third writes tests
+- A fourth adds documentation
+
+### 2. Code Review Workflows
+- Developer agent creates initial code
+- Reviewer agent reads and suggests improvements
+- Developer agent applies changes
+- All changes tracked in history
+
+### 3. Documentation Generation
+- Agents read code from VFS
+- Generate documentation based on actual code
+- Other agents can reference the documentation
+
+### 4. Test Generation
+- Test generation agents read production code
+- Create corresponding test files
+- Integration test agents verify tests work
+
+## Design Principles
+
+1. **Simplicity**: In-memory dict-based structure, no complex database
+2. **Consistency**: All agents see the same state immediately
+3. **Auditability**: Complete edit history for all files
+4. **Performance**: Fast in-memory operations
+5. **Optional Persistence**: Save/load state when needed
+
+## Limitations
+
+- **In-memory only**: Primary storage is in-memory (can be persisted)
+- **No locking**: Assumes cooperative agents (no concurrent edit conflicts)
+- **No branches**: Single linear history per file
+- **Not a Git replacement**: Designed for agent collaboration, not version control
+
+## Future Enhancements
+
+Potential future additions:
+- **Git backend**: Use actual Git repository as storage
+- **Conflict resolution**: Handle concurrent edits
+- **Branching**: Support multiple versions
+- **File watching**: Notify agents of changes
+- **Search**: Full-text search across files
+
+## Contributing
+
+See `CONTRIBUTING.md` for development guidelines.
+
+## License
+
+MIT License - see `LICENSE` file for details.

modules/caas/examples/agents/enterprise_security_agent.py

@@ -0,0 +1,414 @@
+"""
+Enterprise Security Agent
+
+This agent demonstrates how to use the Trust Gateway with enterprise-grade
+security controls for routing AI requests within a private infrastructure.
+
+Features:
+- Trust Gateway with configurable security policies
+- On-premises/private cloud deployment modes
+- Full audit trail for compliance
+- Data classification and encryption
+- Heuristic routing (no external AI calls)
+- Conversation management with security controls
+"""
+
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from datetime import datetime
+from typing import Dict, List, Optional
+
+from caas.gateway import TrustGateway, SecurityPolicy, DeploymentMode
+from caas.routing import HeuristicRouter, ModelTier
+from caas.conversation import ConversationManager
+
+
+class EnterpriseSecurityAgent:
+    """
+    An enterprise security agent that uses Trust Gateway for secure AI routing.
+    
+    This agent demonstrates how to:
+    1. Deploy Trust Gateway in on-prem or private cloud
+    2. Apply enterprise security policies
+    3. Route queries without external API calls
+    4. Maintain full audit trail
+    5. Manage conversations with security controls
+    """
+    
+    def __init__(
+        self,
+        deployment_mode: DeploymentMode = DeploymentMode.ON_PREM,
+        security_level: str = "high",
+        compliance_mode: str = "SOC2"
+    ):
+        """
+        Initialize the enterprise security agent.
+        
+        Args:
+            deployment_mode: Where to deploy (on_prem, private_cloud, etc.)
+            security_level: Security level (basic, high, maximum)
+            compliance_mode: Compliance standard (SOC2, HIPAA, etc.)
+        """
+        # Create security policy
+        self.policy = SecurityPolicy(
+            deployment_mode=deployment_mode,
+            security_level=security_level,
+            require_authentication=True,
+            data_classification_required=True,
+            encrypt_in_transit=True,
+            encrypt_at_rest=True,
+            audit_all_requests=True,
+            compliance_mode=compliance_mode
+        )
+        
+        # Initialize Trust Gateway
+        self.gateway = TrustGateway(security_policy=self.policy)
+        
+        # Initialize conversation manager
+        self.conversation = ConversationManager(max_turns=10)
+        
+        # Track audit events
+        self.audit_log = []
+        
+        print("🔐 Enterprise Security Agent initialized")
+        print(f"   - Deployment: {deployment_mode.value}")
+        print(f"   - Security Level: {security_level}")
+        print(f"   - Compliance: {compliance_mode}")
+        print(f"   - Encryption: In-transit ✅ At-rest ✅")
+        print(f"   - Audit Trail: ✅")
+        print(f"   - Data Classification: Required ✅")
+    
+    def route_request(
+        self,
+        query: str,
+        user_id: str,
+        data_classification: str,
+        request_metadata: Optional[Dict] = None
+    ) -> Dict:
+        """
+        Route a request through the Trust Gateway with security controls.
+        
+        Args:
+            query: User's query
+            user_id: Authenticated user ID
+            data_classification: Data classification (public, internal, confidential, etc.)
+            request_metadata: Additional request metadata
+            
+        Returns:
+            Routing result with security metadata
+        """
+        print(f"\n🛡️  Routing secure request")
+        print(f"   User: {user_id}")
+        print(f"   Classification: {data_classification}")
+        print(f"   Query: \"{query[:50]}...\"" if len(query) > 50 else f"   Query: \"{query}\"")
+        
+        # Route through gateway
+        result = self.gateway.route_request(
+            query=query,
+            user_id=user_id,
+            data_classification=data_classification
+        )
+        
+        # Log to audit trail
+        self._audit_log_event(
+            event_type="request_routed",
+            user_id=user_id,
+            data_classification=data_classification,
+            routing_result=result
+        )
+        
+        print(f"   ✓ Routed to: {result.get('routing_decision', {}).get('model_tier', 'unknown')}")
+        print(f"   ✓ Security checks: Passed ✅")
+        print(f"   ✓ Audit logged: ✅")
+        
+        return result
+    
+    def verify_data_classification(
+        self,
+        data_classification: str
+    ) -> bool:
+        """
+        Verify if data classification is allowed by policy.
+        
+        Args:
+            data_classification: Classification to verify
+            
+        Returns:
+            True if allowed, False otherwise
+        """
+        allowed_classifications = [
+            "public",
+            "internal",
+            "confidential",
+            "restricted",
+            "top_secret"
+        ]
+        return data_classification.lower() in allowed_classifications
+    
+    def secure_chat(
+        self,
+        user_id: str,
+        user_message: str,
+        ai_response: str,
+        data_classification: str
+    ) -> Dict:
+        """
+        Add a conversation turn with security controls.
+        
+        Args:
+            user_id: User identifier
+            user_message: User's message
+            ai_response: AI's response
+            data_classification: Data classification level
+            
+        Returns:
+            Conversation statistics with security info
+        """
+        # Verify classification
+        if not self.verify_data_classification(data_classification):
+            print(f"❌ Invalid data classification: {data_classification}")
+            return {"error": "Invalid data classification"}
+        
+        # Add turn to conversation
+        turn_id = self.conversation.add_turn(user_message, ai_response)
+        stats = self.conversation.get_statistics()
+        
+        # Audit log
+        self._audit_log_event(
+            event_type="conversation_turn_added",
+            user_id=user_id,
+            turn_id=turn_id,
+            data_classification=data_classification
+        )
+        
+        print(f"\n💬 Secure conversation turn added")
+        print(f"   User: {user_id}")
+        print(f"   Turn ID: {turn_id[:16]}...")
+        print(f"   Classification: {data_classification}")
+        print(f"   Current turns: {stats['current_turns']}/{stats['max_turns']}")
+        
+        return {
+            "turn_id": turn_id,
+            "statistics": stats,
+            "security": {
+                "user_id": user_id,
+                "data_classification": data_classification,
+                "audited": True
+            }
+        }
+    
+    def get_audit_trail(
+        self,
+        user_id: Optional[str] = None,
+        event_type: Optional[str] = None,
+        limit: int = 100
+    ) -> List[Dict]:
+        """
+        Get audit trail with optional filtering.
+        
+        Args:
+            user_id: Filter by user ID
+            event_type: Filter by event type
+            limit: Maximum events to return
+            
+        Returns:
+            List of audit events
+        """
+        events = self.audit_log
+        
+        # Filter by user_id
+        if user_id:
+            events = [e for e in events if e.get('user_id') == user_id]
+        
+        # Filter by event_type
+        if event_type:
+            events = [e for e in events if e.get('event_type') == event_type]
+        
+        # Apply limit
+        events = events[-limit:]
+        
+        return events
+    
+    def _audit_log_event(
+        self,
+        event_type: str,
+        user_id: str,
+        **kwargs
+    ):
+        """
+        Log an event to the audit trail.
+        
+        Args:
+            event_type: Type of event
+            user_id: User associated with event
+            **kwargs: Additional event data
+        """
+        event = {
+            "timestamp": datetime.utcnow().isoformat(),
+            "event_type": event_type,
+            "user_id": user_id,
+            "deployment_mode": self.policy.deployment_mode.value,
+            "compliance_mode": self.policy.compliance_mode,
+            **kwargs
+        }
+        self.audit_log.append(event)
+    
+    def get_gateway_status(self) -> Dict:
+        """Get Trust Gateway status and configuration."""
+        return {
+            "deployment_mode": self.policy.deployment_mode.value,
+            "security_level": self.policy.security_level,
+            "compliance_mode": self.policy.compliance_mode,
+            "data_leakage_risk": "zero (on-premises)",
+            "routing_latency": "< 1ms (heuristic, no AI)"
+        }
+    
+    def export_compliance_report(self) -> Dict:
+        """
+        Export a compliance report with audit trail.
+        
+        Returns:
+            Compliance report
+        """
+        print("\n📋 Generating compliance report...")
+        
+        report = {
+            "generated_at": datetime.utcnow().isoformat(),
+            "deployment_mode": self.policy.deployment_mode.value,
+            "security_level": self.policy.security_level,
+            "compliance_mode": self.policy.compliance_mode,
+            "security_controls": {
+                "authentication_required": self.policy.require_authentication,
+                "encryption_in_transit": self.policy.encrypt_in_transit,
+                "encryption_at_rest": self.policy.encrypt_at_rest,
+                "data_classification": self.policy.data_classification_required,
+                "audit_logging": self.policy.audit_all_requests
+            },
+            "audit_summary": {
+                "total_events": len(self.audit_log),
+                "event_types": list(set(e['event_type'] for e in self.audit_log)),
+                "unique_users": list(set(e['user_id'] for e in self.audit_log))
+            },
+            "audit_trail": self.audit_log
+        }
+        
+        print(f"   ✓ Total events: {report['audit_summary']['total_events']}")
+        print(f"   ✓ Event types: {len(report['audit_summary']['event_types'])}")
+        print(f"   ✓ Unique users: {len(report['audit_summary']['unique_users'])}")
+        
+        return report
+
+
+def demo_enterprise_security():
+    """Demonstrate enterprise security agent workflow."""
+    print("=" * 70)
+    print("🔐 Enterprise Security Agent - Demonstration")
+    print("=" * 70)
+    
+    # Initialize agent with on-premises deployment
+    agent = EnterpriseSecurityAgent(
+        deployment_mode=DeploymentMode.ON_PREM,
+        security_level="maximum",
+        compliance_mode="SOC2"
+    )
+    
+    # Example 1: Route public query (low sensitivity)
+    print("\n" + "=" * 70)
+    print("📊 Example 1: Public Data Query")
+    print("=" * 70)
+    
+    agent.route_request(
+        query="What is Python?",
+        user_id="analyst@company.com",
+        data_classification="public",
+        request_metadata={"department": "Engineering"}
+    )
+    
+    # Example 2: Route confidential query (high sensitivity)
+    print("\n" + "=" * 70)
+    print("🔒 Example 2: Confidential Data Query")
+    print("=" * 70)
+    
+    agent.route_request(
+        query="Analyze Q4 financial results and compare with competitors",
+        user_id="cfo@company.com",
+        data_classification="confidential",
+        request_metadata={"department": "Finance", "project": "Q4_Analysis"}
+    )
+    
+    # Example 3: Secure conversation
+    print("\n" + "=" * 70)
+    print("💬 Example 3: Secure Conversation")
+    print("=" * 70)
+    
+    agent.secure_chat(
+        user_id="engineer@company.com",
+        user_message="How do we handle authentication in the new API?",
+        ai_response="Use OAuth 2.0 with JWT tokens. See internal docs.",
+        data_classification="internal"
+    )
+    
+    agent.secure_chat(
+        user_id="engineer@company.com",
+        user_message="What about rate limiting?",
+        ai_response="Currently set to 100 req/min, but team reports issues at 50.",
+        data_classification="internal"
+    )
+    
+    # Example 4: Review audit trail
+    print("\n" + "=" * 70)
+    print("📋 Example 4: Audit Trail Review")
+    print("=" * 70)
+    
+    print("\nAll events:")
+    events = agent.get_audit_trail()
+    for event in events:
+        print(f"   - [{event['timestamp']}] {event['event_type']} by {event['user_id']}")
+    
+    print("\nFiltered by user (engineer@company.com):")
+    engineer_events = agent.get_audit_trail(user_id="engineer@company.com")
+    for event in engineer_events:
+        print(f"   - [{event['timestamp']}] {event['event_type']}")
+    
+    # Example 5: Generate compliance report
+    print("\n" + "=" * 70)
+    print("📄 Example 5: Compliance Report")
+    print("=" * 70)
+    
+    report = agent.export_compliance_report()
+    
+    print("\n✅ Compliance Report Generated")
+    print(f"   - Compliance Mode: {report['compliance_mode']}")
+    print(f"   - Security Level: {report['security_level']}")
+    print(f"   - Total Events: {report['audit_summary']['total_events']}")
+    
+    # Example 6: Gateway status
+    print("\n" + "=" * 70)
+    print("🛡️  Example 6: Gateway Status")
+    print("=" * 70)
+    
+    status = agent.get_gateway_status()
+    print(f"\nGateway Status:")
+    print(f"   - Deployment: {status['deployment_mode']}")
+    print(f"   - Security Level: {status['security_level']}")
+    print(f"   - Data Leakage Risk: {status['data_leakage_risk']}")
+    print(f"   - Routing Latency: {status['routing_latency']}")
+    
+    # Final summary
+    print("\n" + "=" * 70)
+    print("✅ Demo Complete - Enterprise Security Working!")
+    print("=" * 70)
+    print("\n✨ What we demonstrated:")
+    print("   1. On-premises deployment (zero data leakage)")
+    print("   2. Data classification enforcement")
+    print("   3. Full audit trail for compliance")
+    print("   4. Secure conversation management")
+    print("   5. Compliance reporting (SOC2/HIPAA)")
+    print("   6. Local heuristic routing (0ms latency)")
+    print("\n🏆 The Trust Gateway: Built for Enterprise Security")
+
+
+if __name__ == "__main__":
+    demo_enterprise_security()