AIenthusSP commited on
Commit
b6fa51d
·
1 Parent(s): 7640b67

feat: implement FastAPI application structure

Browse files

- Add main FastAPI app with CORS and lifespan
- Add Pydantic models for all endpoints
- Add health check endpoints
- Add /api/query with streaming support
- Add /api/ingest with file upload
- Update settings with API configuration

config/settings.py CHANGED
@@ -49,6 +49,19 @@ class Settings(BaseSettings):
49
  temperature: float = Field(default=0.3, alias="TEMPERATURE")
50
  max_tokens: int = Field(default=2048, alias="MAX_TOKENS")
51
 
 
 
 
 
 
 
 
 
 
 
 
 
 
52
  # Paths
53
  @property
54
  def project_root(self) -> Path:
 
49
  temperature: float = Field(default=0.3, alias="TEMPERATURE")
50
  max_tokens: int = Field(default=2048, alias="MAX_TOKENS")
51
 
52
+ # API Settings
53
+ api_host: str = Field(default="0.0.0.0", alias="API_HOST")
54
+ api_port: int = Field(default=8000, alias="API_PORT")
55
+ cors_origins: list = Field(
56
+ default=["http://localhost:3000", "http://localhost:8501"],
57
+ alias="CORS_ORIGINS"
58
+ )
59
+
60
+ @property
61
+ def environment(self) -> str:
62
+ """Get the environment name."""
63
+ return self.app_env
64
+
65
  # Paths
66
  @property
67
  def project_root(self) -> Path:
