Fastapi conversion

.gitignore

@@ -33,3 +33,6 @@ coverage.xml
 mpcontribs-api/supervisord.conf
 mpcontribs-portal/supervisord.conf
 **/.DS_Store
+.venv/
+.env
+.claude/

mpcontribs-api/.env.example

@@ -0,0 +1,11 @@
+MPCONTRIBS_ENVIRONMENT=dev
+
+MPCONTRIBS_MONGO__URI=mongodb+srv://<db_username>:<db_password>@host.hash.mongodb.net/?appName=database-name
+MPCONTRIBS_MONGO__DB_NAME=database-name
+
+MPCONTRIBS_REDIS_ADDRESS=redis-address # placeholder; not used yet
+MPCONTRIBS_REDIS_URL=redis-url
+
+MPCONTRIBS_MAIL_DEFAULT_SENDER=mail-default-sender # placeholder; not used yet
+
+MPCONTRIBS_VERSION=version

mpcontribs-api/.gitignore

@@ -0,0 +1 @@
+src/mpcontribs_api/old

mpcontribs-api/CLAUDE.md

@@ -0,0 +1,85 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+This is a complete rewrite of the MPContribs API server.
+The core of the package is FastAPI, Pydantic, and Beanie.
+Developer experience and process efficiency are top priorities.
+
+## Commands
+
+```bash
+# Format, fix, and lint (preferred)
+just fmt
+
+# Run tests
+uv run pytest
+
+# Run tests by marker
+uv run pytest -m base
+uv run pytest -m extra
+
+# Run tests in parallel
+uv run pytest -n auto
+
+# Type check
+uv run basedpyright
+```
+
+## Environment
+
+Copy `.env.example` to `.env`. Key variables (all prefixed `MPCONTRIBS_`):
+
+- `MONGO__URI` — MongoDB Atlas URI
+- `MONGO__DB_NAME` — database name
+- `KONG__GATEWAY_SECRET` — shared secret for verifying requests came through Kong
+- `ENVIRONMENT` — `dev` or `prod` (controls log format and debug mode)
+
+## Architecture
+
+### Domain structure
+
+Each resource lives in `src/mpcontribs_api/domains/<resource>/` with four files:
+
+- `models.py` — Beanie `Document` subclass (DB model) + Pydantic output/input/patch/filter models
+- `repository.py` — `MongoDb<Resource>Repository` encapsulating all database access
+- `router.py` — `APIRouter` with CRUD endpoint handlers
+- `dependencies.py` — `<Resource>Dep` type alias (`Annotated[MongoDb<Resource>Repository, Depends(...)]`)
+
+Routers are registered in `src/mpcontribs_api/api/v1/router.py`.
+
+### Authentication and authorization
+
+Kong injects user identity via headers; `auth.py` parses them into a frozen `User` model. The dependency chain is:
+
+- `UserDep` — any caller (anonymous or authenticated)
+- `AuthedDep` — requires authenticated user (raises 401 otherwise)
+- `require_role(role)` — factory returning a dependency that requires a specific group membership
+
+All database access goes through a repository instantiated with the current `User`. The repository's `_scope` dict is injected into every MongoDB query automatically:
+
+- **Admins** (members of `mongo.admin_group`): no filter applied
+- **Authenticated users**: see public+approved data, own resources (`owner == username`), and group resources
+- **Anonymous**: public + approved only
+
+`verify_gateway()` in `dependencies.py` validates the `x-gateway-secret` header to ensure Kong was the actual caller.
+
+### Repository pattern
+
+Repositories take a `User` at construction time and expose typed async methods (`get_*`, `insert_*`, `patch_*`, `upsert_*`, `delete_*`). They never leak the scope logic to routers — routers only call repository methods.
+
+### Sparse field selection
+
+The `_fields` query parameter (handled in `projection.py`) lets callers request specific fields (comma-separated, dotted for nesting). `SparseFieldsModel` dynamically creates a trimmed Pydantic model via `create_model()` and converts field paths to MongoDB projection syntax. Results are cached with `@lru_cache`.
+
+### Cursor-based pagination
+
+`Page[T]` in `pagination.py` contains `items` and a `next_cursor` (base64-encoded last item ID). Pagination is forward-only and stateless. Default page size is 20; max is 100.
+
+### Exception hierarchy
+
+`exceptions.py` defines `AppError` subclasses (`NotFoundError`, `ConflictError`, `ValidationError`, `AuthenticationError`, `PermissionError`). All carry `status_code`, `error_code`, `message`, and a `context` dict. Handlers in `app.py` convert them to a uniform JSON shape; internal context is logged but not sent to clients.
+
+### Observability
+
+`logging.py` configures structlog with per-request context vars (request_id, method, path, consumer_id) bound by the middleware in `middleware.py`. OpenTelemetry traces are exported via OTLP/gRPC and trace/span IDs are injected into every log line.

mpcontribs-api/Dockerfile

@@ -1,58 +1,42 @@
+# NOTE: base image must be updated to Python 3.14 to satisfy requires-python in pyproject.toml
 FROM materialsproject/devops:python-3.1113.4 AS base
-RUN apt-get update && apt-get install -y --no-install-recommends supervisor libopenblas-dev libpq-dev vim && apt-get clean
+RUN apt-get update && apt-get install -y --no-install-recommends supervisor libopenblas-dev vim && apt-get clean
 WORKDIR /app
 
 FROM base AS builder
