feat: Update examples to use modern API

Refactored all applicable examples to use the latest dictionary-style component access for `TradingSuite` (e.g., `suite["MNQ"].data` instead of `suite.data`).

This change brings the examples in line with the current multi-instrument API, ensuring they serve as accurate and up-to-date guides for users.

Key changes include:
- Replaced deprecated direct property access for `data`, `orders`, `positions`, `risk_manager`, and `orderbook` with the recommended instrument-based context access.
- Updated method calls to reflect the latest asynchronous and dictionary-based API, such as for statistics and real-time data handling.
- Corrected the use of instrument properties like `instrument_info` and `symbol`.
- Removed redundant `suite.connect()` calls, as `TradingSuite.create()` now handles connections automatically.
- Modernized the code by using enhanced model properties like `.direction` and `.side_str` for cleaner logic.

Author: TexasCoding

.secrets.baseline

@@ -203,7 +203,7 @@
         "filename": "examples/17_join_orders.py",
         "hashed_secret": "11fa7c37d697f30e6aee828b4426a10f83ab2380",
         "is_verified": false,
-        "line_number": 245
+        "line_number": 247
       }
     ],
     "examples/README.md": [
@@ -325,5 +325,5 @@
       }
     ]
   },
-  "generated_at": "2025-08-31T01:30:08Z"
+  "generated_at": "2025-08-31T14:45:33Z"
 }

examples/00_trading_suite_demo.py

@@ -32,7 +32,9 @@ async def main():
 
     # Everything is connected and ready!
     print(f"Connected: {suite.is_connected}")
-    print(f"Instrument: {suite.symbol}")  # Use symbol property instead of instrument
+    if suite.instrument is None:
+        raise Exception("Instrument is None")
+    print(f"Instrument: {suite.instrument.symbolId}")  # Access instrument info
 
     # Access components - new multi-instrument way (recommended)
     print("\n=== Component Access (Recommended) ===")
@@ -64,7 +66,7 @@ async def main():
     )
 
     print(f"Connected: {suite2.is_connected}")
-    print(f"Has orderbook: {suite2.orderbook is not None}")
+    print(f"Has orderbook: {suite2['MGC'].orderbook is not None}")
 
     # Use as context manager for automatic cleanup
     print("\n\n=== Using as context manager ===")

examples/02_order_management.py

@@ -186,7 +186,7 @@ async def main() -> bool:
 
         # TradingSuite v3 includes order manager with real-time tracking
         print("\n🏗️ Using TradingSuite order manager...")
-        order_manager = suite.orders
+        order_manager = suite["MNQ"].orders
         print("✅ Order manager ready with real-time tracking")
 
         # Track orders placed in this demo for cleanup
@@ -437,7 +437,7 @@ async def main() -> bool:
                         print("📋 No orders filled yet")
 
                     # Check current positions (to detect fills that weren't caught)
-                    current_positions = await suite.client.search_open_positions()
+                    current_positions = await suite["MNQ"].positions.get_all_positions()
                     if current_positions:
                         print(f"📊 Open positions: {len(current_positions)}")
                         for pos in current_positions:
@@ -477,7 +477,7 @@ async def main() -> bool:
             print("📊 ORDER STATISTICS")
             print("=" * 50)
 
-            stats = order_manager.get_order_statistics()
+            stats = await order_manager.get_order_statistics_async()
             print("Order Manager Statistics:")
             print(f"   Orders Placed: {stats.get('orders_placed', 0)}")
             print(f"   Orders Cancelled: {stats.get('orders_cancelled', 0)}")
@@ -517,7 +517,7 @@ async def main() -> bool:
                             print(f"⚠️  Error cancelling order #{order.id}: {e}")
 
                 # Check for positions and close them
-                positions = await suite.client.search_open_positions()
+                positions = await suite["MNQ"].positions.get_all_positions()
                 print(f"Found {len(positions)} open positions")
 
                 closed_count = 0

examples/03_position_management.py

