For Python projects. Update 20260224

AGENTS.md

Repository Guidelines

Scope & Precedence

• Apply these rules unless directly overridden by user instruction.
• Conflict order: (1) user instruction, (2) this guide, (3) generic assistant defaults.

Documentation

• Save markdown files under doc/.
• Sub-folders under doc/ are allowed.
• Prefix plan/summary filenames with YYYYMMDD (example: 20260219_implementation_summary.md).

Environment & Installation (No sudo)

• Assume no sudo access.
• Keep installs user-local and reproducible.
• Ensure $HOME/.local/bin is on PATH.
• Package/tool install priority:
  1. mamba
  2. standalone user-space binary
  3. conda
  4. uv (Python packages only)
  5. pip
• If installation fails, report the cause and provide concrete next options.

Quality Tools

• Use ruff for lint/format and pyright for static type checks.
• Tool configuration lives in pyproject.toml.

Quality Checks

• During iteration (changed files):
  • ruff check <changed_files> --fix
  • ruff format <changed_files>
• Before handoff:
  • ruff check . --fix
  • ruff format .
  • pyright

Workflow Enforcement

• Run pyright after changes affecting more than one file or a shared/core module.
• Core/shared module: utility logic imported by multiple scripts/modules.
• Explicitly report type-check pass/fail.
• If type checks fail, fix relevant errors before handoff.

Python Style

• Follow PEP 8; use 4-space indentation and snake_case.
• Prefer explicit names over abbreviations.
• Prefer pathlib over os.path where feasible.
• Prefer f-strings over .format() / %.
• Add type hints; prefer collections.abc abstract types where useful.
• Guard entry points with if __name__ == "__main__":.
• No wildcard imports.
• Use logging (not print) in serious/production code.
• Prefer enumerate() over manual counters.
• Avoid hard-coded absolute paths.

Project Structure

• Put reusable logic in importable modules under src/.
• Keep runnable scripts thin (arg parsing + orchestration).
• Use ordered step script names in src/ when applicable: 01_...py, 02_...py, 03_...py.

Logging Baseline

• Use logging.getLogger(__name__).
• Use consistent levels: DEBUG, INFO, WARNING, ERROR.
• Include stable identifiers in workflow logs when available (e.g., run_id, gene, pmid).

LLM Constraint

• For iEnigma usage, follow:
  • /home/jhuang/project/NER_label_extraction/doc/iEnigma_v1.0_readme.md

Data & Secret Hygiene

• Never commit credentials, keys, tokens, or secrets.
• Keep large generated artifacts in designated output folders (for example, result/).
• Do not commit caches, temp files, or local environment folders.
• Update .gitignore for new generated artifact patterns.

Testing, Commits, PRs

• Add pytest tests (tests/test_*.py) for reusable/shared logic; run python -m pytest.
• One-off scripts may use lightweight validation unless promoted to reusable workflow logic.
• Prefer Conventional Commits (feat: ..., fix: ...).
• If asked to commit all changes, split into logical commits when appropriate.
• In PRs: state goal, list impacted artifacts (especially under data/), and include a small command/output example when behavior changes.