diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e06ebb2 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,77 @@ +# Development Guide for Agentic Coding Agents + +## Build/Lint/Test Commands + +### Setup + +```bash +# Install dependencies with Poetry +poetry install + +# Install pre-commit hooks +pre-commit install +``` + +### Linting and Formatting + +```bash +# 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 + +```bash +# 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