How profe168/rag-workshop-code works
Project Type and Purpose
• This is a Node.js/TypeScript sample project demonstrating a Retrieval-Augmented Generation (RAG) pipeline using the Mastra library.
• It provides scripts for document chunking, embedding, vector store operations, semantic search via agents, and evaluation of a RAG workflow.
High‑Level Architecture Analysis
• There is no web frontend. The system is a collection of command‑line scripts orchestrating a data ingestion and query pipeline.
• Top‑level modules:
• src/rag – document chunking, embedding, upserting, searching, reranking, generation
• src/mastra – agent and tool abstractions wrapping Mastra’s APIs
• src/bonus – code‑search examples and bonus documents
• src/eval – evaluation routines measuring RAG accuracy
• External dependencies/tools:
• OpenAI API (for embeddings and generation)
• PostgreSQL with pgvector extension (vector database)
• Environment variables in .env for API keys and DB connection
• Docker Compose for spinning up the database
Main Components
• Document Store (ファイルシステム): markdown and JSON documents in src/documents
• Chunker Module (04 strategies): character, recursive, JSON, markdown chunkers
• Embedding Module: calls OpenAI embedding APIs
• Vector Store (PostgreSQL + pgvector): stores and indexes vectors
• Retrieval Module: vector similarity search and reranking
• Agent Layer (Mastra):
• Basic‑search agent
• Query‑vector agent
• Tool abstraction for search operations
• Evaluation Module: scripts in src/eval measuring relevancy
• Bonus Code Search: specialized agent using code documents
Relationships and Data Flows
• Ingestion Flow:
Documents → Chunker → Embedder → Vector Store
(use upsert.ts and 06-vector-upserting.ts)
• Query Flow:
User Query → Agent (Mastra) → Vector Store Search → (Optional) Reranker → Response Generation
(see 07-vector-search.ts, 08-vector-reranking.ts, 09‑10 agent examples)
• Evaluation Flow:
Sample queries + ground truth → src/eval scripts → Metrics
• Bonus Flow:
Code base documents → Bonus agent → Code usage results
Architectural Patterns and Principles
• Modular design: each pipeline step is a separate script/module
• Clear separation of concerns: chunking, embedding, storage, retrieval, evaluation
• Pluggable agents/tools using Mastra abstractions
• Externalized configuration via .env for API keys and DB connection
• Use of containerized DB for reproducibility (docker-compose.yml)