aitbc/packages/py/aitbc-agent-core/README.md

AITBC Agent Core

Shared agent service logic with protocol-based dependency injection.

Purpose

This package provides shared business logic for agent integration and orchestration across multiple AITBC applications. It uses protocol-based dependency injection to avoid coupling to app-specific implementations, enabling code reuse while maintaining flexibility.

Architecture

Protocol-Based Design

The package defines abstract protocols (interfaces) for all dependencies:

• Domain Protocols: IAgentExecution, IAgentStepExecution - Domain model interfaces
• Security Protocols: ISecurityManager, IAuditor - Security and auditing interfaces
• Orchestration Protocol: IAgentOrchestrator - Workflow orchestration interface
• ZK Proof Protocol: IZKProofService - Zero-knowledge proof generation/verification
• Database Protocol: ISessionProvider - Database session management

Core Service

AgentIntegrationService contains pure business logic that:

• Deploys agents with configuration
• Generates verification proofs
• Verifies execution proofs
• Queries execution status

All dependencies are injected via constructor, enabling app-specific adapters.

Usage

App-Specific Adapters

Each app implements protocols for its domain models and services:

# Example adapter for agent-management
from aitbc_agent_core.protocols import ISecurityManager
from app.services.agent_security import AgentSecurityManager

class AgentSecurityManagerAdapter(ISecurityManager):
    def __init__(self, manager: AgentSecurityManager):
        self._manager = manager
    
    async def validate_operation(self, operation: str, context: dict) -> bool:
        return await self._manager.validate_operation(operation, context)
    
    async def audit_event(self, event_type: str, details: dict) -> None:
        await self._manager.audit_event(event_type, details)

Factory Pattern

Create the shared service with app-specific adapters:

from aitbc_agent_core import AgentIntegrationService
from .adapters import (
    SessionProviderAdapter,
    SecurityManagerAdapter,
    AuditorAdapter,
    OrchestratorAdapter,
)

def create_agent_integration_service():
    return AgentIntegrationService(
        session_provider=SessionProviderAdapter(get_session),
        security_manager=SecurityManagerAdapter(AgentSecurityManager()),
        auditor=AuditorAdapter(AgentAuditor()),
        orchestrator=OrchestratorAdapter(AIAgentOrchestrator()),
        zk_proof_service=ZKProofServiceAdapter(ZKProofService()),
    )

Installation

poetry add aitbc-agent-core

Development

Running Tests

poetry install --with test
poetry run pytest

Type Checking

poetry run mypy src

License

Proprietary - AITBC Project