Space-Banane
3cf4a9a40a
python / test (push) Failing after 8s
- Updated README.md to reflect new features and API changes. - Introduced versioning in app initialization. - Enhanced configuration management in app/config.py with new validation functions. - Refactored main.py to improve request handling and response generation. - Added new models in app/models.py for structured API responses. - Implemented a dedicated UI rendering function in app/ui.py. - Improved Docker configuration for better security and health checks. - Updated tests to cover new validation rules and response formats. - Added CLAUDE.md for project guidelines and working rules.
100 lines
3.6 KiB
Markdown
100 lines
3.6 KiB
Markdown
# CLAUDE.md — face-lock
|
|
|
|
## Project Summary
|
|
|
|
face-lock is a standalone FastAPI microservice for image subject detection and
|
|
square cropping. It accepts an uploaded image, finds the primary subject using
|
|
OpenCV-based detectors, expands the crop with a configurable buffer, and
|
|
returns either JSON with preview data URLs or a binary JPEG crop.
|
|
|
|
This repo is intentionally independent from the BetterNews API/frontend/worker
|
|
stack. Treat it as a fifth repo in the workspace with its own runtime, Docker
|
|
image, and CI.
|
|
|
|
---
|
|
|
|
## API Surface
|
|
|
|
| Method | Path | Description |
|
|
| ------ | ------------------ | ----------- |
|
|
| GET | `/health` | Health and runtime config summary. |
|
|
| GET | `/` | Small test UI when enabled. |
|
|
| POST | `/api/focus` | Returns JSON metadata plus crop and annotated previews as data URLs. |
|
|
| POST | `/api/focus/image` | Returns the cropped JPEG directly. |
|
|
| GET | `/docs` | OpenAPI UI when docs are enabled. |
|
|
| GET | `/openapi.json` | OpenAPI schema when docs are enabled. |
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
Key environment variables:
|
|
|
|
- `ENV` or `FACE_LOCK_ENV` — environment label, defaults to `production`.
|
|
- `PORT` — HTTP port, defaults to `8000`.
|
|
- `LOG_LEVEL` — standard Python log level, defaults to `info`.
|
|
- `FACE_LOCK_DOCS` — enable or disable `/docs` and `/openapi.json`.
|
|
- `FACE_LOCK_TEST_UI` — enable or disable the browser test UI at `/`.
|
|
- `FACE_LOCK_MAX_UPLOAD_BYTES` — maximum upload size in bytes.
|
|
- `FACE_LOCK_ALLOWED_MIME_TYPES` — comma-separated allowlist of image MIME types.
|
|
- `FACE_LOCK_AUTH_TOKEN` — optional shared secret for header auth.
|
|
- `FACE_LOCK_AUTH_HEADER` — optional header override, defaults to `X-API-Key`.
|
|
- `WEB_CONCURRENCY` — worker count for the container entrypoint.
|
|
- `UVICORN_KEEPALIVE_TIMEOUT` — keepalive timeout for the container entrypoint.
|
|
|
|
Auth supports either the configured header value or `Authorization: Bearer <token>`.
|
|
|
|
---
|
|
|
|
## Repo Layout
|
|
|
|
- `app/main.py` — FastAPI app, routes, auth, upload validation, response headers.
|
|
- `app/config.py` — environment parsing and validation.
|
|
- `app/models.py` — API enums and response models.
|
|
- `app/ui.py` — embedded test UI HTML.
|
|
- `app/vision.py` — OpenCV detection and crop logic.
|
|
- `tests/` — API and image-processing tests.
|
|
- `docker/entrypoint.sh` — production container startup command.
|
|
- `.gitea/workflows/python.yml` — test and image build pipeline.
|
|
|
|
---
|
|
|
|
## Working Rules
|
|
|
|
1. Keep the service stateless. Do not introduce local persistence or writable app directories without explicit need.
|
|
2. Preserve the current request contract unless a change is clearly documented in both `README.md` and `docs/README.md`.
|
|
3. Validate upload size, detector values, and content type at the API boundary before handing data to OpenCV.
|
|
4. Prefer explicit, deterministic failures over silent fallbacks when configuration is invalid.
|
|
5. Keep the Docker image non-root and production-friendly.
|
|
6. Avoid adding new dependencies unless the standard library, FastAPI, or OpenCV cannot reasonably solve the problem.
|
|
7. Update tests whenever request validation, auth, output shape, or detector behavior changes.
|
|
8. Keep the test UI optional and disabled by default for production-style environments.
|
|
|
|
---
|
|
|
|
## Local Development
|
|
|
|
```sh
|
|
python -m pip install -r requirements.txt
|
|
python -m pytest
|
|
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
|
```
|
|
|
|
Docker:
|
|
|
|
```sh
|
|
docker compose up --build
|
|
```
|
|
|
|
---
|
|
|
|
## Verification
|
|
|
|
Before pushing:
|
|
|
|
```sh
|
|
python -m compileall -q app tests
|
|
python -m pytest
|
|
docker build -t face-lock:test .
|
|
```
|