fix(vercel): align with the documented FastAPI conventions and stop pyproject shadowing requirements

Author: codebybilal18

.github/workflows/ci.yml

@@ -54,10 +54,10 @@ jobs:
           pip install -r requirements-dev.txt
 
       - name: Lint
-        run: ruff check app api scripts tests
+        run: ruff check app scripts tests
 
       - name: Format check
-        run: ruff format --check app api scripts tests
+        run: ruff format --check app scripts tests
 
       - name: Verify the Vercel bundle stays importable without local extras
         # Guards the actual deployment contract: if anything in the import graph

.vercelignore

@@ -1,12 +1,13 @@
-# Keep the serverless bundle under the 250 MB unzipped limit.
+# Keep the serverless bundle small. A FastAPI deployment is bundled as a
+# single function, with a 500 MB limit.
 #
 # Every pattern here is ANCHORED with a leading slash, and that is not stylistic.
 # .vercelignore uses gitignore semantics: an unanchored `evals/` matches a
 # directory of that name at ANY depth, so it silently excluded `app/evals/` —
 # a package the request path imports — and the function died at cold start with
 # FUNCTION_INVOCATION_FAILED while the build itself reported success.
 #
-# Only api/ and app/ are needed at runtime.
+# Only app/ is needed at runtime.
 
 /tests/
 /k8s/

Dockerfile

@@ -55,4 +55,4 @@ HEALTHCHECK --interval=30s --timeout=5s --start-period=40s --retries=3 \
 # Single worker by default: the process holds a database pool and, when the
 # local models are installed, model weights in memory. Scale with replicas, not
 # with workers.
-CMD ["sh", "-c", "uvicorn app.main:create_app --factory --host 0.0.0.0 --port ${PORT} --workers 1 --timeout-keep-alive 75"]
+CMD ["sh", "-c", "uvicorn app.main:app --host 0.0.0.0 --port ${PORT} --workers 1 --timeout-keep-alive 75"]

README.md

@@ -222,7 +222,7 @@ Without Docker:
 ```bash
 uv venv && uv pip install -r requirements.txt -r requirements-local.txt
 alembic upgrade head
-uvicorn app.main:create_app --factory --reload
+uvicorn app.main:app --reload
 ```
 
 > Already running Postgres on 5432? Set `POSTGRES_PORT=5433` in `.env` and update `DATABASE_URL`
@@ -319,8 +319,15 @@ Import the repo at vercel.com/new. Project settings:
 |---|---|
 | Application Preset | **FastAPI** |
 | Root Directory | `./` |
-| Install Command | `pip install -r requirements.txt` (the default) |
-| Build / Output | leave empty — [vercel.json](vercel.json) handles routing |
+| Install Command | leave as the default |
+| Build / Output | leave empty |
+
+Vercel resolves the entrypoint by scanning `app.py`/`index.py`/`main.py`/`server.py`/`wsgi.py`/
+`asgi.py` at the root and inside `src/`, `app/` and `api/`, then bundles the whole app as a single
+function. This repo declares it explicitly instead — `[tool.vercel] entrypoint` in
+[pyproject.toml](pyproject.toml) — so resolution order never matters, and
+[vercel.json](vercel.json) configures that same file. `tests/test_deployment_contract.py` fails if
+the two drift apart, or if a second module-level `app` appears anywhere.
 
 Environment variables:
 

api/index.py

@@ -88,15 +88,9 @@ async def unhandled(request: Request, exc: Exception) -> JSONResponse:
     return app
 
 
-# Deliberately no module-level `app = create_app()` here.
-#
-# Vercel's FastAPI preset scans the repo for a module-level ASGI instance and
-# builds whatever it finds as the function. With one in this module *and* one in
-# api/index.py it picked this file, while the dependency install was scoped to
-# the entrypoint declared in vercel.json — so the deployed function ran without
-# fastapi installed and died with ModuleNotFoundError at cold start.
-#
-# There is now exactly one ASGI callable in the repo, at api/index.py. Anything
-# that needs an instance builds one from the factory:
-#
-#     uvicorn app.main:create_app --factory
+# The single ASGI entrypoint. `app/main.py` is one of the paths Vercel's Python
+# runtime scans for a FastAPI instance named `app`, and it is the location its
+# documentation uses. There must be exactly one such file in the repo: a second
+# one makes the resolved entrypoint ambiguous, and the build installs
+# dependencies for whichever it picked.
+app = create_app()

app/main.py

@@ -56,7 +56,7 @@ services:
       - hf_cache:/home/documind/.cache/huggingface
     command: >
       sh -c "alembic upgrade head &&
-             uvicorn app.main:create_app --factory --host 0.0.0.0 --port 8000 --reload"
+             uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload"
 
   # Optional second vector store, for the pgvector/Qdrant comparison.
   #   docker compose --profile qdrant up

docker-compose.yml

@@ -1,8 +1,16 @@
-[project]
-name = "documind-api"
-version = "0.1.0"
-description = "Cited document Q&A with a measured retrieval benchmark"
-requires-python = ">=3.12"
+# No [project] table on purpose.
+#
+# Vercel's Python builder prefers pyproject.toml over requirements.txt when a
+# [project] table is present. This project is not a distributable package, so
+# that table declared no `dependencies` — and the build installed nothing,
+# leaving the deployed function to die with `ModuleNotFoundError: No module
+# named 'fastapi'`. Without it, requirements.txt is unambiguously the source.
+
+[tool.vercel]
+# Explicit beats inferred. Vercel otherwise scans app.py/index.py/main.py/... at
+# the root and inside src/, app/ and api/, and picks whichever it finds first —
+# a resolution order this repo should not depend on.
+entrypoint = "app.main:app"
 
 [tool.ruff]
 line-length = 100

