Atta - Context Management Agent

Atta is the core agent responsible for conversation management and data persistence in the TKM AI Agency Platform. It serves as the storage layer and conversation manager for the entire system.

Overview

The Atta agent handles all aspects of conversation management, including:

Conversation creation and lifecycle management
Message storage and retrieval
Context management
Integration with other agents

Directory Structure

Atta/
├── atta.py              # Main agent implementation
├── tools.py             # Core functionality and utilities
├── tools_schema.py      # Data models and schemas
├── tools_definitions.py # Tool definitions
├── data_validation.py   # Data validation utilities
└── data/               # Storage directory for conversations

Core Components

Data Models

Message Types

class MessageType(str, Enum):
    AUDIO = "audio"
    TEXT = "text"
    IMAGE = "image"
    DOCUMENT = "document"
    SEARCH = "search"
    NEWS = "news"

Intent Types

class IntentType(str, Enum):
    VIEW_IMAGE = "view_image"
    SHARE_CONTENT = "share_content"
    INTERNET_SEARCH = "internet_search"
    GENERAL_INQUIRY = "general_inquiry"
    DOCUMENT_QUERY = "document_query"
    IMAGE_ANALYSIS = "image_analysis"
    CURRENT_EVENTS = "current_events"
    DOCUMENT_SUMMARY = "document_summary"
    TECHNICAL_SUPPORT = "technical_support"
    SYSTEM_STATUS = "system_status"

Main Features

Conversation Management

Creation of new conversations
Message addition and retrieval
Conversation state management
Context tracking and updates

Message Processing

Message validation and storage
Embedding generation and management
Integration with Invicta for message routing
Event emission for system updates

API Reference

Actions

create_conversation

Creates a new conversation instance.

{
    "action": "create_conversation",
    "user_id": str,
    "session_id": str
}

add_message

Adds a new message to an existing conversation.

{
    "action": "add_message",
    "conversation_id": str,
    "message": {
        "timestamp": datetime,
        "source_agent": str,
        "type": MessageType,
        "content": dict
    }
}

get_conversation

Retrieves a complete conversation by ID.

{
    "action": "get_conversation",
    "conversation_id": str
}

verify_conversation

Verifies the existence and validity of a conversation.

{
    "action": "verify_conversation",
    "conversation_id": str,
    "user_id": str,
    "session_id": str
}

Events

The agent emits the following events:

conversation_created: When a new conversation is created
message_added: When a new message is added to a conversation

Integration

With Other Agents

Invicta Integration

Atta automatically triggers Invicta for message processing when receiving messages from:

Rufa (audio processing)
Burchelli (text processing)

Niger Integration

Optional integration for enhanced storage capabilities:

if AttaAgent.niger is None:
    try:
        AttaAgent.niger = NigerAgent()
    except Exception as e:
        # Falls back to JSON storage if Niger is unavailable

Data Storage

Conversation Structure

class ConversationContext(BaseModel):
    conversation_id: str
    context_id: str
    user_id: str
    session_id: str
    organization_id: str
    messages: List[Message]
    metadata: ConversationMetadata

Metadata Tracking

class ConversationMetadata(BaseModel):
    created_at: datetime
    last_updated: datetime
    message_count: int
    total_tokens: int
    active: bool
    target_agent: str
    organization_id: str
    engagement_level: float
    sentiment: Optional[str]
    intent_type: Optional[IntentType]
    search_type: Optional[SearchType]
    document_type: Optional[DocumentType]

Error Handling

The agent implements comprehensive error handling:

Validation errors for message format
Storage operation failures
Integration errors with other agents
Conversation state conflicts

All errors are logged with detailed information using the Loguru logger.

Overview Bala - Embedding Generation