Dokumentacja Techniczna

Dokumentacja to most między kodem a ludźmi. Dobra dokumentacja sprawia, że projekt żyje nawet gdy Ty śpisz!

README.md - wizytówka projektu

1# 🤖 AI Document Assistant
2
3Inteligentny asystent do przeszukiwania dokumentów wykorzystujący RAG.
4
5## ✨ Funkcje
6
7- 🔍 Semantic search w dokumentach
8- 💬 Odpowiedzi w języku naturalnym
9- 📄 Obsługa PDF, DOCX, TXT
10- ⚡ Szybkie odpowiedzi (<2s)
11
12## 🚀 Quick Start
13
14### Wymagania
15- Python 3.11+
16- Docker (dla Qdrant)
17
18### Instalacja
19
20~~~bash
21# Klonuj repo
22git clone https://github.com/user/ai-doc-assistant.git
23cd ai-doc-assistant
24
25# Utwórz środowisko
26python -m venv venv
27source venv/bin/activate
28
29# Zainstaluj zależności
30pip install -r requirements.txt
31
32# Uruchom Qdrant
33docker-compose up -d qdrant
34
35# Ustaw zmienne środowiskowe
36cp .env.example .env
37# Edytuj .env i dodaj OPENAI_API_KEY
38
39# Uruchom aplikację
40uvicorn app.main:app --reload

📖 API Documentation

Po uruchomieniu: http://localhost:8000/docs

🏗️ Architecture

[Link do diagramu architektury]

🧪 Testing

1pytest tests/ -v

📝 License

MIT

1
2## Docstrings - dokumentacja w kodzie
3
4~~~python
5from typing import Optional
6
7class RAGService:
8    """
9    Serwis RAG do odpowiadania na pytania na podstawie dokumentów.
10
11    Ten serwis implementuje pełny pipeline RAG:
12    1. Embedding pytania
13    2. Wyszukiwanie podobnych dokumentów
14    3. Generowanie odpowiedzi z kontekstem
15
16    Attributes:
17        vector_store: Klient do vector database
18        llm: Klient do modelu językowego
19        embedder: Serwis do tworzenia embeddingów
20
21    Example:
22        >>> service = RAGService(vector_store, llm, embedder)
23        >>> response = await service.query("Co to jest Python?")
24        >>> print(response.answer)
25        "Python to język programowania..."
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        Wykonuje zapytanie RAG.
46
47        Args:
48            question: Pytanie użytkownika w języku naturalnym
49            top_k: Liczba dokumentów do pobrania (default: 5)
50            filters: Opcjonalne filtry metadanych
51
52        Returns:
53            Response: Obiekt zawierający odpowiedź i źródła
54
55        Raises:
56            ValueError: Gdy pytanie jest puste
57            LLMError: Gdy wystąpi błąd generowania
58
59        Example:
60            >>> response = await service.query(
61            ...     "Jak działa RAG?",
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 z FastAPI

1from fastapi import FastAPI, HTTPException
2from pydantic import BaseModel, Field
3
4app = FastAPI(
5    title="AI Document Assistant API",
6    description="REST API dla inteligentnego asystenta dokumentów",
7    version="1.0.0",
8    docs_url="/docs",
9    redoc_url="/redoc"
10)
11
12class QueryRequest(BaseModel):
13    """Request do zapytania RAG."""
14    question: str = Field(
15        ...,
16        description="Pytanie w języku naturalnym",
17        example="Co to jest machine learning?"
18    )
19    top_k: int = Field(
20        default=5,
21        ge=1,
22        le=20,
23        description="Liczba dokumentów źródłowych"
24    )
25
26class QueryResponse(BaseModel):
27    """Odpowiedź z systemu RAG."""
28    answer: str = Field(description="Wygenerowana odpowiedź")
29    sources: list[dict] = Field(description="Dokumenty źródłowe")
30    latency_ms: float = Field(description="Czas odpowiedzi w ms")
31
32@app.post(
33    "/query",
34    response_model=QueryResponse,
35    summary="Zadaj pytanie",
36    description="Wykonuje zapytanie RAG i zwraca odpowiedź z źródłami"
37)
38async def query(request: QueryRequest) -> QueryResponse:
39    """
40    Endpoint do zadawania pytań systemowi RAG.
41
42    - **question**: Pytanie w języku naturalnym
43    - **top_k**: Liczba dokumentów do przeszukania
44    """
45    pass

Dobra dokumentacja to inwestycja, która się zwraca. W następnej lekcji - deployment!