⚡ BizPack

 ____  _     ____             _    
| __ )(_)___|  _ \ __ _  ___| | __
|  _ \| |_  /| |_) / _` |/ __| |/ /
| |_) | |/ / |  __/ (_| | (__|   < 
|____/|_/___||_|   \__,_|\___|_|\_\

🎯 Overview: What BizPack Does vs. What It Doesn't Do

To build trustworthy data infrastructure, developers and business analysts need to know exactly what a library handles—and what boundaries it respects.

✅ What BizPack Does

• Automated Ingestion Hygiene: Converts messy, human-formatted spreadsheet exports (CSV, TSV, Excel) into standardized, type-safe pandas.DataFrame objects in a single line.
• Contextual Two-Tier Date Resolution: Deduces DD/MM/YYYY vs MM/DD/YYYY by combining column frequency heuristics with row-level partner signals (currency symbols, country/region names), achieving 0 dropped NaT rows.
• Intelligent Multi-Currency Normalization: Detects mixed international currencies (₹, $, €, £, Rs.), accounting negatives ($1,200), and European decimal notations (41.392,35), prompting interactively or applying configurable FX matrices.
• Full Audit Trail Transparency: Preserves conversion history, applied exchange rates, and discarded footer rows in non-destructive DataFrame metadata (df.attrs).
• Leading Zero & ID Protection: Protects critical identifiers (ZIP codes, account numbers, SKUs like 00124 or 07001) from being mangled into truncated integers.
• Pythonic Excel Business Math: Vectorized, intuitive implementations of standard analyst routines: bp.xlookup(), bp.pareto() (80/20 distribution with auto-narrative), bp.growth() (MoM/YoY), and bp.run_rate() (quota pacing).
• Boardroom Display Formatter: Instantly converts calculation-ready floats back into executive presentation strings ($ 1,250.00, (9.8%), 33.3%).

❌ What BizPack Does NOT Do

• Does NOT Impute or Hallucinate Missing Data: BizPack never invents numbers or fills empty cells with arbitrary guesses. Blanks and spreadsheet error strings (#REF!, #N/A, -) become true np.nan.
• Does NOT Lock You Into a Proprietary Data Structure: BizPack does not create a wrapper object. It accepts standard pandas.DataFrame and returns standard pandas.DataFrame.
• Does NOT Overwrite Source Files: clean_file() never overwrites your original input CSV in-place; all writes go to a designated output destination.
• Does NOT Require Heavy Compilers or Cloud Runtimes: No JVM, Spark, Docker, C++ toolchains, or mandatory network calls. Runs 100% locally with pure pandas and numpy.
• Does NOT Try to Be an Orchestrator: BizPack is not Airflow, dbt, or Spark. It is a focused data preparation and business analysis engine.

🏆 Benefits of Using BizPack

💼 What You Can Do With BizPack

BizPack is purpose-built for analytics engineers, financial analysts, operations leaders, and Python developers:

┌────────────────────────────────────────────────────────────────────────────────┐
│                           REAL-WORLD APPLICATIONS                              │
├────────────────────────────────────────────────────────────────────────────────┤
│ 1. Multinational Revenue Consolidation                                         │
│    Unify regional sales extracts (APAC ₹, EMEA €, US $) into 1 corporate base   │
│    currency with real FX rates in seconds.                                     │
│                                                                                │
│ 2. Bulletproof Ingestion for Dashboards (Streamlit, Dash, PowerBI)             │
│    Prevent downstream crashes caused by string numbers, accounting brackets,   │
│    or mixed date formats before data reaches visualizations.                   │
│                                                                                │
│ 3. Automated Executive Pareto (80/20) Concentration Audits                    │
│    Instantly identify the top 20% of customer accounts driving 80% of quarterly│
│    revenue with auto-generated executive commentary.                          │
│                                                                                │
│ 4. Cross-System ERP & CRM Reconciliation                                       │
│    Join disparate tables via clean `bp.xlookup()` without messy multi-line     │
│    `df.merge()` key management and suffix collisions.                          │
│                                                                                │
│ 5. Sales Pacing & Run-Rate Projections                                         │
│    Track month-to-date and quarter-to-date performance against sales quotas,    │
│    projecting month-end finish with zero manual date math.                     │
└────────────────────────────────────────────────────────────────────────────────┘

🚨 Why BizPack? The 5 Silent Disasters of Raw Pandas

Pandas was engineered for general data science and statistical computing. When applied to real-world corporate spreadsheets (exported from SAP, Salesforce, Oracle, or Excel), raw Pandas triggers silent financial inaccuracies:

⚡ Quickstart in 4 Lines

Clean dirty spreadsheet exports into analysis-ready dataframes with zero configuration:

import bizpack as bp

# 1. Inspect the raw export
print("Before cleaning:\n", bp.read_csv("dirty_data.csv", clean=False).head(5))

# 2. Clean and save in a single call
clean_df = bp.clean_file("dirty_data.csv", "clean_data.csv")

# 3. View the pristine output
print("\nAfter cleaning:\n", clean_df.head(5))

🖥️ Interactive Terminal Experience

When bizpack encounters mixed currencies in an interactive session, it pauses and prompts the analyst directly:

[BizPack Alert] 🌍 Multiple currencies detected in column 'gross_revenue': [EUR, GBP, INR, USD]
Which currency would you like to standardize to? (default: USD): USD
[BizPack Success] ✔ Standardized 100 rows to USD (rates: EUR=1.087, GBP=1.282, INR=0.0119)

📊 Before vs. After Showcase

Input: Raw Corporate Spreadsheet (dirty_data.csv)

 Customer Name / Client , Account # , Order Date (UTC) , Region / Territory , Gross Revenue , Unit Cost , Profit Margin % , Active Subscription? , Blank Column 
Acme Corp,00124,25/03/2024,APAC,"₹ 1,49,670.67","₹ 84,078.93",33.3%,false,,
Wayne Enterprises,00235,03/25/2024,USA,"($ 12,865.27)","$ 8,045.42",(9.8%),true,,
Massive Dynamic,00280,14.12.2024,Europe,"£ 5,306.25","£ 3,494.04",22.0%,Y,,
Soylent Corp,00945,05/09/2024,India,"₹ 1,17,418.70","₹ 76,087.98",17.3%,No,,
Hooli Inc,00234,05/09/2024,North America,"$ 59,426.74","$ 41,967.12",51.8%,Yes,,
Grand Total,,,,$ 243,901.00,$ 156,012.00,36.0%,,,

Output: Pristine Clean DataFrame (clean_df)

🏗️ Architecture & Transformation Pipeline

flowchart TD
    A["Raw Spreadsheet Export (CSV / Excel)"] --> B["1. Header Normalizer"]
    B -->|"Snake_case, strip whitespace, remove special chars"| C["2. Structural Sanitizer"]
    C -->|"Drop 100% empty rows/cols, extract Grand Total footer"| D["3. Two-Tier Hierarchical Date Engine"]
    
    subgraph DateEngine["Two-Tier Date Disambiguation"]
        D --> D1{"Tier 1: High Column Consensus (>80%)?"}
        D1 -->|Yes| D2["Parse entire column with inferred dayfirst"]
        D1 -->|No / Ambiguous| D3["Tier 2: Row Contextual Inspection (Partner columns: Currency / Region)"]
    end

    D2 --> E["4. Multi-Currency Normalizer"]
    D3 --> E

    subgraph CurrencyEngine["Multi-Currency Engine"]
        E --> E1{"Multiple Currencies Detected?"}
        E1 -->|Yes| E2["Interactive Prompt or target_currency param"]
        E2 --> E3["Apply FX Matrix (USD, EUR, GBP, INR, etc.)"]
        E1 -->|No| E4["Strip single currency symbol & cast to Float64"]
        E3 --> E5["Log Audit Trail in df.attrs['currency_conversions']"]
    end

    E4 --> F["5. Type Cast & Accounting Engine"]
    E5 --> F
    F -->|"Accounting (val) -> -val, % -> float, preserve ID leading zeros"| G["Pristine Analysis-Ready DataFrame"]
    
    G --> H1["Pythonic Business Math (xlookup, pareto, growth, run_rate)"]
    G --> H2["Boardroom Display Formatter (format_for_display)"]

🌟 Flagship 1: Two-Tier Hierarchical Date Engine

Standard tools like pd.to_datetime(df['date']) fail when international datasets combine DD/MM/YYYY (India, UK, Europe) and MM/DD/YYYY (USA).

BizPack introduces a Two-Tier Hierarchical Resolution Engine:

flowchart TD
    Start["Date Column Received"] --> T1Check{"Tier 1: Check Unambiguous Values (Days > 12)"}
    T1Check -->|Strong Consensus >= 80%| T1Apply["Apply Column-Wide Format (dayfirst=True/False)"]
    T1Check -->|Ambiguous or Contradictory| T2Context["Tier 2: Fall back to Row-Level Contextual Inspection"]
    
    T2Context --> InspectRow["Inspect Row's Partner Columns"]
    InspectRow --> R1{"Partner has ₹, INR, £, EUR, or India/Europe?"}
    R1 -->|Yes| ParseDMY["Parse Row as DD/MM/YYYY"]
    R1 -->|No| R2{"Partner has $, USD, or USA/North America?"}
    R2 -->|Yes| ParseMDY["Parse Row as MM/DD/YYYY"]
    R2 -->|No| FallbackIso["Standard ISO Parsing"]
    
    T1Apply --> Finish["Zero NaT Rows • 100% Temporal Accuracy"]
    ParseDMY --> Finish
    ParseMDY --> Finish
    FallbackIso --> Finish

Example:

import bizpack as bp
import pandas as pd

df = pd.DataFrame({
    "date": ["05/09/2024", "05/09/2024"],
    "region": ["India", "USA"],
    "amount": ["₹ 1,000", "$ 100"]
})

clean = bp.clean(df)
print(clean["date"])
# 0   2024-09-05   <- Inferred as September 5th via Indian partner context
# 1   2024-05-09   <- Inferred as May 9th via US partner context

🌍 Flagship 2: Multi-Currency Normalization & Audit Trail

Corporate financial data is often globalized. If an analyst naively strips currency symbols, math across different currencies produces disastrous errors.

BizPack standardizes currencies automatically with built-in or custom exchange rates:

import bizpack as bp

# Convert everything to US Dollars (USD)
df_usd = bp.clean(df, target_currency="USD")

# Or standardize to Indian Rupees (INR)
df_inr = bp.clean(df, target_currency="INR")

# Inspect the full audit trail
print(df_usd.attrs["currency_conversions"])
# Output:
# {'gross_revenue': {
#     'target_currency': 'USD',
#     'counts': {'INR': 42, 'USD': 30, 'EUR': 18, 'GBP': 10},
#     'rates_applied': {'USD': 1.0, 'EUR': 1.087, 'GBP': 1.282, 'INR': 0.0119}
# }}

Custom Exchange Rates:

# Pass exact corporate spot rates
df_clean = bp.clean(
    df, 
    target_currency="USD", 
    rates={"EUR": 1.10, "GBP": 1.30, "INR": 0.012}
)

🧹 Flagship 3: Enterprise Spreadsheet Hygiene

BizPack automates the 10 most common spreadsheet cleanup routines:

1. Snake-Case Headers: " Customer Name / Client " $\rightarrow$ "customer_name_client".
2. Accounting Negatives: "(12,865.27)" or "$ (12,865.27)" $\rightarrow$ -12865.27.
3. European Numbers: "€ 41.392,35" (period for thousands, comma for decimal) $\rightarrow$ 41392.35.
4. Indian Number Format: "₹ 1,49,670.67" (lakh/crore comma grouping) $\rightarrow$ 149670.67.
5. Percentages: "33.3%" or "(9.8%)" $\rightarrow$ 0.333 and -0.098.
6. Booleans: "Y", "Yes", "true" $\rightarrow$ True; "N", "No", "false" $\rightarrow$ False.
7. Excel Error Strings: "#REF!", "#N/A", "-", "null" $\rightarrow$ np.nan.
8. Leading Zero Preservation: IDs ("00124", "00042") remain string objects and are not truncated to integers.
9. Empty Structure Stripping: Completely blank rows and columns are purged.
10. Footer Extraction: "Grand Total" rows are removed from calculation flow and preserved in df.attrs['totals'].

📈 Flagship 4: Pythonic Business Math

1. bp.xlookup(): The Native Excel Lookup Replacement

No more 4-line df.merge() with temporary join keys:

# Exact match lookup with fallback default
df["tier"] = bp.xlookup(
    lookup_val=df["account_id"],
    lookup_series=catalog["sku"],
    return_series=catalog["tier_name"],
    default="Standard"
)

2. bp.pareto(): Automated 80/20 Rule Analysis

Identify key accounts and revenue drivers instantly:

pareto_df = bp.pareto(clean_df, dim_col="customer_name", metric_col="revenue", top_pct=0.80)

# Executive narrative generated automatically:
print(pareto_df.attrs["summary"])
# "Top 14 out of 100 customer_name items (14.0%) account for 80% of total revenue."

3. bp.growth(): Period-over-Period Pacing (MoM / YoY)

Compute delta amounts and percentage growth without manual .shift() gymnastics:

growth_df = bp.growth(clean_df, date_col="order_date", metric_col="revenue", freq="M")

4. bp.run_rate(): Target Pacing & Projected Close

Track month-to-date or quarter-to-date trajectory against quotas:

pacing = bp.run_rate(clean_df, date_col="order_date", metric_col="revenue", target=500_000, period="M")

👔 Flagship 5: Boardroom Presentation Formatter

When calculating, analysts need clean float64 numbers. When presenting to stakeholders, executives need beautiful symbols and formatting.

BizPack restores boardroom-ready formatting in 1 line:

# Do your analytical transformations
clean_df["gross_profit"] = clean_df["gross_revenue"] - clean_df["unit_cost"]

# Format back to executive presentation strings
display_df = bp.format_for_display(clean_df)
print(display_df.head())

🔌 Native Pandas .biz Accessor

BizPack seamlessly attaches to any existing Pandas DataFrame:

import pandas as pd
import bizpack  # registers the .biz accessor

df = pd.read_csv("dirty_data.csv")

# Fluent method chaining
clean_df = (
    df.biz.clean(target_currency="USD")
      .biz.pareto(dim_col="customer_name", metric_col="gross_revenue")
)

⚡ Performance & Benchmarks

BizPack is built on vectorized Pandas and NumPy operations, designed to process thousands of messy enterprise rows in milliseconds with zero heavy dependencies:

Benchmarked on standard x86_64 hardware with Python 3.10.

📖 API Reference

Core Cleaning & I/O

Currency & Dates

Business Math & Presentation

🧪 Testing Suite

BizPack maintains a comprehensive test suite covering edge cases in accounting syntax, international currency conventions, ambiguous date permutations, and formula accuracy:

git clone https://github.com/sudheer-050/bizpack.git
cd bizpack
python -m pytest tests/ -v

tests/test_accessor.py::test_accessor_clean_and_format PASSED            [  2%]
tests/test_cleaner.py::test_clean_international_currencies PASSED        [ 21%]
tests/test_currency.py::test_interactive_user_prompt_choice PASSED       [ 51%]
tests/test_dates.py::test_mixed_dates_in_same_column_with_partner_context PASSED [ 70%]
tests/test_formulas.py::test_pareto PASSED                               [ 97%]
============================= 37 passed in 0.67s ==============================

📦 Installation & Requirements

pip install bizpack

• Python: >= 3.9
• Dependencies: pandas >= 1.5.0, numpy >= 1.20.0
• Zero Heavy Dependencies: No C++ compilers, heavy LLM toolchains, or bloated network runtimes.

🗺️ Roadmap & Community

• Two-Tier Hierarchical Date Engine
• Multi-Currency Normalization & Interactive Prompt
• Leading Zero & Account ID Preservation
• Excel Business Math Formulas (xlookup, pareto, growth, run_rate)
• Multi-table sheet splitter (for multi-report Excel tabs)
• Financial waterfall variance decomposition
• Excel styled export (.xlsx with native number formats and header styling)

Contributions, feature requests, and bug reports are welcome on GitHub Issues!

📄 License

Distributed under the MIT License. See LICENSE for more details.