Spaces:
Paused
Paused
File size: 2,768 Bytes
bcf46c3 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 | ---
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"}`
|