Name	Name	Last commit message	Last commit date
parent directory ..
aral	aral
docs	docs
examples	examples
tests	tests
.env.example	.env.example
GUIDE-CLE-API.md	GUIDE-CLE-API.md
README-PROVIDERS.md	README-PROVIDERS.md
README.md	README.md
RESUME-LLM-PROVIDERS.md	RESUME-LLM-PROVIDERS.md
pyproject.toml	pyproject.toml

ARAL Standard - Python SDK

Reference implementation of the ARAL (Agent Runtime Abstract Layer) Standard in Python.

Version

1.2.0 Production-Ready - All layers (L1-L7) complete and production-ready

Test Results

249 tests passing (100%)
93.34% code coverage (target: 85%)
23.72s test execution time
All 7 layers fully tested and operational

Features

✅ Layer 1: Runtime (ARAL-L1-*)

✅ Resource quota management (memory, CPU, concurrent tasks)
✅ Health check system with custom checks
✅ Graceful lifecycle management (start/shutdown)
✅ Task execution with timeout enforcement
✅ Runtime metrics and monitoring

✅ Layer 2: Memory (ARAL-L2-*)

✅ TTL-based expiration
✅ Fernet encryption at rest
✅ Namespace isolation
✅ Size limits per namespace
✅ Background cleanup of expired entries

✅ Layer 3: Capabilities (ARAL-L3-*)

✅ Capability registry and framework
✅ Permission system (ALLOW/DENY/REQUIRE_APPROVAL)
✅ Input/output validation with Pydantic
✅ Sandboxed execution
✅ Rate limiting and quotas

✅ Layer 4: Reasoning (ARAL-L4-*)

✅ LLM provider abstraction
✅ OpenAI Provider (GPT-4, GPT-3.5-turbo, Azure OpenAI)
✅ Anthropic Provider (Claude 3: Opus, Sonnet, Haiku)
✅ Token counting and limits
✅ Streaming support
✅ Prompt injection defense
✅ Secure API key management
✅ Advanced Multi-LLM Routing (9 strategies)
✅ Response Aggregation (6 methods)
✅ PCL v2.1.0 Compliance

✅ Layer 5: Persona (ARAL-L5-*) - Production-Ready

✅ Persona identity and signing (Ed25519)
✅ Cryptographic provenance
✅ Key rotation and management
✅ Persona validation and constraints
✅ Immutable persona definitions
✅ 93% test coverage, 33+ tests passing

✅ Layer 6: Orchestration (ARAL-L6-*) - Production-Ready

✅ Multi-agent coordination
✅ Circuit breaker patterns
✅ Load balancing (round-robin, least-loaded, priority)
✅ Agent registry and discovery
✅ Routing with persona constraints
✅ Graceful degradation
✅ 94% test coverage, 30+ tests passing

✅ Layer 7: Protocol (ARAL-L7-*) - Production-Ready

✅ Envelope handling and validation
✅ MCP (Model Context Protocol) integration
✅ Rate limiting and authentication
✅ Trace propagation
✅ Request/response flow
✅ 94% test coverage, 15+ tests passing

Installation

From Source (Development)

git clone https://github.com/personalayer/aral-standard.git
cd aral-standard/implementations/python
pip install -e .

With Optional Dependencies

# Development tools (pytest, black, ruff, mypy)
pip install -e ".[dev]"

# LLM providers (OpenAI, Anthropic)
pip install -e ".[llm]"

# Or install directly
pip install openai anthropic tiktoken

# Security extras (HashiCorp Vault)
pip install -e ".[security]"

# Observability (OpenTelemetry)
pip install -e ".[observability]"

Quick Start

Layer 1: Runtime

import asyncio
from aral.runtime import ARALRuntime, ResourceQuota

