aegislib 0.1.1__tar.gz

aegislib-0.1.1/CHANGELOG.md

@@ -0,0 +1,32 @@
+# 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).
+
+## [Unreleased]
+
+## [0.1.1] - 2025-11-06
+
+### Added
+- Initial release of Aegis Python SDK
+- Core `@aegis_guard` decorator for tool protection
+- `AegisConfig` for SDK configuration with environment variable support
+- `DecisionClient` for interacting with Aegis Data Plane
+- Full support for allow/deny/sanitize/approval_needed decisions
+- Async/await compatibility for async functions
+- Built-in retry logic and resilience features
+- Type hints and py.typed marker for type checking
+- Comprehensive error handling with custom exception hierarchy
+- Debug logging and console output utilities
+- Complete unit test suite with 100% code coverage
+- CI/CD workflows for automated testing and publishing
+- Production-ready packaging for PyPI distribution
+
+### Security
+- Secure API key handling with Pydantic SecretStr
+- Safe model dumping with masked sensitive fields
+
+[Unreleased]: https://github.com/mrsidrdx/aegis-python-sdk/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/mrsidrdx/aegis-python-sdk/releases/tag/v0.1.1

aegislib-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,241 @@
+# Contributing to Aegis Python SDK
+
+Thank you for your interest in contributing to Aegis! This document provides guidelines and instructions for contributing.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [Running Tests](#running-tests)
+- [Code Style](#code-style)
+- [Making Changes](#making-changes)
+- [Submitting Changes](#submitting-changes)
+
+## Code of Conduct
+
+We expect all contributors to be respectful and professional. Please be kind and courteous in all interactions.
+
+## Getting Started
+
+1. Fork the repository on GitHub
+2. Clone your fork locally
+3. Create a new branch for your changes
+4. Make your changes
+5. Submit a pull request
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.11 or higher
+- pip or another package manager
+
+### Installation
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/mrsidrdx/aegis-python-sdk.git
+cd aegis-python-sdk
+```
+
+2. Create a virtual environment:
+
+```bash
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+```
+
+3. Install development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Running Tests
+
+### Run all tests
+
+```bash
+pytest
+```
+
+### Run tests with coverage
+
+```bash
+pytest --cov=aegis --cov-report=html --cov-report=term
+```
+
+### Run specific test file
+
+```bash
+pytest tests/test_config.py
+```
+
+### Run with verbose output
+
+```bash
+pytest -v
+```
+
+### View coverage report
+
+After running tests with coverage, open `htmlcov/index.html` in your browser.
+
+## Code Style
+
+We use the following tools to maintain code quality:
+
+- **Black**: Code formatting
+- **Ruff**: Linting and import sorting
+- **MyPy**: Type checking
+
+### Format code
+
+```bash
+black aegis/ tests/
+```
+
+### Run linter
+
+```bash
+ruff check aegis/ tests/
+```
+
+### Run type checker
+
+```bash
+mypy aegis/
+```
+
+### Run all checks
+
+```bash
+make lint
+```
+
+## Making Changes
+
+### Adding New Features
+
+1. Create a new branch from `main`:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. Write tests for your feature first (TDD approach)
+3. Implement your feature
+4. Ensure all tests pass
+5. Update documentation if necessary
+
+### Fixing Bugs
+
+1. Create a new branch from `main`:
+   ```bash
+   git checkout -b fix/bug-description
+   ```
+
+2. Write a test that reproduces the bug
+3. Fix the bug
+4. Ensure all tests pass
+
+### Code Coverage
+
+We maintain 100% test coverage. All new code must include tests.
+
+To check coverage:
+
+```bash
+pytest --cov=aegis --cov-report=term-missing
+```
+
+## Submitting Changes
+
+### Before Submitting
+
+1. Ensure all tests pass:
+   ```bash
+   pytest
+   ```
+
+2. Ensure code is formatted:
+   ```bash
+   black aegis/ tests/
+   ```
+
+3. Ensure linting passes:
+   ```bash
+   ruff check aegis/ tests/
+   ```
+
+4. Ensure type checking passes:
+   ```bash
+   mypy aegis/
+   ```
+
+5. Update CHANGELOG.md with your changes
+
+### Pull Request Process
+
+1. Push your changes to your fork
+2. Create a pull request against the `main` branch
+3. Provide a clear description of the changes
+4. Link any related issues
+5. Wait for review and address feedback
+
+### Pull Request Guidelines
+
+- Keep PRs focused and small
+- Include tests for all changes
+- Update documentation as needed
+- Follow existing code style
+- Write clear commit messages
+
+## Commit Message Format
+
+We follow conventional commit format:
+
+```
+type(scope): subject
+
+body
+
+footer
+```
+
+Types:
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `style`: Code style changes (formatting, etc.)
+- `refactor`: Code refactoring
+- `test`: Test changes
+- `chore`: Build process or auxiliary tool changes
+
+Example:
+
+```
+feat(guard): add support for custom decision handlers
+
+Added ability to provide custom handlers for each decision effect type,
+allowing users to customize behavior beyond the default implementation.
+
+Closes #123
+```
+
+## Questions?
+
+If you have questions, please:
+
+1. Check existing issues and discussions
+2. Open a new issue with your question
+3. Be clear and provide context
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
+
+## Thank You!
+
+Your contributions make Aegis better for everyone. Thank you for taking the time to contribute!

aegislib-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aegis Security
+
+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.

aegislib-0.1.1/MANIFEST.in

@@ -0,0 +1,14 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include CONTRIBUTING.md
+include pyproject.toml
+include setup.cfg
+recursive-include aegis *.py
+recursive-include aegis py.typed
+recursive-exclude tests *
+recursive-exclude examples *
+recursive-exclude .github *
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+recursive-exclude * .DS_Store

aegislib-0.1.1/PKG-INFO

@@ -0,0 +1,369 @@
+Metadata-Version: 2.4
+Name: aegislib
+Version: 0.1.1
+Summary: Aegis Python SDK - Secure AI agents tool guard integration
+Home-page: https://github.com/mrsidrdx/aegis-python-sdk
+Author: Siddhartha Satyakama
+Author-email: Aegis Team <bithal06@gmail.com>
+Maintainer-email: mrsidrdx <bithal06@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/mrsidrdx/aegis-python-sdk
+Project-URL: Documentation, https://github.com/mrsidrdx/aegis-python-sdk
+Project-URL: Repository, https://github.com/mrsidrdx/aegis-python-sdk
+Project-URL: Issues, https://github.com/mrsidrdx/aegis-python-sdk/issues
+Keywords: ai,security,policy,agent,tool,guard
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: backoff>=2.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.1; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: mypy>=1.7.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7.4.0; extra == "test"
+Requires-Dist: pytest-cov>=4.1.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
+Requires-Dist: pytest-mock>=3.12.0; extra == "test"
+Dynamic: license-file
+
+# Aegis Python SDK
+
+[![CI](https://github.com/mrsidrdx/aegis-python-sdk/workflows/CI/badge.svg)](https://github.com/mrsidrdx/aegis-python-sdk/actions)
+[![PyPI version](https://badge.fury.io/py/aegis.svg)](https://pypi.org/project/aegis/)
+[![Python versions](https://img.shields.io/pypi/pyversions/aegis.svg)](https://pypi.org/project/aegis/)
+[![Code coverage](https://codecov.io/gh/aegis/aegis-python-sdk/branch/main/graph/badge.svg)](https://codecov.io/gh/aegis/aegis-python-sdk)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+Secure AI tool guard integration for multi-agent frameworks.
+
+Aegis enables developers to integrate policy-based AI tool security directly into their agent workflows with minimal effort. It provides a simple `@aegis_guard` decorator or wrapper to protect any tool call, with automatic decision requests to the Aegis Data Plane and enforcement of allow/deny/sanitize policies in real time.
+
+## Features
+
+- **Simple Decorator**: One-line `@aegis_guard` decorator for any Python function
+- **Framework Agnostic**: Core SDK works with any Python code
+- **Real-time Policy Enforcement**: Automatic allow/deny/sanitize decisions
+- **Async Support**: Full async/await compatibility
+- **Resilient**: Built-in retries, timeouts, and error handling
+
+## Installation
+
+```bash
+pip install aegislib
+```
+
+## Quick Start
+
+```python
+from aegis import AegisConfig, DecisionClient, aegis_guard
+
+# Configure the SDK
+cfg = AegisConfig(api_key="your-api-key")
+client = DecisionClient(cfg)
+
+# Guard any tool function
+@aegis_guard(client, agent_id="ops-agent", tool_name="slack.post_message")
+def post_to_slack(channel: str, text: str):
+    print(f"Sending message: {text} to {channel}")
+
+# Use normally - Aegis will decide allow/deny/sanitize automatically
+post_to_slack("#support", "Hello!")
+```
+
+## Configuration
+
+Configure via environment variables:
+
+```bash
+export AEGIS_API_KEY="your-api-key"
+export AEGIS_TIMEOUT_S="1.0"
+export AEGIS_RETRIES="2"
+export AEGIS_LOG_LEVEL="info"
+```
+
+Or programmatically:
+
+```python
+cfg = AegisConfig(
+    api_key="your-api-key",
+    timeout_s=1.0,
+    retries=2,
+    log_level="info"
+)
+```
+
+## Advanced Usage
+
+### Async Support
+
+Aegis fully supports async functions:
+
+```python
+@aegis_guard(client, agent_id="async-agent", tool_name="async_tool")
+async def fetch_data(url: str) -> dict:
+    async with httpx.AsyncClient() as http:
+        response = await http.get(url)
+        return response.json()
+
+# Use with await
+data = await fetch_data("https://api.example.com/data")
+```
+
+### Custom Configuration
+
+```python
+from aegis import AegisConfig, DecisionClient
+
+# Detailed configuration
+config = AegisConfig(
+    base_url="https://api.aegis.cloudmatos.ai",
+    api_key="your-api-key",
+    timeout_s=5.0,        # Request timeout
+    retries=3,            # Number of retries
+    log_level="debug",    # Logging level
+    debug=True,           # Enable debug output
+)
+
+client = DecisionClient(config)
+```
+
+### Decision Effects
+
+Aegis supports four decision effects:
+
+1. **Allow**: Tool execution proceeds normally
+2. **Deny**: Tool execution is blocked with `ForbiddenError`
+3. **Sanitize**: Parameters are modified before execution
+4. **Approval Needed**: Requires manual approval
+
+### Error Handling
+
+```python
+from aegis import ForbiddenError, AuthError, TransportError
+
+@aegis_guard(client, agent_id="agent", tool_name="risky_tool")
+def risky_operation(data: str) -> str:
+    return f"Processing: {data}"
+
+try:
+    result = risky_operation("sensitive data")
+except ForbiddenError as e:
+    print(f"Operation blocked: {e}")
+except AuthError as e:
+    print(f"Authentication failed: {e}")
+except TransportError as e:
+    print(f"Network error: {e}")
+```
+
+### Session Context
+
+Pass additional context with your requests:
+
+```python
+session_data = {
+    "user_id": "user-123",
+    "session_id": "sess-456",
+    "context": "production"
+}
+
+# Manually call decide with session
+response = client.decide(
+    agent_id="agent",
+    tool_name="tool",
+    params={"key": "value"},
+    session=session_data
+)
+```
+
+## API Reference
+
+### AegisConfig
+
+Configuration class for the SDK.
+
+**Parameters:**
+- `base_url` (str): Aegis Data Plane endpoint URL
+- `api_key` (str): Tenant API key for authentication
+- `timeout_s` (float): HTTP request timeout in seconds (default: 10.0)
+- `retries` (int): Number of retry attempts (default: 2)
+- `user_agent` (str): User agent string (default: "aegis-python-sdk/0.1.1")
+- `log_level` (str): Logging level (default: "info")
+- `debug` (bool): Enable debug mode (default: False)
+
+**Environment Variables:**
+- `AEGIS_BASE_URL`: Override base URL
+- `AEGIS_API_KEY`: Override API key
+- `AEGIS_TIMEOUT_S`: Override timeout
+- `AEGIS_RETRIES`: Override retries
+- `AEGIS_LOG_LEVEL`: Override log level
+- `AEGIS_DEBUG`: Override debug mode
+
+### DecisionClient
+
+Client for interacting with Aegis Decision API.
+
+**Methods:**
+- `decide(agent_id, tool_name, params, session=None)`: Request a decision
+- `close()`: Close the HTTP client
+
+### aegis_guard
+
+Decorator for guarding tool functions.
+
+**Parameters:**
+- `client` (DecisionClient): Configured client instance
+- `agent_id` (str): Agent identifier
+- `tool_name` (str, optional): Tool name (defaults to function name)
+
+**Returns:** Decorated function
+
+## Development
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/mrsidrdx/aegis-python-sdk.git
+cd aegis-python-sdk
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install development dependencies
+make install-dev
+```
+
+### Running Tests
+
+```bash
+# Run all tests with coverage
+make test-cov
+
+# Run tests without coverage
+make test-fast
+
+# Run specific test file
+pytest tests/test_config.py
+
+# Run with verbose output
+pytest -v
+```
+
+### Code Quality
+
+```bash
+# Run all linting checks
+make lint
+
+# Format code
+make format
+
+# Type checking
+make type-check
+
+# Security checks
+make security
+```
+
+### Building
+
+```bash
+# Build distribution packages
+make build
+
+# Check packages
+make check-dist
+```
+
+### Publishing
+
+```bash
+# Publish to Test PyPI
+make publish-test
+
+# Publish to PyPI (requires confirmation)
+make publish
+```
+
+## Testing
+
+The SDK includes comprehensive unit tests with 100% code coverage:
+
+- Configuration management (`test_config.py`)
+- Error handling (`test_errors.py`)
+- Type definitions (`test_types.py`)
+- Utility functions (`test_util.py`)
+- Logging (`test_logging.py`)
+- HTTP client (`test_http.py`)
+- Decision client (`test_decision.py`)
+- Guard decorator (`test_guard.py`)
+
+Run tests with:
+
+```bash
+pytest --cov=aegis --cov-report=html
+```
+
+View coverage report at `htmlcov/index.html`.
+
+## CI/CD
+
+The project uses GitHub Actions for continuous integration and deployment:
+
+- **CI Workflow**: Runs tests on multiple Python versions (3.11, 3.12, 3.13) and platforms (Linux, macOS, Windows)
+- **Publish Workflow**: Automatically publishes to PyPI on release
+- **Release Workflow**: Creates GitHub releases with changelog
+
+## Versioning
+
+This project follows [Semantic Versioning](https://semver.org/):
+
+- **MAJOR**: Incompatible API changes
+- **MINOR**: New functionality (backward compatible)
+- **PATCH**: Bug fixes (backward compatible)
+
+See [CHANGELOG.md](CHANGELOG.md) for version history.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for:
+
+- Development setup
+- Code style guidelines
+- Testing requirements
+- Pull request process
+
+## Support
+
+- **GitHub Issues**: [Report bugs or request features](https://github.com/mrsidrdx/aegis-python-sdk/issues)
+- **Email**: bithal06@gmail.com
+
+## Acknowledgments
+
+Built with ❤️ by the Aegis team and contributors.