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

modules/control-plane/.github/discussions.yml

@@ -0,0 +1,73 @@
+# GitHub Discussions Configuration
+
+# This file serves as documentation for GitHub Discussions setup
+# GitHub Discussions must be enabled in repository settings
+
+## Categories
+
+The following discussion categories should be configured:
+
+### 📣 Announcements
+- **Purpose:** Official project announcements, releases, and updates
+- **Type:** Announcement (maintainers only can create)
+
+### 💡 Ideas
+- **Purpose:** Feature requests and enhancement proposals
+- **Type:** Open discussion
+
+### 🙏 Q&A
+- **Purpose:** Questions about usage, troubleshooting, and how-tos
+- **Type:** Q&A (can mark answers)
+
+### 🎉 Show and Tell
+- **Purpose:** Share projects built with Agent Control Plane
+- **Type:** Open discussion
+
+### 🛠️ Development
+- **Purpose:** Technical discussions about contributions and architecture
+- **Type:** Open discussion
+
+### 📚 Documentation
+- **Purpose:** Discussions about improving docs and tutorials
+- **Type:** Open discussion
+
+### 🔐 Security
+- **Purpose:** General security discussions (not for vulnerability reports)
+- **Type:** Open discussion
+- **Note:** For vulnerability reports, use Security Advisory or private issue template
+
+## Setup Instructions
+
+To enable GitHub Discussions:
+
+1. Go to repository Settings
+2. Scroll to "Features" section
+3. Check "Discussions"
+4. Configure categories as outlined above
+5. Pin important discussions (welcome, guidelines, roadmap)
+
+## Pinned Discussions
+
+Create and pin these discussions:
+
+1. **Welcome to Agent Control Plane Discussions** 
+   - Introduction and guidelines
+   - Links to documentation
+   - Community expectations
+
+2. **Roadmap & Planning**
+   - Link to ROADMAP.md
+   - Invite feedback on priorities
+   - Quarterly updates
+
+3. **Showcase Your Projects**
+   - Template for project showcases
+   - Encourage community sharing
+   - Highlight exceptional projects
+
+## Moderation
+
+- Maintainers moderate all categories
+- Community members can help in Q&A
+- Follow Code of Conduct (see CONTRIBUTING.md)
+- Report issues to maintainers via private message or email

modules/control-plane/.github/pull_request_template.md

@@ -0,0 +1,82 @@
+## Description
+
+<!-- Provide a clear and concise description of your changes -->
+
+## Type of Change
+
+<!-- Check all that apply -->
+
+- [ ] 🐛 Bug fix (non-breaking change which fixes an issue)
+- [ ] ✨ New feature (non-breaking change which adds functionality)
+- [ ] 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] 📝 Documentation update
+- [ ] ♻️ Code refactoring (no functional changes)
+- [ ] ⚡ Performance improvement
+- [ ] ✅ Test addition or update
+- [ ] 🔧 Configuration change
+- [ ] 🔒 Security improvement
+
+## Related Issues
+
+<!-- Link to related issues, e.g., "Fixes #123" or "Addresses #456" -->
+
+Fixes #
+
+## Changes Made
+
+<!-- List the main changes made in this PR -->
+
+- 
+- 
+- 
+
+## Testing
+
+<!-- Describe the tests you ran to verify your changes -->
+
+- [ ] Existing tests pass (`pytest`)
+- [ ] Added new tests for new functionality
+- [ ] Manually tested the changes
+- [ ] Tested with multiple Python versions (if applicable)
+
+### Test Details
+
+<!-- Provide details about your testing -->
+
+```
+# Example test output or commands used
+```
+
+## Checklist
+
+<!-- Check all that apply before submitting -->
+
+- [ ] My code follows the project's code style (black, flake8)
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have updated the documentation accordingly
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] New and existing unit tests pass locally with my changes
+- [ ] I have updated the CHANGELOG.md with my changes
+- [ ] I have checked my code for security vulnerabilities
+- [ ] My changes generate no new warnings
+- [ ] I have reviewed my own code before submitting
+
+## Screenshots (if applicable)
+
+<!-- Add screenshots to help explain your changes -->
+
+## Additional Context
+
+<!-- Add any other context about the PR here -->
+
+## Breaking Changes
+
+<!-- If this is a breaking change, describe what users need to do to migrate -->
+
+## Performance Impact
+
+<!-- Describe any performance implications of your changes -->
+
+## Security Considerations
+
+<!-- Describe any security implications or considerations -->

