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

metadata

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:

  {
      "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:

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:

curl -s https://opticparse-python-sg.onrender.com/health

Expected response: {"status":"ok","service":"opticparse","version":"1.0.0"}