API Reference¶

Complete technical API reference for Arshai framework interfaces, base classes, and models.

This section provides detailed specifications for all framework components, including method signatures, parameters, return types, and usage contracts.

Overview¶

The Arshai framework follows interface-driven design principles. All major components implement well-defined protocols that specify behavior contracts without implementation details.

Key Principles:

Protocol-Based Interfaces: All interfaces use Python protocols for flexible, duck-typed implementations
DTO Pattern: Structured data transfer using Pydantic models with validation
Provider Pattern: Multiple implementations for external services (LLMs, memory, vector DBs)
Developer Authority: Interfaces provide flexibility while maintaining clear contracts

Interface Categories¶

Core Interfaces

Essential protocols that define the framework’s primary abstractions:

ILLM - LLM client interface
IAgent - Agent interface
IMemoryManager - Memory management interface

Component Interfaces

Specialized protocols for specific capabilities:

IEmbedding - Embedding generation
IVectorDBClient - Vector database operations
IDocumentProcessor - Document processing
IReranker - Result reranking
IWebSearch - Web search integration

Orchestration Interfaces

Protocols for workflow and system coordination:

IWorkflowOrchestrator - Workflow orchestration
IWorkflowRunner - Workflow execution
IWorkflowNode - Workflow nodes

Infrastructure Interfaces

Supporting protocols for notifications and utilities:

INotificationService - Notification delivery
IDTO - Data transfer object base

Base Classes¶

Foundation classes that provide reusable implementations:

BaseAgent - Agent foundation with LLM integration
BaseLLMClient - LLM client foundation with function calling
WorkingMemoryAgent - Agent with working memory

See Base Classes for complete documentation.

Data Models¶

Pydantic models and DTOs used throughout the framework:

LLM Models

ILLMInput - LLM input structure
ILLMConfig - LLM configuration

Agent Models

IAgentInput - Agent input structure
IAgentConfig - Agent configuration

Memory Models

IMemoryInput - Memory operation input
IMemoryItem - Memory item structure
IWorkingMemory - Working memory state
ConversationMemoryType - Memory type enum

Workflow Models

Workflow state and configuration models
Node input/output models

See Models for complete documentation.

Usage Patterns¶

Implementing an Interface

All Arshai interfaces are protocols, so you implement them through duck typing:

from arshai.core.interfaces import IAgent, IAgentInput

class MyCustomAgent:
    """Custom agent implementation"""

    async def process(self, input: IAgentInput) -> dict:
        """Process input and return response"""
        return {"response": f"Processed: {input.message}"}

# MyCustomAgent automatically satisfies IAgent protocol

Using DTOs

All data structures are Pydantic models with validation:

from arshai.core.interfaces import IAgentInput

# Valid input
agent_input = IAgentInput(
    message="Hello",
    metadata={"conversation_id": "123"}
)

# Validation error - missing required field
try:
    bad_input = IAgentInput()  # Raises ValidationError
except ValidationError as e:
    print(f"Validation failed: {e}")

Extending Base Classes

Inherit from base classes to get default implementations:

from arshai.agents.base import BaseAgent
from arshai.core.interfaces import IAgentInput, ILLM

class SmartAgent(BaseAgent):
    def __init__(self, llm_client: ILLM, system_prompt: str):
        super().__init__(llm_client, system_prompt)
        self.interaction_count = 0

    async def process(self, input: IAgentInput) -> dict:
        self.interaction_count += 1
        # Use inherited self.llm_client
        response = await self.llm_client.chat(...)
        return {"response": response, "count": self.interaction_count}

Type Safety¶

Protocol Runtime Checking

Use isinstance() to check protocol implementation at runtime:

from typing import runtime_checkable
from arshai.core.interfaces import IAgent

@runtime_checkable
class IAgent(Protocol):
    async def process(self, input: IAgentInput) -> Any: ...

agent = MyCustomAgent()
if isinstance(agent, IAgent):
    result = await agent.process(input)

Type Hints

All interfaces use proper type hints for IDE support:

from arshai.core.interfaces import ILLM, ILLMInput

async def chat_with_llm(llm: ILLM, message: str) -> dict:
    """IDE provides autocomplete and type checking"""
    input_data = ILLMInput(
        system_prompt="You are helpful",
        user_message=message
    )
    return await llm.chat(input_data)

Validation¶

Pydantic Validation

All DTOs include automatic validation:

from arshai.core.interfaces import ILLMInput

# Automatic validation
llm_input = ILLMInput(
    system_prompt="",  # Will raise ValidationError
    user_message="Hello"
)

# Custom validators
class ILLMInput(IDTO):
    @model_validator(mode='before')
    @classmethod
    def validate_input(cls, data):
        if not data.get('system_prompt'):
            raise ValueError("system_prompt is required")
        return data

Field Validation

Use Pydantic field validators for custom logic:

from pydantic import Field, field_validator

class CustomInput(IDTO):
    temperature: float = Field(ge=0.0, le=2.0)

    @field_validator('temperature')
    @classmethod
    def validate_temperature(cls, v):
        if v > 1.0:
            print("Warning: High temperature may produce random results")
        return v

Section	Description
Interfaces	All framework protocols and their specifications
Base Classes	Foundation classes for extension
Models	Pydantic models and DTOs

Contributing to API Documentation¶

The API reference is maintained alongside the codebase. To improve documentation:

Inline Docstrings: Add comprehensive docstrings to interfaces and classes
Type Hints: Use complete type annotations for all parameters and returns
Examples: Include usage examples in docstrings
Validation: Document validation rules and constraints

See Extending Arshai for contribution guidelines.