Add OrderBook module for managing bid portfolios

.github/workflows/ci.yml

@@ -65,3 +65,4 @@ jobs:
         with:
           file: ./coverage.xml
           fail_ci_if_error: false
+          token: ${{ secrets.CODECOV_TOKEN }}

README.md

@@ -156,6 +156,51 @@ print(f"Must-run is indivisible: {must_run.is_indivisible}")
 print(f"Exclusive group has {options.member_count} options")
 ```
 
+### Managing portfolios with OrderBook
+
+```python
+from nexa_bidkit import (
+    create_order_book,
+    add_bid,
+    add_bids,
+    get_bids_by_zone,
+    get_bids_by_status,
+    count_bids,
+    total_volume_by_zone,
+    update_all_statuses,
+    orders_to_dataframe,
+    BidStatus,
+)
+
+# Create an order book
+book = create_order_book()
+
+# Add individual bids
+book = add_bid(book, must_run)
+book = add_bid(book, peak_bid)
+
+# Add multiple bids at once
+book = add_bids(book, [ramp_up, options])
+
+# Query bids
+no1_bids = get_bids_by_zone(book, BiddingZone.NO1)
+draft_bids = get_bids_by_status(book, BidStatus.DRAFT)
+
+# Aggregate statistics
+bid_counts = count_bids(book)
+volumes = total_volume_by_zone(book)
+
+print(f"Total bids: {sum(bid_counts.values())}")
+print(f"NO1 volume: {volumes[BiddingZone.NO1]} MW")
+
+# Update statuses (e.g., after validation)
+book = update_all_statuses(book, BidStatus.VALIDATED)
+
+# Export to pandas for analysis
+df = orders_to_dataframe(book)
+print(df[["bid_id", "bid_type", "bidding_zone", "status"]])
+```
+
 ## Core Concepts
 
 ### Market Time Units (MTU)

src/nexa_bidkit/__init__.py

@@ -27,9 +27,29 @@
     linear_curve,
     merge_curves,
     scale_curve,
-    to_dataframe,
     validate_dataframe_schema,
 )
+from nexa_bidkit.curves import to_dataframe as curves_to_dataframe
+from nexa_bidkit.orders import (
+    OrderBook,
+    add_bid,
+    add_bids,
+    count_bids,
+    create_order_book,
+    filter_bids,
+    get_bid_by_id,
+    get_bids_by_direction,
+    get_bids_by_status,
+    get_bids_by_type,
+    get_bids_by_zone,
+    get_bids_in_period,
+    get_order_book_summary,
+    remove_bid,
+    total_volume_by_zone,
+    update_all_statuses,
+    update_bid_status,
+)
+from nexa_bidkit.orders import to_dataframe as orders_to_dataframe
 from nexa_bidkit.types import (
     BiddingZone,
     BidStatus,
@@ -60,6 +80,25 @@
     "exclusive_group",
     "with_status",
     "validate_bid_collection",
+    # OrderBook models and functions
+    "OrderBook",
+    "create_order_book",
+    "add_bid",
+    "add_bids",
+    "remove_bid",
+    "filter_bids",
+    "get_bid_by_id",
+    "get_bids_by_zone",
+    "get_bids_by_direction",
+    "get_bids_by_status",
+    "get_bids_by_type",
+    "get_bids_in_period",
+    "count_bids",
+    "total_volume_by_zone",
+    "get_order_book_summary",
+    "update_bid_status",
+    "update_all_statuses",
+    "orders_to_dataframe",
     # Curve construction and manipulation
     "aggregate_by_price",
     "clip_curve",
@@ -73,7 +112,7 @@
     "linear_curve",
     "merge_curves",
     "scale_curve",
-    "to_dataframe",
+    "curves_to_dataframe",
     "validate_dataframe_schema",
     # Types
     "BiddingZone",