-RUN apt-get update && apt-get install -y --no-install-recommends gcc git g++ libsnappy-dev wget liblapack-dev && apt-get clean
-ENV PIP_FLAGS "--no-cache-dir --compile"
-COPY requirements/deployment.txt ./requirements.txt
-RUN pip install $PIP_FLAGS -r requirements.txt
-COPY pyproject.toml .
-COPY mpcontribs mpcontribs
+RUN apt-get update && apt-get install -y --no-install-recommends gcc git g++ wget liblapack-dev && apt-get clean
+RUN pip install uv
+COPY pyproject.toml uv.lock ./
+COPY src src
 ARG CONTRIBS_VERSION
-RUN SETUPTOOLS_SCM_PRETEND_VERSION=${CONTRIBS_VERSION} pip install $PIP_FLAGS --no-deps .
-#ENV SETUPTOOLS_SCM_PRETEND_VERSION 0.0.0
-#COPY marshmallow-mongoengine marshmallow-mongoengine
-#RUN cd marshmallow-mongoengine && pip install $PIP_FLAGS --no-deps -e .
-#COPY mimerender mimerender
-#RUN cd mimerender && pip install $PIP_FLAGS --no-deps -e .
-#COPY flask-mongorest flask-mongorest
-#RUN cd flask-mongorest && pip install $PIP_FLAGS --no-deps -e .
-#COPY AtlasQ AtlasQ
-#RUN cd AtlasQ && pip install $PIP_FLAGS --no-deps -e .
+RUN SETUPTOOLS_SCM_PRETEND_VERSION=${CONTRIBS_VERSION} uv sync --frozen --no-dev
 RUN wget -q https://raw.githubusercontent.com/vishnubob/wait-for-it/master/wait-for-it.sh && \
-  chmod +x wait-for-it.sh && mv wait-for-it.sh /usr/local/bin/ && \
-  wget -q https://github.com/materialsproject/MPContribs/blob/master/mpcontribs-api/mpcontribs/api/contributions/formulae.json.gz?raw=true \
-  -O mpcontribs/api/contributions/formulae.json.gz
+  chmod +x wait-for-it.sh && mv wait-for-it.sh /usr/local/bin/
 
 FROM base
 ARG BUILDARCH
 ENV BUILDARCH=x86_64
-COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
-COPY --from=builder /usr/local/bin /usr/local/bin
-COPY --from=builder /usr/lib/$BUILDARCH-linux-gnu/libsnappy* /usr/lib/$BUILDARCH-linux-gnu/
+COPY --from=builder /app/.venv /app/.venv
+COPY --from=builder /usr/local/bin/wait-for-it.sh /usr/local/bin/
 
-COPY --from=builder /app/mpcontribs/api /app/mpcontribs/api
 WORKDIR /app
 RUN mkdir -p /var/log/supervisor
 
 COPY supervisord supervisord
 COPY scripts scripts
 COPY main.py .
-COPY maintenance.py .
 COPY docker-entrypoint.sh .
-COPY gunicorn.conf.py .
-RUN chmod +x main.py scripts/start.sh scripts/start_rq.sh docker-entrypoint.sh
+RUN chmod +x main.py scripts/start.sh docker-entrypoint.sh
 
 ARG VERSION
-ENV DD_SERVICE=contribs-apis \
+ENV PATH="/app/.venv/bin:$PATH" \
+  DD_SERVICE=contribs-apis \
   DD_ENV=prod \
   DD_VERSION=$VERSION \
   DD_TRACE_HOST=localhost:8126 \
-  DD_TRACE_OTEL_ENABLED=false \
   DD_MAIN_PACKAGE=mpcontribs-api
 
-LABEL com.datadoghq.ad.logs='[{"source": "gunicorn", "service": "contribs-apis"}]'
+LABEL com.datadoghq.ad.logs='[{"source": "uvicorn", "service": "contribs-apis"}]'
 EXPOSE 10000 10002 10003 10005 20000
 ENTRYPOINT ["/app/docker-entrypoint.sh"]
 CMD ["/usr/bin/supervisord", "-c", "supervisord.conf"]

mpcontribs-api/justfile

@@ -0,0 +1,20 @@
+# Run the dev server (auto-reloads on file changes)
+dev:
+    uv run fastapi dev src/mpcontribs_api/app.py
+
+# Format, fix, and lint all source code
+fmt:
+    uv run ruff format
+    -uv run ruff check --fix
+    -uv run ruff check --fix --unsafe-fixes
+    -uv run pydocstringformatter --write
+
+test suite="all":
+    #!/usr/bin/env bash
+    case "{{suite}}" in
+      all|a)           uv run pytest tests/ ;;
+      integration|i)   uv run pytest tests/integration/ -m "not db" ;;
+      unit|u)          uv run pytest tests/unit/ ;;
+      db|d)            uv run pytest tests/integration/db/ -m db ;;
+      *) echo "unknown suite '{{suite}}' — use: all/a, integration/i, unit/u, db/d" && exit 1 ;;
+    esac

mpcontribs-api/main.py

@@ -1,14 +1,14 @@
 #!/usr/bin/env python
-import os
-import requests
-import boto3
 import logging
+import os
 
+import boto3
+import requests
 from supervisor.options import ClientOptions
 from supervisor.supervisorctl import Controller
 
 logger = logging.getLogger(__name__)
-client = boto3.client('ecs')
+client = boto3.client("ecs")
 
 
 def start(program):