salesengine 0.3.0

Universal Sales Intelligence Engine — drop in any dataset, get standardized reports

salesengine

Universal Sales Intelligence Engine — Drop in any sales dataset, answer a short questionnaire, get standardized executive-ready reports. Works across industries.

Install

pip install salesengine

For statistical tests (chi-squared, Cramér's V):

pip install salesengine[stats]

Quick Start

Two-step workflow

import salesengine as se

# Step 1: Scan your data → generates a JSON questionnaire
se.scan("sales_data.csv")

# Step 2: Fill in the JSON, then run
se.run("sales_data.csv", "sales_data_intake.json")

Command line

salesengine scan sales_data.csv
salesengine run sales_data.csv sales_data_intake.json

Use individual functions

from salesengine import clean_numeric, classify_customer_movement, weighted_average

# Clean messy financial data
df['Revenue'] = clean_numeric(df['Revenue'])  # handles $, commas, (negatives), N/A

# Analyze customer churn with 4-level classification
movement = classify_customer_movement(
    current_customers=set(df_current['ID']),
    prior_customers=set(df_prior['ID']),
)
# Returns: left_entirely, left_segment, migrated_out, new_acquisition, retained

How It Works

1. Scan → Auto-detect columns

The scanner reads your CSV/Excel and matches columns to 33 logical field names using pattern matching against 100+ common naming conventions.

2. Questionnaire → Define your business

A JSON questionnaire with 5 sections:

• Business Context — industry, units, currency
• Field Mapping — confirm auto-detected columns
• Business Rules — what is "lost customer"? what is "good lead"?
• Thresholds — numeric cutoffs for your industry
• Report Preferences — toggle analyses on/off

3. Config → Power the functions

Your answers become a ProjectConfig that maps logical names to your column names. Functions that need missing fields auto-skip.

4. Report → Formatted Excel

12+ tab workbook with executive summary, volume/revenue/margin breakdowns, customer churn, segment comparisons, and customer rankings.

Cross-Industry

Same code, different config:

Industry	"Customer"	"Volume"	"Affinity"
Food Distribution	Restaurant	Pounds	Cuisine type
SaaS	Account	MRR	Industry vertical
Healthcare	Provider	Procedures	Specialty
Retail	Store	Units sold	Department
Manufacturing	Distributor	Cases	End-use

22 Functions in 9 Categories

Category	Functions
Data Cleaning	clean_numeric, clean_currency, clean_dataframe
Statistical Analysis	cramers_v, gini_coefficient, run_statistical_summary
Weighted Aggregation	weighted_average, aggregate_to_grain
Customer & Churn	classify_customer_movement, identify_non_buyers
Index / Benchmark	calculate_price_index, classify_index, detect_index_conflicts
Confidence	score_confidence, classify_confidence_band
Banding / Tiering	assign_band, calculate_priority_score
Excel Formatting	get_excel_styles, style_header_row, auto_width, df_to_sheet
File Inspection	inspect_csv

Configuration

from salesengine import ProjectConfig, set_global_config

cfg = ProjectConfig(
    project_name="Q1 Review",
    industry="SaaS"
)
cfg.fields['customer_id'] = 'Account_ID'
cfg.fields['volume_cy'] = 'MRR_Current'
cfg.fields['segment'] = 'Plan_Tier'

# Disable functions you don't need
cfg.disabled_functions.add('calculate_price_index')

# Adjust thresholds
cfg.index_thresholds = {'extreme_high': 2.0, 'high': 1.20, 'low': 0.80}

set_global_config(cfg)

License

MIT