pyproject.toml

@@ -21,7 +21,7 @@ def module_level_asgi_apps() -> list[str]:
     """Files assigning a module-level `app`, which is what Vercel's FastAPI
     preset scans for when choosing an entrypoint."""
     found: list[str] = []
-    for path in list(ROOT.glob("app/**/*.py")) + list(ROOT.glob("api/**/*.py")):
+    for path in ROOT.glob("app/**/*.py"):
         tree = ast.parse(path.read_text())
         for node in tree.body:  # module level only
             targets = (
@@ -37,18 +37,50 @@ def module_level_asgi_apps() -> list[str]:
 
 
 def test_there_is_exactly_one_asgi_entrypoint():
-    """Two module-level `app` instances meant Vercel's preset built
-    `app/main.py` as the function while dependencies were installed for the
-    entrypoint declared in vercel.json. The deployed function had no fastapi and
-    died at cold start.
-
-    Anything needing an instance should use the factory:
-    `uvicorn app.main:create_app --factory`.
+    """Vercel scans app.py/index.py/main.py/server.py/wsgi.py/asgi.py at the
+    root and inside src/, app/ and api/, and builds the first FastAPI instance
+    named `app` that it finds. Two candidates once meant it built one file while
+    dependencies were installed for another, and the deployed function died with
+    ModuleNotFoundError at cold start.
     """
     apps = module_level_asgi_apps()
-    assert apps == ["api/index.py"], (
-        f"expected exactly one ASGI entrypoint at api/index.py, found {apps}. "
-        "A second one makes the deployed entrypoint ambiguous."
+    assert apps == ["app/main.py"], (
+        f"expected exactly one ASGI entrypoint at app/main.py, found {apps}. "
+        "A second one makes the resolved entrypoint ambiguous."
+    )
+
+
+def test_the_declared_entrypoint_matches_the_configured_function():
+    """pyproject.toml names the entrypoint; vercel.json configures the function
+    by resolved file path. If they drift, maxDuration silently applies to a file
+    that is not the entrypoint and every request hits the default timeout."""
+    import json
+    import re
+
+    pyproject = (ROOT / "pyproject.toml").read_text()
+    match = re.search(r'entrypoint\s*=\s*"([^"]+)"', pyproject)
+    assert match, "pyproject.toml must declare [tool.vercel] entrypoint"
+
+    module, _, attribute = match.group(1).partition(":")
+    entry_file = module.replace(".", "/") + ".py"
+    assert attribute == "app"
+    assert (ROOT / entry_file).exists(), f"{entry_file} does not exist"
+
+    configured = list(json.loads((ROOT / "vercel.json").read_text())["functions"])
+    assert configured == [entry_file], (
+        f"vercel.json configures {configured} but the entrypoint is {entry_file}"
+    )
+
+
+def test_pyproject_declares_no_project_table():
+    """A [project] table makes Vercel's Python builder prefer pyproject.toml
+    over requirements.txt. With no `dependencies` listed there, the build
+    installs nothing and the function cannot import fastapi."""
+    pyproject = (ROOT / "pyproject.toml").read_text()
+    has_project = any(line.strip() == "[project]" for line in pyproject.splitlines())
+    assert not has_project, (
+        "pyproject.toml declares [project]; either remove it so requirements.txt "
+        "is used, or list every runtime dependency under [project.dependencies]."
     )
 
 
@@ -87,30 +119,22 @@ def test_nothing_the_runtime_imports_is_excluded_from_the_bundle():
     required = [
         f
         for f in tracked
-        if f.startswith(("app/", "api/"))
-        or f in ("requirements.txt", "vercel.json", ".python-version")
+        if f.startswith("app/")
+        or f in ("requirements.txt", "vercel.json", "pyproject.toml", ".python-version")
     ]
     excluded = [f for f in required if spec.match_file(f)]
 
     assert not excluded, f"runtime files excluded from the Vercel bundle: {excluded}"
 
 
 @pytest.mark.skipif(sys.platform == "win32", reason="posix path assumptions")
-def test_the_entrypoint_loads_without_the_repo_root_on_syspath():
-    """Vercel executes api/index.py from another directory. If the sys.path
-    bootstrap in that file regresses, `app` becomes unimportable in production
-    while every local run still works."""
+def test_the_entrypoint_imports_as_a_module():
+    """Vercel imports the entrypoint as `app.main`, not as a script. An import
+    that only resolves because of the local working directory would work in
+    every dev run and fail in production."""
     result = subprocess.run(
-        [
-            sys.executable,
-            "-c",
-            "import importlib.util,sys;"
-            f"spec=importlib.util.spec_from_file_location('e', r'{ROOT / 'api' / 'index.py'}');"
-            "m=importlib.util.module_from_spec(spec);"
-            "spec.loader.exec_module(m);"
-            "print(len(m.app.routes))",
-        ],
-        cwd="/tmp",
+        [sys.executable, "-c", "from app.main import app; print(len(app.routes))"],
+        cwd=ROOT,
         capture_output=True,
         text=True,
     )

tests/test_deployment_contract.py

@@ -1,10 +1,8 @@
 {
   "$schema": "https://openapi.vercel.sh/vercel.json",
   "functions": {
-    "api/index.py": {
-      "maxDuration": 60,
-      "includeFiles": "app/**"
+    "app/main.py": {
+      "maxDuration": 60
     }
-  },
-  "rewrites": [{ "source": "/(.*)", "destination": "/api/index" }]
+  }
 }