Usage Guide

This guide covers both execution modes: the non-interactive CLI and the interactive menu.

For the full CLI flag reference, see cli.md.

CLI Mode

The CLI is the preferred mode for repeatable runs and automation. All commands are invoked through:

python -m bc_dev_tools <command> [options]

Full pipeline

Runs the complete workflow: import BC fault codes from Excel, import FAQ issue types from the API, normalize both datasets, fuzzy-match them, and export results.

python -m bc_dev_tools pipeline
python -m bc_dev_tools pipeline --threshold 0.90

Import data

Import data sources individually when you need to update one side without rerunning the full pipeline.

# Import FAQ issue types and normalize
python -m bc_dev_tools import faq

# Import BC fault codes from Excel (default file) and normalize
python -m bc_dev_tools import bc

# Import BC fault codes from a custom file
python -m bc_dev_tools import bc --file "updated_fault_codes.xlsx"

# Import all configured Excel files into SQLite
python -m bc_dev_tools import excel

# Import a specific Excel file with a custom table name
python -m bc_dev_tools import excel --file "ServiceItems.xlsx" --table-name service_items

# Import the manual compilation report
python -m bc_dev_tools import manual-report

Compare and export

Compare requires that both BC and FAQ data have been imported into the database.

# Run fuzzy matching with a custom threshold
python -m bc_dev_tools compare --threshold 0.80

# Export comparison results to the default file
python -m bc_dev_tools export

# Export to a specific file
python -m bc_dev_tools export --output results_march.xlsx

Submit quality reports

Reads an Excel spreadsheet and submits each row to the CSM 1.0 API. Produces api_logs_<timestamp>.txt (request/response details) and submission_results.xlsx (row-by-row summary).

python -m bc_dev_tools submit --file "Failed_PSI.xlsx"

Failed CSM Submissions Resolver

The resolver fetches failed service orders from BC via OData, matches each one against the FAQ issue type hierarchy, and writes results to a spreadsheet. It can optionally submit matched rows to the CSM 1.0 API and mark them as sent in BC.

# Standard run (incremental, from last-run date)
python -m bc_dev_tools resolve run

# Preview without writing to the spreadsheet
python -m bc_dev_tools resolve run --dry-run --verbose

# Fetch the full backlog, submit to CSM, and update BC
python -m bc_dev_tools resolve run --full --submit --mark-sent

# Run from a specific date with a lower threshold
python -m bc_dev_tools resolve run --since 2026-01-01 --threshold 0.75

# Write to a custom output file and tab
python -m bc_dev_tools resolve run --output ~/Desktop/resolver.xlsx --tab-name "March 2026"

# Backfill sent timestamps (skips the normal pipeline)
python -m bc_dev_tools resolve run --backfill-sent "2026-03-15 14:30"

Resolver analytics

# Analyze resolver output patterns
python -m bc_dev_tools resolve analyze

# Analyze human correction patterns
python -m bc_dev_tools resolve corrections

Both commands read from the FAILED_CSM_SPREADSHEET path and print analysis to stdout.

Interactive Mode

Launch the interactive menu:

python -m bc_dev_tools interactive

The menu presents eight numbered options. Each prompts for any required input (file paths, thresholds, etc.) at runtime.

Option 1: Complete Import and Comparison (Full Pipeline)

Runs the end-to-end workflow:

1. Import BC fault codes from Excel into SQLite
2. Import FAQ issue types from the API into SQLite
3. Normalize both datasets (if enabled in config.py)
4. Fuzzy-match BC rows against FAQ rows
5. Export results to Excel

Use this when you want a fresh, complete run.

Option 2: Import from FAQ API and Normalize Data

Imports FAQ issue types and normalizes them into dimension tables:

• Main categories
• Sub categories
• Issue types
• Item parts
• A normalized fact table
• SQL views for easy querying

Use this when FAQ data changed but BC data did not.

Option 3: Import BC Fault Codes from Excel and Normalize

Imports BC fault code relationships from Excel and runs BC normalization. Prompts for either the default file or a custom path.

Use this when you have received an updated BC relationship spreadsheet.

Option 4: Import Other Excel Files

Imports additional Excel files into SQLite for offline analysis. Prompts to choose between:

• Import all configured files (from OTHER_EXCEL_FILES in config.py)
• Import a specific configured file
• Import a custom file with an optional table name

Option 5: Compare Data (Match BC codes with FAQ)

Prompts for a similarity threshold (or uses the default of 0.85) and runs the fuzzy matching algorithm. Compares using the column mapping configured in config.py:

BC Column	FAQ Column
Fault Area Description	csMainCategoryName
Symptom Code Description	csSubCategoryName
Fault Code Description	itemPartName
Description	issueTypeName

Results are written back to the BC table as match columns. Run Option 6 afterward to export.

Option 6: Export Results to Excel

Exports comparison results to a multi-sheet Excel workbook:

• All Results — every BC row with match data, sorted
• Matched — only rows where a match was found
• Unmatched — only rows with no match

Prompts for an output filename (default: comparison_results.xlsx).

Option 7: Submit Failed Quality Reports

Reads an Excel file and submits each row to the CSM 1.0 API. Prompts for the file path at runtime.

Outputs:

• api_logs_<timestamp>.txt — full request/response details for each row
• submission_results.xlsx — row-by-row outcome summary

Option 8: Run Manual Compilation Report Compilation

Imports the hardcoded Manual CSM Quality Report Compilation - 2024.xlsx file into the manual_csm_reports_2024 SQLite table with typed columns (dates parsed, strings preserved).

Option 99: Exit

Exits the application.

Verbose HTTP Logging

To enable detailed HTTP request/response logging (useful for debugging API connectivity):

HTTP_DEBUG=1 python -m bc_dev_tools pipeline

This sets http.client.HTTPConnection.debuglevel = 1 and configures urllib3 logging at DEBUG level. Leave it off for normal usage.