Metadata-Version: 2.4
Name: flowboard
Version: 0.1.2
Summary: Production-grade semantic analytics framework. Power BI-style modeling with DuckDB's sub-millisecond query performance.
Author-email: Gyanankur Baruah <gyanankur9@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/gyanankur23/flowboard
Project-URL: Repository, https://github.com/gyanankur23/flowboard.git
Project-URL: Documentation, https://github.com/gyanankur23/flowboard#readme
Project-URL: Issue Tracker, https://github.com/gyanankur23/flowboard/issues
Keywords: analytics,duckdb,semantic-model,business-intelligence,data-visualization,intent-driven,sql
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
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 :: Database
Classifier: Topic :: Office/Business
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: duckdb>=0.8.0
Requires-Dist: plotly>=5.0.0
Requires-Dist: pandas>=1.0.0
Requires-Dist: openpyxl>=3.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Dynamic: license-file

# Flowboard

**Production-Grade Semantic Analytics Framework**

Flowboard is a lightweight, intent-driven analytics engine that brings Power BI-style semantic modeling to Python. Build multi-table data models, query with natural intent, and visualize results—all with blazing-fast in-memory execution powered by DuckDB.

**Why Flowboard?**
- **Semantic First**: Define dimensions and measures once, query with intent
- **DuckDB-Powered**: Sub-millisecond analytics on datasets up to available RAM
- **Multi-Table**: Built-in relationship management across tables
- **Zero Dependencies Hell**: Minimal overhead, fast installation
- **Production Ready**: Designed for embedded analytics and data apps

---

## Installation

```bash
pip install flowboard
```

**Requires Python 3.8+**

---

## Quick Start: 60-Second Example

```python
import flowboard as fb

# 1. Load data
sales_table = fb.load_csv('sales.csv')

# 2. Define semantic model
model = fb.SemanticModel()
model.add_table(
    'sales',
    dimensions=['date', 'region', 'product'],
    measures={
        'revenue': 'SUM(amount)',
        'profit': 'SUM(amount - cost)',
        'units': 'COUNT(*)'
    }
)

# 3. Query with intent
result = fb.query("revenue by region", model)

# 4. Visualize
chart = fb.chart(result)
chart.show()
```

---

## Core Features

### 📊 Multi-Format Data Loading
```python
fb.load_csv('data.csv')      # CSV auto-detection
fb.load_parquet('data.parquet')  # Columnar format
fb.load_xlsx('data.xlsx')    # Excel spreadsheets
```

### 🎯 Intent-Driven Queries
```python
fb.query("revenue by month", model)
fb.query("profit by region", model)
fb.query("units by product", model)
```

### 🔗 Relationship Management
```python
model.add_relationship('sales', 'customer_id', 'customers', 'id')
```

### 📈 One-Line Visualization
```python
chart = fb.chart(result)  # Returns interactive Plotly figure
chart.show()
```

---

## Industry Use Cases

### E-Commerce Analytics
```python
model.add_table('orders', 
    dimensions=['date', 'category', 'region'],
    measures={'gmv': 'SUM(total)', 'orders': 'COUNT(*)'}
)
result = fb.query("gmv by category", model)
```

### SaaS Metrics Dashboard
```python
model.add_table('events',
    dimensions=['event_type', 'cohort', 'date'],
    measures={'dau': 'COUNT(DISTINCT user_id)', 'sessions': 'COUNT(*)'}
)
result = fb.query("dau by cohort", model)
```

### Financial Reporting
```python
model.add_table('transactions',
    dimensions=['account', 'quarter'],
    measures={'revenue': 'SUM(amount)', 'margin': 'SUM(profit)'}
)
result = fb.query("revenue by account", model)
```

---

## Architecture

```
┌─────────────────────────────────────┐
│        Flowboard API Layer          │
│  (Semantic Model + Intent Query)    │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│     DuckDB Execution Engine         │
│    (Sub-ms Query Performance)       │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│    Data Loaders (CSV/Parquet/XLSX)  │
│         + Relationship Mgmt         │
└─────────────────────────────────────┘
```

---

## API Reference

### `load_csv(path)` → `str`
Load CSV file into DuckDB. Returns table name.

### `load_parquet(path)` → `str`
Load Parquet file into DuckDB. Returns table name.

### `load_xlsx(path)` → `str`
Load Excel file into DuckDB. Returns table name.

### `SemanticModel()`
Define your data model.

**Methods:**
- `add_table(name, dimensions, measures)` — Register a table with semantic metadata
- `add_relationship(t1, col1, t2, col2)` — Define foreign key relationships

### `query(intent, model)` → `list[dict]`
Execute semantic query. Format: `"<measure> by <dimension>"`

### `chart(result)` → `plotly.graph_objects.Figure`
Generate interactive bar chart from query result.

---

## Performance Characteristics

| Dataset Size | Query Latency | Memory Usage |
|--------------|---------------|--------------|
| < 100MB      | < 1ms         | Minimal      |
| < 1GB        | 1-10ms        | 1-2GB        |
| < 10GB       | 10-100ms      | 5-15GB       |

*Benchmarks on modern hardware (2023+)*

---

## Development

```bash
git clone https://github.com/gyanankur23/flowboard
cd flowboard
pip install -e .[dev]
pytest
```

---

## License

MIT — See LICENSE file for details.

---

## Contributing

Contributions welcome! Please open an issue or PR on GitHub.

For questions and discussions, reach out to: **gyanankur9@gmail.com**

---

**Flowboard v0.1.1** | Built for data teams, by data builders.
