cv-rest-mcp-server: Instructions file for Codex

AGENTS.md

Python Environment

Targets Python 3.14 — do not use syntax newer than 3.14.

All dependencies are project-specific and managed by uv via pyproject.toml. Never use pip or a requirements.txt. Install with:

uv sync --group dev

Add a dependency with uv add <package> (uv add --group dev <package> for dev-only). Never use uv pip to manage dependencies — it bypasses pyproject.toml and the lockfile.

When running Python commands, use uv run to execute within the project virtual environment.

uv run <command>

Git Workflow

• Branch from main as feature/<name>. Never commit directly to main.
• Use Conventional Commits (feat:, fix:, docs:, refactor:, chore:).
• Stage changes for review. Do not commit or push unless asked.
• No Co-Authored-By: trailers or tool-attribution lines in commits or PR bodies.

Code Style

• Follow existing FastAPI + FastMCP patterns in services/portfolio/main.py
• Use ruff for linting and formatting
• Use ty for type checking
• Type-hint every public function and method, including return types
• Write Google-style docstrings for every public function and method
• Use pathlib for filesystem paths — never os.path
• Prefer f-strings over str.format() or % formatting
• Follow EAFP: handle the exception rather than pre-checking the condition
• Validate request bodies with Pydantic models
• Prefer idiomatic Python: comprehensions, generators, decorators, context managers, memory efficient data structures.
• Avoid hardcoding file paths or line numbers in comments, docstrings, and .md documentation. A path or line reference goes stale the moment the referenced code moves — this repo has already had a rename (app/ → services/portfolio/) break several such references across docs and docstrings. Prefer naming the function/class/fixture instead (e.g. "see the auth_settings fixture" or "see the app.add_middleware(...) block", not "see conftest.py:240" or "main.py:166-188"). If a path must be named, don't pin a line range. Applies to AGENTS.md, CLAUDE.md, README.md, docs/, and plan files too.
• Don't name a module or package inside its own docstring, or point at a sibling module by filename. A module docstring saying "Job-posting document store (job_posting_document_store.py)" or "Mirrors revisions/revision.py's layout" is a rename waiting to lie — the jd_* → job_posting_* rename left exactly these stale. The file already states its own name; describe what it does instead, and refer to other code by the class/function it exports (e.g. "the same shape as Revision", not "same as revisions/revision.py").