Stabilize Windows Python dependency setup

Author: codysj

.python-version

@@ -0,0 +1 @@
+3.12

AGENTS.md

@@ -5,6 +5,7 @@ These instructions apply to Codex and other LLM coding agents working in this re
 ## Coding Standards
 
 - Read `README.md`, `tasks.md`, `docs/architecture.md`, and the docs relevant to the current task before editing.
+- Use Python `>=3.12,<3.13` for backend work. Do not move the project to Python 3.14 until dependency wheel compatibility is verified.
 - Keep each implementation step small and aligned with the V1/V2/V3 roadmap.
 - Prefer typed contracts and explicit validation over ad hoc objects.
 - Keep SQL out of route handlers when backend code is added; use repository or service modules.
@@ -17,6 +18,11 @@ These instructions apply to Codex and other LLM coding agents working in this re
 Database commands available after V1.2:
 
 ```powershell
+py -3.12 -m venv .venv
+.\.venv\Scripts\activate
+python -m pip install --upgrade pip
+python -m pip cache purge
+python -m pip install -r apps/api/requirements.txt
 docker compose up -d postgres
 cd apps/api
 alembic upgrade head
@@ -38,6 +44,8 @@ Until those runtimes exist, validate foundation changes with:
 Get-ChildItem -Recurse -File
 ```
 
+Do not fix Windows dependency installation failures by adding Visual Studio Build Tools or Rust requirements. If `pydantic-core`, `maturin`, or `link.exe` errors appear, recreate the venv with Python 3.12 and reinstall from wheels.
+
 ## Documentation Update Rules
 
 - Update `tasks.md` whenever a roadmap item changes status.

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.3 FastAPI foundation complete. Search routes, frontend pages, ranking logic, Redis, pgvector, and deployment are intentionally not implemented yet.
+Status: V1.4 structured search API complete. Frontend pages, ranking logic, Redis, pgvector, and deployment are intentionally not implemented yet.
 
 ## Project Thesis
 
@@ -37,13 +37,44 @@ Copy-Item .env.example .env
 docker compose up -d postgres
 ```
 
-Install backend tooling:
+### Python Setup
+
+Use Python `>=3.12,<3.13`. Python 3.12 is the supported local development version for this project. Do not use Python 3.14 yet; several native-extension dependencies may not have Windows wheels for it.
+
+Verify your Python launcher can find Python 3.12:
 
 ```powershell
-cd apps/api
-python -m pip install -r requirements.txt
+py -3.12 --version
+```
+
+### Virtual Environment Setup
+
+Create and activate a local Python virtual environment from the project root:
+
+```powershell
+py -3.12 -m venv .venv
+.\.venv\Scripts\activate
 ```
 
+Confirm the venv is active and using Python 3.12:
+
+```powershell
+python --version
+python -c "import sys; print(sys.prefix)"
+```
+
+`sys.prefix` should point at this repository's `.venv` directory.
+
+### Install Dependencies
+
+```powershell
+python -m pip install --upgrade pip
+python -m pip cache purge
+python -m pip install -r apps/api/requirements.txt
+```
+
+Successful installs should download wheels and should not show build steps for `pydantic-core`, `psycopg`, `maturin`, Rust, or MSVC.
+
 Run migrations:
 
 ```powershell
@@ -77,8 +108,33 @@ 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`
 - OpenAPI docs: `http://127.0.0.1:8000/docs`
 
+Example search request:
+
+```powershell
+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"
+```
+
+### 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.
+
+Fix:
+
+```powershell
+deactivate
+Remove-Item -Recurse -Force .venv
+py -3.12 -m venv .venv
+.\.venv\Scripts\activate
+python -m pip install --upgrade pip
+python -m pip cache purge
+python -m pip install -r apps/api/requirements.txt
+```
+
+Do not install Visual Studio Build Tools or Rust for this project just to satisfy dependency installation. The supported path is Python 3.12 plus prebuilt wheels.
+
 ## Roadmap Summary
 
 - V1: Production-quality MVP with database schema, FastAPI foundation, structured search, school profiles, frontend foundation, onboarding, deterministic ranking, saved schools, comparison, Redis caching, and deployment polish.