docs/explanations/api.md ADDED
@@ -0,0 +1,214 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # 🔍 Deep Dive: FastAPI Application Architecture
2
+
3
+ ## 🧠 Why FastAPI for RAG?
4
+
5
+ ```
6
+ ┌─────────────────────────────────────────────────────────────────┐
7
+ │ FASTAPI BENEFITS │
8
+ │ │
9
+ │ ✅ Async support → Efficient I/O for LLM calls │
10
+ │ ✅ Automatic docs → Swagger UI at /docs │
11
+ │ ✅ Pydantic → Type validation and serialization │
12
+ │ ✅ Streaming → SSE for real-time responses │
13
+ │ ✅ Production-ready → Used by Netflix, Uber, Microsoft │
14
+ └─────────────────────────────────────────────────────────────────┘
15
+ ```
16
+
17
+ ---
18
+
19
+ ## 📐 Architecture Overview
20
+
21
+ ```
22
+ src/api/
23
+ ├── main.py # Application entry point
24
+ ├── models.py # Pydantic request/response models
25
+ ├── __init__.py
26
+ └── routes/
27
+ ├── __init__.py
28
+ ├── health.py # Health check endpoints
29
+ ├── query.py # Query/RAG endpoints
30
+ └── ingest.py # Document ingestion endpoints
31
+ ```
32
+
33
+ ---
34
+
35
+ ## 🎯 main.py - Application Entry Point
36
+
37
+ ### FastAPI App Configuration
38
+
39
+ ```python
40
+ app = FastAPI(
41
+ title="DocuMind AI",
42
+ description="RAG-Powered Documentation Assistant API",
43
+ version="1.0.0",
44
+ docs_url="/docs", # Swagger UI
45
+ redoc_url="/redoc", # ReDoc alternative
46
+ lifespan=lifespan, # Startup/shutdown events
47
+ )
48
+ ```
49
+
50
+ ### Lifespan Context Manager
51
+
52
+ ```python
53
+ @asynccontextmanager
54
+ async def lifespan(app: FastAPI):
55
+ # Startup
56
+ logger.info("Starting DocuMind AI API...")
57
+ yield
58
+ # Shutdown
59
+ logger.info("Shutting down...")
60
+ ```
61
+
62
+ ### CORS Configuration
63
+
64
+ ```python
65
+ app.add_middleware(
66
+ CORSMiddleware,
67
+ allow_origins=settings.cors_origins, # ["localhost:3000", "localhost:8501"]
68
+ allow_credentials=True,
69
+ allow_methods=["*"],
70
+ allow_headers=["*"],
71
+ )
72
+ ```
73
+
74
+ ---
75
+
76
+ ## 📋 models.py - Pydantic Schemas
77
+
78
+ ### QueryRequest
79
+
80
+ ```python
81
+ class QueryRequest(BaseModel):
82
+ question: str = Field(..., min_length=1, max_length=2000)
83
+ collection_name: str = Field(default="documents")
84
+ top_k: int = Field(default=5, ge=1, le=20)
85
+ include_sources: bool = Field(default=True)
86
+ ```
87
+
88
+ ### QueryResponse
89
+
90
+ ```python
91
+ class QueryResponse(BaseModel):
92
+ answer: str
93
+ question: str
94
+ sources: Optional[List[SourceDocument]]
95
+ num_sources: Optional[int]
96
+ ```
97
+
98
+ ### IngestResponse
99
+
100
+ ```python
101
+ class IngestResponse(BaseModel):
102
+ success: bool
103
+ message: str
104
+ documents_processed: int
105
+ chunks_created: int
106
+ collection_name: str
107
+ ```
108
+
109
+ ---
110
+
111
+ ## 🛣️ Routes
112
+
113
+ ### Health Routes (`/health`)
114
+
115
+ | Endpoint | Method | Purpose |
116
+ |----------|--------|---------|
117
+ | `/health` | GET | Basic health check |
118
+ | `/health/detailed` | GET | Component-level health |
119
+ | `/ready` | GET | Kubernetes readiness |
120
+ | `/live` | GET | Kubernetes liveness |
121
+
122
+ ### Query Routes (`/api/query`)
123
+
124
+ | Endpoint | Method | Purpose |
125
+ |----------|--------|---------|
126
+ | `/api/query` | POST | Standard RAG query |
127
+ | `/api/query/stream` | POST | Streaming response |
128
+
129
+ ### Ingest Routes (`/api/ingest`)
130
+
131
+ | Endpoint | Method | Purpose |
132
+ |----------|--------|---------|
133
+ | `/api/ingest` | POST | Upload files |
134
+ | `/api/ingest/text` | POST | Ingest raw text |
135
+ | `/api/ingest/{collection}` | DELETE | Delete collection |
136
+
137
+ ---
138
+
139
+ ## 🔄 Query Flow
140
+
141
+ ```
142
+ POST /api/query
143
+ {
144
+ "question": "What is the refund policy?",
145
+ "collection_name": "documents",
146
+ "top_k": 5,
147
+ "include_sources": true
148
+ }
149
+ ↓
150
+ get_pipeline(collection_name, top_k)
151
+ ↓
152
+ pipeline.query(question, include_sources)
153
+ ↓
154
+ {
155
+ "answer": "Based on the documentation...",
156
+ "question": "What is the refund policy?",
157
+ "sources": [...],
158
+ "num_sources": 3
159
+ }
160
+ ```
161
+
162
+ ---
163
+
164
+ ## 📤 Ingest Flow
165
+
166
+ ```
167
+ POST /api/ingest
168
+ [files: policy.pdf, guide.md]
169
+ ↓
170
+ Validate file extensions (.pdf, .md, .txt)
171
+ ↓
172
+ Save to temp files
173
+ ↓
174
+ MultiFormatDocumentLoader.load_file()
175
+ ↓
176
+ DocumentChunker.chunk_documents()
177
+ ↓
178
+ VectorStore.add_documents()
179
+ ↓
180
+ {
181
+ "success": true,
182
+ "documents_processed": 2,
183
+ "chunks_created": 15
184
+ }
185
+ ```
186
+
187
+ ---
188
+
189
+ ## 🚀 Running the API
190
+
191
+ ```bash
192
+ # Development
193
+ python -m src.api.main
194
+
195
+ # Or with uvicorn directly
196
+ uvicorn src.api.main:app --reload --host 0.0.0.0 --port 8000
197
+ ```
198
+
199
+ ### Access Points:
200
+ - **API**: http://localhost:8000
201
+ - **Swagger Docs**: http://localhost:8000/docs
202
+ - **ReDoc**: http://localhost:8000/redoc
203
+
204
+ ---
205
+
206
+ ## 📋 Summary
207
+
208
+ | File | Purpose |
209
+ |------|---------|
210
+ | `main.py` | App config, CORS, routers |
211
+ | `models.py` | Pydantic schemas |
212
+ | `routes/health.py` | Health checks |
213
+ | `routes/query.py` | RAG query endpoints |
214
+ | `routes/ingest.py` | File upload endpoints |
requirements.txt CHANGED
@@ -3,6 +3,7 @@ langchain>=0.3.0
3
  langchain-community>=0.3.0
