.agents/skills/debug-python-opticparse/SKILL.md

---
name: debug-python-opticparse
description: >
  Enforces Python/FastAPI idioms, PEP8 standards, and mandatory local pytest
  execution for all changes to the OpticParse Python backend (server.py and
  related files in the repository root).
---

# OpticParse — Python / FastAPI Debugging Skill

## Scope
This skill applies to ALL files in the repository root that belong to the
OpticParse Python service:
- `server.py` — Main FastAPI application
- `test_server.py` — Pytest unit tests
- `requirements.txt` — Python dependencies
- `Dockerfile` — Docker build for Render deployment
- `.env` — Environment variables (never commit this)
- `render.yaml` — Lines 1–19 only (Python service block)

**DO NOT** modify any files inside `opticparse-js/`. That directory belongs to
the PhishVision TypeScript service and is managed by a separate skill.

## Coding Standards

### Style
- Follow **PEP 8** strictly: 4-space indentation, snake_case for functions
  and variables, PascalCase for classes.
- Add **type hints** to all public function signatures.
- Maximum line length: 100 characters.
- Use f-strings for string formatting, not `.format()` or `%`.

### FastAPI Patterns
- Use `Depends()` for dependency injection (e.g., API key validation).
- Raise `HTTPException` for all error responses — never return raw dicts
  with error codes.
- Define request/response models using Pydantic `BaseModel`.
- All new endpoints must include OpenAPI docstrings.

### AI Provider Rotation
- New AI providers must follow the existing `AI_PROVIDERS` list structure:
  ```python
  {
      "name": "ProviderName",
      "key": os.getenv("ENV_VAR_NAME"),
      "base": "https://api.provider.com/v1",
      "model": "model-name",
      "vision": True,  # or False for text-only fallback
  }
  ```
- Always add new providers to the END of the list (lowest priority).

### Logging
- Use the existing `logger` instance (`logging.getLogger("vision-scrape")`).
- Never use `print()` for operational logging.
- Log at `INFO` for successful operations, `WARNING` for retries, `ERROR` for
  failures.

### Playwright / Browser
- Always close browser instances in a `finally` block to prevent memory leaks
  on Render's 512MB free tier.
- Abort unnecessary resource types (media, font, websocket) via request
  interception to save bandwidth.

## Pre-Commit Verification
Before committing any changes, you MUST run:
```bash
python -m pytest test_server.py -v
```
If any test fails, fix the issue before committing. Do not skip or ignore
failing tests.

## Post-Deploy Verification
After pushing changes, verify the live deployment:
```bash
curl -s https://opticparse-python-sg.onrender.com/health
```
Expected response: `{"status":"ok","service":"opticparse","version":"1.0.0"}`