Add school profile API and validation handler

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.4 structured search API complete. Frontend pages, ranking logic, Redis, pgvector, and deployment are intentionally not implemented yet.
+Status: V1.5 school profile API complete. Frontend pages, ranking logic, Redis, pgvector, 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`
+- School profile: `http://127.0.0.1:8000/schools/1`
 - OpenAPI docs: `http://127.0.0.1:8000/docs`
 
 Example search request:
@@ -117,6 +118,16 @@ Example search request:
 curl "http://127.0.0.1:8000/schools/search?state=CA&min_net_price=15000&max_net_price=40000&sort=net_price&page=1&page_size=10"
 ```
 
+Example profile request:
+
+```powershell
+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.
+
+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.
+
 ### Windows Install Troubleshooting
 
 If installation fails with `Failed building wheel for pydantic-core`, `maturin failed`, or `link.exe not found`, pip is trying to compile native code locally. That usually means the venv is using an unsupported or too-new Python version, or pip has cached an incompatible artifact.
@@ -166,7 +177,7 @@ Expected future commands:
 
 ## Limitations
 
-- `/health`, `/ready`, and `/schools/search` exist. Profile, saved-school, comparison, and ranking endpoints are not implemented yet.
+- `/health`, `/ready`, `/schools/search`, and `/schools/{id}` exist. Saved-school, comparison, and ranking endpoints are not implemented yet.
 - No UI pages, ranking engine, 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.

apps/__init__.py

@@ -0,0 +1 @@
+

apps/api/__init__.py

@@ -0,0 +1 @@
+

apps/api/api/routes/schools.py

@@ -1,13 +1,15 @@
 from typing import Annotated
 
-from fastapi import APIRouter, Depends
+from fastapi import APIRouter, Depends, Header, HTTPException
 from sqlalchemy.orm import Session
 
 from api.deps import get_db
-from schemas.schools import SearchRequest, SearchResponse
+from core.logging import get_logger
+from schemas.schools import SchoolProfileResponse, SearchRequest, SearchResponse
 from services.schools import SchoolService
 
 router = APIRouter(prefix="/schools", tags=["schools"])
+logger = get_logger(__name__)
 
 
 def get_school_service(db: Session = Depends(get_db)) -> SchoolService:
@@ -25,3 +27,28 @@ def search_schools(
     service: SchoolService = Depends(get_school_service),
 ) -> SearchResponse:
     return service.search_schools(filters)
+
+
+@router.get(
+    "/{school_id}",
+    response_model=SchoolProfileResponse,
+    summary="School profile",
+    description="Returns a full structured school profile with explicit missing-data metadata.",
+)
+def get_school_profile(
+    school_id: int,
+    service: SchoolService = Depends(get_school_service),
+    x_request_id: Annotated[str | None, Header(alias="X-Request-ID")] = None,
+) -> SchoolProfileResponse:
+    profile = service.get_school_profile(school_id)
+    if profile is None:
+        logger.info(
+            "school_profile_not_found",
+            extra={
+                "request_id": x_request_id,
+                "school_id": school_id,
+                "failure_reason": "school_id_not_found",
+            },
+        )
+        raise HTTPException(status_code=404, detail="School not found.")
+    return profile

apps/api/core/errors.py

@@ -1,6 +1,7 @@
 from fastapi import Request
 from fastapi.exceptions import RequestValidationError
 from fastapi.responses import JSONResponse
+from pydantic import ValidationError as PydanticValidationError
 from starlette.exceptions import HTTPException as StarletteHTTPException
 from starlette.status import HTTP_422_UNPROCESSABLE_ENTITY, HTTP_500_INTERNAL_SERVER_ERROR
 
@@ -39,6 +40,18 @@ async def validation_exception_handler(request: Request, exc: RequestValidationE
     )
 
 