4
  langchain-google-genai>=2.0.0
5
  langchain-chroma>=0.2.0
 
6
 
7
  # Vector Database
8
  chromadb>=0.5.0
 
3
  langchain-community>=0.3.0
4
  langchain-google-genai>=2.0.0
5
  langchain-chroma>=0.2.0
6
+ langchain-huggingface>=0.2.0
7
 
8
  # Vector Database
9
  chromadb>=0.5.0
src/api/main.py ADDED
@@ -0,0 +1,83 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ FastAPI Application - Main Entry Point
3
+
4
+ DocuMind AI - RAG-Powered Documentation Assistant API
5
+ """
6
+
7
+ import logging
8
+ from contextlib import asynccontextmanager
9
+
10
+ from fastapi import FastAPI
11
+ from fastapi.middleware.cors import CORSMiddleware
12
+
13
+ from src.api.routes import query, ingest, health
14
+ from config.settings import settings
15
+
16
+ # Configure logging
17
+ logging.basicConfig(
18
+ level=logging.INFO,
19
+ format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
20
+ )
21
+ logger = logging.getLogger(__name__)
22
+
23
+
24
+ @asynccontextmanager
25
+ async def lifespan(app: FastAPI):
26
+ """
27
+ Application lifespan manager.
28
+ Handles startup and shutdown events.
29
+ """
30
+ # Startup
31
+ logger.info("Starting DocuMind AI API...")
32
+ logger.info(f"Environment: {settings.environment}")
33
+
34
+ yield
35
+
36
+ # Shutdown
37
+ logger.info("Shutting down DocuMind AI API...")
38
+
39
+
40
+ # Create FastAPI application
41
+ app = FastAPI(
42
+ title="DocuMind AI",
43
+ description="RAG-Powered Documentation Assistant API",
44
+ version="1.0.0",
45
+ docs_url="/docs",
46
+ redoc_url="/redoc",
47
+ lifespan=lifespan,
48
+ )
49
+
50
+ # Configure CORS
51
+ app.add_middleware(
52
+ CORSMiddleware,
53
+ allow_origins=settings.cors_origins,
54
+ allow_credentials=True,
55
+ allow_methods=["*"],
56
+ allow_headers=["*"],
57
+ )
58
+
59
+ # Include routers
60
+ app.include_router(health.router, tags=["Health"])
61
+ app.include_router(query.router, prefix="/api", tags=["Query"])
62
+ app.include_router(ingest.router, prefix="/api", tags=["Ingest"])
63
+
64
+
65
+ @app.get("/")
66
+ async def root():
67
+ """Root endpoint with API info."""
68
+ return {
69
+ "name": "DocuMind AI",
70
+ "version": "1.0.0",
71
+ "description": "RAG-Powered Documentation Assistant",
72
+ "docs": "/docs",
73
+ }
74
+
75
+
76
+ if __name__ == "__main__":
77
+ import uvicorn
78
+ uvicorn.run(
79
+ "src.api.main:app",
80
+ host="0.0.0.0",
81
+ port=8000,
82
+ reload=True,
83
+ )
src/api/models.py ADDED
@@ -0,0 +1,158 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ Pydantic Models for API Request/Response
3
+
4
+ Defines the data structures for API communication.
5
+ """
6
+
7
+ from typing import List, Optional, Dict, Any
8
+ from pydantic import BaseModel, Field
9
+
10
+
11
+ # ============== Query Models ==============
12
+
13
+ class QueryRequest(BaseModel):
14
+ """Request model for query endpoint."""
15
+ question: str = Field(
16
+ ...,
17
+ description="The question to ask about the documents",
18
+ min_length=1,
19
+ max_length=2000,
20
+ examples=["What is the refund policy?"]
21
+ )
22
+ collection_name: str = Field(
23
+ default="documents",
24
+ description="Name of the document collection to search"
25
+ )
26
+ top_k: int = Field(
27
+ default=5,
28
+ description="Number of documents to retrieve",
29
+ ge=1,
30
+ le=20
31
+ )
32
+ include_sources: bool = Field(
33
+ default=True,
34
+ description="Whether to include source documents in response"
35
+ )
36
+
37
+
38
+ class SourceDocument(BaseModel):
39
+ """A source document used in the answer."""
40
+ content: str = Field(..., description="Document content snippet")
41
+ metadata: Dict[str, Any] = Field(
42
+ default_factory=dict,
43
+ description="Document metadata"
44
+ )
45
+ score: Optional[float] = Field(
46
+ None,
47
+ description="Relevance score"
48
+ )
49
+
50
+
51
+ class QueryResponse(BaseModel):
52
+ """Response model for query endpoint."""
53
+ answer: str = Field(..., description="Generated answer")
54
+ question: str = Field(..., description="Original question")
55
+ sources: Optional[List[SourceDocument]] = Field(
56
+ None,
57
+ description="Source documents used"
58
+ )
59
+ num_sources: Optional[int] = Field(
60
+ None,
61
+ description="Number of sources used"
62
+ )
63
+
64
+
65
+ # ============== Ingest Models ==============
66
+
67
+ class IngestRequest(BaseModel):
68
+ """Request model for file ingestion."""
69
+ collection_name: str = Field(
70
+ default="documents",
71
+ description="Name of the collection to ingest into"
72
+ )
73
+ chunk_size: int = Field(
74
+ default=1000,
75
+ description="Size of document chunks",
76
+ ge=100,
77
+ le=4000
78
+ )
79
+ chunk_overlap: int = Field(
80
+ default=200,
81
+ description="Overlap between chunks",
82
+ ge=0,
83
+ le=500
84
+ )
85
+
86
+
87
+ class IngestResponse(BaseModel):
88
+ """Response model for ingestion endpoint."""
89
+ success: bool = Field(..., description="Whether ingestion succeeded")
90
+ message: str = Field(..., description="Status message")
91
+ documents_processed: int = Field(
92
+ default=0,
93
+ description="Number of documents processed"
94
+ )
95
+ chunks_created: int = Field(
96
+ default=0,
97
+ description="Number of chunks created"
98
+ )
99
+ collection_name: str = Field(
100
+ ...,
101
+ description="Collection documents were added to"
102
+ )
103
+
104
+
105
+ class IngestTextRequest(BaseModel):
106
+ """Request model for text ingestion."""
107
+ text: str = Field(
108
+ ...,
109
+ description="Text content to ingest",
110
+ min_length=1,
111
+ max_length=100000
112
+ )
113
+ metadata: Dict[str, Any] = Field(
114
+ default_factory=dict,
115
+ description="Optional metadata for the document"
116
+ )
117
+ collection_name: str = Field(
118
+ default="documents",
119
+ description="Name of the collection"
120
+ )
121
+
122
+
123
+ # ============== Health Models ==============
124
+
125
+ class HealthResponse(BaseModel):
126
+ """Response model for health check."""
127
+ status: str = Field(..., description="Health status")
128
+ version: str = Field(..., description="API version")
129
+ environment: str = Field(..., description="Environment name")
130
+
131
+
132
+ class ComponentHealth(BaseModel):
133
+ """Health status of a component."""
134
+ name: str = Field(..., description="Component name")
135
+ status: str = Field(..., description="Component status")
136
+ details: Optional[str] = Field(None, description="Additional details")
137
+
138
+
139
+ class DetailedHealthResponse(BaseModel):
140
+ """Detailed health check response."""
141
+ status: str = Field(..., description="Overall status")
142
+ version: str = Field(..., description="API version")
143
+ components: List[ComponentHealth] = Field(
144
+ ...,
145
+ description="Component health statuses"
146
+ )
147
+
148
+
149
+ # ============== Error Models ==============
150
+
151
+ class ErrorResponse(BaseModel):
152
+ """Standard error response."""
153
+ error: str = Field(..., description="Error type")
154
+ message: str = Field(..., description="Error message")
155
+ details: Optional[Dict[str, Any]] = Field(
156
+ None,
157
+ description="Additional error details"
158
+ )
src/api/routes/__init__.py CHANGED
@@ -1 +1,5 @@
1
  # API Routes Package
 
 
 
 
 
