¶ (c) Technocore - All Rights Reserved.
NOTICE: All information contained herein is, and remains
the property of TechnoCore.
The intellectual and technical concepts contained
herein are proprietary to TechnoCore and dissemination of this information or reproduction of this material
is strictly forbidden unless prior written permission is obtained
from TechnoCore.
¶ ObjServiceDecisionSwitch
The ObjServiceDecisionSwitch is a service class responsible for managing and executing decision tree logic. It allows for the creation, evaluation, validation, and visualization of complex decision-making processes based on contextual data.
The service can read decision tree structures from a database, compute outcomes based on input context, validate results against expected outcomes, and generate comprehensive reports. It supports both single-tree operations and batch processing of multiple decision trees.
¶ Key Features
- Database-driven: Decision trees and their nodes are stored in and read from database tables (
def_decision_tree,def_decision_treenodes). - Contextual Evaluation: Computes outcomes by evaluating a series of rules against a provided data context.
- Validation & Testing: Compare actual outcomes against expected outcomes with comprehensive reporting.
- Performance Metrics: Track simulation performance with throughput and timing analysis.
- Batch Operations: Process multiple decision trees in a single run with aggregated results.
- Visualizations: Generate Mermaid flowcharts and Sankey diagrams of decision tree logic.
- PMML Support: Import/export decision trees using industry-standard PMML format.
- Data Quality: Validate input data completeness and consistency.
¶ Command-Line Interface (CLI)
The service uses typer to provide a comprehensive set of CLI commands for interaction.
¶ Core Simulation Commands
¶ sim <decision_name>
Runs a simulation for a given decision tree. This command processes a dataset against the tree logic and stores the results with validation.
python factory.service/package.core/ObjServiceDecisionSwitch.py sim hc_collections_abovetheline
Options:
--workers N: Number of parallel workers (default: 4)
What it does:
- Loads decision tree from database
- Reads input data from configured DataTable
- Evaluates each record through decision tree logic
- Stores results in
bloom_sim_{decision_name}table - If Expected_Outcome exists, calculates Verification (Y/N)
¶ run-decision <decision_name>
Alternative command name for running simulations (alias for sim).
python factory.service/package.core/ObjServiceDecisionSwitch.py run-decision hc_collections_abovetheline
¶ Validation & Reporting Commands
¶ validation-report <decision_name>
Generate comprehensive validation report comparing expected vs actual outcomes.
# Basic text report
python factory.service/package.core/ObjServiceDecisionSwitch.py validation-report hc_collections_abovetheline
# Show detailed failures
python factory.service/package.core/ObjServiceDecisionSwitch.py validation-report hc_collections_abovetheline --show-failures
# Export to JSON
python factory.service/package.core/ObjServiceDecisionSwitch.py validation-report hc_collections_abovetheline --output-format json
# Export to CSV
python factory.service/package.core/ObjServiceDecisionSwitch.py validation-report hc_collections_abovetheline --output-format csv > report.csv
Options:
--output-format [text|json|csv]: Output format (default: text)--show-failures: Include detailed failure records--limit N: Maximum failures to show (default: 20)
Output includes:
- Total records processed
- Pass/fail counts and percentages
- Breakdown by expected outcome
- Individual failure records (optional)
¶ performance-report <decision_name>
Generate performance metrics for simulation runs.
# Show stats from existing simulation
python factory.service/package.core/ObjServiceDecisionSwitch.py performance-report hc_collections_abovetheline
# Run new simulation with timing
python factory.service/package.core/ObjServiceDecisionSwitch.py performance-report hc_collections_abovetheline --run-simulation
Options:
--run-simulation: Execute new simulation with performance tracking
Metrics shown:
- Total execution time
- Records processed per second
- Average time per record
- Tree complexity (node count)
- Statistics by simulation run (SetGuid)
¶ compare-simulations <decision_name>
Compare two simulation runs to identify differences in outcomes.
# Compare two runs
python factory.service/package.core/ObjServiceDecisionSwitch.py compare-simulations hc_collections_abovetheline \
--run1 RUN001 --run2 RUN002
# Export comparison to JSON
python factory.service/package.core/ObjServiceDecisionSwitch.py compare-simulations hc_collections_abovetheline \
--run1 RUN001 --run2 RUN002 --output-format json
# Export to CSV
python factory.service/package.core/ObjServiceDecisionSwitch.py compare-simulations hc_collections_abovetheline \
--run1 RUN001 --run2 RUN002 --output-format csv > comparison.csv
Required Options:
--run1 SETGUID: First SetGuid to compare--run2 SETGUID: Second SetGuid to compare
Optional:
--output-format [text|json|csv]: Output format (default: text)
Use cases:
- Validate decision tree changes
- Compare before/after logic updates
- Identify regression issues
- Track outcome changes over time
¶ tree-diff
Compare decision tree structures to identify structural differences.
# Compare two trees
python factory.service/package.core/ObjServiceDecisionSwitch.py tree-diff \
--tree1 hc_collections_v1 --tree2 hc_collections_v2
# Export to JSON
python factory.service/package.core/ObjServiceDecisionSwitch.py tree-diff \
--tree1 hc_collections_v1 --tree2 hc_collections_v2 --output-format json
# Export to CSV
python factory.service/package.core/ObjServiceDecisionSwitch.py tree-diff \
--tree1 hc_collections_v1 --tree2 hc_collections_v2 --output-format csv
Required Options:
--tree1 NAME: First decision tree name--tree2 NAME: Second decision tree name
Optional:
--output-format [text|json|csv]: Output format (default: text)
Output includes:
- Added nodes (new in tree2)
- Removed nodes (removed from tree1)
- Modified nodes (rules changed)
- Unchanged nodes count
- Change magnitude assessment
Example Output:
DECISION TREE STRUCTURE COMPARISON
Tree 1: hc_collections_v1 (275 nodes)
Tree 2: hc_collections_v2 (278 nodes)
SUMMARY
Added Nodes: 5
Removed Nodes: 2
Modified Nodes: 3
Unchanged Nodes: 70
ADDED NODES (5)
Node: N27 (2 rules)
• CollectionsScore < 620 → O51
• CollectionsScore >= 620 → O52
MODIFIED NODES (3)
Node: N10
Added Rules (1):
+ Dispatch Defaulter = '1' → O26
Removed Rules (1):
- Dispatch Defaulter = '0' → N11
CHANGE MAGNITUDE: 3.6% of nodes affected
Assessment: Minor changes - likely safe to deploy
Use cases:
- Track decision tree evolution over time
- Review structural changes before deployment
- Understand impact of tree modifications
- Document changes for audit trail
- Compare development vs production trees
Best practices:
- Run tree-diff before deploying tree changes
- Export to JSON for version control storage
- Review modified nodes carefully
- Use with compare-simulations to see outcome impact
¶ Data Quality & Validation Commands
¶ validate-tree <decision_name>
Validate decision tree structure and data integrity.
python factory.service/package.core/ObjServiceDecisionSwitch.py validate-tree hc_collections_abovetheline
Checks performed:
- ✓ All target nodes exist
- ✓ No unreachable nodes
- ✓ No circular references
- ✓ All condition fields exist in input table
- ✓ All decision nodes have rules
- ✓ No infinite loops
Run this before:
- Deploying new decision trees to production
- Making structural changes to trees
- Troubleshooting unexpected outcomes
¶ validate-input-data <decision_name>
Validate input data quality and completeness.
# Basic validation
python factory.service/package.core/ObjServiceDecisionSwitch.py validate-input-data hc_collections_abovetheline
# Show sample invalid records
python factory.service/package.core/ObjServiceDecisionSwitch.py validate-input-data hc_collections_abovetheline \
--show-samples --limit 20
Options:
--show-samples: Display sample invalid records--limit N: Number of samples to show (default: 10)
Checks performed:
- ✓ All required fields present in input table
- ✓ NULL value detection and counts
- ✓ Data type consistency
- ✓ Value distribution analysis
- ✓ Field cardinality
Use cases:
- Troubleshoot simulation failures
- Identify data quality issues
- Verify data completeness before simulation
- Understand input data characteristics
¶ Maintenance & Cleanup Commands
¶ cleanup-simulations <decision_name>
Clean up old simulation results.
# Delete specific run (with confirmation)
python factory.service/package.core/ObjServiceDecisionSwitch.py cleanup-simulations hc_collections_abovetheline \
--set-guid RUN001
# Delete all runs (with confirmation)
python factory.service/package.core/ObjServiceDecisionSwitch.py cleanup-simulations hc_collections_abovetheline \
--all-runs
# Skip confirmation prompt
python factory.service/package.core/ObjServiceDecisionSwitch.py cleanup-simulations hc_collections_abovetheline \
--set-guid RUN001 --confirm
Options:
--set-guid GUID: Specific SetGuid to delete--all-runs: Delete all simulation results--confirm: Skip confirmation prompt
Safety features:
- Always shows record count before deletion
- Requires explicit confirmation (unless --confirm flag)
- Cannot accidentally delete without specifying target
¶ export-validation-failures <decision_name>
Export failed validation records to CSV for detailed analysis.
# Export failures
python factory.service/package.core/ObjServiceDecisionSwitch.py export-validation-failures hc_collections_abovetheline
# Custom output file and limit
python factory.service/package.core/ObjServiceDecisionSwitch.py export-validation-failures hc_collections_abovetheline \
--output-file failures_analysis.csv --limit 500
Options:
--output-file FILE: Output CSV filename (default: validation_failures.csv)--limit N: Maximum records to export (default: 1000)
CSV columns:
- GUID
- Expected_Outcome
- Actual_Outcome
- All input fields from decision tree
Use cases:
- Detailed failure analysis in Excel/spreadsheet
- Identify patterns in failed records
- Debug specific test cases
- Share results with stakeholders
¶ Visualization Commands
¶ visualize-tree <decision_name>
Generate Mermaid flowchart diagram of decision tree structure.
# Generate diagram
python factory.service/package.core/ObjServiceDecisionSwitch.py visualize-tree hc_collections_abovetheline
# Custom output file
python factory.service/package.core/ObjServiceDecisionSwitch.py visualize-tree hc_collections_abovetheline \
--output-file my_tree.png
Options:
--output-file FILE: Output filename (default: decision_tree.png)
Output formats:
- PNG image (if Mermaid rendering available)
- .mmd text file (Mermaid code for manual rendering)
Diagram features:
- Color-coded nodes (decisions, outcomes, end)
- Edge labels showing conditions
- Hierarchical layout by rank
- Visual representation of tree logic
Use cases:
- Documentation
- Training materials
- Code reviews
- Architecture discussions
¶ diagram <decision_name>
Generates a Mermaid flowchart diagram and stores it in the database.
python factory.service/package.core/ObjServiceDecisionSwitch.py diagram hc_collections_abovetheline
¶ diagram-sankey <decision_name>
Generates a Mermaid Sankey diagram from simulation results showing data flow.
python factory.service/package.core/ObjServiceDecisionSwitch.py diagram-sankey hc_collections_abovetheline
¶ Batch Processing Commands
¶ batch-simulate
Run simulations for multiple decision trees in batch mode.
# Run all trees in package
python factory.service/package.core/ObjServiceDecisionSwitch.py batch-simulate --package HOMECHOICE
# Run specific trees
python factory.service/package.core/ObjServiceDecisionSwitch.py batch-simulate \
--package HOMECHOICE \
--decision-names "tree1,tree2,tree3"
# Adjust parallelism and output
python factory.service/package.core/ObjServiceDecisionSwitch.py batch-simulate \
--package HOMECHOICE \
--workers 8 \
--output-file batch_results.json
Options:
--package NAME: Package name (default: HOMECHOICE)--decision-names LIST: Comma-separated tree names (or all if omitted)--workers N: Number of parallel workers (default: 4)--output-file FILE: JSON output file (default: batch_results.json)
Output includes:
- Per-tree results (records, pass rate, timing)
- Aggregate statistics
- Failed trees with error messages
- Overall throughput metrics
Use cases:
- Regression testing entire package
- Performance benchmarking
- Nightly validation runs
- Release validation
¶ Testing & Development Commands
¶ selftest <decision_name>
Runs predefined test cases against the decision tree.
python factory.service/package.core/ObjServiceDecisionSwitch.py selftest TestTree
¶ test-pmml-cycle [decision_name]
Performs full PMML save/load test cycle.
python factory.service/package.core/ObjServiceDecisionSwitch.py test-pmml-cycle TestTree
¶ PMML Import/Export Commands
¶ save-pmml <decision_name> <file_path>
Export decision tree to PMML format.
python factory.service/package.core/ObjServiceDecisionSwitch.py save-pmml hc_collections_abovetheline tree.pmml
¶ load-pmml <file_path>
Import decision tree from PMML file.
python factory.service/package.core/ObjServiceDecisionSwitch.py load-pmml tree.pmml
¶ Setup Commands
¶ setup-tables
Creates necessary database tables.
python factory.service/package.core/ObjServiceDecisionSwitch.py setup-tables
¶ Workflow Guide
¶ Creating and Testing a New Decision Tree
Step 1: Validate Structure
# Check tree structure for errors
python factory.service/package.core/ObjServiceDecisionSwitch.py validate-tree my_new_tree
Step 2: Validate Input Data
# Check data quality
python factory.service/package.core/ObjServiceDecisionSwitch.py validate-input-data my_new_tree --show-samples
Step 3: Run Simulation
# Execute simulation
python factory.service/package.core/ObjServiceDecisionSwitch.py sim my_new_tree --workers 8
Step 4: Check Results
# Generate validation report
python factory.service/package.core/ObjServiceDecisionSwitch.py validation-report my_new_tree --show-failures
# Check performance
python factory.service/package.core/ObjServiceDecisionSwitch.py performance-report my_new_tree
Step 5: Visualize
# Generate diagram for documentation
python factory.service/package.core/ObjServiceDecisionSwitch.py visualize-tree my_new_tree
¶ Comparing Decision Tree Versions
When updating a decision tree:
# Run simulation with old version (save as RUN_OLD)
python factory.service/package.core/ObjServiceDecisionSwitch.py sim my_tree
# Update decision tree logic in database
# ...
# Run simulation with new version (save as RUN_NEW)
python factory.service/package.core/ObjServiceDecisionSwitch.py sim my_tree
# Compare results
python factory.service/package.core/ObjServiceDecisionSwitch.py compare-simulations my_tree \
--run1 RUN_OLD --run2 RUN_NEW --output-format json > changes.json
¶ Debugging Failed Validations
# 1. Get overview
python factory.service/package.core/ObjServiceDecisionSwitch.py validation-report my_tree
# 2. Export failures for analysis
python factory.service/package.core/ObjServiceDecisionSwitch.py export-validation-failures my_tree \
--output-file failures.csv --limit 100
# 3. Check input data quality
python factory.service/package.core/ObjServiceDecisionSwitch.py validate-input-data my_tree --show-samples
# 4. Validate tree structure
python factory.service/package.core/ObjServiceDecisionSwitch.py validate-tree my_tree
¶ Regular Maintenance
# Weekly: Clean up old test runs
python factory.service/package.core/ObjServiceDecisionSwitch.py cleanup-simulations my_tree \
--set-guid OLD_TEST_RUN --confirm
# Monthly: Full regression test
python factory.service/package.core/ObjServiceDecisionSwitch.py batch-simulate \
--package HOMECHOICE --output-file monthly_regression.json
¶ Troubleshooting Guide
¶ Problem: Simulation Fails to Start
Symptoms: Error before any records are processed
Possible causes:
- Decision tree not found in database
- Input table not configured or doesn't exist
- Missing required fields
Solution:
# Check tree exists and is valid
python factory.service/package.core/ObjServiceDecisionSwitch.py validate-tree my_tree
# Verify input data
python factory.service/package.core/ObjServiceDecisionSwitch.py validate-input-data my_tree
¶ Problem: Low Pass Rate (< 100%)
Symptoms: validation-report shows failed validations
Possible causes:
- Incorrect Expected_Outcome values in input data
- Decision tree logic doesn't match expectations
- Data quality issues (NULLs, invalid values)
Solution:
# Export failures for analysis
python factory.service/package.core/ObjServiceDecisionSwitch.py export-validation-failures my_tree
# Check specific failed records in CSV
# Trace through decision tree logic manually
# Check for data quality issues
python factory.service/package.core/ObjServiceDecisionSwitch.py validate-input-data my_tree --show-samples
¶ Problem: Slow Simulation Performance
Symptoms: Simulation takes longer than expected
Possible causes:
- Large dataset
- Complex decision tree (many nodes)
- Insufficient parallelism
- Database performance issues
Solution:
# Run with more workers
python factory.service/package.core/ObjServiceDecisionSwitch.py sim my_tree --workers 16
# Check performance metrics
python factory.service/package.core/ObjServiceDecisionSwitch.py performance-report my_tree --run-simulation
# Expected: 100-1000 records/second depending on complexity
¶ Problem: Unexpected Outcome Changes
Symptoms: Outcomes changed after tree update
Possible causes:
- Intentional logic changes
- Unintended side effects
- Data changes
Solution:
# Compare before/after runs
python factory.service/package.core/ObjServiceDecisionSwitch.py compare-simulations my_tree \
--run1 BEFORE --run2 AFTER --show-differences
# Analyze which records changed and why
# Review decision tree changes
# Validate tree structure
python factory.service/package.core/ObjServiceDecisionSwitch.py validate-tree my_tree
¶ Problem: Memory Issues with Large Datasets
Symptoms: Process runs out of memory
Possible causes:
- Dataset too large for available RAM
- Too many parallel workers
Solution:
# Reduce worker count
python factory.service/package.core/ObjServiceDecisionSwitch.py sim my_tree --workers 2
# Process in batches (modify input query to use LIMIT/OFFSET)
# Monitor memory usage during simulation
¶ Best Practices
¶ Development
-
Always validate before deploying
- Run
validate-treeto check structure - Run
validate-input-datato verify data quality - Review validation reports before production
- Run
-
Use version control for decision trees
- Export to PMML for version tracking
- Tag simulation runs with meaningful SetGuid values
- Keep comparison reports for major changes
-
Document expected outcomes
- Always include Expected_Outcome in test data
- Document the logic behind each outcome
- Maintain test cases that cover all paths
-
Test incrementally
- Test individual nodes before full tree
- Use small datasets for initial testing
- Scale up after validation passes
¶ Testing
-
Achieve 100% pass rate before production
- All test cases should pass
- Investigate every failure
- Don't assume failures are "close enough"
-
Maintain comprehensive test coverage
- Test all outcome paths
- Include edge cases (NULLs, boundary values)
- Test with realistic data distributions
-
Use batch-simulate for regression testing
- Run full package validation regularly
- Compare results to baseline
- Automate in CI/CD pipeline
¶ Performance
-
Optimize for your workload
- Adjust worker count based on CPU cores
- Monitor memory usage with large datasets
- Consider batching for very large inputs
-
Track performance metrics
- Baseline performance for each tree
- Monitor degradation over time
- Profile complex trees for bottlenecks
¶ Data Quality
-
Validate input data regularly
- Check for NULLs in required fields
- Verify data type consistency
- Monitor value distributions
-
Clean data before simulation
- Handle missing values appropriately
- Standardize categorical values
- Document data assumptions
¶ Maintenance
-
Clean up old simulation results
- Remove test runs after validation
- Archive important historical runs
- Monitor database growth
-
Keep documentation current
- Update diagrams after logic changes
- Document business rules
- Maintain troubleshooting notes
¶ Configuration
Decision trees are configured in the database:
Tables:
def_decision_tree: Tree metadata (name, package, version)def_decision_treenodes: Tree nodes (conditions, outcomes)
Required attributes per ObjServiceDecisionSwitch instance:
_Datatable: Input data table name_Simdatatable: Simulation data table name (optional)_Simoutputtable: Output table name (auto-generated if not set)
SQL Queries:
All SQL queries are stored in ObjServiceDecisionSwitch.yaml under the queries section.
¶ Python API
from ObjServiceDecisionSwitch import ObjServiceApi
# Load decision tree
service = ObjServiceApi()
service.read('hc_collections_abovetheline')
# Run simulation
service.simulate('hc_collections_abovetheline', workers=4)
# Evaluate single record
context = {
'Bureau Status': '',
'Payment': '0',
'Now Due': 100,
# ... other fields
}
result = service.process(context)
print(result) # Returns dict with calculated outcomes
¶ See Also
- ObjData.md: Base class documentation
- ObjWorkflow.md: Workflow integration
- CLAUDE.md: Project coding standards
- resource.notes/howto/decision_trees.md: Decision tree design guide (if exists)