# 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

```bash
pip install storai
```

Postgres support (driver):

```bash
pip install "storai[postgres]"
```

For development:

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

## Quick Start

### DataFrame input

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

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

```python
{
  "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:

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

## Build And Publish

Build distributions:

```bash
python -m build
```

Validate artifacts:

```bash
python -m twine check dist/*
```

Upload:

```bash
python -m twine upload dist/*
```

## License

MIT
