Carina - Search Engine Agent

Overview

Carina is the agent responsible for internet searches and current events analysis in the TKM AI Agency Platform. It integrates with Tavily for web searches and uses LLM capabilities to process and refine search results.

Directory Structure

Backend/CRM/Carina/
├── data/                # Search activity storage
├── carina.py           # Main agent implementation
├── api_carina.py       # FastAPI endpoints
├── tools.py            # Search and processing utilities
├── tools_schema.py     # Data models and schemas
├── tools_definitions.py # Constants and definitions
├── carina_migrations.py # Database migrations
└── test_carina.py      # Unit tests

Main Components

CarinaAgent Class

The main class that handles search operations:

• Multiple LLM provider support (Groq, OpenAI)
• Tavily search integration
• Search refinement and processing
• Activity logging

Search Pipeline

1. Query refinement
2. Web/News search execution
3. Results processing
4. Response generation
5. Activity logging

Key Features

Search Capabilities

• Web search integration
• News search functionality
• Query refinement
• Results aggregation

LLM Integration

• Primary LLM (Groq)
• Fallback LLM (OpenAI)
• Provider configuration
• Error handling

Data Management

• Search activity logging
• Results persistence
• Organization isolation
• User tracking

API Operations

Search Request

# Request Format
{
    "message": str,
    "context": dict,
    "user_id": str,
    "conversation_id": str,
    "organization_id": str,
    "intent_data": {
        "current_events": bool
    }
}
 
# Response Format
{
    "success": bool,
    "message": str,
    "tokens": {
        "prompt_tokens": int,
        "completion_tokens": int,
        "total_tokens": int
    },
    "metadata": {
        "request_id": str,
        "organization_id": str,
        "refined_query": str,
        "sources": List[dict],
        "search_type": str
    }
}

Integration

External Services

• Tavily Search API
• Groq LLM API
• OpenAI API (fallback)

Internal Integration

• Lyra: Email notifications
• Niger: Data persistence
• Bauri: Scheduled tasks

Performance Features

Search Optimization

• Query refinement
• Results processing
• Response generation
• Error recovery

Data Management

• Efficient storage
• Activity tracking
• Result caching
• Performance monitoring

Error Handling

• LLM provider failures
• Search API errors
• Processing issues
• Comprehensive logging

Scheduled Tasks

News Updates

• Automated news searches
• Email notifications
• Results storage
• User preferences

Data Models

Search Activity

{
    "request_id": str,
    "original_query": str,
    "refined_query": str,
    "search_type": str,
    "sources": List[dict],
    "tokens": dict,
    "success": bool
}

Search Results

{
    "id": UUID,
    "user_id": str,
    "organization_id": str,
    "results": JSON,
    "created_at": datetime
}