Metadata-Version: 2.4
Name: hexr-sdk
Version: 0.5.22
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
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 :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: System :: Distributed Computing
Requires-Dist: psutil>=5.9.0,<6.0.0
Requires-Dist: pydantic>=2.5.0,<3.0.0
Requires-Dist: spiffe>=0.3.1,<1.0.0
Requires-Dist: cryptography>=50.0.1
Requires-Dist: pyjwt>=2.13.0
Requires-Dist: pyasn1>=0.6.4
Requires-Dist: idna>=3.19
Requires-Dist: protobuf>=6.31.1,<7.0.0
Requires-Dist: requests>=2.31.0,<3.0.0
Requires-Dist: redis[hiredis]>=5.0.0,<6.0.0
Requires-Dist: httpx>=0.25.0,<1.0.0
Requires-Dist: pyyaml>=6.0.0,<7.0.0
Requires-Dist: structlog>=23.2.0,<24.0.0
Requires-Dist: hexr-sdk[aws,gcp,azure,observability,cli] ; extra == 'all'
Requires-Dist: pip-audit>=2.7.0,<3.0.0 ; extra == 'audit'
Requires-Dist: cyclonedx-bom>=4.0.0,<8.0.0 ; extra == 'audit'
Requires-Dist: reportlab>=4.0.0,<6.0.0 ; extra == 'audit-pack'
Requires-Dist: psycopg2-binary>=2.9.0,<3.0.0 ; extra == 'audit-pack'
Requires-Dist: boto3>=1.34.0,<2.0.0 ; extra == 'aws'
Requires-Dist: azure-identity>=1.15.0,<2.0.0 ; extra == 'azure'
Requires-Dist: click>=8.1.0,<9.0.0 ; extra == 'cli'
Requires-Dist: rich>=13.0.0,<16.0.0 ; extra == 'cli'
Requires-Dist: hexr-sdk[all] ; 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.9.0 ; extra == 'dev'
Requires-Dist: ruff>=0.1.0 ; extra == 'dev'
Requires-Dist: mypy>=1.7.0 ; extra == 'dev'
Requires-Dist: pre-commit>=3.5.0 ; extra == 'dev'
Requires-Dist: onnxruntime>=1.20,<2.0 ; extra == 'enterprise'
Requires-Dist: hexr-sdk-models>=0.1.0,<1.0 ; extra == 'enterprise'
Requires-Dist: crewai>=0.28.0 ; extra == 'frameworks'
Requires-Dist: langchain>=0.1.0 ; extra == 'frameworks'
Requires-Dist: pyautogen>=0.2.0 ; extra == 'frameworks'
Requires-Dist: google-cloud-core>=2.4.0,<3.0.0 ; extra == 'gcp'
Requires-Dist: google-auth>=2.23.0,<3.0.0 ; extra == 'gcp'
Requires-Dist: opentelemetry-api>=1.41.0,<2.0.0 ; extra == 'observability'
Requires-Dist: opentelemetry-sdk>=1.41.0,<2.0.0 ; extra == 'observability'
Requires-Dist: opentelemetry-propagator-b3>=1.41.0,<2.0.0 ; extra == 'observability'
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.41.0,<2.0.0 ; extra == 'observability'
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.41.0,<2.0.0 ; extra == 'observability'
Requires-Dist: sigstore>=4.5.0,<5.0.0 ; extra == 'ops'
Requires-Dist: bandit>=1.7.5 ; extra == 'security'
Requires-Dist: safety>=2.3.0 ; extra == 'security'
Requires-Dist: semgrep>=1.45.0 ; extra == 'security'
Requires-Dist: pytest>=8.0.0 ; extra == 'test'
Requires-Dist: pytest-asyncio>=1.0.0 ; extra == 'test'
Requires-Dist: pytest-httpx>=0.35.0 ; extra == 'test'
Requires-Dist: pytest-mock>=3.14.0 ; extra == 'test'
Requires-Dist: boto3>=1.34.0,<2.0.0 ; extra == 'test'
Provides-Extra: all
Provides-Extra: audit
Provides-Extra: audit-pack
Provides-Extra: aws
Provides-Extra: azure
Provides-Extra: cli
Provides-Extra: dev
Provides-Extra: enterprise
Provides-Extra: frameworks
Provides-Extra: gcp
Provides-Extra: observability
Provides-Extra: ops
Provides-Extra: security
Provides-Extra: test
License-File: LICENSE
Summary: Hexr AI Agent Platform SDK - SPIFFE-based identity and authentication
Keywords: ai,agents,spiffe,identity,authentication,zero-trust
Author-email: Hexr Team <sdk@hexr.dev>
Maintainer-email: Hexr Team <sdk@hexr.dev>
License: Proprietary - Source Available
Requires-Python: >=3.11, <3.14
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/hexrdev/hexr/blob/main/sdk/python/CHANGELOG.md
Project-URL: Documentation, https://docs.hexr.dev/sdk/python
Project-URL: Homepage, https://github.com/hexrdev/hexr
Project-URL: Issues, https://github.com/hexrdev/hexr/issues
Project-URL: Repository, https://github.com/hexrdev/hexr

# Hexr SDK - Secure Multi-Agent AI Platform

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Tests](https://img.shields.io/badge/tests-12%2F12%20passing-brightgreen.svg)](#testing)
[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

**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

```bash
# 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](CHANGELOG.md) for the 0.5.0 → 0.5.5 release notes.

### Your First Agent

```python
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

```bash
# 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:**
   ```bash
   git clone https://github.com/hexrdev/hexr.git
   cd hexr/sdk/python
   ```

2. **Set up virtual environment:**
   ```bash
   # 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:**
   ```bash
   # Development installation (includes testing and linting tools)
   pip install -e ".[dev]"
   
   # Production installation
   pip install -e .
   ```

4. **Configure IDE (VS Code):**
   ```bash
   # 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

```bash
# 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

```bash
# 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
```python
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](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
```bash
# 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
```python
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

```bash
pip install hexr-sdk
```

## Quick Start

```python
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

```bash
# 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

