How last-dance-collective/chatboxd works
Project type and purpose
• Project type: Full-stack web application with a single-page UI (Streamlit) that leverages Large Language Models (via LangChain/LangGraph) to query and analyze user movie data from Letterboxd.
• Purpose: Enable chat-based exploration of a user’s Letterboxd data (reviews, diary entries) and external movie details, using LLM agents and custom “tools.”
File structure
• src/main.py → Entry point for Streamlit UI.
• src/config.py + src/enviroment_config.py → Application configuration.
• src/data_ingestion/ → Batch script to load and transform CSV exports into SQLite (letterboxd.db).
• src/services/ → Definitions of agent “tools” and services: LLM interface, graph generation, database access, movie-data retrieval.
• src/catalog/ → Prompt templates, styles, translations for chat UI.
• src/utils/ → Helper modules (file loaders, session, logging, LLM/agent utilities).
• letterboxd.db → SQLite database.
Extract architectural insights from the README
• Core components: Streamlit frontend, SQLite database, ReAct agent built on LangChain/LangGraph, external services (OpenAI/Ollama, OMDb API).
• Agent pattern: Filter → Reason → Act → Observe loop, invoking “tools” to query DB or external APIs.
• Data ingestion pipeline: CSV → sqlite_utils → populated tables (reviews, diary) with E/R model.
a. Frontend (Streamlit UI)
• Hosts chat interface, renders graphs/images, collects user input.
• Calls backend Python functions via Streamlit’s process.
b. Application Layer / Agent Orchestrator
• LangChain/LangGraph orchestrator module sits here.
• Implements Filter → Agent (ReAct) loop, dispatches tool calls.
• Modules: llm_service (OpenAI/Ollama client), langgraph_service, agent_tools.
c. Tools/Services
• get_movies, get_reviews, get_graph, get_movie_details(extended).
• graph_services (generates network/visual graph).
• movies_data_service (OMDb fallback).
• sqlite_service (CRUD interface to letterboxd.db).
d. Data Layer
• SQLite database (reviews, diary tables).
• Data ingestion pipeline (data_ingestion/main.py, sqlite_utils).
e. External Services
• OpenAI API (chat/completion).
• OMDb API (movie metadata).
• (Optionally) Ollama local LLM endpoint.
Relationships and data flows
• User ↔ Streamlit UI: enters query / displays response.
• Streamlit UI → Agent Orchestrator: passes user message.
• Agent Orchestrator → llm_service: obtains next action (e.g., call tool).
• Agent Orchestrator → Tools → Data Layer or External Services.
• Tool outputs → Agent Orchestrator → llm_service (observe) → final response.
• Data Ingestion: separate offline pipeline that populates SQLite (one-way).
Architectural patterns and tech stack
• ReAct Agent Pattern (chain of thought + tool use).
• Modular “services” layer separating domain logic (DB, graph, API).
• Single-process Streamlit UI with embedded Python backend.
• SQLite as embedded relational DB for portability.
• LangChain & LangGraph for LLM orchestration.