@@ -92,6 +148,9 @@ See [tasks.md](tasks.md) for the working checklist.
 Current backend validation commands are:
 
 ```powershell
+py -3.12 --version
+.\.venv\Scripts\activate
+python --version
 docker compose up -d postgres
 cd apps/api
 alembic upgrade head
@@ -107,7 +166,7 @@ Expected future commands:
 
 ## Limitations
 
-- Only `/health` and `/ready` API endpoints exist. Search, profile, saved-school, comparison, and ranking endpoints are not implemented yet.
+- `/health`, `/ready`, and `/schools/search` exist. Profile, 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/api/api/routes/schools.py

@@ -0,0 +1,27 @@
+from typing import Annotated
+
+from fastapi import APIRouter, Depends
+from sqlalchemy.orm import Session
+
+from api.deps import get_db
+from schemas.schools import SearchRequest, SearchResponse
+from services.schools import SchoolService
+
+router = APIRouter(prefix="/schools", tags=["schools"])
+
+
+def get_school_service(db: Session = Depends(get_db)) -> SchoolService:
+    return SchoolService(db)
+
+
+@router.get(
+    "/search",
+    response_model=SearchResponse,
+    summary="Structured school search",
+    description="Returns paginated school search cards using structured filters and deterministic sorting.",
+)
+def search_schools(
+    filters: Annotated[SearchRequest, Depends()],
+    service: SchoolService = Depends(get_school_service),
+) -> SearchResponse:
+    return service.search_schools(filters)

apps/api/main.py

@@ -3,6 +3,7 @@
 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,
@@ -22,6 +23,7 @@ def create_app() -> FastAPI:
         description="Backend API foundation for the College Exploration Platform.",
     )
     app.include_router(health_router)
+    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(Exception, unhandled_exception_handler)

apps/api/repositories/schools.py

@@ -1,7 +1,14 @@
+from time import perf_counter
+
+from sqlalchemy import Select, func, select
 from sqlalchemy.orm import Session
 
-from models.school import School
+from core.logging import get_logger
+from models.school import School, SchoolAcademics, SchoolCosts
 from repositories.base import BaseRepository
+from schemas.schools import SchoolSearchResult, SearchRequest
+
+logger = get_logger(__name__)
 
 
 class SchoolRepository(BaseRepository[School]):
@@ -11,3 +18,102 @@ def __init__(self, db: Session) -> None:
     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 search_schools(self, filters: SearchRequest) -> tuple[list[SchoolSearchResult], int]:
+        base_query = (
+            select(
+                School.id.label("school_id"),
+                School.name,
+                School.city,
+                School.state,
+                School.type,
+                School.setting,
+                School.undergraduate_enrollment.label("enrollment"),
+                School.acceptance_rate,
+                SchoolCosts.net_price,
+                SchoolAcademics.graduation_rate,
+            )
+            .join(SchoolCosts, SchoolCosts.school_id == School.id, isouter=True)
+            .join(SchoolAcademics, SchoolAcademics.school_id == School.id, isouter=True)
+        )
+        filtered_query = self._apply_filters(base_query, filters)
+
+        total_results = self.db.scalar(
+            select(func.count()).select_from(filtered_query.order_by(None).subquery())
+        )
+        total = int(total_results or 0)
+
+        sorted_query = self._apply_sort(filtered_query, filters)
+        paged_query = sorted_query.offset((filters.page - 1) * filters.page_size).limit(filters.page_size)
+
+        start = perf_counter()
+        rows = self.db.execute(paged_query).mappings().all()
+        duration_ms = round((perf_counter() - start) * 1000, 2)
+
+        results = [
+            SchoolSearchResult(
+                school_id=row["school_id"],
+                name=row["name"],
+                city=row["city"],
+                state=row["state"],
+                type=row["type"],
+                setting=row["setting"],
+                enrollment=row["enrollment"],
+                acceptance_rate=float(row["acceptance_rate"]) if row["acceptance_rate"] is not None else None,
+                net_price=row["net_price"],
+                graduation_rate=float(row["graduation_rate"]) if row["graduation_rate"] is not None else None,
+            )
+            for row in rows
+        ]
+        logger.info(
+            "school_search_query",
+            extra={
+                "duration_ms": duration_ms,
+                "row_count": len(results),
+                "total_results": total,
+                "page": filters.page,
+                "page_size": filters.page_size,
+            },
+        )
+        return results, total
+
+    def _apply_filters(self, query: Select[tuple], filters: SearchRequest) -> Select[tuple]:
+        if filters.query:
+            query = query.where(School.name.ilike(f"%{filters.query}%"))
+        if filters.state:
+            query = query.where(School.state == filters.state.upper())
+        if filters.region:
+            query = query.where(School.region == filters.region)
+        if filters.type:
+            query = query.where(School.type == filters.type)
+        if filters.setting:
+            query = query.where(School.setting == filters.setting)
+        if filters.min_enrollment is not None:
+            query = query.where(School.undergraduate_enrollment >= filters.min_enrollment)
+        if filters.max_enrollment is not None:
+            query = query.where(School.undergraduate_enrollment <= filters.max_enrollment)
+        if filters.min_net_price is not None:
+            query = query.where(SchoolCosts.net_price >= filters.min_net_price)
+        if filters.max_net_price is not None:
+            query = query.where(SchoolCosts.net_price <= filters.max_net_price)
+        if filters.min_acceptance_rate is not None:
+            query = query.where(School.acceptance_rate >= filters.min_acceptance_rate)
+        if filters.max_acceptance_rate is not None:
+            query = query.where(School.acceptance_rate <= filters.max_acceptance_rate)
+        if filters.min_graduation_rate is not None:
+            query = query.where(SchoolAcademics.graduation_rate >= filters.min_graduation_rate)
+        if filters.max_graduation_rate is not None:
+            query = query.where(SchoolAcademics.graduation_rate <= filters.max_graduation_rate)
+        return query
+
+    def _apply_sort(self, query: Select[tuple], filters: SearchRequest) -> Select[tuple]:
+        sort_columns = {
+            "name": School.name,
+            "net_price": SchoolCosts.net_price,
+            "graduation_rate": SchoolAcademics.graduation_rate,
+            "acceptance_rate": School.acceptance_rate,
+            "enrollment": School.undergraduate_enrollment,
+        }
+        sort_column = sort_columns[filters.sort]
+        sort_expression = sort_column.desc().nulls_last() if filters.direction == "desc" else sort_column.asc().nulls_last()
+        return query.order_by(sort_expression, School.id.asc())

apps/api/requirements.txt

@@ -1,8 +1,10 @@
-alembic==1.13.3
-fastapi==0.115.4
-httpx==0.27.2
-psycopg[binary]==3.2.3
-pydantic-settings==2.6.1
-pytest==8.3.3
-SQLAlchemy==2.0.36
-uvicorn[standard]==0.32.0
+alembic>=1.13.3,<1.15
+fastapi>=0.115.4,<0.116
+httpx>=0.27.2,<0.28
+psycopg[binary]>=3.2.10,<3.4
+pydantic>=2.10,<2.12
+pydantic-settings>=2.6.1,<2.8
+pytest>=8.3.3,<9
+python-dotenv>=1.0.1,<2
+SQLAlchemy>=2.0.36,<2.1
+uvicorn[standard]>=0.32,<0.35

apps/api/schemas/schools.py

@@ -1,14 +1,14 @@
 from typing import Literal
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 
 SchoolSort = Literal[
     "name",
     "acceptance_rate",
     "graduation_rate",
     "net_price",
-    "undergraduate_enrollment",
+    "enrollment",
 ]
 SortDirection = Literal["asc", "desc"]
 
@@ -37,6 +37,23 @@ class SchoolProfile(BaseModel):
     campus_tags: list[str] = Field(default_factory=list)
 
 
+class SchoolSearchResult(BaseModel):
+    school_id: int
+    name: str
+    city: str
+    state: str
+    type: str
+    setting: str
+    enrollment: int | None = None
+    acceptance_rate: float | None = None
+    net_price: int | None = None
+    graduation_rate: float | None = None
+    fit_score: float | None = None
+    confidence_score: float | None = None
+    top_reasons: list[str] = Field(default_factory=list)
+    top_tradeoffs: list[str] = Field(default_factory=list)
+
+
 class SearchRequest(BaseModel):
     query: str | None = Field(default=None, max_length=120)
     state: str | None = Field(default=None, min_length=2, max_length=2)
@@ -45,17 +62,33 @@ class SearchRequest(BaseModel):
     setting: str | None = Field(default=None, max_length=32)
     min_enrollment: int | None = Field(default=None, ge=0)
     max_enrollment: int | None = Field(default=None, ge=0)
+    min_net_price: int | None = Field(default=None, ge=0)
     max_net_price: int | None = Field(default=None, ge=0)
+    min_acceptance_rate: float | None = Field(default=None, ge=0, le=1)
     max_acceptance_rate: float | None = Field(default=None, ge=0, le=1)
     min_graduation_rate: float | None = Field(default=None, ge=0, le=1)
+    max_graduation_rate: float | None = Field(default=None, ge=0, le=1)
     sort: SchoolSort = "name"
     direction: SortDirection = "asc"
     page: int = Field(default=1, ge=1)
-    page_size: int = Field(default=20, ge=1, le=100)
+    page_size: int = Field(default=20, ge=1, le=50)
+
+    @model_validator(mode="after")
+    def validate_ranges(self) -> "SearchRequest":
+        ranges = [
+            ("min_enrollment", self.min_enrollment, "max_enrollment", self.max_enrollment),
+            ("min_net_price", self.min_net_price, "max_net_price", self.max_net_price),
+            ("min_acceptance_rate", self.min_acceptance_rate, "max_acceptance_rate", self.max_acceptance_rate),
+            ("min_graduation_rate", self.min_graduation_rate, "max_graduation_rate", self.max_graduation_rate),
+        ]
+        for min_name, min_value, max_name, max_value in ranges:
+            if min_value is not None and max_value is not None and min_value > max_value:
+                raise ValueError(f"{min_name} cannot be greater than {max_name}")
+        return self
 
 
 class SearchResponse(BaseModel):
-    results: list[SchoolSummary] = Field(default_factory=list)
+    results: list[SchoolSearchResult] = Field(default_factory=list)
     page: int = 1
     page_size: int = 20
     total_results: int = 0