Skip to content

AGENTS.md

Latest commit

 

History

History
32 lines (22 loc) · 2.15 KB

AGENTS.md

File metadata and controls

32 lines (22 loc) · 2.15 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

Standalone PII redaction API wrapping OpenAI's privacy-filter model via HuggingFace transformers. POST text, get back redacted text with typed numbered placeholders (e.g. <PRIVATE_PERSON_1>, <PRIVATE_EMAIL_2>) and detected span metadata.

Commands

uv sync                              # Install dependencies
cp .env.example .env                 # Configure environment
DEV_MODE=true uv run python server.py  # Run with debug logging
docker build -t privacy-filter . && docker run -p 8000:8000 --env-file .env privacy-filter

Architecture

Flat 4-file structure, no package hierarchy:

  • server.py — FastAPI app. Loads .env manually (no python-dotenv). Lifespan loads the model at startup. Auth (optional Bearer token), rate limiting (slowapi, in-memory per-IP), CORS, and all error responses are configured here. Every error returns ErrorResponse JSON — no stack traces leak.
  • redactor.py — PIIRedactor class. Lazy-imports transformers inside __init__ to avoid loading torch at module import time. Runs the token-classification pipeline, sorts entities by offset, assigns per-label sequential IDs, and builds redacted text via cursor-based string assembly.
  • schemas.py — Pydantic models. RedactRequest uses extra="forbid" to reject unknown fields. All responses (including errors) are typed here.
  • Dockerfile — Multi-stage build. Builder installs CPU-only PyTorch via the PyTorch wheel index. Final stage runs as non-root user app with HF_HOME set so the pre-downloaded model cache is found at runtime.

Key decisions

  • device parameter (not device_map) on the pipeline — device_map requires accelerate; device handles single-device natively.
  • httpx/httpcore loggers are capped to WARNING to suppress HuggingFace download noise in DEV_MODE.
  • Auth, rate limiting, and CORS are all optional — disabled by default, activated via env vars.
  • The model (~1.5GB) downloads from HuggingFace on first use and caches locally.