modules/control-plane/.github/workflows/publish.yml

@@ -0,0 +1,146 @@
+# Agent Control Plane - PyPI Publishing Workflow
+# 
+# This workflow uses PyPI Trusted Publishing (OIDC) for secure, tokenless authentication.
+# See: https://docs.pypi.org/trusted-publishers/
+#
+# Setup Required:
+# 1. Go to PyPI.org → Your Project → Settings → Publishing → Add Trusted Publisher
+# 2. Enter: GitHub owner, repo name, workflow filename, and environment name
+#
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: 'Target repository'
+        required: true
+        type: choice
+        options:
+          - testpypi
+          - pypi
+        default: testpypi
+
+# Ensure only one publish job runs at a time
+concurrency:
+  group: publish-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build Distribution 📦
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+    
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+    
+    - name: Extract version
+      id: version
+      run: |
+        VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+        echo "version=$VERSION" >> $GITHUB_OUTPUT
+        echo "📦 Building version: $VERSION"
+    
+    - name: Build package
+      run: python -m build
+    
+    - name: Check package
+      run: |
+        twine check dist/*
+        echo "📋 Built packages:"
+        ls -la dist/
+    
+    - name: Upload artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+        retention-days: 5
+
+  publish-testpypi:
+    name: Publish to TestPyPI 🧪
+    needs: build
+    if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/agent-control-plane/${{ needs.build.outputs.version }}
+    
+    permissions:
+      id-token: write  # Required for OIDC trusted publishing
+    
+    steps:
+    - name: Download artifact
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+    
+    - name: Publish to TestPyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        repository-url: https://test.pypi.org/legacy/
+        print-hash: true
+        verbose: true
+
+  publish-pypi:
+    name: Publish to PyPI 🚀
+    needs: build
+    if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && inputs.target == 'pypi')
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/agent-control-plane/${{ needs.build.outputs.version }}
+    
+    permissions:
+      id-token: write  # Required for OIDC trusted publishing
+    
+    steps:
+    - name: Download artifact
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+    
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        print-hash: true
+        verbose: true
+
+  github-release-assets:
+    name: Upload to GitHub Release 📎
+    needs: [build, publish-pypi]
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    
+    permissions:
+      contents: write
+    
+    steps:
+    - name: Download artifact
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+    
+    - name: Upload to GitHub Release
+      uses: softprops/action-gh-release@v1
+      with:
+        files: dist/*

modules/control-plane/.github/workflows/release.yml

@@ -0,0 +1,39 @@
+name: Create Release
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+jobs:
+  create-release:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        fetch-depth: 0
+    
+    - name: Extract version from tag
+      id: get_version
+      run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
+    
+    - name: Extract changelog for version
+      id: changelog
+      run: |
+        VERSION=${{ steps.get_version.outputs.VERSION }}
+        # Extract the changelog section for this version
+        CHANGELOG=$(sed -n "/## \[$VERSION\]/,/## \[/p" CHANGELOG.md | sed '$d' | tail -n +2)
+        # Save to file to preserve newlines
+        echo "$CHANGELOG" > /tmp/release_notes.md
+    
+    - name: Create Release
+      uses: actions/create-release@v1
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      with:
+        tag_name: ${{ github.ref }}
+        release_name: Release v${{ steps.get_version.outputs.VERSION }}
+        body_path: /tmp/release_notes.md
+        draft: false
+        prerelease: false

modules/control-plane/.github/workflows/tests.yml

@@ -0,0 +1,58 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
+
+    steps:
+    - uses: actions/checkout@v3
+    
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+    
+    - name: Install package
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .
+    
+    - name: Run tests
+      run: |
+        python -m unittest discover -s tests -p 'test_*.py' -v
+    
+    - name: Check examples run
+      run: |
+        python examples/basic_usage.py > /dev/null 2>&1 || echo "Basic usage example completed"
+
+  lint:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v3
+    
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.12'
+    
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install flake8
+    
+    - name: Lint with flake8
+      run: |
+        # Stop the build if there are Python syntax errors or undefined names
+        flake8 src/ --count --select=E9,F63,F7,F82 --show-source --statistics
+        # Exit-zero treats all errors as warnings
+        flake8 src/ --count --exit-zero --max-complexity=10 --max-line-length=100 --statistics

modules/control-plane/.gitignore

@@ -0,0 +1,55 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Logs
+*.log
+
+# Benchmark results (generated)
+benchmark_results.csv
+benchmark_summary.csv
+
+# Flight Recorder database
+flight_recorder.db
+*.db
+.pypirc

modules/control-plane/CHANGELOG.md

@@ -0,0 +1,203 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.2.0] - 2026-01-23
+
+### Added
+
+#### Layer 3: The Framework - Dependency Injection Architecture
+- **KernelInterface**: Abstract interface for custom kernel implementations
+  - `KernelInterface` - Base interface for all kernels (SCAK can now implement this)
+  - `SelfCorrectingKernelInterface` - Extended interface for self-correcting kernels
+  - `CapabilityRestrictedKernelInterface` - For Mute Agent pattern implementations
+  - `KernelCapability` enum for declaring kernel capabilities
+  - `KernelMetadata` dataclass for kernel information
+
+- **Plugin Interfaces**: Extensible component architecture
+  - `ValidatorInterface` - For custom request validators
+  - `CapabilityValidatorInterface` - For capability-based validation (Mute Agent pattern)
+  - `ExecutorInterface` - For custom action executors
+  - `ContextRouterInterface` - For context routing plugins
+  - `PolicyProviderInterface` - For custom policy sources
+  - `SupervisorInterface` - For supervisor agent plugins
+  - `PluginCapability` and `PluginMetadata` for plugin information
+
+- **Protocol Interfaces**: Integration points for Layer 2 protocols
+  - `MessageSecurityInterface` - For iatp (Inter-Agent Transport Protocol) integration
+  - `VerificationInterface` - For cmvk (Cryptographic Message Verification Kit) integration
+  - `ContextRoutingInterface` - For caas (Context-as-a-Service) integration
+
+- **PluginRegistry**: Central dependency injection system
+  - Singleton pattern for global plugin management
+  - Runtime registration of kernels, validators, executors, routers
+  - Forbidden dependency enforcement (scak, mute-agent cannot be hard-imported)
+  - Plugin discovery and loading from paths
+  - Health check and lifecycle management
+
+### Changed
+
+- **AgentControlPlane**: Now supports dependency injection
+  - New `use_plugin_registry` parameter for plugin-based architecture
+  - New `kernel` parameter for injecting custom KernelInterface implementations
+  - New `validators` parameter for injecting ValidatorInterface implementations
+  - New `context_router` parameter for caas integration
+  - New `message_security` parameter for iatp integration
+  - New `verifier` parameter for cmvk integration
+  - New methods: `register_validator()`, `register_kernel()`, `register_context_router()`, etc.
+
+- **MuteAgentValidator**: Refactored to implement CapabilityValidatorInterface
+  - Now implements `CapabilityValidatorInterface` for plugin compatibility
+  - Returns `ValidationResult` instead of tuple for new interface
+  - Backward compatible with legacy usage
+  - Added deprecation notice for direct imports
+
+### Documentation
+
+- Added `docs/LAYER3_FRAMEWORK.md` - Comprehensive architecture guide for Layer 3
+
+### Dependency Policy
+
+- **Allowed Dependencies**: iatp, cmvk, caas (optional protocol integrations)
+- **Forbidden Dependencies**: scak, mute-agent (must implement interfaces instead)
+
+## [1.1.0] - 2026-01-18
+
+### Added
+
+#### ML-Based Safety & Anomaly Detection
+- **JailbreakDetector**: Pattern-based and embedding-based jailbreak detection with 60+ attack vectors
+  - Supports ignore instructions, roleplay, system override, hypothetical scenarios, and encoding tricks
+  - Behavioral analysis with context-aware threat scoring
+  - Ensemble detection combining patterns, embeddings, and behavioral signals
+- **AnomalyDetector**: Behavioral anomaly detection for agent actions
+  - Baseline establishment through historical behavior
+  - Novel action type detection
+  - Statistical anomaly scoring
+
+#### Compliance & Regulatory Frameworks
+- **ComplianceEngine**: Multi-framework compliance checking
+  - EU AI Act support with risk category assessment (unacceptable, high-risk, limited-risk, minimal-risk)
+  - SOC 2 Trust Service Criteria validation
+  - GDPR, HIPAA, PCI-DSS, ISO 27001 framework templates
+  - Automated control validation and audit trail generation
+  - Compliance reporting and dashboard
+- **ConstitutionalAI**: Value alignment framework
+  - Inspired by Anthropic's Constitutional AI research
+  - Default principles: harmlessness, honesty, privacy, transparency, fairness
+  - Self-critique capability for pre-response validation
+  - Custom constitutional rule support
+  - Automatic compliance scoring and violation detection
+
+#### Multimodal Capabilities
+- **VisionCapability**: Image analysis with governance
+  - Support for JPEG, PNG, GIF, WebP formats
+  - Safety checking and content moderation hooks
+  - Integration-ready for GPT-4V, Claude Vision, etc.
+- **AudioCapability**: Audio processing
+  - Transcription support (MP3, WAV, OGG, FLAC)
+  - Safety checking for audio content
+  - Duration and file size limits
+- **VectorStoreIntegration**: RAG support with multiple backends
+  - In-memory, Pinecone, Weaviate, ChromaDB, Qdrant, Milvus support
+  - Document storage with embeddings
+  - Semantic search with metadata filtering
+  - Hybrid search capabilities
+- **RAGPipeline**: Complete Retrieval-Augmented Generation pipeline
+  - Document retrieval and context assembly
+  - Citation tracking
+  - RAG-optimized prompt engineering
+
+#### Production Observability
+- **PrometheusExporter**: Metrics export for Prometheus scraping
+  - Counter, gauge, histogram, and summary metrics
+  - Multi-dimensional labels
+  - Prometheus text format export
+- **AlertManager**: Rule-based alerting system
+  - Configurable alert rules with severity levels
+  - Alert aggregation and deduplication
+  - Alert history and resolution tracking
+- **TraceCollector**: Distributed tracing
+  - OpenTelemetry-compatible span collection
+  - Parent-child span relationships
+  - Trace visualization data generation
+  - Performance analysis capabilities
+- **ObservabilityDashboard**: Unified observability interface
+  - Real-time metrics aggregation
+  - Active alert monitoring
+  - Trace visualization
+  - System health status reporting
+
+### Enhanced
+- Extended `__init__.py` exports to include all new modules
+- Updated README with v1.1 feature highlights
+- Comprehensive test coverage: 196 tests (68 new tests added)
+
+### Documentation
+- New comprehensive guide: `docs/ADVANCED_FEATURES.md`
+- Example scripts for all new features:
+  - `examples/ml_safety_demo.py`: Jailbreak and anomaly detection examples
+  - `examples/compliance_demo.py`: Compliance and Constitutional AI examples
+  - `examples/multimodal_demo.py`: Vision, audio, and RAG examples
+  - `examples/observability_demo.py`: Metrics, alerting, and tracing examples
+
+### Research Foundations
+All new features are grounded in peer-reviewed research:
+- Universal and Transferable Adversarial Attacks (arXiv:2307.15043)
+- Red-Teaming Large Language Models (arXiv:2308.10263)
+- Multimodal Agents: A Survey (arXiv:2404.12390)
+- Constitutional AI from Anthropic research
+- EU AI Act (2024) regulatory framework
+- Prometheus and OpenTelemetry observability standards
+
+## [0.1.0] - 2025-01-11
+
+### Added
+- Initial release of Agent Control Plane
+- Core agent kernel functionality
+- Policy engine with rate limiting and quotas
+- Execution engine with sandboxing
+- Advanced features:
+  - Mute Agent (capability-based execution)
+  - Shadow Mode (simulation without execution)
+  - Constraint Graphs (multi-dimensional context)
+  - Supervisor Agents (recursive governance)
+- Comprehensive test suite (31 tests)
+- Example scripts:
+  - Getting Started tutorial
+  - Basic usage examples
+  - Advanced features showcase
+  - Real-world use cases
+  - Configuration patterns
+- Documentation:
+  - Quick Start Guide
+  - Implementation Guide
+  - Philosophy document
+  - Architecture overview
+  - Contributing guidelines
+- Project structure:
+  - src/agent_control_plane/ package
+  - tests/ directory
+  - examples/ directory
+  - docs/ directory
+- CI/CD with GitHub Actions
+- Package configuration (setup.py, pyproject.toml)
+- MIT License
+
+### Changed
+- N/A (initial release)
+
+### Deprecated
+- N/A (initial release)
+
+### Removed
+- N/A (initial release)
+
+### Fixed
+- N/A (initial release)
+
+### Security
+- N/A (initial release)