Add EUPHEMIA-compatible bid objects module

[tommed]

Summary

Implements the bids.py module containing Pydantic v2 models for the four EUPHEMIA-compatible bid types used in European power market auctions:

• SimpleBid: Price-quantity curve bid for a single MTU
• BlockBid: Fixed price/volume across contiguous MTUs with configurable min acceptance ratio
• LinkedBlockBid: Block bid with parent dependency for operational constraints
• ExclusiveGroupBid: Container for mutually exclusive block bids (max one accepted)

Also includes 8 helper functions for ergonomic bid construction (block_bid, linked_block_bid, exclusive_group, etc.) and validation utilities.

Implementation Details

• Frozen Pydantic models: All bids are immutable with comprehensive field/model validators
• Type safety: Decimal for prices/volumes, timezone-aware datetimes only
• Validation: Enforces EUPHEMIA constraints (e.g., min_acceptance_ratio ∈ [0.0, 1.0], zone/direction consistency in exclusive groups)
• Graph-based validation: Detects circular dependencies in linked bid collections
• Property-based testing: Uses hypothesis for robust validation coverage

Test Coverage

• 54 new tests in tests/test_bids.py
• 96% coverage of bids.py module (exceeds 80% target)
• 97% overall project coverage
• All tests pass: make test ✅
• Type checking passes: mypy ✅
• Linting passes: ruff ✅

Documentation

• Updated README.md with comprehensive bid construction examples
• Added workflow documentation to CLAUDE.md
• Google-style docstrings on all public API functions

Test Plan

• All existing tests pass
• New bid tests pass (unit, validation, property-based)
• Type checking with mypy passes
• Linting with ruff passes
• Code coverage ≥80% (achieved 96%)
• README examples are accurate and runnable
• Manual verification of bid creation in Python REPL

🤖 Generated with Claude Code