myice/AGENTS.md

Development Guide for Agentic Coding Agents

Build/Lint/Test Commands

Setup

# Install dependencies with Poetry
poetry install

# Install pre-commit hooks
pre-commit install

Linting and Formatting

# Run all pre-commit checks (linting, formatting, type checking)
pre-commit run --all-files

# Run specific linters
ruff check .                    # Python linting
ruff format .                   # Python formatting
mypy .                          # Type checking
yamllint .                      # YAML linting
markdownlint .                  # Markdown linting

Testing

# Run tests (no specific test framework configured)
# Project uses manual testing with example PDF files in repository

Code Style Guidelines

Imports

• Standard library imports first, then third-party, then local imports
• Use explicit imports rather than wildcard imports
• Group imports logically with blank lines between groups

Formatting

• Use ruff-format for automatic formatting
• Follow PEP 8 style guide
• Maximum line length: 88 characters (default ruff setting)
• Use 4 spaces for indentation

Types

• Use type hints for function parameters and return values
• Prefer built-in types (str, int, list, dict) over typing aliases when possible
• Use typing.Annotated for Typer command options

Naming Conventions

• Variables and functions: snake_case
• Classes: PascalCase
• Constants: UPPER_SNAKE_CASE
• Private members: prefixed with underscore (_private)

Error Handling

• Use try/except blocks for expected exceptions
• Raise appropriate HTTPException for API errors
• Include descriptive error messages
• Use sys.exit(1) for command-line tool errors

Frameworks and Libraries

• Typer for CLI interface
• FastAPI for web API
• requests for HTTP requests
• PyPDF2 for PDF processing
• Use rich for enhanced console output