@@ -40,7 +40,7 @@ async def get_current_market_price(
     """Get current market price with async fallback for closed markets."""
     # Try to get real-time price first if available
     try:
-        current_price = await suite.data.get_current_price()
+        current_price = await suite[symbol].data.get_current_price()
         if current_price:
             return float(current_price)
     except Exception as e:
@@ -103,10 +103,10 @@ async def display_positions(
         if suite:
             try:
                 # Get current market price
-                current_price = await suite.data.get_current_price()
-                if current_price and suite.instrument:
+                current_price = await suite[position.symbol].data.get_current_price()
+                if current_price and suite[position.symbol].instrument_info:
                     # Use the instrument already loaded in suite
-                    instrument_info = suite.instrument
+                    instrument_info = suite[position.symbol].instrument_info
                     point_value = instrument_info.tickValue / instrument_info.tickSize
 
                     # Calculate P&L using position manager's method
@@ -138,20 +138,32 @@ async def display_risk_metrics(position_manager: "PositionManager") -> None:
             if hasattr(position_manager, "get_risk_metrics"):
                 risk_check = await position_manager.get_risk_metrics()
                 # Check if we're within daily loss limits and position limits
-                within_daily_loss = risk_check["daily_loss"] <= risk_check["daily_loss_limit"]
-                within_position_limit = risk_check["position_count"] <= risk_check["position_limit"]
-                within_risk_limits = risk_check["current_risk"] <= risk_check["max_risk"]
+                within_daily_loss = (
+                    risk_check["daily_loss"] <= risk_check["daily_loss_limit"]
+                )
+                within_position_limit = (
+                    risk_check["position_count"] <= risk_check["position_limit"]
+                )
+                within_risk_limits = (
+                    risk_check["current_risk"] <= risk_check["max_risk"]
+                )
 
                 if within_daily_loss and within_position_limit and within_risk_limits:
                     print("✅ All positions within risk limits")
                 else:
                     violations = []
                     if not within_daily_loss:
-                        violations.append(f"Daily loss: ${risk_check['daily_loss']:.2f} / ${risk_check['daily_loss_limit']:.2f}")
+                        violations.append(
+                            f"Daily loss: ${risk_check['daily_loss']:.2f} / ${risk_check['daily_loss_limit']:.2f}"
+                        )
                     if not within_position_limit:
-                        violations.append(f"Position count: {risk_check['position_count']} / {risk_check['position_limit']}")
+                        violations.append(
+                            f"Position count: {risk_check['position_count']} / {risk_check['position_limit']}"
+                        )
                     if not within_risk_limits:
-                        violations.append(f"Current risk: ${risk_check['current_risk']:.2f} / ${risk_check['max_risk']:.2f}")
+                        violations.append(
+                            f"Current risk: ${risk_check['current_risk']:.2f} / ${risk_check['max_risk']:.2f}"
+                        )
                     if violations:
                         print(f"⚠️  Risk limit violations: {', '.join(violations)}")
                     else:
@@ -162,14 +174,12 @@ async def display_risk_metrics(position_manager: "PositionManager") -> None:
             if hasattr(position_manager, "get_risk_metrics"):
                 risk_summary = await position_manager.get_risk_metrics()
                 print("\nRisk Summary:")
+                print(f"  Current Risk: ${risk_summary.get('current_risk', 0):,.2f}")
+                print(f"  Max Risk Allowed: ${risk_summary.get('max_risk', 0):,.2f}")
                 print(
-                    f"  Current Risk: ${risk_summary.get('current_risk', 0):,.2f}"
-                )
-                print(
-                    f"  Max Risk Allowed: ${risk_summary.get('max_risk', 0):,.2f}"
+                    f"  Max Drawdown: {risk_summary.get('max_drawdown', 0) * 100:.1f}%"
                 )
-                print(f"  Max Drawdown: {risk_summary.get('max_drawdown', 0)*100:.1f}%")
-                print(f"  Win Rate: {risk_summary.get('win_rate', 0)*100:.1f}%")
+                print(f"  Win Rate: {risk_summary.get('win_rate', 0) * 100:.1f}%")
                 print(f"  Profit Factor: {risk_summary.get('profit_factor', 0):.2f}")
             else:
                 print("Risk summary not available")
@@ -210,10 +220,10 @@ async def monitor_positions(
                     try:
                         # Try to calculate real P&L with current prices
                         if suite and positions:
-                            current_price = await suite.data.get_current_price()
-                            if current_price and suite.instrument:
+                            current_price = await suite["MNQ"].data.get_current_price()
+                            if current_price and suite["MNQ"].instrument_info:
                                 # Use the instrument already loaded in suite
-                                instrument_info = suite.instrument
+                                instrument_info = suite["MNQ"].instrument_info
                                 point_value = (
                                     instrument_info.tickValue / instrument_info.tickSize
                                 )
@@ -282,11 +292,11 @@ async def main() -> bool:
 
         # Check for existing positions
         print("\n📊 Checking existing positions...")
-        existing_positions = await suite.positions.get_all_positions()
+        existing_positions = await suite["MNQ"].positions.get_all_positions()
 
         if existing_positions:
             print(f"Found {len(existing_positions)} existing positions")
-            await display_positions(suite.positions, suite)
+            await display_positions(suite["MNQ"].positions, suite)
         else:
             print("No existing positions found")
 
@@ -312,15 +322,17 @@ async def main() -> bool:
                     try:
                         response = await loop.run_in_executor(
                             None,
-                            lambda: input("\n   Place test order? (y/N): ").strip().lower(),
+                            lambda: input("\n   Place test order? (y/N): ")
+                            .strip()
+                            .lower(),
                         )
                     except (KeyboardInterrupt, asyncio.CancelledError):
                         print("\n\n⚠️  Script interrupted by user")
                         return False
 
                     if response == "y":
                         print("\n   Placing market order...")
-                        order_response = await suite.orders.place_market_order(
+                        order_response = await suite["MNQ"].orders.place_market_order(
                             contract_id=contract_id,
                             side=0,
                             size=1,  # Buy
@@ -334,9 +346,9 @@ async def main() -> bool:
                             await asyncio.sleep(3)
 
                             # Refresh positions
-                            existing_positions = (
-                                await suite.positions.get_all_positions()
-                            )
+                            existing_positions = await suite[
+                                "MNQ"
+                            ].positions.get_all_positions()
                             if existing_positions:
                                 print("   ✅ Position created!")
                         else:
@@ -345,23 +357,23 @@ async def main() -> bool:
                     print("\n   ⚠️  Skipping test order")
 
         # Display comprehensive position information
-        if await suite.positions.get_all_positions():
+        if await suite["MNQ"].positions.get_all_positions():
             print("\n" + "=" * 80)
             print("📈 POSITION MANAGEMENT DEMONSTRATION")
             print("=" * 80)
 
             # 1. Display current positions
-            await display_positions(suite.positions, suite)
+            await display_positions(suite["MNQ"].positions, suite)
 
             # 2. Show risk metrics
-            await display_risk_metrics(suite.positions)
+            await display_risk_metrics(suite["MNQ"].positions)
 
             # 3. Portfolio statistics
             print("\n📊 Portfolio Statistics:")
             print("-" * 80)
             try:
-                if hasattr(suite.positions, "get_portfolio_pnl"):
-                    stats = await suite.positions.get_portfolio_pnl()
+                if hasattr(suite["MNQ"].positions, "get_portfolio_pnl"):
+                    stats = await suite["MNQ"].positions.get_portfolio_pnl()
                     print(f"  Total Trades: {stats.get('total_trades', 0)}")
                     print(f"  Winning Trades: {stats.get('winning_trades', 0)}")
                     print(f"  Average Win: ${stats.get('average_win', 0):,.2f}")
@@ -377,8 +389,8 @@ async def main() -> bool:
             print("\n📈 Performance Analytics:")
             print("-" * 80)
             try:
-                if hasattr(suite.positions, "get_portfolio_pnl"):
-                    analytics = await suite.positions.get_portfolio_pnl()
+                if hasattr(suite["MNQ"].positions, "get_portfolio_pnl"):
+                    analytics = await suite["MNQ"].positions.get_portfolio_pnl()
                     print(f"  Total P&L: ${analytics.get('total_pnl', 0):,.2f}")
                     print(f"  Max Drawdown: ${analytics.get('max_drawdown', 0):,.2f}")
                     print(
@@ -398,10 +410,10 @@ async def main() -> bool:
             print("=" * 80)
 
             # Monitor for 30 seconds
-            await monitor_positions(suite.positions, suite, duration=30)
+            await monitor_positions(suite["MNQ"].positions, suite, duration=30)
 
             # 6. Offer to close positions
-            if await suite.positions.get_all_positions():
+            if await suite["MNQ"].positions.get_all_positions():
                 print("\n" + "=" * 80)
                 print("🔧 POSITION MANAGEMENT")
                 print("=" * 80)
@@ -413,19 +425,21 @@ async def main() -> bool:
                     try:
                         response = await loop.run_in_executor(
                             None,
-                            lambda: input("\nClose all positions? (y/N): ").strip().lower(),
+                            lambda: input("\nClose all positions? (y/N): ")
+                            .strip()
+                            .lower(),
                         )
                     except (KeyboardInterrupt, asyncio.CancelledError):
                         print("\n\n⚠️  Script interrupted by user")
                         return False
 
                     if response == "y":
                         print("\n🔄 Closing all positions...")
-                        positions = await suite.positions.get_all_positions()
+                        positions = await suite["MNQ"].positions.get_all_positions()
 
                         for position in positions:
                             try:
-                                result = await suite.orders.close_position(
+                                result = await suite["MNQ"].orders.close_position(
                                     position.contractId, method="market"
                                 )
                                 if result and result.success:
@@ -439,7 +453,9 @@ async def main() -> bool:
 
                         # Final position check
                         await asyncio.sleep(3)
-                        final_positions = await suite.positions.get_all_positions()
+                        final_positions = await suite[
+                            "MNQ"
+                        ].positions.get_all_positions()
                         if not final_positions:
                             print("\n✅ All positions closed successfully!")
                         else:
@@ -453,8 +469,8 @@ async def main() -> bool:
         print("=" * 80)
 
         try:
-            if hasattr(suite.positions, "get_portfolio_pnl"):
-                session_summary = await suite.positions.get_portfolio_pnl()
+            if hasattr(suite["MNQ"].positions, "get_portfolio_pnl"):
+                session_summary = await suite["MNQ"].positions.get_portfolio_pnl()
                 print(f"  Session Duration: {session_summary.get('duration', 'N/A')}")
                 print(
                     f"  Positions Opened: {session_summary.get('positions_opened', 0)}"
@@ -485,7 +501,7 @@ async def main() -> bool:
         # Ask user if they want to close positions
         if suite:
             try:
-                positions = await suite.positions.get_all_positions()
+                positions = await suite["MNQ"].positions.get_all_positions()
                 if positions:
                     print(f"\n⚠️  You have {len(positions)} open position(s).")
                     print("Would you like to close them before exiting?")
@@ -511,12 +527,12 @@ async def main() -> bool:
                 # Check if we need to close positions
                 if cleanup_positions:
                     print("\n🧹 Performing cleanup...")
-                    positions = await suite.positions.get_all_positions()
+                    positions = await suite["MNQ"].positions.get_all_positions()
                     if positions:
                         print(f"  Closing {len(positions)} open position(s)...")
                         for position in positions:
                             try:
-                                result = await suite.orders.close_position(
+                                result = await suite["MNQ"].orders.close_position(
                                     position.contractId, method="market"
                                 )
                                 if result and result.success:
@@ -530,7 +546,9 @@ async def main() -> bool:
                         await asyncio.sleep(2)
 
                         # Final check
-                        final_positions = await suite.positions.get_all_positions()
+                        final_positions = await suite[
+                            "MNQ"
+                        ].positions.get_all_positions()
                         if final_positions:
                             print(f"  ⚠️  {len(final_positions)} position(s) still open")
                         else:

examples/04_realtime_data.py

@@ -242,7 +242,7 @@ async def main() -> bool:
             print(f"   Timeframes: {', '.join(timeframes)}")
 
             # Components are now accessed as attributes
-            data_manager = suite.data
+            data_manager = suite["MNQ"].data
 
             print("\n✅ All components connected and subscribed:")
             print("   - Real-time client connected")

examples/05_orderbook_analysis.py

@@ -451,7 +451,7 @@ async def main() -> bool:
             print(f"   Simulated: {account.simulated}", flush=True)
 
         # Get orderbook from suite
-        orderbook = suite.orderbook
+        orderbook = suite["MNQ"].orderbook
         if not orderbook:
             print("❌ Orderbook not available in suite", flush=True)
             await suite.disconnect()

examples/06_advanced_orderbook.py

@@ -446,14 +446,14 @@ async def main():
         print("✅ Suite initialized successfully!")
         if suite.client.account_info:
             print(f"   Account: {suite.client.account_info.name}")
-        if suite.orderbook:
-            print(f"   Tracking: {suite.orderbook.instrument}")
+        if suite["MNQ"].orderbook:
+            print(f"   Tracking: {suite["MNQ"].orderbook.instrument}")
 
         # Wait for initial data
         print("\n⏳ Collecting market data for 10 seconds...")
         await asyncio.sleep(10)
 
-        orderbook: OrderBook | None = suite.orderbook
+        orderbook: OrderBook | None = suite["MNQ"].orderbook
         if not orderbook:
             raise ValueError("Orderbook not found")
 

examples/07_technical_indicators.py

@@ -528,8 +528,8 @@ async def main() -> int | None:
         print("\n📊 Monitoring indicators in real-time...")
 
         # Check if we have data_manager
-        if hasattr(suite, "data") and suite.data:
-            await real_time_indicator_updates(suite.data, duration_seconds=30)
+        if "MNQ" in suite and suite["MNQ"].data:
+            await real_time_indicator_updates(suite["MNQ"].data, duration_seconds=30)
         else:
             print("   Real-time monitoring not available in this configuration")