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

modules/control-plane/docs/DOCKER_DEPLOYMENT.md

@@ -0,0 +1,184 @@
+# Docker Deployment Guide
+
+This directory contains Docker configuration for deploying the Agent Control Plane.
+
+## Quick Start
+
+### Production Deployment
+
+```bash
+# Build and start the service
+docker-compose up -d
+
+# View logs
+docker-compose logs -f
+
+# Stop the service
+docker-compose down
+```
+
+### Development Environment
+
+```bash
+# Start development container
+docker-compose --profile dev up -d acp-dev
+
+# Enter the container
+docker exec -it acp-dev bash
+
+# Run tests inside container
+python -m pytest tests/
+
+# Run examples
+python examples/basic_usage.py
+```
+
+### Distributed Setup (with Redis)
+
+```bash
+# Start with Redis for distributed coordination
+docker-compose --profile distributed up -d
+
+# This includes Redis for message queues and caching
+```
+
+## Configuration
+
+### Environment Variables
+
+- `ACP_DATA_DIR`: Directory for persistent data (default: `/app/data`)
+- `ACP_LOG_LEVEL`: Logging level (default: `INFO`, options: `DEBUG`, `INFO`, `WARNING`, `ERROR`)
+
+### Volumes
+
+- `acp-data`: Persistent storage for audit logs, databases, and configurations
+- `acp-dev-data`: Separate volume for development work
+- `redis-data`: Redis persistence (when using distributed profile)
+
+## Building Images
+
+### Build Production Image
+
+```bash
+docker build --target production -t agent-control-plane:latest .
+```
+
+### Build Development Image
+
+```bash
+docker build --target development -t agent-control-plane:dev .
+```
+
+## Health Checks
+
+The production container includes health checks:
+
+```bash
+# Check health status
+docker inspect --format='{{.State.Health.Status}}' acp-main
+```
+
+## Networking
+
+All services are connected via the `acp-network` bridge network, allowing inter-container communication.
+
+## Security Considerations
+
+1. **Non-root User**: Containers run as `acp` user (UID 1000)
+2. **Read-only Mounts**: Examples are mounted read-only
+3. **Network Isolation**: Services communicate only via defined network
+4. **Secrets Management**: Use Docker secrets for sensitive data in production
+
+### Using Docker Secrets
+
+```bash
+# Create a secret
+echo "your-secret-value" | docker secret create acp_secret -
+
+# Reference in docker-compose.yml
+services:
+  agent-control-plane:
+    secrets:
+      - acp_secret
+```
+
+## Production Deployment Checklist
+
+- [ ] Review and set appropriate environment variables
+- [ ] Configure volume persistence for audit logs
+- [ ] Set up monitoring and alerting
+- [ ] Configure resource limits (CPU, memory)
+- [ ] Enable TLS/SSL for API endpoints
+- [ ] Set up backup strategy for data volumes
+- [ ] Review security hardening options
+- [ ] Configure log aggregation
+
+## Resource Limits
+
+Add resource limits in production:
+
+```yaml
+services:
+  agent-control-plane:
+    deploy:
+      resources:
+        limits:
+          cpus: '2'
+          memory: 2G
+        reservations:
+          cpus: '0.5'
+          memory: 512M
+```
+
+## Kubernetes Deployment
+
+For Kubernetes deployment, see `k8s/` directory (coming soon).
+
+## Troubleshooting
+
+### Container won't start
+
+```bash
+# Check logs
+docker-compose logs agent-control-plane
+
+# Check health
+docker inspect acp-main
+```
+
+### Permission issues
+
+```bash
+# Fix volume permissions
+docker-compose run --rm agent-control-plane chown -R acp:acp /app/data
+```
+
+### Network issues
+
+```bash
+# Inspect network
+docker network inspect acp-network
+
+# Test connectivity
+docker-compose exec agent-control-plane ping redis
+```
+
+## Updates and Maintenance
+
+```bash
+# Update to latest version
+git pull
+docker-compose down
+docker-compose build --no-cache
+docker-compose up -d
+
+# Backup data before updates
+docker run --rm -v acp-data:/data -v $(pwd):/backup \
+  alpine tar czf /backup/acp-data-backup.tar.gz /data
+```
+
+## Support
+
+For issues and questions:
+- GitHub Issues: https://github.com/imran-siddique/agent-control-plane/issues
+- Documentation: https://github.com/imran-siddique/agent-control-plane/tree/main/docs