async def main():
    # Create runtime with resource limits
    runtime = ARALRuntime(
        agent_id="my-agent",
        agent_version="1.0.0",
        quota=ResourceQuota(
            max_memory_mb=512,
            max_cpu_percent=50.0,
            max_tasks_concurrent=10,
            max_task_duration_seconds=30.0,
        )
    )

    # Start runtime
    await runtime.start()

    # Register custom health check
    def check_database():
        # Your health check logic
        return True

    runtime.register_health_check("database", check_database)

    # Execute task with resource enforcement
    async def my_task():
        await asyncio.sleep(1)
        return "Task result"

    result = await runtime.execute_with_quota(my_task)
    print(f"Result: {result}")

    # Check health
    health = await runtime.health_check()
    print(f"Health: {health.status}")

    # Graceful shutdown
    await runtime.shutdown(timeout=5.0)

asyncio.run(main())

Layer 2: Memory

import asyncio
from aral.memory import MemoryLayer

async def main():
    # Create memory layer with encryption
    memory = MemoryLayer(
        enable_encryption=True,
        default_ttl_seconds=3600,
        cleanup_interval_seconds=60
    )

    await memory.start()

    # Basic operations
    await memory.set("user:123", {"name": "Alice", "role": "admin"})
    user = await memory.get("user:123")
    print(f"User: {user}")

    # With TTL (expires after 300 seconds)
    await memory.set("session:abc", "token", ttl_seconds=300)

    # Namespace isolation
    memory.create_namespace("cache", max_size_mb=100)
    await memory.set("api:response", {"data": [1, 2, 3]}, namespace="cache")

    # Check existence
    if await memory.exists("user:123"):
        print("User exists")

    # List keys in namespace
    keys = await memory.list_keys(namespace="cache")
    print(f"Cache keys: {keys}")

    # Get statistics
    stats = memory.get_stats()
    print(f"Total entries: {stats['total_entries']}")

    await memory.stop()

asyncio.run(main())

Layer 4: Reasoning (LLM Providers)

import asyncio
from aral.providers import OpenAIProvider, AnthropicProvider
from aral.reasoning import Message, MessageRole

async def main():
    # Initialize provider (loads from OPENAI_API_KEY env var)
    provider = OpenAIProvider(model="gpt-4")

    # Create messages
    messages = [
        Message(role=MessageRole.SYSTEM, content="You are a helpful assistant."),
        Message(role=MessageRole.USER, content="What is ARAL?"),
    ]

    # Get completion
    response = await provider.complete(messages)
    print(f"Response: {response.content}")
    print(f"Tokens: {response.usage.total_tokens}")

    # Streaming
    async for chunk in provider.complete_stream(messages):
        print(chunk, end="", flush=True)

asyncio.run(main())

Security Note: For production, store API keys in encrypted memory:

from aral.memory import MemoryLayer
from aral.providers import OpenAIProvider

memory = MemoryLayer(enable_encryption=True)
await memory.set("openai_key", "sk-...", namespace="credentials")

api_key = await memory.get("openai_key", namespace="credentials")
provider = OpenAIProvider(api_key=api_key)

See GUIDE-CLE-API.md and README-PROVIDERS.md for complete documentation.

Integrated Example: Runtime + Memory + LLM

import asyncio
from aral.runtime import ARALRuntime, ResourceQuota
from aral.memory import MemoryLayer
from aral.providers import OpenAIProvider
from aral.reasoning import Message, MessageRole

async def main():
    # Initialize all layers
    runtime = ARALRuntime(agent_id="agent-001")
    memory = MemoryLayer(enable_encryption=True)

    await runtime.start()
    await memory.start()

    # Store API key securely
    await memory.set("llm_key", "sk-...", namespace="credentials")
    api_key = await memory.get("llm_key", namespace="credentials")

    provider = OpenAIProvider(api_key=api_key, model="gpt-4")

    # Use LLM in a runtime-managed task
    async def llm_task():
        messages = [
            Message(role=MessageRole.USER, content="Hello!"),
        ]
        response = await provider.complete(messages)

        # Cache response
        await memory.set("last_response", response.content, ttl_seconds=3600)
        return response.content

    result = await runtime.execute_with_quota(llm_task)
    print(f"Result: {result}")

    # Cleanup
    await runtime.shutdown()
    await memory.stop()

asyncio.run(main())

