06 developer guide - VforVitorio/F1_Strat_Manager GitHub Wiki

Integration Guide

Relevant source files

2. Adding New Data Sources

The first step in extending the system is to add new data sources and create transformation functions to convert the data into facts that the rule engine can process.

2.1 Data Source Requirements

New data sources should provide one or more of the following types of information:

  • Telemetry data (lap times, tire age, etc.)
  • Gap information between cars
  • Degradation predictions
  • Radio communications
  • Race status information

2.2 Creating Transformation Functions

You need to create a transformation function that converts your data into fact objects. Follow this pattern:

2.3 Implementation Steps

  1. Create a new loader function for your data source
  2. Create a transformation function that converts the data into facts
  3. Add your transformation function to transform_all_facts() Example of adding a new transformation function:

Then, update the transform_all_facts() function to include your new transformation:

3. Creating Custom Fact Classes

If your data doesn't fit into existing fact classes, you'll need to create a new fact class.

4.2 Implementation Steps

  1. Create a new class that inherits from F1StrategyEngine
  2. Define rules using the @Rule decorator from Experta
  3. Implement methods that execute when rules are triggered Example of a custom rule system:

5. Integrating with the Complete Strategy Engine

After creating your custom rule system, you need to integrate it with the F1CompleteStrategyEngine.

5.1 Updating the Complete Strategy Engine

  1. Modify the class definition to include your rule system
  2. Update the record_rule_fired method to track your rule system
  3. Update the active_systems dictionary initialization

5.2 Updating Conflict Resolution

You may need to update the conflict resolution mechanism in _resolve_conflicts method if your new rules can potentially conflict with existing rules:

6. Testing Integration

Testing is crucial to ensure that your new components integrate properly with the system.

6.1 Testing Transformation Functions

Create test functions to verify that your transformation functions correctly convert data to facts:

6.2 Testing Rule Activation

Test that your rules are correctly activated when conditions are met:

6.3 Integration Testing

Finally, test that your components work within the complete system:

7. Complete Integration Flow

The following diagram provides an end-to-end view of the integration process, from loading data to generating recommendations:

8. Common Integration Issues and Solutions

Issue Possible Cause Solution
Rules not activating Missing or incorrectly formatted facts Verify fact structure with print statements, ensure all required fields are present
Type errors in facts Incorrect data types in transformation functions Add explicit type conversion in transformation functions (e.g., int(), float())
Recommendations not showing up Conflicts being resolved against your rules Check conflict resolution, adjust priorities or confidence levels
Integration exceptions Import path issues Make sure your modules are in the Python path, use absolute imports
Duplicate rules firing Multiple rule systems handling same condition Use more specific rule conditions, add mutual exclusion constraints

9. Best Practices for Integration

  1. Follow Naming Conventions: Use consistent prefixes for your rule methods (e.g., weather_* for weather rules)
  2. Document Everything: Add detailed docstrings to all new functions, methods, and classes
  3. Handle Errors Gracefully: Wrap transformation functions in try-except blocks to prevent failure cascades
  4. Test Incrementally: Test each component separately before full integration
  5. Be Mindful of Performance: Avoid expensive operations in rule conditions as they evaluate frequently
  6. Maintain Backward Compatibility: Don't modify existing fact structures, extend them instead
  7. Use Debug Flags: Add debug parameters to transformation functions for easier troubleshooting

Summary

This integration guide provides the foundation for extending the F1 Strategy Manager with new data sources, models, and rules. By following the outlined steps and patterns, you can add new capabilities while maintaining compatibility with the existing system.