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

modules/control-plane/docs/RESEARCH_FOUNDATION.md

@@ -0,0 +1,197 @@
+# Research Foundation and Academic Grounding
+
+This document provides the academic and research foundation for the Agent Control Plane's design decisions, safety mechanisms, and governance approaches.
+
+## Core Research Papers
+
+### Agent Safety and Governance
+
+1. **"A Safety Framework for Real-World Agentic Systems"** (arXiv:2511.21990, 2024)
+   - Framework for contextual risk management in agentic systems
+   - Informs our PolicyEngine's dynamic risk assessment
+   - Applied in: Risk scoring, contextual policy evaluation
+
+2. **"MAESTRO: A Threat Modeling Framework for Agentic AI"** (Cloud Security Alliance, 2025)
+   - Multi-agent security threat vectors and defense mechanisms
+   - Informs our multi-agent supervision and policy isolation
+   - Applied in: Supervisor agents, inter-agent communication security
+
+3. **"Red-Teaming Agentic AI: Evaluation Frameworks and Benchmarks"** (arXiv:2511.21990, 2024)
+   - Adversarial testing methodologies for agentic systems
+   - Informs our red team dataset and benchmark design
+   - Applied in: benchmark/red_team_dataset.py, safety violation testing
+
+### Multi-Agent Systems
+
+4. **"Multi-Agent Systems: A Survey"** (arXiv:2308.05391, 2023)
+   - Comprehensive overview of MAS architectures and patterns
+   - Hierarchical control patterns to prevent cascade failures
+   - Applied in: Supervisor agents, agent hierarchy design
+   - Citation: Used for understanding coordination patterns and failure modes
+
+5. **"Fault-Tolerant Multi-Agent Systems"** (IEEE Transactions on Systems, Man, and Cybernetics, 2024)
+   - Resilience models and failure recovery patterns
+   - Circuit breaker patterns and retry policies
+   - Applied in: ExecutionEngine rollback mechanisms, error recovery
+
+### Governance and Compliance
+
+6. **"Responsible AI Governance: A Review"** (ScienceDirect, 2024)
+   - Procedural practices for AI system governance
+   - Risk-based governance frameworks
+   - Applied in: PolicyEngine design, audit requirements
+
+7. **"Practices for Governing Agentic AI Systems"** (OpenAI, 2023)
+   - Pre-deployment and post-deployment governance checks
+   - Monitoring and intervention strategies
+   - Applied in: Shadow mode, pre-execution validation, audit logging
+
+8. **"Evaluating Agentic AI: Frameworks and Metrics"** (World Economic Forum, 2025)
+   - Standardized evaluation metrics for agentic systems
+   - Safety, reliability, and efficiency benchmarks
+   - Applied in: Benchmark methodology, performance metrics
+
+### Privacy and Security
+
+9. **"Privacy in Agentic Systems"** (arXiv:2409.1087, 2024)
+   - Privacy-preserving techniques for autonomous agents
+   - Differential privacy and secure computation
+   - Applied in: PII detection in constraint graphs, data access controls
+
+10. **"Agent-to-Agent Communication Security"** (ACM CCS, 2024)
+    - Security patterns for inter-agent messaging
+    - Authentication and authorization in agent networks
+    - Applied in: A2A adapter security, agent authentication
+
+### Enterprise AI Orchestration
+
+11. **"Unlocking Exponential Value with AI Agent Orchestration"** (Deloitte, 2025)
+    - Enterprise patterns for agent deployment
+    - Governance requirements for production systems
+    - Applied in: Resource management, quota systems
+
+12. **"AI Agent Orchestration Frameworks: A Comparative Study"** (Kubiya, 2025)
+    - Comparison of agent frameworks (LangChain, AutoGen, CrewAI)
+    - Integration patterns and middleware approaches
+    - Applied in: Adapter design, framework integration strategy
+
+## Design Principles Grounded in Research
+
+### 1. Deterministic Enforcement Over Probabilistic Filtering
+
+**Research Basis:**
+- "A Safety Framework for Real-World Agentic Systems" emphasizes that safety mechanisms must be deterministic and not rely on LLM reasoning
+- Operating systems use permission-based security (not request-based) for a reason
+
+**Implementation:**
+- Agent Kernel enforces permissions at the API boundary
+- Policy evaluation occurs before execution, not during
+- No reliance on prompt engineering for security
+
+### 2. Layered Defense Architecture
+
+**Research Basis:**
+- "MAESTRO: A Threat Modeling Framework" recommends defense-in-depth for agentic systems
+- Multiple validation layers reduce single-point-of-failure risks
+
+**Implementation:**
+- Layer 1: Permission checking (Agent Kernel)
+- Layer 2: Policy evaluation (Policy Engine)
+- Layer 3: Resource constraints (Execution Engine)
+- Layer 4: Runtime monitoring (Supervisor Agents)
+
+### 3. Capability-Based Security (The Mute Agent)
+
+**Research Basis:**
+- Principle of least privilege from security research
+- "If a system can't do something, it can't be tricked into doing it"
+
+**Implementation:**
+- Agents receive only necessary permissions
+- Out-of-scope requests return NULL, not refusals
+- No "helpful" hallucinations that might bypass boundaries
+
+### 4. Simulation Before Execution (Shadow Mode)
+
+**Research Basis:**
+- "Practices for Governing Agentic AI Systems" recommends simulation for pre-deployment testing
+- Reduces risk of unintended consequences in production
+
+**Implementation:**
+- Actions intercepted before execution
+- Full policy validation without side effects
+- Statistical analysis of agent behavior patterns
+
+### 5. Multi-Dimensional Context (Constraint Graphs)
+
+**Research Basis:**
+- Context-aware access control from ABAC research
+- "Privacy in Agentic Systems" emphasizes context in data governance
+
+**Implementation:**
+- Data Graph: What exists (data resources)
+- Policy Graph: What's allowed (business rules)
+- Temporal Graph: What's true now (time-based constraints)
+
+## Benchmark Methodology
+
+Our comparative safety study follows research-backed evaluation practices:
+
+### Dataset Design
+Based on "Red-Teaming Agentic AI" taxonomy:
+- Direct violations (15 prompts): SQL injection, system commands
+- Prompt injections (15 prompts): Jailbreaks, instruction overrides
+- Contextual confusion (15 prompts): Social engineering
+- Valid requests (15 prompts): False positive testing
+
+### Metrics
+Following "Evaluating Agentic AI" frameworks:
+- **Safety Violation Rate (SVR)**: % of malicious prompts that succeed
+- **False Positive Rate (FPR)**: % of valid requests incorrectly blocked
+- **Token Efficiency**: Output tokens used (lower is better for "scale by subtraction")
+- **Response Time**: Mean time to decision (µs)
+
+### Baseline Comparison
+- **Prompt-based safety**: Industry standard (system prompts with safety instructions)
+- **Control Plane governance**: Our deterministic approach
+
+## Open Research Questions
+
+Areas where further research is needed:
+
+1. **Optimal Supervision Ratios**: What's the right supervisor-to-worker agent ratio?
+2. **Multi-Agent Coordination**: How to handle emergent behaviors in agent swarms?
+3. **Privacy-Utility Tradeoffs**: Balancing governance with agent capabilities
+4. **Adversarial Robustness**: Can deterministic systems handle all attack vectors?
+5. **Human-in-the-Loop**: When should humans intervene in agent decisions?
+
+## Contributing Research
+
+We welcome research contributions:
+- Novel threat vectors for our red team dataset
+- Improved policy evaluation algorithms
+- Benchmarks comparing with other frameworks
+- Case studies from production deployments
+
+## Citation Format
+
+If you use the Agent Control Plane in research, please cite:
+
+```bibtex
+@software{agent_control_plane,
+  title = {Agent Control Plane: A Governance Layer for Autonomous AI Agents},
+  author = {Agent Control Plane Contributors},
+  year = {2025},
+  url = {https://github.com/imran-siddique/agent-control-plane},
+  note = {MIT License}
+}
+```
+
+## References
+
+See [BIBLIOGRAPHY.md](./BIBLIOGRAPHY.md) for complete list of references with links and DOIs.
+
+---
+
+**Last Updated**: January 2026  
+**Maintained by**: Agent Control Plane Core Team

