storai 0.1.2

Generate business insights from summary and source data.

StorAI

storai is a reusable Python library that generates business insights from:

• summary-level data (monthly/periodic KPIs), and
• optional source-level data (row-level transactions/events).

It returns display-ready output, human-readable insights, reasons, and optional ML findings.

Install

pip install storai

Postgres support (driver):

pip install "storai[postgres]"

For development:

pip install -e ".[dev,test,postgres]"

Quick Start

DataFrame input

import pandas as pd
from storai import analyze

summary_df = pd.DataFrame(
    {
        "year": [2025, 2025, 2025, 2025],
        "month": [7, 8, 9, 10],
        "payment": [391585.01, 342235.81, 402424.61, 434446.20],
        "visit_count": [1474, 1309, 1428, 1433],
    }
)

source_df = summary_df.copy()

result = analyze(summary_df=summary_df, source_df=source_df)
print(result["insights"])

SQL input

from sqlalchemy import create_engine
from storai import analyze

engine = create_engine("postgresql+psycopg2://user:pass@host:5432/db")

summary_sql = """
select year, month, sum(payment_amount) as payment, sum(visit_count) as visit_count
from semantic.tbl_executive_summary
where year = 2025 and month in (7,8,9,10)
group by 1,2
"""

source_sql = """
select *
from semantic.tbl_executive_summary
where year = 2025 and month in (7,8,9,10)
"""

result = analyze(summary_sql=summary_sql, source_sql=source_sql, db_engine=engine)
print(result["insights"])

Output Contract

{
  "display_df": pandas.DataFrame,
  "display_rows": list[dict],
  "source_sql": str | None,
  "insights": list[{"insight": str, "reason": str}],
  "ml_findings": {"outliers": list, "patterns": list},
}

Public API

• storai.analyze(...)
• storai.story(...) (alias of analyze)
• storai.detect_insights(...)
• storai.compute_metrics(...)
• storai.detect_ml_findings(...)
• storai.infer_schema(...)

Project Layout

The package uses src layout for clean packaging boundaries:

src/storai/
  api/
  application/
  analysis/
  core/
  data/
  domain/
  insights/
  metrics/
  ml/
  narrative/
  schema/
  utils/

Build And Publish

Build distributions:

python -m build

Validate artifacts:

python -m twine check dist/*

Upload:

python -m twine upload dist/*

License

MIT