Hexr SDK - Secure Multi-Agent AI Platform

Transform your Python AI agents into production-ready containerized deployments with automatic SPIFFE identity management and cloud credential injection.

Hexr SDK enables Fortune 500 enterprises to securely deploy multi-agent AI systems at scale with zero-trust architecture, automated cloud resource provisioning, and comprehensive observability.

🚀 Quick Start

Installation

# Install from the private PyPI mirror (current pivot distribution channel)
pip install "hexr-sdk[cli]" --extra-index-url https://pypi.hexr.cloud/simple/

# Or build the manylinux + macOS-arm64 wheels locally (air-gapped / pre-release)
git clone https://github.com/hexrdev/hexr.git
cd hexr/sdk/python
RUSTFLAGS="-C link-arg=-undefined -C link-arg=dynamic_lookup" uv build
pip install dist/hexr_sdk-*-cp311-cp311-*.whl

Current released version: 0.5.5 (2026-06-08, hybrid-pivot maintenance train). See CHANGELOG.md for the 0.5.0 → 0.5.5 release notes.

Your First Agent

from hexr import hexr_agent, hexr_tool
from crewai import Agent, Task, Crew

@hexr_agent(
    name="financial-analyst", 
    tenant="acme-corp",
    resources=["aws_s3", "gcp_bigquery"]
)
def create_financial_analyst():
    # Access cloud resources with automatic credential injection
    s3_client = hexr_tool("aws_s3", bucket="financial-data")
    bq_client = hexr_tool("gcp_bigquery", project_id="analytics-warehouse")
    
    analyst = Agent(
        role='Senior Financial Analyst',
        goal='Analyze market trends and generate insights',
        backstory='Expert in quantitative analysis and market research'
    )
    
    task = Task(
        description='Generate quarterly financial report',
        agent=analyst
    )
    
    crew = Crew(agents=[analyst], tasks=[task])
    return crew.kickoff()

if __name__ == "__main__":
    create_financial_analyst()

Build & Deploy

# Build container image and Kubernetes manifests
hexr build financial_analyst.py --tenant acme-corp

# Push to container registry with security scanning
hexr push financial-analyst --registry harbor.company.com --scan

# Deploy to Kubernetes with SPIFFE identity
hexr deploy financial-analyst --env production --namespace acme-corp

🎯 Key Features

� Zero-Trust Security

• SPIFFE Identity: Automatic service identity management with cryptographic attestation
• Credential Injection: Secure cloud credentials without hardcoded secrets
• Network Isolation: Kubernetes network policies for multi-tenant security
• Vulnerability Scanning: Trivy integration for container security assessment

☁️ Multi-Cloud Support

• AWS: S3, DynamoDB, Lambda, SQS, SNS with IAM role-based access
• Google Cloud: BigQuery, Cloud Storage, Pub/Sub with service account injection
• Azure: Storage, Cosmos DB, Service Bus with managed identity integration
• On-Premises: Support for private cloud and hybrid deployments

🤖 AI Framework Integration

• CrewAI: Multi-agent collaboration with role-based workflows
• LangChain: Chain-of-thought reasoning with memory persistence
• AutoGen: Conversational multi-agent systems with dynamic routing
• StrandAgent: Custom workflow orchestration with state management

🏗️ Enterprise Architecture

• Multi-Tenancy: Isolated namespaces with resource quotas and RBAC
• Scalability: Horizontal pod autoscaling based on workload metrics
• Observability: Prometheus metrics, structured logging, distributed tracing
• GitOps Ready: Kubernetes manifests compatible with ArgoCD and Flux

📋 Requirements

System Requirements

• Python: 3.11 or higher
• Container Runtime: Docker 20.10+ or containerd 1.6+
• Kubernetes: 1.24+ (for deployment)
• Operating System: Linux, macOS, Windows (WSL2)

Cloud Prerequisites

