gobbler: Instructions file for Codex

AGENTS.md - Gobbler Development Guidelines

Guidelines for AI coding agents. See CONTRIBUTING.md for full details.

Quick Reference

# Install
make dev                    # Development install with all extras

# Tests
make test                   # Unit tests
make test-unit              # Unit tests only
make test-integration       # Integration tests
make test-all               # Unit + integration + end-to-end tests
uv run pytest tests/unit/test_youtube_converter.py -v                        # Single file
uv run pytest tests/unit/test_youtube_converter.py::TestVideoIdExtraction -v # Single class
uv run pytest tests/unit/test_youtube_converter.py::TestVideoIdExtraction::test_extract_video_id_standard_url -v  # Single test

# Linting & Formatting
make lint                   # Run ruff linter + format check
uv run ruff check src/ --fix   # Auto-fix lint issues
uv run ruff format src/     # Format code

# Type Checking
make typecheck              # Run mypy

# All Checks
uv run pre-commit run --all-files

# Documentation
uv run --extra docs mkdocs build --strict

Project Structure

src/
  gobbler_cli/      # CLI commands (Typer-based)
  gobbler_core/     # Core converters and providers
  gobbler_relay/    # WebSocket relay for browser extension
  gobbler_queue/    # SQLite-backed background job queue and worker
skills/             # AI agent skill definitions
tests/unit/         # Unit tests
tests/integration/  # Integration tests
tests/e2e/          # End-to-end tests

Code Style

• Python 3.11+ required
• Line length: 100 characters max
• Type hints: Strict mode - all public functions must have annotations
• Docstrings: Google-style, required for public functions
• Imports: Organized by ruff/isort (stdlib, third-party, first-party, local)

First-party packages: gobbler_core, gobbler_cli, gobbler_relay, gobbler_queue

Type Annotations

# Use modern syntax
async def convert(url: str, provider: Provider | None = None) -> tuple[str, dict]:
    ...