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

Running Tests

# Manual testing approach - run individual commands to test functionality
# Test schedule fetching
myice schedule --days 7

# Test mobile login
myice mobile-login

# Test specific command help
myice search --help

# Test web API (run in background)
poetry run fastapi run myice/webapi.py &

# Run a single pre-commit hook on specific file
pre-commit run ruff --files myice/myice.py
pre-commit run ruff-format --files myice/webapi.py
pre-commit run mypy --files myice/myice.py

Running the Web API

# Run with poetry
poetry run fastapi run myice/webapi.py --host 127.0.0.1

# Run with uv (alternative)
uv run fastapi run myice/webapi.py --host 127.0.0.1

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
• pypdf for PDF processing
• Use rich for enhanced console output
• Custom rl_ai_tools package for AI functionalities

Git Commit Messages

• Use conventional commits format
• Never mention Claude in commit messages
• Be descriptive but concise
• Use present tense ("add feature" not "added feature")

Additional Rules

• Always use ddg-mcp to perform Web Search functionality
• Follow the existing code patterns in myice/myice.py and myice/webapi.py
• Maintain backward compatibility when modifying existing APIs
• Document new features in README.md
• Always run ruff format and ruff check after editing a python file
• Use conventional commit messages
• When fixing JSON parsing issues, follow the pattern established in sanitize_json_response function