feat: added facets endpoint #737

Author: MillenniumFalconMechanic

.gitignore

@@ -1,5 +1,8 @@
 node_modules/
 lib/
 .vscode/
+.venv/
+__pycache__/
+*.pyc
 .DS_Store
 .idea

.husky/pre-commit

@@ -27,6 +27,13 @@ npm test ||
 	false;
 )
 
+# Check Black (Python formatter)
+python -m black backend --check ||
+(
+	echo '🤔 Black Check Failed. Run: python -m black backend';
+	false;
+)
+
 # Check TypeScript
 npm run test-compile ||
 (

backend/README.md

@@ -0,0 +1,64 @@
+# Findable Backend (FastAPI)
+
+This folder contains a minimal FastAPI backend that exposes a stubbed **query-to-facets** endpoint for experimentation and PoC work.
+
+## Requirements
+
+- Python 3.9+
+- `pip`
+
+## Set up a Python virtual environment
+
+From the repo root:
+
+```bash
+python -m venv backend/.venv
+source backend/.venv/bin/activate
+python -m pip install --upgrade pip
+```
+
+## Install dependencies
+
+From the repo root:
+
+```bash
+pip install -r backend/requirements.txt
+```
+
+## Run the server
+
+From the repo root:
+
+```bash
+uvicorn backend.main:app --reload
+```
+
+## Format code
+
+From the repo root:
+
+```bash
+python -m black backend
+```
+
+The app will start on `http://127.0.0.1:8000` by default.
+
+### Endpoint
+
+- **Method:** `POST`
+- **Path:** `/api/v0/facets`
+- **Request body:**
+
+  ```json
+  { "query": "string" }
+  ```
+
+- **Example request:**
+
+  ```bash
+  curl -sS -X POST "http://127.0.0.1:8000/api/v0/facets" \
+    -H "Content-Type: application/json" \
+    -d '{ "query": "public bam files for latino patients with diabetes" }'
+  ```
+
+- **Response:** currently returns a **hard-coded** JSON structure representing resolved facets for the query. This is intentionally stubbed for PoC and will be replaced by a real implementation later.

backend/__init__.py

@@ -0,0 +1,17 @@
+from fastapi import APIRouter
+from pydantic import BaseModel
+
+from backend.services.facets_service import compute_facets_from_query
+from backend.services.facets_service import FacetsResponse
+
+from backend.controllers.models import FacetsRequest
+
+router = APIRouter(prefix="/api/v0/facets", tags=["facets"])
+
+
+@router.post("")
+def get_facets(payload: FacetsRequest) -> FacetsResponse:
+    # NOTE: Stubbed PoC implementation. This will be replaced by
+    # LLM-backed intent parsing and real facet resolution in a later step.
+    # For now, delegate to the service layer so the controller stays thin.
+    return compute_facets_from_query()

backend/controllers/__init__.py

@@ -0,0 +1,6 @@
+from pydantic import BaseModel
+
+
+# Model of the request body for the /api/v0/facets endpoint.
+class FacetsRequest(BaseModel):
+    query: str

backend/controllers/facets_controller.py

@@ -0,0 +1,9 @@
+from fastapi import FastAPI
+
+from backend.controllers.facets_controller import router as facets_router
+
+
+app = FastAPI(title="Findable API")
+
+# Register controller(s)
+app.include_router(facets_router)

backend/controllers/models.py

@@ -0,0 +1,4 @@
+fastapi==0.115.0
+uvicorn[standard]==0.30.0
+pydantic==2.9.0
+black==24.10.0