ChunkScope

The n8n for RAG. Visual pipeline builder with AI suggestions, code export, and live evaluation.

---

Key Features

• Visual Pipeline Builder -- n8n-style drag-and-drop interface to assemble chunking, embedding, and retrieval stages
• AI Suggestion Engine -- auto-recommend chunking strategy, chunk size, embedding model, and retrieval method based on your documents
• Code Export -- generate framework-agnostic Python / FastAPI code from any pipeline configuration
• Live Evaluation Dashboard -- RAGAS-style metrics (faithfulness, relevance, context precision) computed in real time
• Side-by-Side Comparison -- run two pipeline configurations against the same queries and diff the results
• Cost Calculator -- estimate token and API costs before committing to a pipeline
• 8 Chunking Strategies -- Recursive, Semantic, Sentence-Window, Code-Aware, Fixed, Paragraph, Agentic, and Custom
• Multiple Embedding Providers -- OpenAI, Cohere, HuggingFace, and any provider reachable through LiteLLM
• Hybrid Retrieval + Reranking -- vector search, BM25, HyDE, Multi-Query, MMR, with optional cross-encoder reranking

---

Quick Start

git clone https://github.com/1Ash0/chunkscope.git
cd chunkscope
cp .env.example .env
# Add your API keys to .env
docker compose up

Open http://localhost:3000 to launch the UI. The API docs are at http://localhost:8000/api/docs.

---

Architecture

Frontend (Next.js :3000)
    |
    | REST / WebSocket
    v
Backend (FastAPI :8000)
    |
    | SQLAlchemy + asyncpg
    v
PostgreSQL + pgvector (:5432)

The frontend sends pipeline configurations and queries to the backend API. The backend orchestrates document processing, chunking, embedding, retrieval, and evaluation, storing vectors and metadata in PostgreSQL with the pgvector extension.

---

Tech Stack

Layer	Technologies
Frontend	Next.js 14, TypeScript, Tailwind CSS, React Flow, Zustand, Framer Motion
Backend	FastAPI, SQLAlchemy (async), Pydantic, LiteLLM
Database	PostgreSQL 16, pgvector
Infra	Docker Compose, Alembic migrations

---

API Endpoints

All routes are under /api/v1. Main groups:

Group	Description
/health	Liveness check
/projects	Project CRUD, file upload, analysis, chunking, chunk-status, sample-queries, validation
/documents	Upload and manage PDF/text documents
/chunks	Chunk documents with configurable strategies
/embeddings	Generate and store embeddings
/pipelines	Create, update, and execute full pipelines
/presets	Built-in and custom pipeline presets
/query	Run retrieval queries against a pipeline
/rerank	Cross-encoder reranking
/evaluations	RAGAS-style evaluation metrics
/suggestions	AI-powered configuration recommendations
/export	Generate Python code from pipeline config
/cost	Estimate token and API costs
/config	Available models, strategies, and providers

Full OpenAPI spec: http://localhost:8000/api/docs

---

Development Setup (without Docker)

Backend

cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt    # or: uv pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload --port 8000

Requires PostgreSQL with pgvector. Set DATABASE_URL in .env.

Frontend

cd frontend
npm install
npm run dev

Opens on http://localhost:3000.

---

License

MIT -- see LICENSE.md.