image-gen-mcp: Instructions file for Codex

Repository Guidelines

Project Structure & Module Organization

• src/ — main package (MCP server). Key modules: main.py (entry), schema.py (Pydantic I/O), engines/ (providers: OpenAI, Gemini, Vertex/Imagen, DALL·E), utils/, shard/ (enums/constants), settings.py (env config).
• tests/ — pytest tests (add new tests here).
• scripts/ — helper workflows (feature scaffolding, plan checks).
• templates/, docs/, memory/ — specs, docs, and working notes.

Build, Test, and Development Commands

• Run server: python -m src.main
• With uv: uv run python -m src.main (installs/uses lockfile).
• Lint: ruff check . Format: black .
• Type-check: pyright
• Tests: pytest -q
• Feature scaffolding: ./scripts/create-new-feature.sh "image upscaling"

Coding Style & Naming Conventions

• Python 3.12, 4-space indent, type hints required for new/changed code.
• Modules: lower_snake_case.py; Classes: CapWords; Functions/vars: snake_case.
• Pydantic v2 models in schema.py define the public contract; keep field names and enums stable.
• Run ruff and black before pushing; keep diffs minimal and cohesive.

No inline imports

• Do not use function-local (inline) imports anywhere in the codebase. All imports must appear at module top-level.
• Exception: imports guarded by if TYPE_CHECKING: for typing-only imports are allowed.

Rationale: top-level imports avoid surprising runtime side-effects, make static analysis and packaging reliable, and ensure dependency graphs are clear. If an import causes circular import issues, prefer one of:

• move type-only imports into a if TYPE_CHECKING: block, or
• refactor module boundaries (e.g., move shared types into schema.py), or
• use lazy-loading helpers in a single, well-documented location (engines/factory.py uses lazy import resolution via _load_engine_class).

Example (bad):

def my_tool():
    # avoid this
    from .schema import ImageToolStructured

    ...

Example (good):