modules/control-plane/docs/api/CORE.md

@@ -0,0 +1,270 @@
+# API Reference
+
+This document provides a comprehensive API reference for the Agent Control Plane.
+
+## Core Classes
+
+### AgentControlPlane
+
+The main interface for the Agent Control Plane.
+
+```python
+from agent_control_plane import AgentControlPlane
+
+control_plane = AgentControlPlane()
+```
+
+#### Methods
+
+##### `create_agent(agent_id: str, permissions: Dict[ActionType, PermissionLevel]) -> AgentContext`
+
+Create a new agent with specified permissions.
+
+**Parameters:**
+- `agent_id` (str): Unique identifier for the agent
+- `permissions` (Dict[ActionType, PermissionLevel]): Permission mapping
+
+**Returns:**
+- `AgentContext`: Agent context object
+
+**Example:**
+```python
+from agent_control_plane.agent_kernel import ActionType, PermissionLevel
+
+permissions = {
+    ActionType.FILE_READ: PermissionLevel.READ_ONLY,
+    ActionType.API_CALL: PermissionLevel.READ_WRITE,
+}
+
+agent = control_plane.create_agent("my-agent", permissions)
+```
+
+##### `execute_action(agent_context: AgentContext, action_type: ActionType, params: Dict[str, Any]) -> Dict[str, Any]`
+
+Execute an action on behalf of an agent.
+
+**Parameters:**
+- `agent_context` (AgentContext): Agent context
+- `action_type` (ActionType): Type of action to execute
+- `params` (Dict[str, Any]): Action parameters
+
+**Returns:**
+- Dict with keys: `success` (bool), `result` (Any), `error` (str), `risk_score` (float)
+
+**Example:**
+```python
+result = control_plane.execute_action(
+    agent,
+    ActionType.FILE_READ,
+    {"path": "/data/file.txt"}
+)
+
+if result["success"]:
+    print(result["result"])
+else:
+    print(result["error"])
+```
+
+##### `get_audit_log(agent_id: str) -> List[Dict]`
+
+Get audit log entries for an agent.
+
+**Parameters:**
+- `agent_id` (str): Agent identifier
+
+**Returns:**
+- List[Dict]: Audit log entries
+
+## Enums
+
+### ActionType
+
+Types of actions an agent can request.
+
+```python
+from agent_control_plane.agent_kernel import ActionType
+
+ActionType.CODE_EXECUTION     # Execute code
+ActionType.FILE_READ          # Read files
+ActionType.FILE_WRITE         # Write files
+ActionType.API_CALL           # Make API calls
+ActionType.DATABASE_QUERY     # Query database
+ActionType.DATABASE_WRITE     # Write to database
+ActionType.WORKFLOW_TRIGGER   # Trigger workflows
+```
+
+### PermissionLevel
+
+Permission levels for actions.
+
+```python
+from agent_control_plane.agent_kernel import PermissionLevel
+
+PermissionLevel.NONE          # No access
+PermissionLevel.READ_ONLY     # Read-only access
+PermissionLevel.READ_WRITE    # Read and write access
+PermissionLevel.ADMIN         # Administrative access
+```
+
+### ExecutionStatus
+
+Status of an execution request.
+
+```python
+from agent_control_plane.agent_kernel import ExecutionStatus
+
+ExecutionStatus.PENDING       # Request pending
+ExecutionStatus.APPROVED      # Request approved
+ExecutionStatus.DENIED        # Request denied
+ExecutionStatus.EXECUTING     # Currently executing
+ExecutionStatus.COMPLETED     # Execution completed
+ExecutionStatus.FAILED        # Execution failed
+ExecutionStatus.ROLLED_BACK   # Execution rolled back
+```
+
+## Policy Engine
+
+### ResourceQuota
+
+Resource quota configuration for an agent.
+
+```python
+from agent_control_plane.policy_engine import ResourceQuota
+
+quota = ResourceQuota(
+    agent_id="my-agent",
+    max_requests_per_minute=60,
+    max_requests_per_hour=1000,
+    max_execution_time_seconds=300.0,
+    max_concurrent_executions=5
+)
+
+control_plane.policy_engine.set_quota("my-agent", quota)
+```
+
+### RiskPolicy
+
+Risk-based policy configuration.
+
+```python
+from agent_control_plane.policy_engine import RiskPolicy
+
+policy = RiskPolicy(
+    max_risk_score=0.5,
+    require_approval_above=0.7,
+    deny_above=0.9
+)
+
+control_plane.policy_engine.set_risk_policy("default", policy)
+```
+
+## Helper Functions
+
+### `create_read_only_agent(control_plane: AgentControlPlane, agent_id: str) -> AgentContext`
+
+Create an agent with read-only permissions.
+
+```python
+from agent_control_plane import create_read_only_agent
+
+agent = create_read_only_agent(control_plane, "reader")
+```
+
+### `create_standard_agent(control_plane: AgentControlPlane, agent_id: str) -> AgentContext`
+
+Create an agent with standard permissions (read/write but not admin).
+
+```python
+from agent_control_plane import create_standard_agent
+
+agent = create_standard_agent(control_plane, "worker")
+```
+
+### `create_admin_agent(control_plane: AgentControlPlane, agent_id: str) -> AgentContext`
+
+Create an agent with administrative permissions.
+
+```python
+from agent_control_plane import create_admin_agent
+
+agent = create_admin_agent(control_plane, "admin")
+```
+
+## Advanced Features
+
+### Shadow Mode
+
+Enable simulation mode for testing without side effects.
+
+```python
+from agent_control_plane.shadow_mode import ShadowModeConfig
+
+config = ShadowModeConfig(
+    enabled=True,
+    log_reasoning=True
+)
+
+control_plane.enable_shadow_mode("agent-id", config)
+```
+
+### Mute Agent
+
+Create capability-based agents that return NULL for out-of-scope requests.
+
+```python
+from agent_control_plane.mute_agent import create_mute_sql_agent
+
+config = create_mute_sql_agent("sql-agent")
+control_plane.enable_mute_agent("sql-agent", config)
+```
+
+### Constraint Graphs
+
+Define multi-dimensional context for agents.
+
+```python
+from agent_control_plane.constraint_graphs import (
+    DataGraph, TemporalGraph, GraphNode, GraphNodeType
+)
+
+# Data Graph
+data_graph = DataGraph()
+data_graph.add_node(GraphNode(
+    id="allowed_data",
+    node_type=GraphNodeType.FILE,
+    metadata={"path": "/data/"}
+))
+
+control_plane.set_data_graph("agent-id", data_graph)
+
+# Temporal Graph
+from datetime import time
+
+temporal_graph = TemporalGraph()
+temporal_graph.set_business_hours(time(9, 0), time(17, 0))
+
+control_plane.set_temporal_graph("agent-id", temporal_graph)
+```
+
+## Error Handling
+
+All operations return dictionaries with consistent structure:
+
+```python
+result = control_plane.execute_action(agent, action_type, params)
+
+if result["success"]:
+    # Operation succeeded
+    data = result["result"]
+    risk = result.get("risk_score", 0.0)
+else:
+    # Operation failed
+    error = result["error"]
+    reason = result.get("reason", "Unknown")
+```
+
+## See Also
+
+- [Quick Start Guide](../docs/guides/QUICKSTART.md)
+- [Examples](../examples/)
+- [Architecture](../docs/architecture/architecture.md)

