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

modules/control-plane/CONTRIBUTING.md

@@ -0,0 +1,311 @@
+# Contributing to Agent Control Plane
+
+Thank you for your interest in contributing to the Agent Control Plane! This document provides guidelines and instructions for contributing to this project.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [Project Structure](#project-structure)
+- [Making Changes](#making-changes)
+- [Testing](#testing)
+- [Code Style](#code-style)
+- [Submitting Changes](#submitting-changes)
+
+## Code of Conduct
+
+This project is committed to providing a welcoming and inclusive environment. Please be respectful and considerate in all interactions.
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork: `git clone https://github.com/YOUR-USERNAME/agent-control-plane.git`
+3. Create a new branch: `git checkout -b feature/your-feature-name`
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.8 or higher
+- pip
+
+### Installation
+
+1. Install the package in development mode:
+```bash
+pip install -e .
+```
+
+2. Install development dependencies:
+```bash
+pip install -e ".[dev]"
+```
+
+## Project Structure
+
+```
+agent-control-plane/
+├── src/
+│   └── agent_control_plane/     # Main package source code
+│       ├── __init__.py
+│       ├── agent_kernel.py
+│       ├── control_plane.py
+│       ├── policy_engine.py
+│       ├── execution_engine.py
+│       ├── constraint_graphs.py
+│       ├── shadow_mode.py
+│       ├── mute_agent.py
+│       ├── supervisor_agents.py
+│       └── example_executors.py
+├── tests/                        # Test files
+│   ├── test_control_plane.py
+│   └── test_advanced_features.py
+├── examples/                     # Example scripts
+│   ├── basic_usage.py
+│   ├── advanced_features.py
+│   └── configuration.py
+├── docs/                         # Documentation
+│   ├── guides/
+│   ├── api/
+│   └── architecture/
+├── setup.py                      # Package setup
+├── pyproject.toml               # Project configuration
+└── README.md                    # Main documentation
+```
+
+## Making Changes
+
+### Guidelines
+
+1. **Keep changes focused**: One feature or bug fix per pull request
+2. **Write clear commit messages**: Use descriptive commit messages that explain what and why
+3. **Add tests**: All new features should include tests
+4. **Update documentation**: Update relevant documentation for new features or changes
+5. **Follow existing patterns**: Maintain consistency with existing code
+
+### Code Organization
+
+- **Core modules**: Place core functionality in `src/agent_control_plane/`
+- **Tests**: Place tests in `tests/` directory
+- **Examples**: Place examples in `examples/` directory
+- **Documentation**: Place documentation in `docs/` directory
+
+## Testing
+
+### Running Tests
+
+Run all tests:
+```bash
+python -m pytest tests/
+```
+
+Run tests with coverage:
+```bash
+python -m pytest --cov=agent_control_plane tests/
+```
+
+Run specific test file:
+```bash
+python -m pytest tests/test_control_plane.py
+```
+
+Run specific test:
+```bash
+python -m pytest tests/test_control_plane.py::TestAgentKernel::test_create_agent_session
+```
+
+### Writing Tests
+
+- Use unittest framework (consistent with existing tests)
+- Place tests in the `tests/` directory
+- Name test files with `test_` prefix
+- Write descriptive test names that explain what is being tested
+- Include both positive and negative test cases
+- Test edge cases and error conditions
+
+Example:
+```python
+import unittest
+from agent_control_plane import AgentControlPlane, create_standard_agent
+
+class TestMyFeature(unittest.TestCase):
+    def setUp(self):
+        self.control_plane = AgentControlPlane()
+    
+    def test_feature_success_case(self):
+        """Test that feature works in normal conditions"""
+        # Test implementation
+        pass
+    
+    def test_feature_error_case(self):
+        """Test that feature handles errors properly"""
+        # Test implementation
+        pass
+```
+
+## Code Style
+
+### Python Style Guidelines
+
+- Follow PEP 8 style guide
+- Use 4 spaces for indentation (no tabs)
+- Maximum line length: 100 characters
+- Use descriptive variable names
+- Add docstrings to all public classes and functions
+- Add type hints where appropriate
+
+### Formatting
+
+Use Black for code formatting:
+```bash
+black src/ tests/ examples/
+```
+
+### Linting
+
+Use flake8 for linting:
+```bash
+flake8 src/ tests/ examples/
+```
+
+### Type Checking
+
+Use mypy for type checking:
+```bash
+mypy src/
+```
+
+## Submitting Changes
+
+### Pull Request Process
+
+1. **Update your branch**: Ensure your branch is up to date with the main branch
+   ```bash
+   git checkout main
+   git pull upstream main
+   git checkout your-feature-branch
+   git rebase main
+   ```
+
+2. **Run tests**: Ensure all tests pass
+   ```bash
+   python -m pytest tests/
+   ```
+
+3. **Update documentation**: Update relevant documentation
+
+4. **Commit your changes**: Use clear, descriptive commit messages
+   ```bash
+   git add .
+   git commit -m "Add feature: description of your feature"
+   ```
+
+5. **Push to your fork**:
+   ```bash
+   git push origin your-feature-branch
+   ```
+
+6. **Create a Pull Request**: 
+   - Go to the original repository on GitHub
+   - Click "New Pull Request"
+   - Select your branch
+   - Provide a clear description of your changes
+   - Reference any related issues
+
+### Pull Request Guidelines
+
+- **Title**: Use a clear, descriptive title
+- **Description**: Explain what changes you made and why
+- **Tests**: Ensure all tests pass
+- **Documentation**: Include documentation updates if needed
+- **Review**: Be responsive to feedback and questions
+
+### Commit Message Format
+
+```
+<type>: <subject>
+
+<body>
+
+<footer>
+```
+
+Types:
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `test`: Adding or updating tests
+- `refactor`: Code refactoring
+- `style`: Code style changes (formatting, etc.)
+- `chore`: Maintenance tasks
+
+Example:
+```
+feat: add shadow mode simulation capability
+
+Implement shadow mode that allows agents to simulate execution
+without actually performing actions. This enables safe testing
+of agent behavior before production deployment.
+
+Closes #123
+```
+
+## Questions?
+
+If you have questions or need help, please:
+- Check [GitHub Discussions](https://github.com/imran-siddique/agent-control-plane/discussions)
+- Open an issue on GitHub
+- Check existing documentation in the `docs/` directory
+- Review [SUPPORT.md](SUPPORT.md) for detailed support options
+- Look at existing code and tests for examples
+
+## Release Process
+
+### For Maintainers
+
+The release process is mostly automated through GitHub Actions. Here's how to create a new release:
+
+1. **Update Version Numbers**
+   - Update version in `pyproject.toml` (line 7)
+   - Update version in `setup.py` (line 16)
+   - Follow [Semantic Versioning](https://semver.org/): MAJOR.MINOR.PATCH
+
+2. **Update CHANGELOG.md**
+   - Add a new section at the top with the version and date
+   - List all changes under appropriate categories (Added, Changed, Fixed, etc.)
+   - Follow [Keep a Changelog](https://keepachangelog.com/) format
+
+3. **Run Pre-release Checks**
+   ```bash
+   # Run full test suite
+   python -m pytest tests/ -v
+   
+   # Run linting
+   flake8 src/ --count --select=E9,F63,F7,F82 --show-source
+   
+   # Test package build
+   python -m build
+   twine check dist/*
+   ```
+
+4. **Create and Push Git Tag**
+   ```bash
+   git tag -a v1.2.0 -m "Release version 1.2.0"
+   git push origin v1.2.0
+   ```
+
+5. **Automated Workflows**
+   - GitHub Actions automatically creates a GitHub Release from the tag
+   - Release notes are extracted from CHANGELOG.md
+   - Package is automatically published to PyPI
+
+6. **Post-Release Tasks**
+   - Verify release appears on GitHub: https://github.com/imran-siddique/agent-control-plane/releases
+   - Verify package on PyPI: https://pypi.org/project/agent-control-plane/
+   - Test installation: `pip install agent-control-plane==X.Y.Z`
+   - Announce in GitHub Discussions
+
+For detailed PyPI publishing instructions, see [docs/PYPI_PUBLISHING.md](docs/PYPI_PUBLISHING.md).
+
+Thank you for contributing to Agent Control Plane!

modules/control-plane/CONTRIBUTORS.md

@@ -0,0 +1,88 @@
+# Contributors
+
+Thank you to everyone who has contributed to Agent Control Plane! 🎉
+
+This project exists thanks to all the people who contribute.
+
+## Core Team
+
+- **[imran-siddique](https://github.com/imran-siddique)** - Creator and Lead Maintainer
+
+## Contributors
+
+We welcome and recognize all contributors! Below is a list of people who have contributed to this project.
+
+<!-- 
+To add yourself to this list:
+1. Make a contribution to the project
+2. Add your name below in alphabetical order
+3. Include a brief description of your contribution
+-->
+
+### Code Contributors
+
+<!-- Add contributors here -->
+
+### Documentation Contributors
+
+<!-- Add documentation contributors here -->
+
+### Community Contributors
+
+<!-- Add community contributors here: bug reports, feature suggestions, discussions, etc. -->
+
+## How to Contribute
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute to this project.
+
+### Ways to Contribute
+
+- 🐛 **Fix bugs** - Help squash those pesky bugs
+- ✨ **Add features** - Implement new capabilities
+- 📝 **Improve documentation** - Make the docs clearer
+- 🧪 **Write tests** - Improve test coverage
+- 💡 **Share ideas** - Suggest improvements in Discussions
+- 🔍 **Review PRs** - Help review pull requests
+- ⭐ **Star the repo** - Show your support
+- 📢 **Spread the word** - Tell others about the project
+
+## Recognition
+
+All contributors will be recognized in this file and in release notes. We use the [All Contributors](https://allcontributors.org/) specification.
+
+### Contribution Types
+
+We recognize various types of contributions:
+
+- 💻 **Code** - Writing code
+- 📖 **Documentation** - Writing documentation
+- 🎨 **Design** - UI/UX design
+- 🤔 **Ideas** - Feature proposals and suggestions
+- 🐛 **Bug Reports** - Finding and reporting bugs
+- 🚇 **Infrastructure** - CI/CD, build tools, etc.
+- 🚧 **Maintenance** - Repository maintenance
+- 👀 **Review** - Reviewing pull requests
+- 💬 **Q&A** - Answering questions in Discussions
+- 📢 **Talks** - Presenting about the project
+- 📹 **Videos** - Creating video tutorials
+- ✅ **Tests** - Writing tests
+- 🌍 **Translation** - Translating documentation
+- ⚠️ **Security** - Identifying security issues
+
+## Acknowledgments
+
+Special thanks to:
+
+- The open-source community for inspiration and best practices
+- All users who provide feedback and bug reports
+- Everyone who stars, forks, or shares this project
+
+## Join Us!
+
+Want to see your name here? Check out our [Contributing Guide](CONTRIBUTING.md) and [good first issues](https://github.com/imran-siddique/agent-control-plane/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) to get started.
+
+---
+
+*This file is maintained manually. If you've contributed and don't see your name, please open a PR to add yourself!*
+
+*Last updated: January 18, 2026*

modules/control-plane/Dockerfile

@@ -0,0 +1,82 @@
+# Agent Control Plane Docker Image
+# 
+# Multi-stage build for production deployment
+# Based on Python 3.11 slim image
+
+FROM python:3.11-slim as base
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    gcc \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy package files
+COPY pyproject.toml setup.py MANIFEST.in ./
+COPY src/ ./src/
+COPY README.md LICENSE ./
+
+# Install the package
+RUN pip install --no-cache-dir -e .
+
+# Create non-root user
+RUN useradd -m -u 1000 acp && chown -R acp:acp /app
+USER acp
+
+# Copy examples and docs (optional for runtime)
+COPY examples/ ./examples/
+COPY docs/ ./docs/
+
+# Expose port for potential API server
+EXPOSE 8000
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1
+ENV ACP_DATA_DIR=/app/data
+
+# Create data directory
+RUN mkdir -p /app/data
+
+# Default command (can be overridden)
+CMD ["python", "-m", "agent_control_plane"]
+
+# -------------------
+# Development Stage
+# -------------------
+FROM base as development
+
+# Switch back to root for dev tools installation
+USER root
+
+# Install development dependencies
+RUN pip install --no-cache-dir \
+    pytest>=7.0.0 \
+    pytest-cov>=4.0.0 \
+    black>=23.0.0 \
+    flake8>=6.0.0 \
+    mypy>=1.0.0 \
+    ipython \
+    jupyter
+
+# Switch back to acp user
+USER acp
+
+# Development command
+CMD ["bash"]
+
+# -------------------
+# Production Stage
+# -------------------
+FROM base as production
+
+# Production optimizations
+ENV PYTHONOPTIMIZE=1
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD python -c "import agent_control_plane; print('healthy')" || exit 1
+
+# Production command
+CMD ["python", "-m", "agent_control_plane"]

modules/control-plane/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Agent Control Plane Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

modules/control-plane/MANIFEST.in

@@ -0,0 +1,17 @@
+# Include documentation
+include README.md
+include LICENSE
+recursive-include docs *.md *.rst *.txt
+
+# Include examples
+recursive-include examples *.py
+
+# Include tests
+recursive-include tests *.py
+
+# Exclude compiled files
+global-exclude __pycache__
+global-exclude *.py[co]
+global-exclude .DS_Store
+global-exclude *.swp
+global-exclude *.swo