+async def pydantic_validation_exception_handler(request: Request, exc: PydanticValidationError) -> JSONResponse:
+    logger.info(
+        "pydantic_validation_exception",
+        extra={"path": request.url.path, "errors": exc.errors()},
+    )
+    return _error_response(
+        status_code=HTTP_422_UNPROCESSABLE_ENTITY,
+        code="validation_error",
+        message="Request validation failed.",
+    )
+
+
 async def unhandled_exception_handler(request: Request, exc: Exception) -> JSONResponse:
     logger.exception(
         "unhandled_exception",

apps/api/main.py

@@ -1,12 +1,14 @@
 from fastapi import FastAPI
 from fastapi.exceptions import RequestValidationError
+from pydantic import ValidationError as PydanticValidationError
 from starlette.exceptions import HTTPException as StarletteHTTPException
 
 from api.routes.health import router as health_router
 from api.routes.schools import router as schools_router
 from core.config import get_settings
 from core.errors import (
     http_exception_handler,
+    pydantic_validation_exception_handler,
     unhandled_exception_handler,
     validation_exception_handler,
 )
@@ -26,6 +28,7 @@ def create_app() -> FastAPI:
     app.include_router(schools_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)
     app.add_exception_handler(Exception, unhandled_exception_handler)
     return app
 

apps/api/pytest.ini

@@ -1,4 +1,6 @@
 [pytest]
-pythonpath = .
+pythonpath =
+    ../..
+    .
 testpaths = tests
 addopts = -q

apps/api/repositories/schools.py

@@ -4,7 +4,7 @@
 from sqlalchemy.orm import Session
 
 from core.logging import get_logger
-from models.school import School, SchoolAcademics, SchoolCosts
+from models.school import School, SchoolAcademics, SchoolCampusLife, SchoolCosts, SchoolOutcomes
 from repositories.base import BaseRepository
 from schemas.schools import SchoolSearchResult, SearchRequest
 
@@ -15,9 +15,41 @@ class SchoolRepository(BaseRepository[School]):
     def __init__(self, db: Session) -> None:
         super().__init__(db)
 
-    def get_school_by_id(self, school_id: int) -> School | None:
-        """Example repository method for future routes and services."""
-        return self.db.get(School, school_id)
+    def get_school_profile_row(self, school_id: int) -> dict[str, object] | None:
+        query = (
+            select(
+                School.id.label("school_id"),
+                School.name,
+                School.city,
+                School.state,
+                School.region,
+                School.type,
+                School.setting,
+                School.undergraduate_enrollment.label("enrollment"),
+                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)
+            .where(School.id == school_id)
+        )
+        row = self.db.execute(query).mappings().one_or_none()
+        return dict(row) if row is not None else None
 
     def search_schools(self, filters: SearchRequest) -> tuple[list[SchoolSearchResult], int]:
         base_query = (

apps/api/schemas/schools.py

@@ -37,6 +37,60 @@ class SchoolProfile(BaseModel):
     campus_tags: list[str] = Field(default_factory=list)
 
 
+class SchoolProfileAcademics(BaseModel):
+    majors: list[str] | None = None
+    popular_majors: list[str] | None = None
+    graduation_rate: float | None = None
+    retention_rate: float | None = None
+    student_faculty_ratio: float | None = None
+
+
+class SchoolProfileCost(BaseModel):
+    tuition_in_state: int | None = None
+    tuition_out_state: int | None = None
+    net_price: int | None = None
+    average_aid: int | None = None
+    debt_median: int | None = None
+
+
+class SchoolProfileOutcomes(BaseModel):
+    median_earnings: int | None = None
+    completion_rate: float | None = None
+    repayment_rate: float | None = None
+    outcome_percentiles: dict[str, float] | None = None
+
+
+class SchoolProfileCampusLife(BaseModel):
+    sports: str | None = None
+    greek_life: float | None = None
+    housing: bool | None = None
+    weather_band: str | None = None
+    diversity_metrics: dict[str, float] | None = None
+    culture_tags: list[str] | None = None
+
+
+class SchoolProfileResponse(BaseModel):
+    school_id: int
+    name: str
+    city: str
+    state: str
+    region: str
+    type: str
+    setting: str
+    enrollment: int | None = None
+    academics: SchoolProfileAcademics
+    cost: SchoolProfileCost
+    outcomes: SchoolProfileOutcomes
+    campus_life: SchoolProfileCampusLife
+    data_fields_missing: list[str] = Field(default_factory=list)
+    data_confidence_score: float
+    fit_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)
+    similar_schools: list[dict[str, object]] = Field(default_factory=list)
+
+
 class SchoolSearchResult(BaseModel):
     school_id: int
     name: str

apps/api/services/schools.py

@@ -1,16 +1,106 @@
 from sqlalchemy.orm import Session
 
-from models.school import School
 from repositories.schools import SchoolRepository
-from schemas.schools import SearchRequest, SearchResponse
+from schemas.schools import (
+    SchoolProfileAcademics,
+    SchoolProfileCampusLife,
+    SchoolProfileCost,
+    SchoolProfileOutcomes,
+    SchoolProfileResponse,
+    SearchRequest,
+    SearchResponse,
+)
+
+
+PROFILE_COMPLETENESS_FIELDS = (
+    "school_id",
+    "name",
+    "city",
+    "state",
+    "region",
+    "type",
+    "setting",
+    "enrollment",
+    "academics.majors",
+    "academics.popular_majors",
+    "academics.graduation_rate",
+    "academics.retention_rate",
+    "academics.student_faculty_ratio",
+    "cost.tuition_in_state",
+    "cost.tuition_out_state",
+    "cost.net_price",
+    "cost.average_aid",
+    "cost.debt_median",
+    "outcomes.median_earnings",
+    "outcomes.completion_rate",
+    "outcomes.repayment_rate",
+    "outcomes.outcome_percentiles",
+    "campus_life.sports",
+    "campus_life.greek_life",
+    "campus_life.housing",
+    "campus_life.weather_band",
+    "campus_life.diversity_metrics",
+    "campus_life.culture_tags",
+)
 
 
 class SchoolService:
     def __init__(self, db: Session) -> None:
         self.repository = SchoolRepository(db)
 
-    def get_school_by_id(self, school_id: int) -> School | None:
-        return self.repository.get_school_by_id(school_id)
+    def get_school_profile(self, school_id: int) -> SchoolProfileResponse | None:
+        row = self.repository.get_school_profile_row(school_id)
+        if row is None:
+            return None
+
+        top_majors = row["top_majors"]
+        culture_tags = row["culture_tags"]
+        profile = SchoolProfileResponse(
+            school_id=int(row["school_id"]),
+            name=str(row["name"]),
+            city=str(row["city"]),
+            state=str(row["state"]),
+            region=str(row["region"]),
+            type=str(row["type"]),
+            setting=str(row["setting"]),
+            enrollment=row["enrollment"],
+            academics=SchoolProfileAcademics(
+                majors=top_majors,
+                popular_majors=top_majors,
+                graduation_rate=self._to_float(row["graduation_rate"]),
+                retention_rate=self._to_float(row["retention_rate"]),
+                student_faculty_ratio=self._to_float(row["student_faculty_ratio"]),
+            ),
+            cost=SchoolProfileCost(
+                tuition_in_state=row["tuition_in_state"],
+                tuition_out_state=row["tuition_out_state"],
+                net_price=row["net_price"],
+                average_aid=row["average_aid"],
+                debt_median=row["debt_median"],
+            ),
+            outcomes=SchoolProfileOutcomes(
+                median_earnings=row["median_earnings"],
+                completion_rate=None,
+                repayment_rate=self._to_float(row["repayment_rate"]),
+                outcome_percentiles=None,
+            ),
+            campus_life=SchoolProfileCampusLife(
+                sports=row["sports_division"],
+                greek_life=self._to_float(row["greek_life_rate"]),
+                housing=row["housing_available"],
+                weather_band=None,
+                diversity_metrics=None,
+                culture_tags=culture_tags,
+            ),
+            data_confidence_score=0,
+        )
+        missing_fields = self._missing_fields(profile)
+        profile.data_fields_missing = missing_fields
+        profile.data_confidence_score = round(
+            (len(PROFILE_COMPLETENESS_FIELDS) - len(missing_fields)) / len(PROFILE_COMPLETENESS_FIELDS),
+            4,
+        )
+        return profile
 
     def search_schools(self, filters: SearchRequest) -> SearchResponse:
         results, total_results = self.repository.search_schools(filters)
@@ -21,3 +111,17 @@ def search_schools(self, filters: SearchRequest) -> SearchResponse:
             total_results=total_results,
             has_next=filters.page * filters.page_size < total_results,
         )
+
+    def _missing_fields(self, profile: SchoolProfileResponse) -> list[str]:
+        payload = profile.model_dump()
+        missing: list[str] = []
+        for field in PROFILE_COMPLETENESS_FIELDS:
+            value: object = payload
+            for part in field.split("."):
+                value = value[part] if isinstance(value, dict) else None
+            if value is None:
+                missing.append(field)
+        return missing
+
+    def _to_float(self, value: object) -> float | None:
+        return float(value) if value is not None else None