DOC: Remove dead app/schemas/test.py and compress signature-restating docstrings (follow-up to #1458) #1499

What's wrong with the existing documentation

Two follow-ups from #1458 that #1480 deliberately left out of scope to keep that PR reviewable. Both are in-code documentation rather than prose docs.

1. Two dead test.py files.

backend/app/schemas/test.py is 51 lines of Pydantic models. On dev its only reference in code is a commented-out import:

backend/app/routes/test.py:9:# from app.schemas.test import (

#1480 deletes routes/test.py outright (173 lines, entirely commented out). After that merges, schemas/test.py has no references in code, commented or live. The test.py row in the schemas table of docs/backend/backend_python/directory-structure.md should go with it.

backend/test.py is a 69-line standalone script that nothing imports. It queries an image_id_mapping table that no longer exists in the schema, so it cannot run against a current database. It was last changed in March 2025.

Both belong in one PR, straight after #1480 lands. Not before: deleting schemas/test.py first would leave a comment pointing at a missing module.

2. Multi-line docstrings that restate the signature.

AGENTS.md says comments should be "one or two lines, explaining why rather than what" and that "the codebase does not use long prose comment blocks or multi-paragraph docstrings". Measured with an AST walk over every backend Python file:

Heaviest files on dev:

23  backend/app/utils/videos.py
20  backend/app/database/memories.py
20  backend/tests/test_face_clusters.py
16  backend/app/utils/face_clusters.py
16  backend/app/utils/memory_curator.py
15  backend/app/database/video_frames.py
15  backend/tests/test_memory_curator.py
14  backend/app/database/folders.py

The same rule from #1458 applies: this is not a blanket strip. Per @rohan-pandeyy's steer on that issue, docstrings carrying real reasoning get compressed with the argument intact, and only the ones restating the signature below them get removed. An Args: block that names each parameter and its type, when the annotated signature already says both, is the clear case.

MyPy now shapes the split. CI type-checks every Python file a PR touches, in full (3d84d7b). Of the 98 files holding a multi-line docstring, 37 already fail MyPy on dev, with 301 errors between them. A docstring-only change to any of those goes red without touching a type, so each pass either fixes the existing errors in the files it touches or leaves those files until they are type-clean.

#1480 also hands these passes the comment cleanup for 27 files it left untouched for the same reason; its body lists them.

Suggested split:

• the two dead files, straight after docs: strip comment slop and dead commented-out code #1480 merges
• app/database/ and app/utils/ in one pass
• tests/ in a second

Add ScreenShots

Not applicable, this is in-code documentation.

Record

• I agree to follow this project's Code of Conduct
• I want to work on this issue