• SPIRE Server: Deployed in Kubernetes cluster for identity management
• Hexr Runtime: Credential injection service (provided separately)
• Container Registry: Docker Hub, Harbor, ECR, GCR, or ACR
• Cloud Accounts: Configured service accounts with appropriate permissions

🛠️ Installation & Setup

Development Environment

1. Clone the repository:

   git clone https://github.com/hexrdev/hexr.git
   cd hexr/sdk/python
   

2. Set up virtual environment:

   # Using uv (recommended)
   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   
   # Or using standard venv
   python -m venv .venv
   source .venv/bin/activate
   

3. Install dependencies:

   # Development installation (includes testing and linting tools)
   pip install -e ".[dev]"
   
   # Production installation
   pip install -e .
   

4. Configure IDE (VS Code):

   # Install Python extension and select interpreter
   # Path: .venv/bin/python (or .venv\Scripts\python.exe on Windows)
   # The project includes .vscode/settings.json for optimal development experience
   

🧪 Testing

Running Tests

# Run all integration tests (recommended)
python -m pytest tests/integration/ -v

# Run specific test categories
python -m pytest tests/integration/test_cli_workflow.py -v  # CLI functionality
python -m pytest tests/integration/test_build_integration.py -v  # Build pipeline

# Run with coverage reporting
python -m pytest tests/integration/ --cov=src/hexr --cov-report=html

# Run tests in parallel for faster execution
python -m pytest tests/integration/ -n auto

Test Categories

Integration Tests (12 tests)

• ✅ CLI Component Import - Verify all SDK imports resolve correctly
• ✅ Configuration Creation - Test BuildConfig and PushConfig with enterprise parameters
• ✅ Mock System Integration - SPIFFE client and credential injection workflows
• ✅ Framework Detection - AST analysis for CrewAI, LangChain, AutoGen patterns
• ✅ Build Pipeline - Dockerfile generation and container building
• ✅ Kubernetes Manifests - Pod, Service, NetworkPolicy, RBAC generation
• ✅ Circular Import Prevention - Shared configuration architecture validation

Unit Tests (Coming Soon)

• AST analyzer components
• Mock system individual functions
• Utility functions and helpers
• Error handling and edge cases

Test Environment Setup

# Install test dependencies
pip install pytest pytest-asyncio pytest-cov pytest-mock pytest-xdist

# Configure pytest (already included in pyproject.toml)
python -m pytest --version
python -m pytest --collect-only tests/integration/  # Show all available tests

• Simulates: File system monitoring and context management
• Features: Process hierarchy, subprocess role tracking, file events
• Contract: platform/contracts/runtime/process-context-files.yaml

✅ Kubernetes Auto-Registrar Mock

• File: src/hexr/testing/mocks.py:MockKubernetesAPI
• Simulates: Pod monitoring and SPIFFE registration
• Features: Annotation validation, pod lifecycle, Auto-Registrar simulation
• Contract: platform/contracts/runtime/kubernetes-auto-registrar.yaml

✅ Cloud Provider Client Mocks

• Files: create_mock_aws_client, create_mock_gcp_client, create_mock_azure_client
• AWS Support: S3, Bedrock Runtime
• GCP Support: BigQuery, Cloud Storage
• Azure Support: Storage, Key Vault, Cognitive Services
• Features: Realistic API responses, error simulation, operation tracking

📋 SDK Implementation Guide

Basic Usage

from hexr.sdk import create_agent_sdk

# Create main agent SDK
sdk = create_agent_sdk(
    agent_name="financial-orchestrator",
    tenant="corp-finance", 
    framework="crewai",
    required_resources=["aws_s3", "gcp_bigquery"],
    mock_mode=True  # Use mocks during development
)

# Get authenticated cloud clients
s3_client = await sdk.get_aws_client("s3", region="us-west-2")
---

## 🤝 **Contributing**