Architecture

The ARAL Python SDK follows a layered architecture (L1-L7):

┌─────────────────────────────────────┐
│  L7: Protocol (Envelope Handling)   │  🚧 Coming soon
├─────────────────────────────────────┤
│  L6: Orchestration (Multi-Agent)    │  🚧 Coming soon
├─────────────────────────────────────┤
│  L5: Persona (Identity & Signing)   │  🚧 Coming soon
├─────────────────────────────────────┤
│  L4: Reasoning (LLM Integration)    │  ✅ OpenAI, Anthropic
├─────────────────────────────────────┤
│  L3: Capabilities (Tools/Actions)   │  ✅ Implemented
├─────────────────────────────────────┤
│  L2: Memory (TTL, Encryption)       │  ✅ Implemented
├─────────────────────────────────────┤
│  L1: Runtime (Quotas, Health)       │  ✅ Implemented
└─────────────────────────────────────┘

Testing

Run tests with pytest:

# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=aral --cov-report=term-missing

# Run specific test file
pytest tests/test_runtime.py

# Run specific test class
pytest tests/test_runtime.py::TestARALRuntime

# Run specific test
pytest tests/test_runtime.py::TestARALRuntime::test_start_runtime

Current Test Coverage: 89.89% (70 tests, all passing)

Development

Code Quality

# Format code
black aral/ tests/

# Lint
ruff check aral/ tests/

# Type checking
mypy aral/

Project Structure

implementations/python/
├── aral/
│   ├── __init__.py          # Package exports
│   ├── runtime.py           # L1: Runtime implementation
│   └── memory.py            # L2: Memory implementation
├── tests/
│   ├── test_runtime.py      # Runtime tests (29 tests)
│   └── test_memory.py       # Memory tests (41 tests)
├── pyproject.toml           # Package configuration
└── README.md                # This file

Requirements

Python >= 3.9
cryptography >= 41.0.0 (Fernet encryption)
pydantic >= 2.0.0 (Data validation)
python-dateutil >= 2.8.0 (Datetime handling)

ARAL Standard Compliance

This implementation follows the ARAL Standard v0.9.5.

Implemented Requirements

Layer	Requirements	Status
L1: Runtime	ARAL-L1-001 to ARAL-L1-005	✅ Complete
L2: Memory	ARAL-L2-001 to ARAL-L2-005	✅ Complete
L3: Capabilities	ARAL-L3-*	🚧 Planned
L4: Reasoning	ARAL-L4-*	🚧 Planned
L5: Persona	ARAL-L5-*	🚧 Planned
L6: Orchestration	ARAL-L6-*	🚧 Planned
L7: Protocol	ARAL-L7-*	🚧 Planned

Security

Encryption: Fernet symmetric encryption (AES-128-CBC + HMAC-SHA256)
Key Management: Auto-generated keys per MemoryLayer instance
Best Practices: See Security Implementation Guide

⚠️ Production Considerations:

Use proper key management (e.g., HashiCorp Vault, AWS KMS)
Implement key rotation policies
Enable audit logging
Follow least-privilege principles

Performance

Benchmarks (Preliminary)

Runtime startup: <10ms
Memory get/set: <1ms (unencrypted), <2ms (encrypted)
Health checks: <5ms
Task execution overhead: <100μs

Benchmarks run on: Python 3.13, Windows 11, AMD Ryzen

Contributing

See CONTRIBUTING.md for development guidelines.

License

License details

Roadmap

Phase 2: Implementation (Current - Week 1)

✅ Week 1 (Jan 15-21): Python SDK L1-L2 complete
🔜 Week 2 (Jan 22-27): L3 Capabilities + L4 Reasoning
🔜 Week 3 (Jan 28-Feb 3): L5 Persona + L6 Orchestration

Next Steps

Layer 3: Capabilities framework
Layer 4: LLM integration
Integration tests L1-L7
Performance benchmarks
Production hardening

Support

For questions, issues, or contributions:

Open an issue in the repository
Review existing discussions
Check the tutorials and examples

Uh oh!