How jash4305/berkshire-hathaway-rag works
Project Type and Purpose
• This is a full-stack Retrieval-Augmented-Generation (RAG) system for interactive Q&A over Warren Buffett’s shareholder letters.
• It consists of two main workflows:
• Ingestion Pipeline – to parse documents, generate embeddings, and store them in a vector‐enabled PostgreSQL database.
• Query/API Layer – to accept user questions via a UI, perform semantic search + LLM calls, and return answers with citations.
High‐Level Components
a. User Interface (Web Client)
• A browser‐based chat interface (accessed on http://localhost:4111).
• Streaming responses, conversation memory, and citation display.
b. API / Application Server
• A Node.js TypeScript service (entrypoint via src/mastra/index.ts, built & run with npm run dev / npm run start).
• Hosts HTTP endpoints for:
1. Ingestion trigger (npm run ingest → src/run-ingestion.ts).
2. Chat queries (handled by Mastra workflows).
c. Ingestion Workflow
• src/mastra/workflows/ingestion-workflow.ts: orchestrates reading PDF/text files, calling the Berkshire‐tool for text extraction, generating embeddings, and inserting vector records.
• Relies on src/mastra/tools/berkshire-tool.ts.
d. Query Workflow
• src/mastra/workflows/weather-workflow.ts (example of a second domain) & primary chat workflow in src/mastra/index.ts.
• Agents (src/mastra/agents/*.ts) orchestrate LLM calls + tool invocations.
e. Tools & Agents
• Tools encapsulate concrete actions:
• berkshire-tool.ts (loads shareholder letters, returns chunks).
• weather-tool.ts (retrieves live weather data).
• Agents implement chain logic: call the LLM, decide on tool invocation, and parse results.
f. Vector Store (PostgreSQL + pgvector)
• Database schema defined in src/database/schema.sql.
• src/mastra/vectors/postgres-vector.ts wraps vector insert/search.
g. External Services
• OpenAI API for embeddings & GPT-4o calls.
• PostgreSQL for persistent vector storage.
Relationships and Data Flows
• Ingestion flow (one‐time):
User or CI → run-ingestion.ts → Ingestion Workflow → Berkshire‐tool → Text chunks → OpenAI Embeddings API → Postgres Vector Store
• Query/chat flow:
Web Client → HTTP API endpoint in index.ts → Query Workflow/Agent →
• Vector Store (semantic search)
• OpenAI Chat API →
→ Query Workflow aggregates results with citations → API returns streamed chat to Web Client
Architectural Patterns & Design Principles
• RAG (Retrieval before Generation)
• Separation of concerns:
• Ingestion vs. Query pipelines
• Agents vs. Tools vs. Vector store wrapper
• Modular design using Mastra framework for workflows & agents
Technologies & Frameworks to Call Out
• TypeScript / Node.js
• Mastra (workflow/agent orchestration)
• OpenAI (GPT-4o & Embeddings)
• PostgreSQL + pgvector
• NPM scripts as “infrastructure as code” for setup & execution