Metadata-Version: 2.4
Name: salesengine
Version: 0.2.1
Summary: Universal Sales Intelligence Engine — drop in any dataset, get standardized reports
Author: KTG
License: MIT
Project-URL: Homepage, https://github.com/ktg/salesengine
Project-URL: Documentation, https://github.com/ktg/salesengine#readme
Project-URL: Issues, https://github.com/ktg/salesengine/issues
Keywords: sales analytics,business intelligence,churn analysis,price index,revenue management,data cleaning,report generation,cross-industry
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: pandas>=1.3
Requires-Dist: numpy>=1.20
Requires-Dist: openpyxl>=3.0
Provides-Extra: stats
Requires-Dist: scipy>=1.7; extra == "stats"
Provides-Extra: all
Requires-Dist: scipy>=1.7; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: scipy>=1.7; extra == "dev"

# salesengine

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

## Install

```bash
pip install salesengine
```

For statistical tests (chi-squared, Cramér's V):
```bash
pip install salesengine[stats]
```

## Quick Start

### Two-step workflow

```python
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

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

### Use individual functions

```python
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

```python
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
