Hugging Face's logo

Spaces:
paras9909
/
opticparse-python
Paused

App Files Community
opticparse-python / .agents /AGENTS.md
Nanny7's picture
Nanny7
initial deploy
bcf46c3
preview code
|
Raw History Blame Contribute Delete
2.56 kB

Project-Wide Agent Rules — OpticParse Monorepo

These rules apply to ALL agents working in this repository, regardless of which service they are modifying.

Repository Structure

This is a polyglot monorepo containing two independent microservices:

Service Language Directory Render URL
OpticParse Python / FastAPI Repository root opticparse-python-sg.onrender.com
PhishVision TypeScript / Express opticparse-js/ opticparse-1opticparse-node-sg.onrender.com

Strict Isolation Rules

  1. Never cross service boundaries. If you are fixing OpticParse, do NOT touch files inside opticparse-js/. If you are fixing PhishVision, do NOT touch server.py or other root-level Python files.
  2. render.yaml ownership: Lines 1–19 belong to OpticParse. Lines 21–39 belong to PhishVision. Never edit the other service's block.

Git Workflow

  1. Never push directly to main. Always create a fix/<service>-<description> branch.
  2. Use conventional commit format:
    • fix(opticparse): <description> for bug fixes
    • feat(opticparse): <description> for new features
    • chore(opticparse): <description> for maintenance
    • Replace opticparse with phishvision for the Node service.
  3. After pushing, create a Draft Pull Request and halt for user review.

Security Rules

  1. Never commit .env files. They contain API keys and database credentials.
  2. Never log API keys — not even partially. Use *** masking if needed.
  3. Never hardcode secrets in source code. Always use os.getenv() (Python) or process.env (TypeScript).

Testing Requirements

  1. Python (OpticParse): Run python -m pytest test_server.py -v before committing.
  2. TypeScript (PhishVision): Run npx tsc --noEmit before committing.
  3. If any test or compilation fails, fix it before committing. No exceptions.

AI Provider Rotation

Both services share the same set of free AI provider API keys. When adding or modifying providers:

  1. Follow the existing data structure (AI_PROVIDERS dict in Python, AIProvider interface in TypeScript).
  2. Add new providers to the END of the rotation list.
  3. Update BOTH services if a provider key changes or a model is deprecated.

Documentation

  1. Preserve all existing comments and docstrings unless directly related to your code change.
  2. New public endpoints must include OpenAPI documentation.
  3. Update README.md if adding new endpoints or changing the API contract.