Metadata-Version: 2.5
Name: vizzbreeze
Version: 1.1.1
Summary: A high-performance streamlined transactional web-dashboard and Jupyter-compatible framework for advanced graph analytics and risk audit.
Project-URL: Homepage, https://github.com/mila-alex-cloud/VizzBreeze
Project-URL: Repository, https://github.com/mila-alex-cloud/VizzBreeze.git
Project-URL: Documentation, https://github.com/mila-alex-cloud/VizzBreeze/blob/main/README.md
Project-URL: Linkedin, https://www.linkedin.com/in/mila-alex-cfa
Author: Mila Alex
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.9
Requires-Dist: numpy>=1.25.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: pandas>=2.1.0
Requires-Dist: plotly>=5.18.0
Requires-Dist: streamlit>=1.35.0
Description-Content-Type: text/markdown

[![PyPI Downloads](https://static.pepy.tech/personalized-badge/vizzbreeze?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/vizzbreeze)

A lightweight, high-performance transactional web-dashboard designed for advanced data flow analytics, multi-stage routing visualization, and statistical risk audit, and AI Agent trace visualization. Built natively on top of Streamlit, Pandas, and Plotly.

### Try It Out
* **Interactive Demo:** [Streamlit stateless site](https://vizzbreeze.streamlit.app)
* **Source Code:** [GitHub Repository](https://github.com/mila-alex-cloud/VizzBreeze)

If you find this project useful, please drop a ⭐ to support its development!

---
## Key Features

- **Flat Transaction Processing Engine**: Optimized for fast processing of un-aggregated logs.
- **Global Session Synchronization**: Seamlessly locks metric column selections, typography sizes, and alignments across all workspace views.
- **Advanced Graph Matrix Analytics**: Includes high-fidelity stacked charts, multi-dimensional Parcats layouts, Density Matrices, and automated IQR risk audit profiling tools.
- **AI Agent Trace & Observability**: Native templates designed to map LLM chain-of-thought routing, monitor token consumption footprints, and catch execution latency anomalies.

## Supported Data Formats
VizzBreeze is engine-agnostic and designed to fit natively into standard AI development, LLM engineering, and data science workflows. It accepts un-aggregated raw logs in three major formats:

- **JSON / JSONL (Recommended for LLM Ops)**: Direct export pipelines from frameworks like LangChain, CrewAI, AutoGen, or custom OpenAI/Anthropic API telemetry wrappers.
- **CSV**: High-performance, lightweight flat tabular traces optimized for rapid Pandas processing and memory efficiency.
- **Excel (.xlsx / .xls)**: Native spreadsheet ingestion for transactional business analysis, enterprise risk audits, and manual log reviews.

*(Note: Data Ingestion Tip: Regardless of the source format, the internal Streamlit ingestion engine normalizes all uploads into an optimized pandas.DataFrame configuration to guarantee backward compatibility with all graph matrices).*

## Built With
1  - [Plotly](https://plotly.com) - Core interactive charting engine.
2  - [Streamlit](https://streamlit.io) - Cloud infrastructure and web UI framework.
3  - [Pandas](https://pydata.org) - High-performance data structures and data analysis engine.

## Quick Start

#### 1. Standard Python / Jupyter & Google Colab Usage
VizzBreeze functions process un-aggregated raw DataFrames and return native Plotly figures, making them fully compatible with Jupyter views and pipeline automation:

```python
import vizzbreeze as vb
import pandas as pd
```
To explore the dashboard features instantly, you can use the pre-configured spreadsheet **`1. sample_(ai_traces).xlsx`** or download the interactive [Quickstart Jupyter Notebook](./demo_notebook.ipynb) directly from this repository to run all graph matrices in one click. 

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](http://localhost:8890/notebooks/Desktop%2Fdemo_notebook.ipynb)


#### JupyterLab/ VS Code Layout Tip
If you are rendering massive multi-agent chains with a large width (e.g., `width_px=1300`) and notice that the chart gets clipped at the screen boundary without horizontal scrollbars, simply run this native cell macro in your notebook right before displaying the chart to force responsive layout scrolling:

```python
%%html
<style>
.jp-OutputArea-output, .output_subarea {
    overflow-x: auto !important;
}
</style>
```
*(Note: In cloud environments like Google Colab, horizontal scrolling works natively out-of-the-box without any tweaks).*

#### 2. Standalone Web Control Room Execution
If you prefer a full-scale interactive UI with global layout sync, just open your local terminal and run:

```bash
vizzbreeze-run
```
*(Note: If you explicitly need to run VizzBreeze in cloud environments like Google Colab, please use a secure SSH/Port-forwarding tunnel to bypass iframe infrastructure limits).*

To explore the dashboard features instantly, you can use the pre-configured spreadsheet **`1. sample_(ai_traces).xlsx`** located in the root folder of this repository. Just drag and drop it into the sidebar upload zone!

### Accessing Built-in Color Palettes
You don't need to hardcode HEX styles. Access the corporate design system directly from the package configuration:
```python
import vizzbreeze as vb

# View all available palette names
print(vb.COLOR_PALETTES.keys())

# Extract a specific synchronized list of colors
chosen_colors = vb.COLOR_PALETTES["Consulting Premium"]
```

## Core Analytical Tabs

1. **Flows**: Explore multi-stage category paths (e.g., LLM chain-of-thought: Intent ➔ Agent ➔ Tool) with thin, light axis labels and custom high-contrast hover tooltips.
2. **Funnel**: Track progressive conversion drops along specific workflow layers.
3. **Structural Breakdown**: Classic stacked column bar charts configured with responsive axis titles that update on the fly based on active filters.
4. **Bento**: An asymmetrical modular tile framework designed to compress complex multi-level dimensions (like Token Consumption Footprints) into a clean, prioritized grid dashboard.
5. **Heatmap**: High-density dashboard to scan cluster intersections instantly.
5. **Anomaly & Risk Audit**: Automated statistical anomaly profiling that detects execution latency spikes and infinite loop outliers without freezing the browser engine.

### Core Functions API Reference & Parameter Mapping

All visualization engines are fully modular, accept un-aggregated raw `pandas.DataFrame` inputs, and return native `plotly.graph_objects.Figure` interactive objects.

---

### 1. Flows
```python
flow_fig = vb.generate_parcats(
    df=df,
    stage_nodes=['user_intent', 'active_agent', 'tool_called'],
    target_node='execution_status',
    value_col='tokens_used',  # Flows will scale by token consumption!
    chart_title="AI Agent Chain of Thought & Token Distribution",
    selected_palette=chosen_colors,
    title_size=20,
    width_px=1600,
    height_px=500,
    title_x = 0.5
)

flow_fig.show()
```

<img width="1350" height="500" alt="newplot" src="https://github.com/user-attachments/assets/0ac9dd2f-a09c-4127-bb31-4eed977385cd" />


### 2. Funnel
```python
fig = vb.generate_funnel_chart(
    df=df,
    stage_nodes=['user_intent', 'active_agent', 'tool_called'],   
    target_node='execution_status',                               
    value_col='tokens_used',                                      
    
    selected_route_dict={
        'user_intent':'Tech Support', 'active_agent':'Router_Agent', 'tool_called':'Knowledge_Base_Lookup'

    },                                       
    selected_palette=chosen_colors,            
    unit_divider=1.0,
    force_shuffle=True,
    chart_title="AI Agent Chain of Thought & Token Distribution", 
    width_px=1050,
    height_px=500,
    title_x=0.5
)

fig.update_layout(
    margin=dict(l=350, r=20, t=100, b=50)
)
```

<img width="1050" height="500" alt="newplot (1)" src="https://github.com/user-attachments/assets/e611cc82-5d4c-4c91-85ce-29890f83aec5" />


### 3. Structural Breakdown
```python
stage_nodes=['user_intent']
target_node='execution_status'
value_col='tokens_used'

fig = vb.generate_stacked_bar_chart(
    df=df,
    stage_nodes=stage_nodes,
    target_node=target_node,           
    value_col=value_col,            
    selected_palette=chosen_colors,
    unit_divider=1.0,
    force_shuffle=True,
    chart_title="Systemic Error Distribution Across Active Agents",
    width_px=1600,
    height_px=500,
    title_x = 0.5
)
fig.update_layout(
    margin=dict(l=100, r=20, t=50, b=120),
    yaxis=dict(title="")
)

fig.show()
```

<img width="1100" height="500" alt="newplot (2)" src="https://github.com/user-attachments/assets/2a499747-46b8-481a-8982-68a5fd57f352" />


### 4. Bento
```python
fig = vb.generate_bento_treemap(
    df=df,
    id_col='user_intent',      
    value_col=value_col,           
    selected_palette=chosen_colors,
    unit_divider=1.0,
    force_shuffle=True,
    chart_title="Token Consumption Footprint by Intent Layer",
    width_px=1050,
    height_px=500,
    title_x = 0.5
)
fig.update_layout(
    margin=dict(l=50, r=20, t=50, b=50)
    )
fig.show()
```

<img width="1050" height="500" alt="newplot (3)" src="https://github.com/user-attachments/assets/6b621d64-f52e-4b99-bda1-c14ddb081544" />


### 5. Heatmap
```python
fig = vb.generate_heatmap(
    df=df,
    x_col='user_intent',
    y_col='execution_status',
    value_col='tokens_used',
    selected_palette=chosen_colors,
    chart_title="AI Agent Token Consumption Heatmap by Execution Status", 
    show_annot=True,
    width_px=1050,
    height_px=500,
    title_x=0.5
)

fig.update_xaxes(title_text="USER INTENT LAYER")
fig.update_yaxes(title_text="EXECUTION STATUS")

fig.update_layout(
    margin=dict(l=150, r=20, t=50, b=50)
)
fig.show()
```

<img width="700" height="500" alt="newplot (4)" src="https://github.com/user-attachments/assets/b37dac6a-2973-427a-8183-629660ef5f02" />


### 6. Anomaly & Risk Audit
```python
anomaly_fig = vb.generate_outliers_chart(
    df=df,
    stage_col='active_agent',
    target_col='tool_called',
    value_col='execution_time_sec',
    agg_func='max', 
    chart_title="AI Execution Latency Anomaly Profile (IQR Bounds)",
    selected_palette=chosen_colors,
    width_px=1050,
    height_px=500,
    title_x=0.5
)

anomaly_fig.update_xaxes(title_text="MAX SINGLE-RUN EXECUTION TIME (SEC)")

anomaly_fig.update_layout(
    margin=dict(l=310, r=20, t=50, b=50)
)
anomaly_fig.show()
```

<img width="1050" height="500" alt="newplot (5)" src="https://github.com/user-attachments/assets/08835580-94cb-4de1-98bf-16f906d0216e" />


## Requirements


- Python >= 3.9
- Streamlit >= 1.35.0
- Pandas >= 2.1.0
- Plotly >= 5.18.0

## Roadmap

- Advanced Data Preprocessing Pipeline: Implementing automated anomaly tracking and missing value imputation optimized for multi-source financial and operational data arrays.
- Interactive Risk Metrics: Adding features for deep data analysis, including volatility tracking, anomaly detection, and custom structural breakdown widgets.
- Large-Scale Data Engineering: Adding chunks-based data loading and optimization widgets to seamlessly process unaggregated corporate and industrial datasets exceeding 500MB.
- Enterprise Stability & Testing: Expanding code verification with an extensive pytest suite to achieve 85%+ test coverage for secure local CLI execution.

## License

This project is licensed under the MIT License - see the LICENSE file for details.