1
  # API Routes Package
2
+ from src.api.routes import health, query, ingest
3
+
4
+ __all__ = ["health", "query", "ingest"]
5
+
src/api/routes/health.py ADDED
@@ -0,0 +1,137 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ Health Check Routes
3
+
4
+ Provides endpoints for monitoring API health and readiness.
5
+ """
6
+
7
+ import logging
8
+ from fastapi import APIRouter, HTTPException
9
+
10
+ from src.api.models import HealthResponse, DetailedHealthResponse, ComponentHealth
11
+ from config.settings import settings
12
+
13
+ logger = logging.getLogger(__name__)
14
+
15
+ router = APIRouter()
16
+
17
+
18
+ @router.get("/health", response_model=HealthResponse)
19
+ async def health_check():
20
+ """
21
+ Basic health check endpoint.
22
+
23
+ Returns the API status, version, and environment.
24
+ """
25
+ return HealthResponse(
26
+ status="healthy",
27
+ version="1.0.0",
28
+ environment=settings.environment,
29
+ )
30
+
31
+
32
+ @router.get("/health/detailed", response_model=DetailedHealthResponse)
33
+ async def detailed_health_check():
34
+ """
35
+ Detailed health check with component status.
36
+
37
+ Checks the health of each component:
38
+ - Embeddings model
39
+ - Vector store
40
+ - LLM connection
41
+ """
42
+ components = []
43
+ overall_status = "healthy"
44
+
45
+ # Check embeddings
46
+ try:
47
+ from src.rag.embeddings import get_embeddings
48
+ embeddings = get_embeddings()
49
+ # Quick test
50
+ _ = embeddings.embed_query("test")
51
+ components.append(ComponentHealth(
52
+ name="embeddings",
53
+ status="healthy",
54
+ details="Model loaded successfully"
55
+ ))
56
+ except Exception as e:
57
+ logger.error(f"Embeddings health check failed: {e}")
58
+ components.append(ComponentHealth(
59
+ name="embeddings",
60
+ status="unhealthy",
61
+ details=str(e)
62
+ ))
63
+ overall_status = "degraded"
64
+
65
+ # Check vector store
66
+ try:
67
+ from src.rag.vectorstore import create_vector_store
68
+ from src.rag.embeddings import get_embeddings
69
+ embeddings = get_embeddings()
70
+ store = create_vector_store(embeddings)
71
+ stats = store.get_collection_stats()
72
+ components.append(ComponentHealth(
73
+ name="vector_store",
74
+ status="healthy",
75
+ details=f"Collection: {stats['collection_name']}, Docs: {stats['document_count']}"
76
+ ))
77
+ except Exception as e:
78
+ logger.error(f"Vector store health check failed: {e}")
79
+ components.append(ComponentHealth(
80
+ name="vector_store",
81
+ status="unhealthy",
82
+ details=str(e)
83
+ ))
84
+ overall_status = "degraded"
85
+
86
+ # Check LLM
87
+ try:
88
+ from src.rag.llm import LLMManager
89
+ manager = LLMManager()
90
+ info = manager.get_model_info()
91
+ if info.get("api_key_configured"):
92
+ components.append(ComponentHealth(
93
+ name="llm",
94
+ status="healthy",
95
+ details=f"Model: {info['model_name']}"
96
+ ))
97
+ else:
98
+ components.append(ComponentHealth(
99
+ name="llm",
100
+ status="degraded",
101
+ details="API key not configured"
102
+ ))
103
+ overall_status = "degraded"
104
+ except Exception as e:
105
+ logger.error(f"LLM health check failed: {e}")
106
+ components.append(ComponentHealth(
107
+ name="llm",
108
+ status="unhealthy",
109
+ details=str(e)
110
+ ))
111
+ overall_status = "degraded"
112
+
113
+ return DetailedHealthResponse(
114
+ status=overall_status,
115
+ version="1.0.0",
116
+ components=components,
117
+ )
118
+
119
+
120
+ @router.get("/ready")
121
+ async def readiness_check():
122
+ """
123
+ Kubernetes-style readiness probe.
124
+
125
+ Returns 200 if the service is ready to accept traffic.
126
+ """
127
+ return {"ready": True}
128
+
129
+
130
+ @router.get("/live")
131
+ async def liveness_check():
132
+ """
133
+ Kubernetes-style liveness probe.
134
+
135
+ Returns 200 if the service is alive.
136
+ """
137
+ return {"alive": True}
src/api/routes/ingest.py ADDED
@@ -0,0 +1,217 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ Ingest Routes
3
+
4
+ Handles document ingestion into the vector store.
5
+ """
6
+
7
+ import logging
8
+ import tempfile
9
+ from pathlib import Path
10
+ from typing import List
11
+
12
+ from fastapi import APIRouter, HTTPException, UploadFile, File, Form
13
+ from langchain_core.documents import Document
14
+
15
+ from src.api.models import IngestResponse, IngestTextRequest, ErrorResponse
16
+ from src.rag.loaders import MultiFormatDocumentLoader
17
+ from src.rag.chunking import DocumentChunker
18
+ from src.rag.embeddings import get_embeddings
19
+ from src.rag.vectorstore import create_vector_store
20
+
21
+ logger = logging.getLogger(__name__)
22
+
23
+ router = APIRouter()
24
+
25
+ # Supported file types
26
+ SUPPORTED_EXTENSIONS = {".txt", ".md", ".pdf"}
27
+
28
+
29
+ @router.post(
30
+ "/ingest",
31
+ response_model=IngestResponse,
32
+ responses={
33
+ 400: {"model": ErrorResponse, "description": "Invalid file type"},
34
+ 500: {"model": ErrorResponse, "description": "Ingestion failed"}
35
+ }
36
+ )
37
+ async def ingest_files(
38
+ files: List[UploadFile] = File(..., description="Files to ingest"),
39
+ collection_name: str = Form(default="documents"),
40
+ chunk_size: int = Form(default=1000),
41
+ chunk_overlap: int = Form(default=200),
42
+ ):
43
+ """
44
+ Ingest files into the vector store.
45
+
46
+ Accepts PDF, Markdown, and text files. Files are chunked
47
+ and stored with embeddings for retrieval.
48
+
49
+ - **files**: Files to upload and process
50
+ - **collection_name**: Target collection name
51
+ - **chunk_size**: Size of document chunks
52
+ - **chunk_overlap**: Overlap between chunks
53
+ """
54
+ try:
55
+ logger.info(f"Ingesting {len(files)} file(s) to collection '{collection_name}'")
56
+
57
+ all_documents = []
58
+ loader = MultiFormatDocumentLoader()
59
+
60
+ for file in files:
61
+ # Validate file type
62
+ ext = Path(file.filename).suffix.lower()
63
+ if ext not in SUPPORTED_EXTENSIONS:
64
+ raise HTTPException(
65
+ status_code=400,
66
+ detail={
67
+ "error": "InvalidFileType",
68
+ "message": f"Unsupported file type: {ext}. Supported: {SUPPORTED_EXTENSIONS}"
69
+ }
70
+ )
71
+
72
+ # Save to temp file and load
73
+ with tempfile.NamedTemporaryFile(delete=False, suffix=ext) as tmp:
74
+ content = await file.read()
75
+ tmp.write(content)
76
+ tmp_path = tmp.name
77
+
78
+ try:
79
+ docs = loader.load_file(tmp_path)
80
+ # Update metadata with original filename
81
+ for doc in docs:
82
+ doc.metadata["file_name"] = file.filename
83
+ doc.metadata["original_file"] = file.filename
84
+ all_documents.extend(docs)
85
+ finally:
86
+ # Clean up temp file
87
+ Path(tmp_path).unlink(missing_ok=True)
88
+
89
+ if not all_documents:
90
+ return IngestResponse(
91
+ success=True,
92
+ message="No documents to process",
93
+ documents_processed=0,
94
+ chunks_created=0,
95
+ collection_name=collection_name,
96
+ )
97
+
98
+ # Chunk documents
99
+ chunker = DocumentChunker(
100
+ chunk_size=chunk_size,
101
+ chunk_overlap=chunk_overlap,
102
+ )
103
+ chunks = chunker.chunk_documents(all_documents)
104
+
105
+ # Store in vector store
106
+ embeddings = get_embeddings()
107
+ store = create_vector_store(
108
+ embedding_function=embeddings,
109
+ collection_name=collection_name,
110
+ )
111
+ store.add_documents(chunks)
112
+
113
+ logger.info(
114
+ f"Ingested {len(all_documents)} documents, "
115
+ f"created {len(chunks)} chunks"
116
+ )
117
+
118
+ return IngestResponse(
119
+ success=True,
120
+ message="Files ingested successfully",
121
+ documents_processed=len(all_documents),
122
+ chunks_created=len(chunks),
123
+ collection_name=collection_name,
124
+ )
125
+
126
+ except HTTPException:
127
+ raise
128
+ except Exception as e:
129
+ logger.error(f"Ingestion failed: {e}")
130
+ raise HTTPException(
131
+ status_code=500,
132
+ detail={"error": "IngestionError", "message": str(e)}
133
+ )
134
+
135
+
136
+ @router.post(
137
+ "/ingest/text",
138
+ response_model=IngestResponse,
139
+ responses={
140
+ 500: {"model": ErrorResponse, "description": "Ingestion failed"}
141
+ }
142
+ )
143
+ async def ingest_text(request: IngestTextRequest):
144
+ """
145
+ Ingest raw text into the vector store.
146
+
147
+ Useful for adding content programmatically without file upload.
148
+
149
+ - **text**: The text content to ingest
150
+ - **metadata**: Optional metadata for the document
151
+ - **collection_name**: Target collection name
152
+ """
153
+ try:
154
+ logger.info(f"Ingesting text ({len(request.text)} chars) to '{request.collection_name}'")
155
+
156
+ # Create document from text
157
+ doc = Document(
158
+ page_content=request.text,
159
+ metadata=request.metadata,
160
+ )
161
+
162
+ # Chunk
163
+ chunker = DocumentChunker()
164
+ chunks = chunker.chunk_documents([doc])
165
+
166
+ # Store
167
+ embeddings = get_embeddings()
168
+ store = create_vector_store(
169
+ embedding_function=embeddings,
170
+ collection_name=request.collection_name,
171
+ )
172
+ store.add_documents(chunks)
173
+
174
+ return IngestResponse(
175
+ success=True,
176
+ message="Text ingested successfully",
177
+ documents_processed=1,
178
+ chunks_created=len(chunks),
179
+ collection_name=request.collection_name,
180
+ )
181
+
182
+ except Exception as e:
183
+ logger.error(f"Text ingestion failed: {e}")
184
+ raise HTTPException(
185
+ status_code=500,
186
+ detail={"error": "IngestionError", "message": str(e)}
187
+ )
188
+
189
+
190
+ @router.delete("/ingest/{collection_name}")
191
+ async def delete_collection(collection_name: str):
192
+ """
193
+ Delete a document collection.
194
+
195
+ Removes all documents and the collection from the vector store.
196
+ """
197
+ try:
198
+ logger.info(f"Deleting collection: {collection_name}")
199
+
200
+ embeddings = get_embeddings()
201
+ store = create_vector_store(
202
+ embedding_function=embeddings,
203
+ collection_name=collection_name,
204
+ )
205
+ store.delete_collection()
206
+
207
+ return {
208
+ "success": True,
209
+ "message": f"Collection '{collection_name}' deleted",
210
+ }
211
+
212
+ except Exception as e:
213
+ logger.error(f"Delete collection failed: {e}")
214
+ raise HTTPException(
215
+ status_code=500,
216
+ detail={"error": "DeleteError", "message": str(e)}
217
+ )
src/api/routes/query.py ADDED
@@ -0,0 +1,121 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ Query Routes
3
+
4
+ Handles document querying with RAG pipeline.
5
+ """
6
+
7
+ import logging
8
+ from typing import AsyncGenerator
9
+
10
+ from fastapi import APIRouter, HTTPException
11
+ from fastapi.responses import StreamingResponse
12
+
13
+ from src.api.models import QueryRequest, QueryResponse, SourceDocument, ErrorResponse
14
+ from src.rag.pipeline import create_rag_pipeline
15
+
16
+ logger = logging.getLogger(__name__)
17
+
18
+ router = APIRouter()
19
+
20
+ # Cache pipeline instances per collection
21
+ _pipeline_cache = {}
22
+
23
+
24
+ def get_pipeline(collection_name: str, top_k: int):
25
+ """Get or create a RAG pipeline for the collection."""
26
+ cache_key = f"{collection_name}_{top_k}"
27
+ if cache_key not in _pipeline_cache:
28
+ _pipeline_cache[cache_key] = create_rag_pipeline(
29
+ collection_name=collection_name,
30
+ top_k=top_k,
31
+ )
32
+ return _pipeline_cache[cache_key]
33
+
34
+
35
+ @router.post(
36
+ "/query",
37
+ response_model=QueryResponse,
38
+ responses={
39
+ 500: {"model": ErrorResponse, "description": "Internal server error"}
40
+ }
41
+ )
42
+ async def query_documents(request: QueryRequest):
43
+ """
44
+ Query documents using RAG pipeline.
45
+
46
+ Retrieves relevant documents and generates an answer
47
+ using the configured LLM.
48
+
49
+ - **question**: The question to ask
50
+ - **collection_name**: Document collection to search
51
+ - **top_k**: Number of documents to retrieve
52
+ - **include_sources**: Include source documents in response
53
+ """
54
+ try:
55
+ logger.info(f"Query received: {request.question[:50]}...")
56
+
57
+ # Get pipeline
58
+ pipeline = get_pipeline(request.collection_name, request.top_k)
59
+
60
+ # Execute query
61
+ result = pipeline.query(
62
+ question=request.question,
63
+ include_sources=request.include_sources,
64
+ )
65
+
66
+ # Build response
67
+ sources = None
68
+ if request.include_sources and result.get("sources"):
69
+ sources = [
70
+ SourceDocument(
71
+ content=s["content"],
72
+ metadata=s["metadata"],
73
+ score=s.get("score"),
74
+ )
75
+ for s in result["sources"]
76
+ ]
77
+
78
+ return QueryResponse(
79
+ answer=result["answer"],
80
+ question=result["question"],
81
+ sources=sources,
82
+ num_sources=result.get("num_sources"),
83
+ )
84
+
85
+ except Exception as e:
86
+ logger.error(f"Query failed: {e}")
87
+ raise HTTPException(
88
+ status_code=500,
89
+ detail={"error": "QueryError", "message": str(e)}
90
+ )
91
+
92
+
93
+ @router.post("/query/stream")
94
+ async def stream_query(request: QueryRequest):
95
+ """
96
+ Stream query response.
97
+
98
+ Returns a streaming response with chunks of the answer
99
+ as they are generated.
100
+ """
101
+ try:
102
+ logger.info(f"Streaming query: {request.question[:50]}...")
103
+
104
+ pipeline = get_pipeline(request.collection_name, request.top_k)
105
+
106
+ async def generate() -> AsyncGenerator[str, None]:
107
+ """Generate response chunks."""
108
+ for chunk in pipeline.stream(request.question):
109
+ yield chunk
110
+
111
+ return StreamingResponse(
112
+ generate(),
113
+ media_type="text/plain",
114
+ )
115
+
116
+ except Exception as e:
117
+ logger.error(f"Stream query failed: {e}")
118
+ raise HTTPException(
119
+ status_code=500,
120
+ detail={"error": "StreamError", "message": str(e)}
121
+ )