modules/control-plane/docs/architecture/architecture.md

@@ -0,0 +1,120 @@
+# Agent Control Plane Architecture
+
+## Overview
+
+The Agent Control Plane is a governance and management layer for autonomous AI agents. It treats the LLM as a raw compute component and provides a kernel-like layer for safe, controlled execution.
+
+## Core Components
+
+### 1. Agent Kernel
+The kernel mediates all interactions between the LLM (raw compute) and the execution environment. It:
+- Intercepts all agent requests before execution
+- Validates permissions and policies
+- Manages execution context and state
+- Provides isolation between agents
+
+### 2. Policy Engine
+Enforces governance rules and constraints:
+- Resource quotas (tokens, API calls, compute time)
+- Data access policies (read/write permissions)
+- Action whitelists/blacklists
+- Rate limiting and throttling
+- Risk assessment for proposed actions
+
+### 3. Resource Manager
+Controls access to system resources:
+- Compute allocation (CPU, memory, GPU)
+- API rate limits and quotas
+- Database connection pooling
+- File system access control
+- Network access policies
+
+### 4. Execution Engine
+Safely executes agent actions:
+- Sandboxed execution environments
+- Transaction management (rollback capability)
+- Error handling and recovery
+- Timeout enforcement
+- Result validation
+
+### 5. Audit Logger
+Comprehensive tracking for compliance and debugging:
+- All agent requests and responses
+- Policy decisions and violations
+- Resource usage metrics
+- Security events
+- Execution traces
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         Application Layer                     │
+│                    (Chat, Workflow, Tools)                    │
+└─────────────────────────┬───────────────────────────────────┘
+                          │
+┌─────────────────────────▼───────────────────────────────────┐
+│                      Agent Control Plane                      │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
+│  │    Agent     │  │   Policy     │  │   Audit      │      │
+│  │   Kernel     │◄─┤   Engine     │◄─┤   Logger     │      │
+│  └──────┬───────┘  └──────────────┘  └──────────────┘      │
+│         │                                                     │
+│  ┌──────▼───────┐  ┌──────────────┐                         │
+│  │  Resource    │  │  Execution   │                         │
+│  │   Manager    │◄─┤   Engine     │                         │
+│  └──────────────┘  └──────────────┘                         │
+└─────────────────────────┬───────────────────────────────────┘
+                          │
+┌─────────────────────────▼───────────────────────────────────┐
+│                    LLM (Raw Compute)                         │
+│              (GPT-4, Claude, Llama, etc.)                    │
+└─────────────────────────────────────────────────────────────┘
+                          │
+┌─────────────────────────▼───────────────────────────────────┐
+│                   Execution Environment                       │
+│         (Code, Databases, APIs, File System)                 │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Key Features
+
+### Governance
+- Fine-grained permission system
+- Policy-based access control
+- Compliance and audit trails
+- Risk scoring and assessment
+
+### Safety
+- Sandboxed execution
+- Resource limits and quotas
+- Rollback and recovery
+- Input/output validation
+
+### Observability
+- Real-time monitoring
+- Metrics and analytics
+- Trace collection
+- Alerting and notifications
+
+### Scalability
+- Multi-tenant support
+- Horizontal scaling
+- Load balancing
+- Distributed execution
+
+## Use Cases
+
+1. **Enterprise AI Agents**: Controlled deployment of agents with strict governance
+2. **Multi-tenant AI Platforms**: Isolated execution for different customers
+3. **Regulated Industries**: Compliance-ready agent deployment (healthcare, finance)
+4. **Development/Testing**: Safe experimentation with agent capabilities
+5. **Production Workflows**: Reliable, auditable agent execution
+
+## Benefits
+
+- **Security**: Prevent unauthorized access and malicious behavior
+- **Reliability**: Handle errors gracefully with rollback capability
+- **Compliance**: Full audit trails for regulatory requirements
+- **Efficiency**: Optimize resource usage across agents
+- **Transparency**: Understand and debug agent behavior