modules/control-plane/docs/ECOSYSTEM_STATUS.md

@@ -0,0 +1,98 @@
+# Ecosystem Status
+
+> **Last Updated:** January 23, 2026
+
+This page tracks the status of all utility packages in the Agent Control Plane ecosystem.
+
+## Core Framework
+
+| Package | PyPI | Status | Description |
+|---------|------|--------|-------------|
+| [agent-control-plane](https://pypi.org/project/agent-control-plane/) | ![PyPI](https://img.shields.io/pypi/v/agent-control-plane?color=blue) | ![Status](https://img.shields.io/badge/status-passing-brightgreen) | Layer 3: The Framework - Governance layer for autonomous AI agents |
+
+## Layer 2: Protocol Utilities
+
+These are the foundational utility packages that integrate with the Agent Control Plane.
+
+| Package | PyPI | Status | Description |
+|---------|------|--------|-------------|
+| [caas-core](https://pypi.org/project/caas-core/) | ![PyPI](https://img.shields.io/pypi/v/caas-core?color=blue) | ![Status](https://img.shields.io/badge/status-passing-brightgreen) | Context-as-a-Service - Context routing and management |
+| [cmvk](https://pypi.org/project/cmvk/) | ![PyPI](https://img.shields.io/pypi/v/cmvk?color=blue) | ![Status](https://img.shields.io/badge/status-passing-brightgreen) | Cryptographic Message Verification Kit - Message verification and signing |
+| [iatp](https://pypi.org/project/inter-agent-trust-protocol/) | ![PyPI](https://img.shields.io/pypi/v/inter-agent-trust-protocol?color=blue) | ![Status](https://img.shields.io/badge/status-passing-brightgreen) | Inter-Agent Transport Protocol - Secure message transport |
+| [amb](https://pypi.org/project/amb-core/) | ![PyPI](https://img.shields.io/pypi/v/amb-core?color=blue) | ![Status](https://img.shields.io/badge/status-passing-brightgreen) | Agent Message Bus - Pub/sub messaging for agents |
+| [emk](https://pypi.org/project/emk/) | ![PyPI](https://img.shields.io/pypi/v/emk?color=blue) | ![Status](https://img.shields.io/badge/status-passing-brightgreen) | Event Messaging Kit - Event-driven communication primitives |
+| [atr](https://pypi.org/project/agent-tool-registry/) | ![PyPI](https://img.shields.io/pypi/v/agent-tool-registry?color=blue) | ![Status](https://img.shields.io/badge/status-passing-brightgreen) | Agent Tool Registry - Task distribution and routing |
+
+## Installation
+
+All packages are available via pip:
+
+```bash
+# Core framework
+pip install agent-control-plane
+
+# Individual utilities
+pip install caas-core
+pip install cmvk
+pip install inter-agent-trust-protocol
+pip install amb-core
+pip install emk
+pip install agent-tool-registry
+```
+
+## Package Relationships
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                  Layer 3: The Framework                      │
+│                   agent-control-plane                        │
+│         (Governance, Policy, Orchestration)                  │
+└─────────────────────────┬───────────────────────────────────┘
+                          │
+          ┌───────────────┼───────────────┐
+          │               │               │
+          ▼               ▼               ▼
+┌─────────────────────────────────────────────────────────────┐
+│                  Layer 2: Protocols                          │
+│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐           │
+│  │  iatp   │ │  cmvk   │ │  caas   │ │   amb   │           │
+│  │Transport│ │ Verify  │ │ Context │ │ Message │           │
+│  └─────────┘ └─────────┘ └─────────┘ └─────────┘           │
+│  ┌─────────┐ ┌─────────┐                                    │
+│  │   emk   │ │   atr   │                                    │
+│  │ Events  │ │ Routing │                                    │
+│  └─────────┘ └─────────┘                                    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Version Compatibility
+
+| Utility Package | Compatible with agent-control-plane |
+|-----------------|-------------------------------------|
+| caas-core       | >= 1.2.0                            |
+| cmvk            | >= 1.2.0                            |
+| iatp            | >= 1.2.0                            |
+| amb             | >= 1.2.0                            |
+| emk             | >= 1.2.0                            |
+| atr             | >= 1.2.0                            |
+
+## Integration Points
+
+Each utility package integrates with Agent Control Plane through defined interfaces:
+
+| Package | Interface | Purpose |
+|---------|-----------|---------|
+| caas-core | `ContextRoutingInterface` | Context lifecycle and routing |
+| cmvk | `VerificationInterface` | Cryptographic verification |
+| iatp | `MessageSecurityInterface` | Secure message transport |
+| amb | `MessageBusInterface` | Publish/subscribe messaging |
+| emk | `EventInterface` | Event-driven patterns |
+| atr | `TaskRoutingInterface` | Task distribution |
+
+## Contributing
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines on contributing to any package in the ecosystem.
+
+## License
+
+All packages are released under the [MIT License](../LICENSE).

modules/control-plane/docs/HF_MODEL_CARD.md

@@ -0,0 +1,168 @@
+---
+license: MIT
+tags:
+  - ai-safety
+  - agents
+  - governance
+  - control-plane
+  - deterministic
+  - agentic-ai
+  - guardrails
+language:
+  - en
+library_name: agent-control-plane
+pipeline_tag: other
+---
+
+# Agent Control Plane (ACP)
+
+[![PyPI version](https://badge.fury.io/py/agent-control-plane.svg)](https://badge.fury.io/py/agent-control-plane)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+
+A **deterministic kernel** for zero-violation governance in agentic AI systems. ACP interposes between LLM intent and action execution, providing ABAC-based policy enforcement, constraint graphs, and shadow mode simulation.
+
+> "Vibes are not engineering. We don't ask a database to 'please not drop tables' — we enforce permissions via ACLs."
+
+## 🎯 Intended Use
+
+**Primary Use Cases:**
+- Enterprise AI agent governance and safety enforcement
+- Multi-agent orchestration with policy-based access control (ABAC)
+- Research into deterministic AI safety mechanisms
+- Drop-in middleware for OpenAI, LangChain, and MCP-based agents
+- Red team testing and safety benchmarking
+
+**Out-of-Scope Uses:**
+- ⚠️ Direct use as an LLM or chat model (this is a governance layer, not a model)
+- ⚠️ Content moderation (this is action-level, not content-level governance)
+- ⚠️ Replacing human oversight in safety-critical systems
+- ⚠️ Guaranteed protection against all possible adversarial attacks
+
+## ⚠️ Limitations
+
+| Limitation | Details |
+|------------|---------|
+| **Policy Configuration Required** | ACP requires explicit policy configuration for each deployment. Default policies provide baseline protection but should be customized. |
+| **Not a Silver Bullet** | Does not prevent all possible adversarial attacks. Defense-in-depth is required. |
+| **Shadow Mode ≠ Production** | Shadow mode simulation does not guarantee real-world behavior. Always test in staging. |
+| **Performance Overhead** | Latency scales with policy complexity. Complex constraint graphs add ~5-10ms overhead. |
+| **No Content Analysis** | Governs actions, not content. Use complementary content moderation for text safety. |
+
+## 📊 Evaluation Results
+
+Results from the 60-prompt red team benchmark (`imran-siddique/agent-control-redteam-60`):
+
+| Metric | Value | Notes |
+|--------|-------|-------|
+| **Safety Violation Rate** | 0.00% | All 60 adversarial prompts blocked |
+| **False Positive Rate** | 0.00% | All legitimate actions permitted |
+| **Token Reduction** | 98.1% | "Scale by Subtraction" vs verbose refusals |
+| **Avg Latency Overhead** | <5ms | Per policy check (simple rules) |
+| **P99 Latency** | <15ms | Per policy check (complex constraints) |
+
+### Statistical Validation
+
+| Ablation | Violation Rate | p-value | Cohen's d |
+|----------|---------------|---------|-----------|
+| Full ACP | 0.00% | - | - |
+| Without PolicyEngine | 40.00% | <0.0001 | 8.7 |
+| Without ConstraintGraphs | 15.00% | <0.001 | 4.2 |
+| Without MuteAgent | 0.00% (token leak) | - | - |
+
+## 🚀 Installation
+
+```bash
+pip install agent-control-plane
+```
+
+For Hugging Face Hub integration:
+```bash
+pip install agent-control-plane[hf]
+# or
+pip install agent-control-plane huggingface_hub datasets
+```
+
+## 📖 Quick Start
+
+```python
+from agent_control_plane import AgentControlPlane, create_governed_client
+
+# Wrap any OpenAI-compatible client
+governed_client = create_governed_client(
+    openai_client,
+    permission_level="read_only"  # NONE, READ_ONLY, READ_WRITE, ADMIN
+)
+
+# All tool calls are now governed
+response = governed_client.chat.completions.create(
+    model="gpt-4",
+    messages=[{"role": "user", "content": "Read the Q3 sales report"}],
+    tools=[{
+        "type": "function",
+        "function": {"name": "read_file", "parameters": {...}}
+    }]
+)
+```
+
+### With LangChain
+
+```python
+from agent_control_plane import create_governed_langchain_client
+
+agent = create_governed_langchain_client(
+    langchain_agent,
+    permission_level="read_write"
+)
+```
+
+### Shadow Mode (Simulation)
+
+```python
+control_plane = AgentControlPlane(
+    enable_shadow_mode=True,
+    enable_constraint_graphs=True
+)
+
+# Simulate without executing
+result = control_plane.shadow_execute(
+    agent_id="analyst",
+    tool_name="database_query",
+    tool_args={"query": "SELECT * FROM sensitive_data"}
+)
+print(f"Would be blocked: {result.would_block}")
+```
+
+## 📚 Resources
+
+- **Paper**: [Agent Control Plane: A Deterministic Kernel for Zero-Violation Governance in Agentic AI](https://arxiv.org/abs/...)
+- **Documentation**: [GitHub Docs](https://github.com/imran-siddique/agent-control-plane/tree/main/docs)
+- **Red Team Dataset**: [imran-siddique/agent-control-redteam-60](https://huggingface.co/datasets/imran-siddique/agent-control-redteam-60)
+- **Reproducibility**: See `reproducibility/` folder for exact commands and configs
+
+## 📜 Citation
+
+If you use this work in your research, please cite:
+
+```bibtex
+@article{siddique2026acp,
+  title={Agent Control Plane: A Deterministic Kernel for Zero-Violation Governance in Agentic AI},
+  author={Siddique, Imran},
+  journal={arXiv preprint arXiv:XXXX.XXXXX},
+  year={2026}
+}
+```
+
+## 👤 Author
+
+**Imran Siddique**  
+Principal Group Engineering Manager, Microsoft  
+[imran.siddique@microsoft.com](mailto:imran.siddique@microsoft.com)
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/imran-siddique/agent-control-plane/blob/main/LICENSE) file for details.
+
+---
+
+*"The LLM is the CPU. The Control Plane is the Operating System."*