We welcome contributions from the community! Hexr SDK is open source and designed for collaborative development.

### Development Workflow

1. **Fork the repository** on GitHub
2. **Create a feature branch** from `main`
3. **Make your changes** with tests and documentation
4. **Run the test suite** to ensure quality
5. **Submit a pull request** with clear description

### Code Quality Standards

```bash
# Format code with ruff
python -m ruff format src/ tests/ examples/

# Run linting checks
python -m ruff check src/ tests/ examples/ --fix

# Type checking with mypy (optional)
python -m mypy src/hexr --ignore-missing-imports

# Run full test suite
python -m pytest tests/integration/ -v --cov=src/hexr

Contribution Guidelines

• Tests Required: All new features must include integration tests
• Documentation: Update README and docstrings for public APIs
• Code Style: Follow ruff formatting and PEP 8 conventions
• Security: No hardcoded credentials or security vulnerabilities
• Performance: Consider impact on build times and resource usage

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

The Apache 2.0 license allows for:

• ✅ Commercial Use: Use in proprietary enterprise applications
• ✅ Modification: Adapt the SDK for your specific requirements
• ✅ Distribution: Include in your software distributions
• ✅ Patent Rights: Protection against patent litigation
• ✅ Private Use: Use internally without disclosure requirements

📊 Statistics

• 4,111+ lines of production code
• 12/12 integration tests passing (100% success rate)
• 729 lines of comprehensive mock system for development
• 4 AI frameworks supported (CrewAI ✅, LangChain 🔄, AutoGen 🔄, StrandAgent 🔄)
• 3 major cloud providers (AWS, GCP, Azure)
• Zero critical security vulnerabilities
• Sub-5s container build times
• Sub-30s deployment times to Kubernetes

Built with ❤️ by the Hexr team. Empowering Fortune 500 enterprises to deploy AI agents securely at scale. 3. Performance testing and optimization 4. Security penetration testing

🤝 Team Coordination

SDK Development Process

• Feature Development: Use mocks for all new features
• Testing: Validate against mock contracts
• Documentation: Update contracts as requirements evolve
• Integration: Test with real Runtime services when available

Runtime Development Process

• Contract Review: Understand SDK expectations from contracts
• Implementation: Build services matching contract specifications
• Validation: Use SDK test suite to verify compatibility
• Deployment: Roll out services to match SDK requirements

🔍 Troubleshooting

Common Issues

# Import errors
export PYTHONPATH="${PYTHONPATH}:$(pwd)/src"

# Mock not working  
export HEXR_MOCK_MODE=true

# Test failures
python -m pytest tests/test_mocks.py::TestMockSpiffeClient -v -s

Debug Mode

from hexr.testing.mocks import reset_all_mocks, get_mock_statistics

reset_all_mocks()  # Clean state
stats = get_mock_statistics()  # Check activity

🏆 Success Criteria

✅ SDK team can develop independently
✅ Complete Runtime dependency mocking
✅ Contract-driven development process
✅ Comprehensive test coverage
✅ Runtime team has clear specifications
✅ Seamless mock → production transition

Result: Parallel development with no team blocking! 🚀

Installation

pip install hexr-sdk

Quick Start

from hexr_sdk import HexrClient

# Initialize client with SPIFFE identity
client = HexrClient()

# Authenticate agent
identity = client.authenticate()
print(f"Agent ID: {identity.spiffe_id}")

# Communicate with other agents
response = client.call_agent("other-agent", {"message": "hello"})

Development

# Install in development mode
pip install -e .

# Run tests
pytest tests/

# Build and publish
python setup.py sdist bdist_wheel

Features

• ✅ SPIFFE/SPIRE integration
• ✅ Zero-trust agent authentication
• ✅ Encrypted agent-to-agent communication
• ✅ Multi-cloud support (AWS, GCP, Azure)
• 🚧 Kubernetes operator integration
• 🚧 Automatic identity rotation