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

modules/control-plane/docs/guides/IMPLEMENTATION.md

@@ -0,0 +1,225 @@
+# Agent Control Plane - Implementation Summary
+
+## What Was Built
+
+This repository implements a complete **Agent Control Plane** - a governance and management layer for autonomous AI agents. It addresses the problem stated: moving from chatbots to autonomous agents requires governance, not just intelligence.
+
+## Core Philosophy
+
+**Treat the LLM as a raw compute component that requires a kernel.**
+
+Just as operating systems provide kernels to safely manage hardware access, the Agent Control Plane provides a kernel to safely manage agent actions. Every action goes through governance checks before execution.
+
+## Architecture
+
+The implementation follows a layered architecture:
+
+```
+Application → Control Plane → LLM → Execution Environment
+                    ↓
+        [Kernel + Policy + Execution + Audit]
+```
+
+## Components Implemented
+
+### 1. Agent Kernel (`agent_kernel.py`)
+The central coordinator that mediates all agent interactions:
+- Permission management (4 levels: NONE, READ_ONLY, READ_WRITE, ADMIN)
+- Request validation and approval
+- Risk assessment (0.0 to 1.0 scale)
+- Audit logging
+- Session management
+
+**Key Classes:**
+- `AgentKernel`: Core coordinator
+- `AgentContext`: Session context with permissions
+- `ExecutionRequest`: Action request with validation status
+- `ActionType`: 7 supported action types
+- `PermissionLevel`: 4-level permission system
+
+### 2. Policy Engine (`policy_engine.py`)
+Enforces governance rules and constraints:
+- Rate limiting (per minute, per hour)
+- Concurrent execution limits
+- Resource quotas per agent
+- Risk-based policies
+- Custom policy rules with validators
+- Default security policies (system file protection, SQL injection prevention, etc.)
+
+**Key Classes:**
+- `PolicyEngine`: Policy enforcement
+- `ResourceQuota`: Rate limits and quotas
+- `RiskPolicy`: Risk-based rules
+- `create_default_policies()`: Built-in security policies
+
+### 3. Execution Engine (`execution_engine.py`)
+Safely executes agent actions:
+- Sandboxed execution (4 levels: NONE, BASIC, STRICT, ISOLATED)
+- Timeout enforcement
+- Resource monitoring
+- Error handling
+- Execution history tracking
+- Pluggable executors for different action types
+
+**Key Classes:**
+- `ExecutionEngine`: Execution coordinator
+- `ExecutionContext`: Sandbox configuration
+- `ExecutionMetrics`: Performance tracking
+- Action-specific executors (file, code, API)
+
+### 4. Control Plane (`control_plane.py`)
+Main interface that integrates all components:
+- Unified API for agent management
+- Complete governance pipeline
+- Agent status monitoring
+- Execution history
+- Convenience functions for common patterns
+
+**Key Functions:**
+- `AgentControlPlane`: Main interface
+- `create_read_only_agent()`: Read-only preset
+- `create_standard_agent()`: Standard preset
+- `create_admin_agent()`: Admin preset
+
+## Governance Pipeline
+
+Every action goes through this pipeline:
+
+1. **Permission Check** (Kernel)
+   - Does agent have required permission level?
+   
+2. **Policy Validation** (Policy Engine)
+   - Does action violate any policies?
+   - Is agent within rate limits?
+   - Are custom rules satisfied?
+
+3. **Risk Assessment** (Kernel)
+   - What is the risk score?
+   - Is it within acceptable limits?
+
+4. **Execution** (Execution Engine)
+   - Execute in sandboxed environment
+   - Monitor resources
+   - Enforce timeouts
+
+5. **Audit Logging** (Kernel)
+   - Record all actions
+   - Track policy decisions
+   - Monitor resource usage
+
+## Security Features
+
+### Default Security Policies
+1. **System File Protection**: Blocks access to /etc/, /sys/, /proc/, etc.
+2. **Credential Protection**: Prevents exposure of passwords, tokens, API keys
+3. **SQL Injection Prevention**: Blocks destructive SQL operations
+
+### Built-in Safety
+- Sandboxed execution by default
+- Risk scoring for all actions
+- Rate limiting to prevent abuse
+- Audit logging for compliance
+- Permission isolation between agents
+
+## Testing
+
+Comprehensive test suite (`test_control_plane.py`):
+- 13 unit tests covering all components
+- Permission control tests
+- Rate limiting tests
+- Policy enforcement tests
+- Execution tests
+- End-to-end integration tests
+- Multi-agent isolation tests
+
+**All tests pass ✓**
+
+## Documentation
+
+1. **README.md**: Complete overview and API reference
+2. **architecture.md**: Detailed architecture documentation
+3. **QUICKSTART.md**: 5-minute getting started guide
+4. **examples.py**: 6 comprehensive examples demonstrating features
+5. **config_examples.py**: Configuration patterns for different use cases
+
+## Use Cases Supported
+
+1. **Enterprise AI Agents**: Strict governance, audit trails, compliance
+2. **Multi-tenant Platforms**: Isolated execution, per-tenant quotas
+3. **Development/Testing**: Safe experimentation, comprehensive logging
+4. **Production Workflows**: Reliable execution, error handling, monitoring
+5. **Regulated Industries**: Full audit trails, policy enforcement
+
+## Example Usage
+
+```python
+# Create control plane
+control_plane = AgentControlPlane()
+
+# Create agent with permissions
+agent = create_standard_agent(control_plane, "my-agent")
+
+# Execute action with full governance
+result = control_plane.execute_action(
+    agent,
+    ActionType.FILE_READ,
+    {"path": "/data/file.txt"}
+)
+
+# Result includes: success, result, risk_score, metrics
+```
+
+## Key Metrics
+
+- **Lines of Code**: ~2000+ lines of implementation
+- **Components**: 4 major components
+- **Action Types**: 7 supported
+- **Permission Levels**: 4 levels
+- **Default Policies**: 3 security policies
+- **Tests**: 13 unit tests
+- **Documentation**: 5 comprehensive docs
+
+## Innovation
+
+This implementation demonstrates:
+
+1. **LLM-as-Compute**: Treats LLM as raw compute needing governance
+2. **Kernel Pattern**: OS-like kernel for agent management
+3. **Defense in Depth**: Multiple layers of security checks
+4. **Observability**: Complete visibility into agent behavior
+5. **Extensibility**: Pluggable policies and executors
+
+## Future Enhancements
+
+The architecture supports these planned features:
+- Distributed execution across nodes
+- Real-time monitoring dashboard
+- ML-based risk assessment
+- Container-based sandboxing
+- Transaction rollback
+- Integration with external policy engines (OPA)
+
+## Running the Code
+
+```bash
+# Run examples
+python3 examples.py
+
+# Run tests
+python3 test_control_plane.py
+
+# Run configuration examples
+python3 config_examples.py
+```
+
+## Conclusion
+
+The Agent Control Plane solves the governance bottleneck for autonomous agents. It provides:
+
+✓ **Safety**: Sandboxed execution, permission control
+✓ **Governance**: Policy enforcement, rate limiting
+✓ **Observability**: Audit logs, metrics, tracing
+✓ **Reliability**: Error handling, resource management
+✓ **Compliance**: Full audit trails, risk assessment
+
+This implementation proves that treating the LLM as a kernel-managed compute resource enables safe, controlled deployment of autonomous agents at scale.

