Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
233 lines (192 loc) · 7.86 KB

ARCHITECTURE.md

File metadata and controls

233 lines (192 loc) · 7.86 KB
Raw

Let's Talk Architecture Documentation

Overview

Let's Talk is a conversational RAG (Retrieval-Augmented Generation) system that enables interactive discussions with blog content. The system has been restructured into a modular, layered architecture for improved maintainability and scalability.

Architecture Principles

Separation of Concerns

  • Agents: AI conversation logic
  • API: Web interface and endpoints
  • Core: Business logic and data processing
  • Tools: External integrations
  • Utils: Helper functions
  • Shared: Common components

Dependency Direction

  • Outer layers depend on inner layers
  • Core business logic is independent
  • Configuration is centralized in shared module

Module Structure

lets_talk/
├── main.py                 # Application entry point
├── agents/                 # AI Agent Layer
│   ├── base.py            # Abstract base agent
│   ├── factory.py         # Agent factory pattern
│   ├── rag_agent.py       # RAG conversation agent
│   └── react_agent.py     # ReAct reasoning agent
├── api/                   # Web API Layer
│   ├── main.py            # FastAPI application
│   ├── dependencies.py    # Dependency injection
│   ├── endpoints/         # API routers
│   │   ├── health.py      # Health checks
│   │   ├── pipeline.py    # Pipeline management
│   │   └── scheduler.py   # Job scheduling
│   └── models/            # Request/response models
│       ├── common.py      # Shared models
│       ├── health.py      # Health check models
│       ├── pipeline.py    # Pipeline models
│       └── scheduler.py   # Scheduler models
├── core/                  # Core Business Logic Layer
│   ├── models/            # Domain models
│   │   ├── domain.py      # Business entities
│   │   └── state.py       # Agent state management
│   ├── pipeline/          # Data processing
│   │   ├── engine.py      # Pipeline execution
│   │   ├── jobs.py        # Job definitions
│   │   └── job_functions.py # Standalone functions
│   ├── rag/               # RAG functionality
│   │   └── retriever.py   # Document retrieval
│   └── scheduler/         # Job scheduling
│       ├── manager.py     # Scheduler management
│       ├── config.py      # Scheduler configuration
│       └── cli.py         # Command-line interface
├── tools/                 # External Integration Layer
│   ├── base.py            # Tool base class
│   ├── datetime/          # Date/time utilities
│   │   └── datetime_utils.py
│   └── external/          # External services
│       ├── contact.py     # Contact form integration
│       └── rss_feed.py    # RSS feed processing
├── utils/                 # Utility Layer
│   ├── blog/              # Blog processing
│   │   └── processors.py  # Document processing
│   ├── evaluation/        # Evaluation utilities
│   └── formatters.py      # Document formatting
├── data/                  # Data Access Layer
│   ├── repositories/      # Data repositories
│   └── migrations/        # Database migrations
└── shared/                # Shared Components Layer
    ├── config.py          # Application configuration
    ├── constants.py       # Application constants
    ├── exceptions.py      # Custom exceptions
    └── prompts/           # LLM prompt templates
        └── templates.py

Component Relationships

Agent Layer

  • Purpose: Handle user conversations and AI interactions
  • Dependencies: Core (RAG, models), Tools, Utils, Shared
  • Key Classes: BaseAgent, RAGAgent, ReactAgent, AgentFactory

API Layer

  • Purpose: Provide REST endpoints for web integration
  • Dependencies: Core (scheduler, pipeline), Shared
  • Key Components: FastAPI app, routers, Pydantic models

Core Layer

  • Purpose: Implement core business logic
  • Dependencies: Shared only (no external dependencies)
  • Key Components: Pipeline engine, RAG retriever, scheduler manager

Tools Layer

  • Purpose: Integrate with external services
  • Dependencies: Shared
  • Key Components: RSS feeds, contact forms, datetime utilities

Utils Layer

  • Purpose: Provide helper functions
  • Dependencies: Shared
  • Key Components: Document processors, formatters

Shared Layer

  • Purpose: Provide common functionality across all layers
  • Dependencies: None (base layer)
  • Key Components: Configuration, constants, exceptions, prompts

Data Flow

1. Conversation Flow

User Input → API → Agent → RAG Retriever → LLM → Response

2. Pipeline Flow

Raw Documents → Blog Processor → Embeddings → Vector Store → Retriever

3. Scheduling Flow

Schedule Config → Scheduler Manager → Pipeline Jobs → Execution → Monitoring

Configuration Management

Centralized Configuration

  • All configuration in shared/config.py
  • Environment variable loading
  • Type-safe configuration classes
  • Prompt template integration

Configuration Sources

  1. Environment variables (.env file)
  2. Default values in configuration
  3. Runtime configuration objects

Error Handling

Exception Hierarchy

  • Custom exceptions in shared/exceptions.py
  • Domain-specific error types
  • Proper error propagation through layers

Logging Strategy

  • Structured logging throughout application
  • Configurable log levels
  • Component-specific loggers

Testing Strategy

Unit Testing

  • Isolated component testing
  • Mock external dependencies
  • Test configuration variations

Integration Testing

  • End-to-end workflow testing
  • API endpoint testing
  • Database integration testing

Performance Testing

  • Pipeline performance monitoring
  • RAG retrieval benchmarking
  • API response time testing

Deployment Considerations

Entry Points

  • Web API: python lets_talk/main.py
  • Pipeline: python -m lets_talk.core.pipeline.engine
  • Scheduler: python -m lets_talk.core.scheduler.cli

Environment Variables

  • Development: .env file
  • Production: Environment-specific configuration
  • Container: Docker environment variables

Scalability

  • Modular architecture supports horizontal scaling
  • Stateless API design
  • Configurable worker pools for background tasks

Migration from Legacy Structure

Old Structure Issues

  • Monolithic files (webapp.py, agent.py, pipeline.py)
  • Circular dependencies
  • Mixed concerns
  • Difficult to test and maintain

New Structure Benefits

  • Clear separation of concerns
  • Minimal coupling between components
  • Easy to extend and modify
  • Better testability
  • Type safety improvements

Migration Guide

# Old imports
from lets_talk.agent import RAGAgent
from lets_talk.webapp import app
from lets_talk.scheduler import PipelineScheduler

# New imports
from lets_talk.agents import create_rag_agent
from lets_talk.api.main import app
from lets_talk.core.scheduler.manager import PipelineScheduler

Future Enhancements

Planned Improvements

  1. Enhanced Agent Capabilities: More sophisticated reasoning
  2. Advanced RAG: Better retrieval and ranking
  3. Real-time Updates: Live content synchronization
  4. Multi-tenancy: Support multiple blog sources
  5. Performance Optimization: Caching and query optimization

Extension Points

  • New agent types via factory pattern
  • Additional API endpoints via FastAPI routers
  • Custom tools via base tool class
  • New pipeline stages via engine extension
  • Custom schedulers via manager inheritance

This architecture provides a solid foundation for building and maintaining a sophisticated conversational AI system while keeping the codebase organized and extensible.