Metadata-Version: 2.4
Name: storai
Version: 0.1.2
Summary: Generate business insights from summary and source data.
Author-email: Gurudev Kumar <gurudevkumar51@hotmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/your-org/storai
Project-URL: Documentation, https://github.com/your-org/storai#readme
Project-URL: Repository, https://github.com/your-org/storai
Project-URL: Issues, https://github.com/your-org/storai/issues
Keywords: analytics,insights,narrative,sql,pandas
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: pydantic>=2.6.0
Requires-Dist: pydantic-settings>=2.1.0
Requires-Dist: sqlalchemy>=2.0.0
Provides-Extra: postgres
Requires-Dist: psycopg2-binary>=2.9.0; extra == "postgres"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: coverage>=7.0; extra == "test"
Provides-Extra: dev
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: isort>=5.12; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Dynamic: license-file

# 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
