File size: 8,527 Bytes
55a76a3 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 | # PHASE_4_API_LAYER.md — Phase 4: API Layer
## RAG-Based Technical Documentation Assistant
---
## 1. Phase Goal
* **Business Goal**: Expose the corrective RAG engine and ingestion services via standard, authenticated, documented REST endpoints.
* **Technical Goal**: Implement FastAPI application containing routes for querying, doc ingestion (multipart upload / URL scrape), listing current registry catalog, deleting entries, and storing feedback metrics.
* **Completion Criteria**: Starting the uvicorn API server allows Swagger UI documentation access, and HTTP clients successfully execute queries, uploads, and feedback submissions.
---
## 2. Scope
### Included
* FastAPI application setup with strict CORS configurations.
* Pydantic request and response schemas for all endpoints.
* FastAPI dependency injection provider mapping singleton connections.
* Routes implementations:
- `POST /query`: Invokes LangGraph, returns response with references.
- `POST /ingest`: Accepts file uploads or remote URLs.
- `GET /documents`: Lists registered documents with stats.
- `DELETE /documents/{document_id}`: Removes document vectors and meta records.
- `POST /feedback`: Records user ratings (thumbs up/down) to SQLite.
- `GET /feedback`: Fetches feedback catalog.
- `GET /health`: Diagnostic checking.
* Custom error handler middleware returning structured JSON responses.
### Excluded
* Frontend UI implementation.
* Multi-tenant API keys or JWT authorization handlers.
---
## 3. Dependencies
* Phases 1, 2, and 3 completed successfully.
* LangGraph StateGraph compiled and verified.
* SQLite databases verified.
---
## 4. Deliverables
* `app/api/schemas/common.py`
* `app/api/schemas/query.py`
* `app/api/schemas/ingest.py`
* `app/api/schemas/documents.py`
* `app/api/schemas/feedback.py`
* `app/api/routes/query.py`
* `app/api/routes/ingest.py`
* `app/api/routes/documents.py`
* `app/api/routes/feedback.py`
* `app/api/routes/health.py`
* `app/dependencies.py`
* `app/services/query_service.py`
* `app/services/feedback_service.py`
* `app/repositories/feedback_repository.py`
* `app/core/middleware.py`
* `app/main.py`
---
## 5. Sub-Phases
### Phase 4.1: API Schemas & Core Setup
* **Goal**: Create validation models and setup core FastAPI application.
* **Tasks**:
1. Define Pydantic request/response schemas for query, ingestion, documents, and feedback.
2. Setup FastAPI application scaffold inside `app/main.py` with CORS.
3. Write custom timing and logging middleware in `app/core/middleware.py`.
* **Files**:
- `app/api/schemas/*.py`
- `app/core/middleware.py`
- `app/main.py` (scaffold)
* **Acceptance Criteria**: Running uvicorn starts the server and parses Swagger details without schema conflicts.
* **Verification**: Navigate to `http://localhost:8000/docs` in browser.
---
### Phase 4.2: Dependency Injection & Services
* **Goal**: Setup resource factories and build intermediate business services.
* **Tasks**:
1. Write `app/dependencies.py` initializing database connections and LangGraph singletons.
2. Write query broker service `app/services/query_service.py` coordinating the LangGraph executions.
3. Write database repository `app/repositories/feedback_repository.py` storing user reviews.
4. Write `app/services/feedback_service.py`.
* **Files**:
- `app/dependencies.py`
- `app/services/query_service.py`
- `app/repositories/feedback_repository.py`
- `app/services/feedback_service.py`
* **Acceptance Criteria**: Server startup executes resource allocations idempotently. Query and feedback services map dependencies correctly.
* **Verification**: Write a short execution check testing uvicorn launches with initialized services.
---
### Phase 4.3: Query, Feedback & Diagnostics Routes
* **Goal**: Implement the routing modules for execution queries, feedbacks, and health statuses.
* **Tasks**:
1. Write query router `app/api/routes/query.py` invoking query service.
2. Write feedback router `app/api/routes/feedback.py` recording ratings.
3. Write diagnostic router `app/api/routes/health.py` validating storage and LLM client connectivity.
* **Files**:
- `app/api/routes/query.py`
- `app/api/routes/feedback.py`
- `app/api/routes/health.py`
* **Acceptance Criteria**: Submitting questions via query route executes the LangGraph pipeline. Health router verifies database health status.
* **Verification**: Submit HTTP curl queries and assert response states.
---
### Phase 4.4: Ingestion & Catalog Routes
* **Goal**: Implement the document ingestion routes (file/URL) and catalog listing.
* **Tasks**:
1. Write ingestion router `app/api/routes/ingest.py` supporting file uploads and remote URL scrapes.
2. Write catalog router `app/api/routes/documents.py` for listing and deletion operations.
3. Wire all routers into the main application.
* **Files**:
- `app/api/routes/ingest.py`
- `app/api/routes/documents.py`
- `app/main.py` (updated)
* **Acceptance Criteria**: Files uploaded via multipart routes get ingested and indexed. Registry listings correctly update document count attributes.
* **Verification**: Test PDF/MD uploads and delete files verifying DB states update.
---
## 6. AI Build Prompt (`AI_BUILD_PROMPT.md`)
```markdown
# AI Build Prompt: Phase 4 (API Layer)
## Goal
Expose the RAG pipeline and ingestion systems through a FastAPI REST API with validation schemas, service mapping dependencies, and structured exception handlers.
## Files to Create/Modify
- **app/api/schemas/common.py**: Standard error response model: `{"error": {"code": str, "message": str, "details": dict}, "request_id": str}`.
- **app/api/schemas/query.py**: QueryRequest, QueryResponse, SourceReference models.
- **app/api/schemas/ingest.py**: IngestRequest, IngestResponse models.
- **app/api/schemas/documents.py**: DocumentRecord, DocumentListResponse models.
- **app/api/schemas/feedback.py**: FeedbackRequest, FeedbackResponse models.
- **app/api/routes/health.py**: GET /health returning check status of databases and providers.
- **app/api/routes/query.py**: POST /query routing questions to query service.
- **app/api/routes/ingest.py**: POST /ingest handling file upload (multipart) or URL scraping.
- **app/api/routes/documents.py**: GET /documents (paginated) and DELETE /documents/{id} removing records.
- **app/api/routes/feedback.py**: POST /feedback recording thumbs up/down and comments to SQLite.
- **app/dependencies.py**: Startup resource initialization mapping database clients and graph compilers.
- **app/services/query_service.py**: Runs async execution tasks using compiled StateGraph.
- **app/repositories/feedback_repository.py**: Inserts records to SQLite feedback table.
- **app/services/feedback_service.py**: Stores rating metrics.
- **app/core/middleware.py**: Custom timing middleware logging execution times.
- **app/main.py**: Initializes FastAPI application mapping exception handlers and registering routers.
## Constraints
- File uploads must not exceed 10MB.
- Return structured error formatting on validation exceptions (Pydantic 422 errors).
- Cleanly release SQLite connections at endpoint completions.
## Acceptance Criteria
- Starting server via `uvicorn app.main:app` runs cleanly, and tests endpoints using Swagger `/docs`.
```
---
## 7. Verification Package
### Manual Verification
1. Start API server locally:
```bash
uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload
```
2. Test health check endpoint:
```bash
curl http://127.0.0.1:8000/health
```
3. Submit question query:
```bash
curl -X POST http://127.0.0.1:8000/query -H "Content-Type: application/json" -d "{\"question\": \"How do I install FastAPI?\"}"
```
### Expected Results
* Health endpoint returns `{"status": "healthy", ...}`.
* Query request prints JSON answer displaying source documentation citations.
### Failure Conditions
* Incorrect input models return generic 500 crashes instead of validated 422 JSON errors.
* Deleted documents remain searchable inside ChromaDB.
---
## 8. Review Gates
- [ ] FastAPI Swagger UI validates clean schema models.
- [ ] Ingestion route blocks files larger than 10MB.
- [ ] Exception wrappers translate LLM timeouts to standard 503 errors.
- [ ] Feedback records update SQLite tables correctly.
- [ ] Timing middlewares trace requests successfully.
|