PHASE_4_API_LAYER.md

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)

# 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:

   uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload
   

2. Test health check endpoint:

   curl http://127.0.0.1:8000/health
   

3. Submit question query:

   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.