modules/control-plane/docs/guides/PHILOSOPHY.md

@@ -0,0 +1,354 @@
+# The Agent Control Plane: Architecture and Philosophy
+
+## Executive Summary
+
+The Agent Control Plane treats the LLM as a raw compute component that requires a kernel. Just as operating systems provide kernels to safely manage hardware access, the Agent Control Plane provides a kernel to safely manage agent actions with deterministic enforcement.
+
+## The Problem: "Vibes" Are Not Engineering
+
+We are currently trying to control autonomous AI agents with "vibes":
+- *"You are a helpful assistant"*
+- *"Please do not lie"*
+- *"Ensure your SQL query is safe"*
+
+We hope the LLM honors the request. **But hope is not an engineering strategy.**
+
+In distributed systems:
+- We don't ASK a microservice to respect a rate limit → We ENFORCE it at the gateway
+- We don't ASK a database query not to drop a table → We ENFORCE it via permissions
+- We don't ASK a process not to access another's memory → The kernel PREVENTS it
+
+Yet with AI agents, we've convinced ourselves that "prompt engineering" is a substitute for systems engineering. **It isn't.**
+
+## The Philosophy: Scale by Subtraction
+
+**To make a complex system reliable, you don't add features; you remove the variables that cause chaos.**
+
+In Enterprise AI, the variable we need to subtract is **creativity**.
+
+### The Mute Agent
+
+When I build a SQL-generating agent for a finance team, I don't want it to be "creative." I want it to execute a precise task: *Get the data, or tell me you can't.*
+
+If I ask a SQL agent to "build me a rocket ship," the current generation of agents will try to be helpful:
+- They hallucinate a schema
+- They offer conversational pivots: *"I can't build rockets, but I can tell you about physics!"*
+
+**This is waste.** It consumes tokens, confuses users, and erodes trust.
+
+A robust agent architecture should strip away the LLM's desire to be a "conversationalist." If the request does not map to a capability defined in the system's constraints, the response should be `NULL`. It should be silence.
+
+**The Mute Agent knows when to shut up and fail fast rather than improvising.**
+
+## The Architecture: Kubernetes for Agents
+
+We need to stop embedding logic inside the prompt and start lifting it into a distinct infrastructure layer.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         Application Layer                     │
+│                    (Chat, Workflow, Tools)                    │
+└─────────────────────────┬───────────────────────────────────┘
+                          │
+┌─────────────────────────▼───────────────────────────────────┐
+│                      Agent Control Plane                      │
+│                                                               │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
+│  │    Agent     │  │   Policy     │  │   Audit      │      │
+│  │   Kernel     │◄─┤   Engine     │◄─┤   Logger     │      │
+│  └──────┬───────┘  └──────────────┘  └──────────────┘      │
+│         │                                                     │
+│  ┌──────▼───────┐  ┌──────────────┐  ┌──────────────┐      │
+│  │  Execution   │  │  Shadow Mode │  │ Constraint   │      │
+│  │   Engine     │  │  Executor    │  │   Graphs     │      │
+│  └──────────────┘  └──────────────┘  └──────────────┘      │
+│                                                               │
+│  ┌──────────────────────────────────────────────────┐       │
+│  │          Supervisor Agent Network                 │       │
+│  │         (Agents Watching Agents)                  │       │
+│  └──────────────────────────────────────────────────┘       │
+└─────────────────────────┬───────────────────────────────────┘
+                          │
+┌─────────────────────────▼───────────────────────────────────┐
+│                    LLM (Raw Compute)                         │
+│              (GPT-4, Claude, Llama, etc.)                    │
+└─────────────────────────┬───────────────────────────────────┘
+                          │
+┌─────────────────────────▼───────────────────────────────────┐
+│                   Execution Environment                       │
+│         (Code, Databases, APIs, File System)                 │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Think of It Like This:
+- **LLM = CPU/Container**: Provides reasoning and compute
+- **Control Plane = Orchestrator/OS**: Provides deterministic boundaries
+
+The Control Plane creates a boundary around the stochastic (probabilistic) nature of the model using deterministic policies. It answers the questions the model cannot be trusted to answer for itself:
+
+- **Identity**: Who is this agent acting on behalf of?
+- **Topology**: What other agents or tools can it "see"?
+- **Resource Limits**: How many steps is it allowed to take?
+- **The "No-Fly" List**: What concepts are strictly forbidden?
+
+## Core Components
+
+### 1. Agent Kernel
+
+The kernel is the central coordinator that mediates all agent interactions. It provides:
+
+- **Permission Management**: 4-level system (NONE, READ_ONLY, READ_WRITE, ADMIN)
+- **Request Validation**: Every action validated before execution
+- **Risk Assessment**: Automatic scoring of action risk (0.0 to 1.0)
+- **Audit Logging**: Complete traceability for compliance
+- **Session Management**: Isolated contexts per agent
+
+**Key Principle**: Like an OS kernel, it intercepts EVERY action before execution.
+
+### 2. Policy Engine
+
+Enforces governance rules and constraints:
+
+- **Rate Limiting**: Per-minute, per-hour, concurrent execution limits
+- **Resource Quotas**: Token limits, API call limits, compute time limits
+- **Risk Policies**: Risk-based rules with thresholds
+- **Custom Rules**: Pluggable validators for organization-specific policies
+
+**Key Principle**: Policies are CODE, not prompts. They execute deterministically.
+
+### 3. Execution Engine
+
+Safely executes approved actions:
+
+- **Sandboxing**: 4 levels (NONE, BASIC, STRICT, ISOLATED)
+- **Timeout Enforcement**: Hard limits on execution time
+- **Resource Monitoring**: Track CPU, memory, network usage
+- **Error Handling**: Graceful failure and recovery
+
+**Key Principle**: Even approved actions execute in controlled environments.
+
+## Advanced Features
+
+### The Mute Agent: Capability-Based Execution
+
+**Problem**: Agents try to be helpful when they should return NULL.
+
+**Solution**: Define explicit capabilities. Out-of-scope requests return NULL, not hallucinations.
+
+```python
+# Define what this agent CAN do
+capabilities = [
+    AgentCapability(
+        name="query_database",
+        action_types=[ActionType.DATABASE_QUERY],
+        validator=lambda req: req.parameters['query'].startswith('SELECT')
+    )
+]
+
+# Anything else? NULL.
+```
+
+**Result**: If you ask a SQL agent to "build a rocket," it returns NULL instead of trying to help.
+
+### Shadow Mode: The Matrix for Agents
+
+**Problem**: How do we trust agent behavior before production?
+
+**Solution**: Simulation mode where agents THINK they're executing, but we're just logging and validating.
+
+```
+Agent: "I'm going to write to the database now"
+Shadow Mode: *intercepts* "Sure buddy. Let me just log what you WOULD do..."
+                         "And validate it against all policies..."
+                         "And calculate the impact..."
+                         "But I'm not actually doing it."
+```
+
+**Benefits**:
+- Test agent behavior without side effects
+- Validate policy coverage
+- Analyze reasoning chains
+- Safe experimentation
+
+### Constraint Graphs: Multi-Dimensional Context
+
+**Problem**: Context in an enterprise isn't flat; it's a graph.
+
+**Solution**: Three types of graphs that act as the "physics" of the agent's world:
+
+#### 1. Data Graph
+What data resources exist and are accessible:
+- Database tables and schemas
+- File systems and directories
+- API endpoints
+- Data lakes
+
+#### 2. Policy Graph
+What corporate rules and compliance constraints apply:
+- "No PII in output"
+- "Finance data requires CFO approval"
+- "HIPAA protected resources"
+
+#### 3. Temporal Graph
+What is true RIGHT NOW:
+- Maintenance windows (no writes 2-4 AM)
+- Business hours (9-5 EST)
+- Freeze periods (end of quarter)
+- Peak traffic hours (throttle)
+
+**Key Principle**: Deterministic Enforcement.
+
+If a SQL Agent tries to query a table that exists in the Data Graph but is blocked in the Policy Graph, the Control Plane intercepts the action. **The request never even reaches the database.**
+
+The LLM can "think" whatever it wants, but it can only **ACT** on what the graphs permit.
+
+### Supervisor Agents: Recursive Governance
+
+**Problem**: Eventually, the Control Plane itself will be too complex for humans to manage manually.
+
+**Solution**: Supervisor Agents - specialized, highly constrained agents whose ONLY job is to watch worker agents and flag violations to humans.
+
+**Agents watching agents, bound by a constitution of code.**
+
+```
+Worker Agents → Do the actual work
+     ↓
+Supervisor Agents → Watch workers, detect anomalies
+     ↓
+Meta-Supervisors → Watch supervisors (optional)
+     ↓
+Human Oversight → Final escalation
+```
+
+**What They Detect**:
+- Repeated failures
+- Excessive risk scores
+- Policy circumvention attempts
+- Anomalous behavior patterns
+- Resource exhaustion
+
+**Key Principle**: Supervisors are MORE constrained than workers. They can only READ logs, not EXECUTE actions.
+
+## The Governance Pipeline
+
+Every action goes through this pipeline:
+
+```
+1. Mute Agent Validation
+   └─> Does this map to a defined capability?
+       └─> NO → Return NULL
+       └─> YES → Continue
+
+2. Permission Check (Kernel)
+   └─> Does agent have required permission level?
+       └─> NO → DENIED
+       └─> YES → Continue
+
+3. Constraint Graph Validation
+   └─> Data Graph: Is resource accessible?
+   └─> Policy Graph: Any blocking rules?
+   └─> Temporal Graph: Allowed right now?
+       └─> Any violation → DENIED
+       └─> All pass → Continue
+
+4. Policy Engine Validation
+   └─> Rate limits okay?
+   └─> Custom rules satisfied?
+       └─> Any violation → DENIED
+       └─> All pass → Continue
+
+5. Risk Assessment (Kernel)
+   └─> Calculate risk score (0.0 to 1.0)
+   └─> Within acceptable limits?
+       └─> NO → DENIED
+       └─> YES → Continue
+
+6. Execution
+   └─> Shadow Mode?
+       └─> YES → Simulate and log
+       └─> NO → Execute in sandbox
+
+7. Audit Logging (Kernel)
+   └─> Record everything
+   └─> Update metrics
+```
+
+**If ANY step fails, the action is denied and logged.**
+
+## Security Model
+
+### Defense in Depth
+
+Multiple layers of security:
+
+1. **Permission Layer**: Coarse-grained access control
+2. **Policy Layer**: Fine-grained rule enforcement
+3. **Constraint Graph Layer**: Context-aware validation
+4. **Risk Layer**: Dynamic threat assessment
+5. **Execution Layer**: Sandboxed environment
+6. **Supervision Layer**: Continuous monitoring
+
+### Default Deny
+
+- Agents start with minimal permissions
+- Resources not in graphs are inaccessible
+- Unknown action types are denied
+- High-risk actions require elevated permissions
+
+### Auditability
+
+Every action is logged with:
+- Who (agent ID, session ID)
+- What (action type, parameters)
+- When (timestamp)
+- Why (risk score, policy decisions)
+- Outcome (success/failure, result)
+
+## Comparison with Other Approaches
+
+| Aspect | Prompt Engineering | Guardrails | Tool Directory | Agent Control Plane |
+|--------|-------------------|------------|----------------|-------------------|
+| **Enforcement** | Advisory (hope) | Reactive (post-process) | Discovery (phonebook) | **Deterministic (kernel)** |
+| **Scope** | Text/context | Input/output content | Tool availability | **Execution & capabilities** |
+| **Timing** | Pre-generation | Post-generation | Pre-execution | **Pre-execution** |
+| **Failures** | Hallucination | Content leak | Wrong tool | **Hard denial** |
+| **Auditability** | Low | Medium | Low | **Complete** |
+| **Simulation** | No | No | No | **Yes (Shadow Mode)** |
+
+## When to Use
+
+### Use Agent Control Plane When:
+- Deploying agents in production environments
+- Compliance and audit trails are required
+- Agents have access to sensitive data or critical systems
+- Multiple agents need isolation
+- You need deterministic enforcement, not advisory hints
+
+### Use Prompt Engineering When:
+- Building prototypes or demos
+- No security or compliance requirements
+- Agent behavior is not critical
+- You're okay with probabilistic boundaries
+
+### Use Both:
+The Agent Control Plane doesn't replace good prompting—it provides the deterministic layer that prompts cannot. Use prompts to guide agent behavior; use the Control Plane to enforce boundaries.
+
+## Future Directions
+
+1. **Distributed Execution**: Scale across multiple nodes with shared policy state
+2. **ML-Based Risk**: Use historical data to predict action risk
+3. **Auto-Policy Generation**: Learn policies from past agent behavior
+4. **Visual Dashboard**: Real-time monitoring of agent swarm
+5. **Integration with External Systems**: Connect to enterprise IAM, secrets management, observability platforms
+
+## Conclusion
+
+**The "magic" phase of AI is ending. The "engineering" phase is beginning.**
+
+We are moving away from prompt engineering and toward **Agent Orchestration and Governance**. The winners of the next cycle won't be the ones with the cleverest prompts; they will be the ones who can guarantee safety, predictability, and control.
+
+**Don't build a chatbot. Build a Control Plane.**
+
+---
+
+*"In the world of distributed systems, we don't ask nicely. We enforce. It's time to bring that same rigor to AI agents."*