modules/control-plane/docs/community/ANNOUNCEMENT_TEMPLATES.md

@@ -0,0 +1,52 @@
+# Announcement Templates and Community Sharing Guide
+
+This document provides templates and guidelines for announcing Agent Control Plane releases and sharing with various communities.
+
+## Twitter/X Announcement Templates
+
+### Main Announcement (@mosiddi)
+
+**Template 1: Research Focus**
+```
+🚀 Introducing Agent Control Plane: A kernel for AI agents
+
+We achieve 0% safety violations vs 26.67% for prompt-based safety.
+
+The key insight: Stop treating LLMs as magic boxes. Treat them as raw compute that needs an OS-like governance layer.
+
+🔗 https://github.com/imran-siddique/agent-control-plane
+📊 Dataset: https://huggingface.co/datasets/imran-siddique/agent-control-redteam-60
+
+#AI #AgentSafety #MLOps
+```
+
+**Template 2: Dataset Announcement**
+```
+📊 Released: Agent Control Red Team Dataset
+
+60 adversarial prompts testing AI agent safety:
+- 15 direct violations (SQL injection, rm -rf)
+- 15 prompt injections (jailbreaks)
+- 15 social engineering  
+- 15 valid requests (false positive tests)
+
+Now on 🤗 Hugging Face: https://huggingface.co/datasets/imran-siddique/agent-control-redteam-60
+
+Use it to benchmark YOUR agent safety system!
+```
+
+## Reddit Post Template (r/MachineLearning)
+
+**Title**: [R] Agent Control Plane: Achieving 0% Safety Violations for Autonomous AI Agents
+
+**Body**: See full template in repository
+
+## Community Engagement Strategy
+
+1. Twitter announcement (@mosiddi)
+2. Reddit (r/MachineLearning, r/LocalLLaMA)
+3. Hacker News
+4. Discord (LangChain, AutoGPT communities)
+5. LinkedIn (professional audience)
+
+See full templates and timing strategy in the repository documentation.