Technical Documentation

Documentation is the bridge between code and people. Good documentation keeps a project alive even when you are asleep!

README.md - The Project's Business Card

1# 🤖 AI Document Assistant
2
3An intelligent assistant for searching documents using RAG.
4
5## ✨ Features
6
7- 🔍 Semantic search across documents
8- 💬 Answers in natural language
9- 📄 Support for PDF, DOCX, TXT
10- ⚡ Fast responses (<2s)
11
12## 🚀 Quick Start
13
14### Requirements
15- Python 3.11+
16- Docker (for Qdrant)
17
18### Installation
19
20~~~bash
21# Clone the repo
22git clone https://github.com/user/ai-doc-assistant.git
23cd ai-doc-assistant
24
25# Create environment
26python -m venv venv
27source venv/bin/activate
28
29# Install dependencies
30pip install -r requirements.txt
31
32# Launch Qdrant
33docker-compose up -d qdrant
34
35# Set environment variables
36cp .env.example .env
37# Edit .env and add OPENAI_API_KEY
38
39# Run the application
40uvicorn app.main:app --reload

📖 API Documentation

After launching: http://localhost:8000/docs

🏗️ Architecture

[Link to architecture diagram]

🧪 Testing

1pytest tests/ -v

📝 License

MIT

1
2## Docstrings - In-Code Documentation
3
4~~~python
5from typing import Optional
6
7class RAGService:
8    """
9    RAG service for answering questions based on documents.
10
11    This service implements the full RAG pipeline:
12    1. Embedding the question
13    2. Searching for similar documents
14    3. Generating a response with context
15
16    Attributes:
17        vector_store: Vector database client
18        llm: Language model client
19        embedder: Embedding service
20
21    Example:
22        >>> service = RAGService(vector_store, llm, embedder)
23        >>> response = await service.query("What is Python?")
24        >>> print(response.answer)
25        "Python is a programming language..."
26    """
27
28    def __init__(
29        self,
30        vector_store: VectorStore,
31        llm: LLMClient,
32        embedder: EmbeddingService
33    ):
34        self.vector_store = vector_store
35        self.llm = llm
36        self.embedder = embedder
37
38    async def query(
39        self,
40        question: str,
41        top_k: int = 5,
42        filters: Optional[dict] = None
43    ) -> Response:
44        """
45        Performs a RAG query.
46
47        Args:
48            question: User question in natural language
49            top_k: Number of documents to retrieve (default: 5)
50            filters: Optional metadata filters
51
52        Returns:
53            Response: Object containing the answer and sources
54
55        Raises:
56            ValueError: When the question is empty
57            LLMError: When a generation error occurs
58
59        Example:
60            >>> response = await service.query(
61            ...     "How does RAG work?",
62            ...     top_k=3,
63            ...     filters={"category": "ai"}
64            ... )
65        """
66        if not question.strip():
67            raise ValueError("Question cannot be empty")
68
69        # Implementation...

API Documentation with FastAPI

1from fastapi import FastAPI, HTTPException
2from pydantic import BaseModel, Field
3
4app = FastAPI(
5    title="AI Document Assistant API",
6    description="REST API for an intelligent document assistant",
7    version="1.0.0",
8    docs_url="/docs",
9    redoc_url="/redoc"
10)
11
12class QueryRequest(BaseModel):
13    """RAG query request."""
14    question: str = Field(
15        ...,
16        description="Question in natural language",
17        example="What is machine learning?"
18    )
19    top_k: int = Field(
20        default=5,
21        ge=1,
22        le=20,
23        description="Number of source documents"
24    )
25
26class QueryResponse(BaseModel):
27    """Response from the RAG system."""
28    answer: str = Field(description="Generated answer")
29    sources: list[dict] = Field(description="Source documents")
30    latency_ms: float = Field(description="Response time in ms")
31
32@app.post(
33    "/query",
34    response_model=QueryResponse,
35    summary="Ask a question",
36    description="Performs a RAG query and returns an answer with sources"
37)
38async def query(request: QueryRequest) -> QueryResponse:
39    """
40    Endpoint for asking questions to the RAG system.
41
42    - **question**: Question in natural language
43    - **top_k**: Number of documents to search
44    """
45    pass

Good documentation is an investment that pays off. In the next lesson - deployment!