Implement deterministic ranking engine

Author: codysj

README.md

@@ -2,7 +2,7 @@
 
 College Exploration Platform is a full-stack decision-support product for helping prospective and admitted students discover, compare, rank, and justify college choices with transparent data and deterministic scoring.
 
-Status: V1.8 onboarding and local preference profile complete. Ranking logic, Redis, pgvector, and deployment are intentionally not implemented yet.
+Status: V1.9 deterministic ranking engine complete. Redis, pgvector, saved schools, comparisons, and deployment are intentionally not implemented yet.
 
 ## Project Thesis
 
@@ -109,6 +109,7 @@ Useful local URLs:
 - API health: `http://127.0.0.1:8000/health`
 - DB readiness: `http://127.0.0.1:8000/ready`
 - Structured search: `http://127.0.0.1:8000/schools/search`
+- Deterministic rankings: `http://127.0.0.1:8000/rankings`
 - School profile: `http://127.0.0.1:8000/schools/1`
 - OpenAPI docs: `http://127.0.0.1:8000/docs`
 
@@ -124,10 +125,12 @@ Example profile request:
 curl "http://127.0.0.1:8000/schools/1"
 ```
 
-`GET /schools/{id}` composes a full profile from the core `schools` row plus academic, cost, outcome, and campus-life tables. The API keeps ranking placeholders such as `fit_score`, `category_scores`, reasons, tradeoffs, and `similar_schools` empty until those roadmap steps are implemented.
+`GET /schools/{id}` composes a full profile from the core `schools` row plus academic, cost, outcome, and campus-life tables. Profile ranking placeholders such as `fit_score`, `category_scores`, reasons, tradeoffs, and `similar_schools` remain empty until the frontend profile workflow consumes ranking output.
 
 Missing data is treated as unknown. The API returns `null` for missing values, lists those fields in `data_fields_missing`, and includes a simple `data_confidence_score` based on profile completeness. It does not convert missing numbers to zero or infer school facts that are not in the database.
 
+`POST /rankings` ranks search-card results against a supplied preference profile using deterministic V1.0 category scoring, normalized weights, confidence scores, hard constraints, and reason-code explanations. Ranking does not use semantic search, ML models, or LLM-generated scoring.
+
 ### Frontend Setup
 
 The V1.6 frontend lives in `apps/web` and uses the Next.js App Router with TypeScript, Tailwind CSS, and small shadcn/ui-compatible component primitives.
@@ -217,12 +220,12 @@ Expected future commands:
 
 ## Limitations
 
-- `/health`, `/ready`, `/schools/search`, and `/schools/{id}` exist. Preference persistence, saved-school, comparison, and ranking endpoints are not implemented yet.
+- `/health`, `/ready`, `/schools/search`, `/schools/{id}`, and `/rankings` exist. Preference persistence, saved-school, and comparison endpoints are not implemented yet.
 - The frontend has a landing page, onboarding, search UI, route shell, UI primitives, and typed API client, but no backend preference persistence, persisted saved-school flows, comparison workflow, or profile pages yet.
 - Onboarding stores a typed `PreferenceProfile` in browser `localStorage` and forwards supported filters such as state, setting, school type, and max net price to `/search`.
 - Search supports structured filters, sort controls, URL state, pagination, local save/compare state, loading/empty/error states, and API-backed result cards.
-- The “Best fit” sort is a UI placeholder that falls back to name sorting until deterministic ranking exists in V1.9.
-- No ranking engine, Redis cache, pgvector integration, or deployment exists yet.
+- The "Best fit" sort is a UI placeholder until the frontend calls `POST /rankings`.
+- No Redis cache, pgvector integration, or deployment exists yet.
 - No performance metrics are available.
 - Seed data is synthetic and intended for deterministic local development, not factual school reporting.
 - End-to-end validation will be added after the product workflows exist.

apps/api/api/routes/rankings.py

@@ -0,0 +1,26 @@
+from fastapi import APIRouter, Depends
+from sqlalchemy.orm import Session
+
+from api.deps import get_db
+from repositories.schools import SchoolRepository
+from schemas.rankings import RankingRequest, RankingResponse
+from services.ranking_service import RankingService
+
+router = APIRouter(prefix="/rankings", tags=["rankings"])
+
+
+def get_ranking_service(db: Session = Depends(get_db)) -> RankingService:
+    return RankingService(SchoolRepository(db))
+
+
+@router.post(
+    "",
+    response_model=RankingResponse,
+    summary="Rank schools deterministically",
+    description="Returns ranked school search cards using structured preferences and deterministic reason codes.",
+)
+def rank_schools(
+    request: RankingRequest,
+    service: RankingService = Depends(get_ranking_service),
+) -> RankingResponse:
+    return service.rank_schools(request)

apps/api/main.py

@@ -4,6 +4,7 @@
 from starlette.exceptions import HTTPException as StarletteHTTPException
 
 from api.routes.health import router as health_router
+from api.routes.rankings import router as rankings_router
 from api.routes.schools import router as schools_router
 from core.config import get_settings
 from core.errors import (
@@ -26,6 +27,7 @@ def create_app() -> FastAPI:
     )
     app.include_router(health_router)
     app.include_router(schools_router)
+    app.include_router(rankings_router)
     app.add_exception_handler(StarletteHTTPException, http_exception_handler)
     app.add_exception_handler(RequestValidationError, validation_exception_handler)
     app.add_exception_handler(PydanticValidationError, pydantic_validation_exception_handler)

apps/api/repositories/schools.py

@@ -109,6 +109,43 @@ def search_schools(self, filters: SearchRequest) -> tuple[list[SchoolSearchResul
         )
         return results, total
 
+    def get_ranking_candidate_rows(self, filters: SearchRequest) -> list[dict[str, object]]:
+        query = (
+            select(
+                School.id.label("school_id"),
+                School.name,
+                School.city,
+                School.state,
+                School.region,
+                School.type,
+                School.setting,
+                School.undergraduate_enrollment.label("enrollment"),
+                School.acceptance_rate,
+                SchoolAcademics.top_majors,
+                SchoolAcademics.graduation_rate,
+                SchoolAcademics.retention_rate,
+                SchoolAcademics.student_faculty_ratio,
+                SchoolCosts.tuition_in_state,
+                SchoolCosts.tuition_out_state,
+                SchoolCosts.net_price,
+                SchoolCosts.average_aid,
+                SchoolCosts.debt_median,
+                SchoolOutcomes.median_earnings,
+                SchoolOutcomes.repayment_rate,
+                SchoolCampusLife.housing_available,
+                SchoolCampusLife.sports_division,
+                SchoolCampusLife.greek_life_rate,
+                SchoolCampusLife.culture_tags,
+            )
+            .join(SchoolAcademics, SchoolAcademics.school_id == School.id, isouter=True)
+            .join(SchoolCosts, SchoolCosts.school_id == School.id, isouter=True)
+            .join(SchoolOutcomes, SchoolOutcomes.school_id == School.id, isouter=True)
+            .join(SchoolCampusLife, SchoolCampusLife.school_id == School.id, isouter=True)
+        )
+        filtered_query = self._apply_filters(query, filters).order_by(School.id.asc())
+        rows = self.db.execute(filtered_query).mappings().all()
+        return [dict(row) for row in rows]
+
     def _apply_filters(self, query: Select[tuple], filters: SearchRequest) -> Select[tuple]:
         if filters.query:
             query = query.where(School.name.ilike(f"%{filters.query}%"))

apps/api/schemas/preferences.py

@@ -3,6 +3,7 @@
 from pydantic import BaseModel, ConfigDict, Field
 
 JsonScalar: TypeAlias = str | int | float | bool | None
+JsonValue: TypeAlias = JsonScalar | list[JsonScalar] | dict[str, JsonScalar]
 
 
 class Preference(BaseModel):
@@ -22,4 +23,4 @@ class Preference(BaseModel):
     home_state: str | None = Field(default=None, min_length=2, max_length=2)
     max_annual_cost: int | None = Field(default=None, ge=0)
     weights: dict[str, float] = Field(default_factory=dict)
-    constraints: dict[str, JsonScalar] = Field(default_factory=dict)
+    constraints: dict[str, JsonValue] = Field(default_factory=dict)

apps/api/schemas/rankings.py

@@ -1,5 +1,8 @@
 from pydantic import BaseModel, ConfigDict, Field
 
+from schemas.preferences import Preference
+from schemas.schools import SchoolSearchResult, SearchRequest
+
 
 class RankingScore(BaseModel):
     school_id: int
@@ -8,17 +11,50 @@ class RankingScore(BaseModel):
     category_scores: dict[str, float] = Field(default_factory=dict)
     reason_codes: list[str] = Field(default_factory=list)
     tradeoff_codes: list[str] = Field(default_factory=list)
+    ranking_version: str
+
+
+class RankingRequest(BaseModel):
+    preferences: Preference
+    filters: SearchRequest = Field(default_factory=SearchRequest)
 
 
 class RankingResponse(BaseModel):
     model_config = ConfigDict(
         json_schema_extra={
             "example": {
-                "ranking_version": "placeholder",
-                "results": [],
+                "ranking_version": "v1.0",
+                "results": [
+                    {
+                        "school_id": 2,
+                        "name": "Bayview Technical University",
+                        "city": "New Haven",
+                        "state": "CT",
+                        "type": "Public",
+                        "setting": "Urban",
+                        "enrollment": 11800,
+                        "acceptance_rate": 0.52,
+                        "net_price": 24400,
+                        "graduation_rate": 0.78,
+                        "fit_score": 86.42,
+                        "confidence_score": 0.95,
+                        "category_scores": {"academic": 92.0, "cost": 82.5},
+                        "top_reasons": ["academic_major_match", "cost_within_budget"],
+                        "top_tradeoffs": ["admissions_more_selective_than_target"],
+                        "ranking_version": "v1.0",
+                    }
+                ],
+                "page": 1,
+                "page_size": 20,
+                "total_results": 1,
+                "has_next": False,
             }
         }
     )
 
     ranking_version: str
-    results: list[RankingScore] = Field(default_factory=list)
+    results: list[SchoolSearchResult] = Field(default_factory=list)
+    page: int = 1
+    page_size: int = 20
+    total_results: int = 0
+    has_next: bool = False

apps/api/schemas/schools.py

@@ -104,8 +104,10 @@ class SchoolSearchResult(BaseModel):
     graduation_rate: float | None = None
     fit_score: float | None = None
     confidence_score: float | None = None
+    category_scores: dict[str, float] = Field(default_factory=dict)
     top_reasons: list[str] = Field(default_factory=list)
     top_tradeoffs: list[str] = Field(default_factory=list)
+    ranking_version: str | None = None
 
 
 class SearchRequest(BaseModel):