btc-trading/AGENTS.md

Agent Development Guidelines

Project Overview

This is a Bitcoin trading dashboard with FastAPI backend, PostgreSQL database, and technical analysis features. The system consists of:

• Backend: FastAPI (Python 3.9+)
• Frontend: HTML/JS dashboard with lightweight-charts
• Database: PostgreSQL (TimescaleDB optimized)
• Features: Real-time candle data, technical indicators (SMA, EMA, RSI, MACD, Bollinger Bands), trading strategy simulation, backtesting

Build/Lint/Test Commands

Setup

# Create and activate virtual environment
python -m venv venv
venv\Scripts\activate  # Windows
# or source venv/bin/activate  # Linux/Mac

# Install dependencies
pip install -r requirements.txt

Running Development Server

# Quick start (Windows)
start_dev.cmd

# Quick start (Linux/Mac)
chmod +x start_dev.sh
./start_dev.sh

# Manual start
uvicorn src.api.server:app --reload --host 0.0.0.0 --port 8000

Testing

# Test database connection
python test_db.py

# Run single test (no existing test framework found but for any future tests)
python -m pytest <test_file>.py::test_<function_name> -v

Environment Setup

Environment variables in .env file:

DB_HOST=20.20.20.20
DB_PORT=5433
DB_NAME=btc_data
DB_USER=btc_bot
DB_PASSWORD=your_password

Code Style Guidelines

Python Standards

• Follow PEP 8 style guide
• Use type hints consistently throughout
• Module names should be lowercase with underscores
• Class names should use PascalCase
• Function and variable names should use snake_case
• Constants should use UPPER_CASE
• All functions should have docstrings
• Use meaningful variable names (avoid single letter names except for loop counters)

Imports

• Group imports in order: standard library, third-party, local
• Use relative imports for internal modules
• Sort imports alphabetically within each group

Error Handling

• Use explicit exception handling with specific exceptions
• Log errors with appropriate context
• Don't suppress exceptions silently
• Use try/except/finally blocks for resource management

Naming Conventions

• Classes: PascalCase
• Functions and variables: snake_case
• Constants: UPPER_CASE
• Private methods: _private_method
• Protected attributes: _protected_attribute

Documentation

• All public functions should have docstrings in Google style format
• Class docstrings should explain the class purpose and usage
• Complex logic should be commented appropriately
• API endpoints should be documented in docstrings
• Use inline comments for complex operations

Data Processing

• Use async/await for database operations
• Handle database connection pooling properly
• Validate incoming data before processing
• Use pydantic models for data validation
• Ensure proper timezone handling for datetime operations

Security

• Never log sensitive information (passwords, tokens)
• Use environment variables for configuration
• Validate all input data
• Use prepared statements for database queries to prevent injection

Asynchronous Programming

• Use asyncio for concurrent database operations
• Use async context managers for resource management
• Implement timeouts for database operations
• Handle task cancellation appropriately

Configuration

• Use pydantic-settings for configuration management
• Load environment variables with python-dotenv
• Provide default values for configuration settings

Logging

• Use logging module with appropriate log levels (DEBUG, INFO, WARNING, ERROR)
• Include contextual information in log messages
• Use structured logging where appropriate
• Log exceptions with traceback information

Testing

• Write unit tests for core components
• Test database operations asynchronously
• Mock external services where appropriate
• Test both success and failure cases
• Ensure tests are isolated

AI Coding Agent Rules

File Structure and Organization

• Organize code into logical modules: api, data_collector, strategies, etc.
• Use consistent naming across the codebase
• Follow existing project conventions when adding new features
• Place new code in corresponding directories (src/strategies/ for strategies)

Code Quality

• Maintain clean, readable code
• Write efficient code with good performance characteristics
• Follow existing code patterns for consistency
• Ensure proper error handling in all code paths
• Use type hints and validate with mypy when applicable

Documentation

• Update docstrings when modifying functions or classes
• Add usage comments for complex logic
• Update README.md if adding major new features
• Document any new environment variables or configuration options

Integration

• Respect existing patterns for API endpoints and database access
• Follow established data flow patterns
• Ensure compatibility with existing code when making changes
• Maintain backward compatibility for public APIs

Dependencies

• Only add dependencies to requirements.txt when necessary
• Check for conflicts with existing dependencies
• Keep dependency versions pinned to avoid breaking changes
• Avoid adding heavyweight dependencies unless truly required