AIenthusSP's picture
feat: implement FastAPI application structure
b6fa51d
|
Raw History Blame Contribute Delete
5.02 kB
# πŸ” Deep Dive: FastAPI Application Architecture
## 🧠 Why FastAPI for RAG?
```
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ FASTAPI BENEFITS β”‚
β”‚ β”‚
β”‚ βœ… Async support β†’ Efficient I/O for LLM calls β”‚
β”‚ βœ… Automatic docs β†’ Swagger UI at /docs β”‚
β”‚ βœ… Pydantic β†’ Type validation and serialization β”‚
β”‚ βœ… Streaming β†’ SSE for real-time responses β”‚
β”‚ βœ… Production-ready β†’ Used by Netflix, Uber, Microsoft β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
```
---
## πŸ“ Architecture Overview
```
src/api/
β”œβ”€β”€ main.py # Application entry point
β”œβ”€β”€ models.py # Pydantic request/response models
β”œβ”€β”€ __init__.py
└── routes/
β”œβ”€β”€ __init__.py
β”œβ”€β”€ health.py # Health check endpoints
β”œβ”€β”€ query.py # Query/RAG endpoints
└── ingest.py # Document ingestion endpoints
```
---
## 🎯 main.py - Application Entry Point
### FastAPI App Configuration
```python
app = FastAPI(
title="DocuMind AI",
description="RAG-Powered Documentation Assistant API",
version="1.0.0",
docs_url="/docs", # Swagger UI
redoc_url="/redoc", # ReDoc alternative
lifespan=lifespan, # Startup/shutdown events
)
```
### Lifespan Context Manager
```python
@asynccontextmanager
async def lifespan(app: FastAPI):
# Startup
logger.info("Starting DocuMind AI API...")
yield
# Shutdown
logger.info("Shutting down...")
```
### CORS Configuration
```python
app.add_middleware(
CORSMiddleware,
allow_origins=settings.cors_origins, # ["localhost:3000", "localhost:8501"]
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
```
---
## πŸ“‹ models.py - Pydantic Schemas
### QueryRequest
```python
class QueryRequest(BaseModel):
question: str = Field(..., min_length=1, max_length=2000)
collection_name: str = Field(default="documents")
top_k: int = Field(default=5, ge=1, le=20)
include_sources: bool = Field(default=True)
```
### QueryResponse
```python
class QueryResponse(BaseModel):
answer: str
question: str
sources: Optional[List[SourceDocument]]
num_sources: Optional[int]
```
### IngestResponse
```python
class IngestResponse(BaseModel):
success: bool
message: str
documents_processed: int
chunks_created: int
collection_name: str
```
---
## πŸ›£οΈ Routes
### Health Routes (`/health`)
| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/health` | GET | Basic health check |
| `/health/detailed` | GET | Component-level health |
| `/ready` | GET | Kubernetes readiness |
| `/live` | GET | Kubernetes liveness |
### Query Routes (`/api/query`)
| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/api/query` | POST | Standard RAG query |
| `/api/query/stream` | POST | Streaming response |
### Ingest Routes (`/api/ingest`)
| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/api/ingest` | POST | Upload files |
| `/api/ingest/text` | POST | Ingest raw text |
| `/api/ingest/{collection}` | DELETE | Delete collection |
---
## πŸ”„ Query Flow
```
POST /api/query
{
"question": "What is the refund policy?",
"collection_name": "documents",
"top_k": 5,
"include_sources": true
}
↓
get_pipeline(collection_name, top_k)
↓
pipeline.query(question, include_sources)
↓
{
"answer": "Based on the documentation...",
"question": "What is the refund policy?",
"sources": [...],
"num_sources": 3
}
```
---
## πŸ“€ Ingest Flow
```
POST /api/ingest
[files: policy.pdf, guide.md]
↓
Validate file extensions (.pdf, .md, .txt)
↓
Save to temp files
↓
MultiFormatDocumentLoader.load_file()
↓
DocumentChunker.chunk_documents()
↓
VectorStore.add_documents()
↓
{
"success": true,
"documents_processed": 2,
"chunks_created": 15
}
```
---
## πŸš€ Running the API
```bash
# Development
python -m src.api.main
# Or with uvicorn directly
uvicorn src.api.main:app --reload --host 0.0.0.0 --port 8000
```
### Access Points:
- **API**: http://localhost:8000
- **Swagger Docs**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc
---
## πŸ“‹ Summary
| File | Purpose |
|------|---------|
| `main.py` | App config, CORS, routers |
| `models.py` | Pydantic schemas |
| `routes/health.py` | Health checks |
| `routes/query.py` | RAG query endpoints |
| `routes/ingest.py` | File upload endpoints |