Mahdi Bazrafshan
754da323ff
Why: - Need documentation for team onboarding and reference - Need technical details for strategy implementations - Need API reference for developers Changes: - README.md: Documentation index and quick start guide - api-reference.md: All 10 endpoints with examples - architecture.md: System structure and design decisions - configuration.md: All environment variables and parameters - data-flow.md: How data moves through the system - evaluation-metrics.md: How scoring works with weights - strategy-technical-details.md: Deep dive into each strategy's implementation
104 lines
4.1 KiB
Markdown
104 lines
4.1 KiB
Markdown
# Documentation Index
|
|
|
|
Complete documentation for the RAG Chunking Benchmarker.
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
1. **New to the project?** Start with [Architecture Overview](architecture.md)
|
|
2. **Want to understand strategies?** Read [Strategy Technical Details](strategy-technical-details.md)
|
|
3. **Need to use the API?** Check [API Reference](api-reference.md)
|
|
4. **Configuring the system?** See [Configuration Guide](configuration.md)
|
|
5. **Understanding results?** Read [Evaluation Metrics](evaluation-metrics.md)
|
|
6. **Curious about data flow?** See [Data Flow](data-flow.md)
|
|
|
|
---
|
|
|
|
## Documentation Files
|
|
|
|
| File | Purpose | Audience |
|
|
|------|---------|----------|
|
|
| [architecture.md](architecture.md) | System structure and design | New team members |
|
|
| [strategy-technical-details.md](strategy-technical-details.md) | Deep dive into each strategy | Engineers |
|
|
| [api-reference.md](api-reference.md) | All endpoints documented | Developers |
|
|
| [configuration.md](configuration.md) | Settings and environment variables | DevOps |
|
|
| [evaluation-metrics.md](evaluation-metrics.md) | How scoring works | Data scientists |
|
|
| [data-flow.md](data-flow.md) | How data moves through the system | Engineers |
|
|
| [chunking_strategies.md](chunking_strategies.md) | High-level strategy overview | Everyone |
|
|
| [phases.md](phases.md) | Implementation phases | Project managers |
|
|
| [tasks.md](tasks.md) | Task tracking | Developers |
|
|
|
|
---
|
|
|
|
## Architecture at a Glance
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ RAG Chunking Benchmarker │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ Documents → Parser → Chunking → Embedding → Qdrant │
|
|
│ │
|
|
│ Questions → Query Pipeline → LLM → Answers │
|
|
│ │
|
|
│ Answers → Evaluation → Metrics → Reports │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Key Concepts
|
|
|
|
### Chunking Strategies
|
|
|
|
| Strategy | Splitting | Best For |
|
|
|----------|-----------|----------|
|
|
| fixed_size | Token count | Baseline comparison |
|
|
| recursive | Structural boundaries | Structured documents |
|
|
| semantic | Similarity thresholds | Topic shifts |
|
|
| contextual_retrieval | LLM-enriched tokens | Retrieval quality |
|
|
| semantic_parent_child | Paragraph clusters | Context needed |
|
|
|
|
### Evaluation Metrics
|
|
|
|
| Metric | What It Measures |
|
|
|--------|------------------|
|
|
| Context Relevance | Did we find the right information? |
|
|
| Answer Similarity | Did we produce the right answer? |
|
|
| Faithfulness | Is the answer trustworthy? |
|
|
| Hallucination | Did we invent information? |
|
|
|
|
---
|
|
|
|
## API Endpoints
|
|
|
|
| Endpoint | Method | Purpose |
|
|
|----------|--------|---------|
|
|
| `/documents` | GET/POST | Manage documents |
|
|
| `/documents/{id}/process` | POST | Run chunking strategies |
|
|
| `/queries` | POST | Ask questions |
|
|
| `/benchmarks` | POST | Run comparisons |
|
|
| `/benchmarks/{id}/report` | GET | View results |
|
|
| `/experiments` | GET | List experiments |
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
All settings via `.env` file. See [Configuration Guide](configuration.md) for details.
|
|
|
|
Key settings:
|
|
- `OPENAI_API_KEY` - Required for embeddings and LLM
|
|
- `CHUNK_SIZE` - Target tokens per chunk (default: 512)
|
|
- `SEMANTIC_THRESHOLD` - Similarity threshold (default: 0.5)
|
|
|
|
---
|
|
|
|
## Further Reading
|
|
|
|
- [Phases](phases.md) - Implementation roadmap
|
|
- [Tasks](tasks.md) - Task tracking
|
|
- [ADRs](adr/) - Architectural Decision Records
|