Cristian Sangucho

Conversational System

An agentic conversational system that enables multimodal interactions through text and speech, leveraging advanced LLM tooling and orchestration frameworks.

Agentic AI
Mistral LLM
Multimodal Interaction
Langgraph
Langchain
FastAPI
Swagger
SQLAlchemy
Alembic
Docker
PyTest
Pydantic

API Documentation

🌟 Project Overview

The Conversational System is an application that enables natural communication between users and AI through multiple modalities. It features:

  • Multimodal Interaction: Supports both text and audio (speech) inputs and responses
  • Conversation Memory: Maintains context across multiple exchanges using a stateful architecture
  • Tool Integration: Enhances AI capabilities through specialized tools that expand beyond the model’s knowledge
  • User Management: Tracks individual users and their conversation history
  • Containerized Deployment: Packaged for easy deployment with Docker and available on GitHub Container Registry

The system was designed for extensibility, with a clean separation between the conversation orchestration layer and the underlying model implementation, allowing for easy model swapping and tool integration.

🛠️ Technology Stack

Core AI Frameworks

  • Langchain: Powers the foundational LLM integration, prompt engineering, and tool binding
  • Langgraph: Orchestrates complex conversation flows and tool execution through directed graphs

Backend Infrastructure

  • FastAPI: High-performance API framework enabling both synchronous and asynchronous endpoints
  • SQLAlchemy: ORM for database interaction with asynchronous support
  • Alembic: Database migration management for version control of schema changes
  • MySQL: Relational database for storing users, conversations, and messages

DevOps & Testing

  • Docker & Docker Compose: Application containerization and orchestration
  • GitHub Actions: CD pipeline for automated building and publishing
  • GitHub Container Registry: Container image hosting and distribution
  • PyTest: Comprehensive test framework with async support for API endpoint testing

📚 What I Learned

Advanced LLM Orchestration

Langgraph Framework

  • Implemented stateful conversation flows using directed graph structures
  • Leveraged the graph-based approach to create complex decision trees for handling different user inputs
  • Utilized the StateGraph system to maintain conversation context across multiple turns
  • Implemented checkpoint management with MemorySaver for conversation persistence

Langchain Integration

  • Built tool-augmented agents that can execute external functions based on user requests
  • Created a binding mechanism between LLM capabilities and custom tools
  • Implemented proper prompt engineering for consistent AI personality
  • Utilized the MessagesState pattern for managing conversation history
# Tool definition showing function binding
@tool
def tool(query: str):
    """description"""
    return "value"

bound_model = model.bind_tools(tool)

Multimodal Interaction Processing

  • Implemented Speech-to-Text (STT) processing using Google’s recognition API
  • Created Text-to-Speech (TTS) generation with gTTS for audio responses
  • Designed a unified API that handles both text and audio seamlessly
  • Built proper file handling for temporary audio storage and processing

Database Design for Conversational Systems

  • Designed a schema optimized for conversation history storage
  • Implemented a three-table structure (Users, Conversations, Messages) for efficient data modeling
  • Used asynchronous database access patterns for improved performance

🚀 Engineering Insights

The application follows a clear separation of concerns with distinct layers:

  • API Layer: FastAPI routers defining endpoints for user interaction
  • Service Layer: Business logic implementing core functionality
  • Repository Layer: Data access abstraction for database operations
  • Model Layer: SQLAlchemy models representing database entities
  • Agent Layer: LLM and agent logic for conversational capabilities

Container Deployment

The project includes complete containerization with:

  • Multi-container setup: Separate containers for application and database
  • GitHub Container Registry: Automated builds and publishing on main branch updates on ghcr.io/cristian-sangucho-a/conversational-system-v1:latest
  • Environment Configuration: Flexible configuration through environment variables

Testing Strategy

A comprehensive testing approach:

  • Unit Tests: Isolated testing of individual components
  • Integration Tests: Testing API endpoints with mocked services
  • Mock Framework: Use of unittest.mock for isolating service behavior
  • Async Testing: Utilization of pytest-asyncio for asynchronous test cases