TRACE

AI-powered repository intelligence platform.

TRACE ingests documents, embeds them into vectors, and answers natural language questions using Retrieval-Augmented Generation (RAG).

Documentation: See docs/ for architecture guides, API references, and examples.

---

Features

• Document Ingestion — Import TXT, PDF, and Markdown with automatic type detection
• Text Normalization — Unicode normalization, whitespace cleanup, line stripping
• Semantic Chunking — Sentence-aware splitting with configurable size and overlap
• Embedding Generation — Dense vector representations using sentence-transformers (BAAI/bge-m3)
• Vector Database — Qdrant integration with automatic collection management
• Semantic Search — Top-k retrieval with cosine similarity scoring
• LLM Abstraction — Provider-agnostic interface supporting Ollama, OpenAI, and OpenRouter
• RAG Pipeline — Retrieval-Augmented Generation with grounded answers and citations
• REST API — FastAPI endpoints for ingest, index, query, and ask operations
• CLI — Command-line interface with colored output and progress indicators
• Benchmarking — Performance measurement with detailed statistics (avg, min, max, P95, P99)
• Evaluation — Retrieval quality metrics (Recall@K, Precision@K, MRR, NDCG)
• Docker Infrastructure — Qdrant vector database with Docker Compose

---

Architecture

flowchart LR
    A[Document] --> B[Ingestion]
    B --> C[Cleaning]
    C --> D[Chunking]
    D --> E[Embeddings]
    E --> F[(Vector Database)]
    F --> G[Retrieval]
    G --> H[Prompt Builder]
    H --> I[LLM]
    I --> J[Answer + Citations]

    style A fill:#e1f5fe
    style B fill:#e8f5e9
    style C fill:#e8f5e9
    style D fill:#fff3e0
    style E fill:#fce4ec
    style F fill:#f3e5f5
    style G fill:#e0f2f1
    style H fill:#ede7f6
    style I fill:#ede7f6
    style J fill:#e8f5e9

Loading

Layer	Description
Ingestion	File parsing, type detection, text extraction
Cleaning	Unicode normalization, whitespace collapse
Chunking	Sentence-aware splitting with overlap
Embeddings	Dense vector generation (BAAI/bge-m3)
Vector Database	Qdrant storage and similarity search
Retrieval	Top-k semantic search
Prompt Builder	Context assembly from retrieved chunks
LLM	Provider-agnostic generation (Ollama/OpenAI/OpenRouter)
RAG	Grounded answers with source citations

---

Tech Stack

Component	Technology
Frontend	Next.js, React, TypeScript, TailwindCSS, Shadcn UI
Backend API	FastAPI, Pydantic, Uvicorn
CLI	Click, Rich
Embeddings	sentence-transformers (BAAI/bge-m3)
Vector Database	Qdrant
LLM Providers	Ollama, OpenAI, OpenRouter
Containerization	Docker, Docker Compose
Language	Python 3.11+, TypeScript

---

Project Structure

trace/
├── apps/
│   ├── backend/
│   │   ├── api/              # FastAPI route handlers
│   │   ├── core/             # Shared interfaces, config, models
│   │   ├── ingestion/        # Document readers (TXT, PDF, Markdown)
│   │   ├── chunking/         # Sentence-aware text splitting
│   │   ├── embeddings/       # sentence-transformers integration
│   │   ├── vectorstore/      # Qdrant vector storage
│   │   ├── llm/              # LLM provider abstraction
│   │   ├── rag/              # RAG pipeline and prompt builder
│   │   ├── pipeline/         # Index pipeline orchestration
│   │   ├── benchmark/        # Performance benchmarking
│   │   ├── evaluation/       # Retrieval quality evaluation
│   │   ├── repository/       # Repository analysis & knowledge graph
│   │   ├── retrieval/        # Hybrid retrieval engine
│   │   ├── cli/              # Command-line interface
│   │   ├── tests/            # Unit and integration tests
│   │   └── main.py           # FastAPI application
│   └── web/                  # Next.js frontend
│       ├── src/app/          # Pages (Dashboard, Chat, Upload, etc.)
│       ├── src/components/   # UI components
│       ├── src/hooks/        # React Query hooks
│       └── src/lib/          # API client and utilities
├── docs/                     # Documentation
├── docker-compose.yml        # Infrastructure
└── .env.example              # Configuration template

