Spaces:
Build error
Build error
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 +13 -0
- docs/explanations/api.md +214 -0
- requirements.txt +1 -0
- src/api/main.py +83 -0
- src/api/models.py +158 -0
- src/api/routes/__init__.py +4 -0
- src/api/routes/health.py +137 -0
- src/api/routes/ingest.py +217 -0
- src/api/routes/query.py +121 -0
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 |
+
)
|