# 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