---

Installation

Prerequisites

• Python 3.11+
• Docker and Docker Compose

Setup

git clone https://github.com/Feroan101/trace.git
cd trace

python -m venv .venv
source .venv/bin/activate

pip install -e "apps/backend[dev]"

cp .env.example .env

Start Infrastructure

docker compose up -d

This starts:

• Qdrant — http://localhost:6333 (vector database)

The backend and frontend services can also be started with Docker:

docker compose up -d --build

---

Usage

CLI

# Check system health
trace health

# Ingest documents
trace ingest /path/to/document.txt
trace ingest /path/to/documents/

# Search (retrieval only)
trace search "How does the embedding engine work?"

# Ask questions (RAG)
trace query "What is the architecture of TRACE?"

# View statistics
trace stats

# Run benchmarks
trace benchmark -n 5

# Run evaluation
trace evaluate apps/backend/evaluation/sample_dataset.json

API

# Start the server
uvicorn apps.backend.main:app --reload

Method	Endpoint	Description
GET	/health	Health check
POST	/ingest	Ingest a document
POST	/index	Full pipeline: ingest → chunk → embed → store
POST	/query	Semantic search
POST	/ask	RAG question answering

Examples:

# Ingest
curl -X POST http://localhost:8000/ingest \
  -H "Content-Type: application/json" \
  -d '{"source": "path/to/document.txt"}'

# Search
curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{"query": "How does authentication work?", "top_k": 5}'

# Ask
curl -X POST http://localhost:8000/ask \
  -H "Content-Type: application/json" \
  -d '{"query": "What are the core modules?", "top_k": 3}'

Testing

python -m pytest apps/backend/tests/ -v

Frontend

cd apps/web
npm install
npm run dev

The frontend will be available at http://localhost:3000.

Page	Description	Backend Support
/	Dashboard - API health status and quick start guide	Live via /health
/upload	Index documents and repositories	Live via /index
/chat	RAG chat interface with source citations	Live via /ask
/repositories	Repository list (CLI-driven)	Empty state - use trace repo analyze
/benchmarks	Performance metrics (CLI-driven)	Empty state - use trace benchmark run
/evaluation	Retrieval quality metrics (CLI-driven)	Empty state - use trace evaluate run
/settings	Configuration overview	Read-only - configure via .env

---

Configuration

All settings use environment variables with the TRACE_ prefix.

Variable	Default	Description
TRACE_EMBEDDING_MODEL	BAAI/bge-m3	Sentence-transformer model
TRACE_EMBEDDING_DIMENSION	1024	Vector dimension
TRACE_QDRANT_URL	http://localhost:6333	Qdrant endpoint
TRACE_QDRANT_COLLECTION	trace_chunks	Collection name
TRACE_CHUNK_TARGET_TOKENS	500	Target tokens per chunk
TRACE_CHUNK_OVERLAP_RATIO	0.12	Chunk overlap ratio
TRACE_LLM_PROVIDER	ollama	LLM provider: ollama, openai, openrouter
TRACE_LLM_MODEL	llama3.2	Model name
TRACE_LLM_API_KEY	(empty)	API key for OpenAI/OpenRouter
TRACE_LLM_TEMPERATURE	0.7	Generation temperature
TRACE_LLM_MAX_TOKENS	2048	Max output tokens
TRACE_LLM_TIMEOUT	30.0	Request timeout (seconds)
TRACE_RAG_TOP_K	5	Context chunks to retrieve
TRACE_RAG_MIN_RELEVANCE	0.3	Minimum similarity threshold
TRACE_RAG_MAX_CONTEXT_LENGTH	8000	Max context chars in prompt

---

License

MIT License. See LICENSE for details.