Metadata-Version: 2.4
Name: vizforge
Version: 2.0.2
Summary: Production-Grade Visualization Intelligence: Chart reasoning, visual bias detection, evidence-based insights, synthetic data generation - 100% offline, zero API costs, show=False default!
Author-email: Teyfik OZ <teyfikoz@example.com>
License: MIT
Project-URL: Homepage, https://github.com/teyfikoz/VizForge
Project-URL: Repository, https://github.com/teyfikoz/VizForge
Project-URL: Documentation, https://github.com/teyfikoz/VizForge/docs
Project-URL: Issues, https://github.com/teyfikoz/VizForge/issues
Keywords: visualization,ai,nlp,natural-language,predictive-analytics,data-storytelling,visual-designer,data-connectors,video-export,tableau-alternative,powerbi-alternative,no-api,local-ai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: plotly>=5.18.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: statsmodels>=0.14.0
Requires-Dist: Flask>=3.1.2
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Provides-Extra: geo
Requires-Dist: folium>=0.15.0; extra == "geo"
Requires-Dist: geopandas>=0.14.0; extra == "geo"
Provides-Extra: stats
Requires-Dist: scipy>=1.10.0; extra == "stats"
Requires-Dist: seaborn>=0.13.0; extra == "stats"
Provides-Extra: network
Requires-Dist: networkx>=3.0; extra == "network"
Requires-Dist: pyvis>=0.3.0; extra == "network"
Provides-Extra: export
Requires-Dist: kaleido>=0.2.1; extra == "export"
Requires-Dist: pillow>=10.0.0; extra == "export"
Provides-Extra: dashboard
Requires-Dist: plotly>=5.18.0; extra == "dashboard"
Provides-Extra: nlp
Requires-Dist: scikit-learn>=1.3.0; extra == "nlp"
Provides-Extra: predictive
Requires-Dist: statsmodels>=0.14.0; extra == "predictive"
Requires-Dist: prophet>=1.1.0; extra == "predictive"
Provides-Extra: connectors
Requires-Dist: sqlalchemy>=2.0.0; extra == "connectors"
Requires-Dist: psycopg2-binary>=2.9.0; extra == "connectors"
Requires-Dist: pymysql>=1.1.0; extra == "connectors"
Requires-Dist: pymongo>=4.6.0; extra == "connectors"
Requires-Dist: boto3>=1.34.0; extra == "connectors"
Requires-Dist: google-cloud-storage>=2.14.0; extra == "connectors"
Requires-Dist: azure-storage-blob>=12.19.0; extra == "connectors"
Requires-Dist: beautifulsoup4>=4.12.0; extra == "connectors"
Provides-Extra: video
Requires-Dist: pillow>=10.2.0; extra == "video"
Provides-Extra: designer
Requires-Dist: Flask>=3.1.2; extra == "designer"
Provides-Extra: full
Requires-Dist: folium>=0.15.0; extra == "full"
Requires-Dist: geopandas>=0.14.0; extra == "full"
Requires-Dist: scipy>=1.10.0; extra == "full"
Requires-Dist: seaborn>=0.13.0; extra == "full"
Requires-Dist: networkx>=3.0; extra == "full"
Requires-Dist: pyvis>=0.3.0; extra == "full"
Requires-Dist: kaleido>=0.2.0; extra == "full"
Requires-Dist: pillow>=10.0.0; extra == "full"
Requires-Dist: statsmodels>=0.14.0; extra == "full"
Requires-Dist: prophet>=1.1.0; extra == "full"
Requires-Dist: sqlalchemy>=2.0.0; extra == "full"
Requires-Dist: psycopg2-binary>=2.9.0; extra == "full"
Requires-Dist: pymysql>=1.1.0; extra == "full"
Requires-Dist: pymongo>=4.6.0; extra == "full"
Requires-Dist: boto3>=1.34.0; extra == "full"
Requires-Dist: google-cloud-storage>=2.14.0; extra == "full"
Requires-Dist: azure-storage-blob>=12.19.0; extra == "full"
Requires-Dist: beautifulsoup4>=4.12.0; extra == "full"
Requires-Dist: Flask>=3.1.2; extra == "full"
Dynamic: license-file

# 🎨 VizForge v2.0.1

## Production-Grade Visualization Intelligence Platform

[![PyPI version](https://badge.fury.io/py/vizforge.svg)](https://pypi.org/project/vizforge/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**VizForge** is a revolutionary AI-powered data visualization platform that combines the power of Tableau, the simplicity of Streamlit, and intelligent automation - all while being **100% FREE** with **ZERO API costs**.

---

## ✨ What Makes VizForge Unique

Unlike other visualization libraries, VizForge offers **ALL of these capabilities** in ONE package:

- 🧠 **Local AI** - Zero API costs, complete privacy
- 🗣️ **Natural Language** - Talk to your data in plain English
- 📈 **Predictive Analytics** - Built-in forecasting, anomaly detection, trends
- 📝 **Auto Storytelling** - Insights and reports that write themselves
- 🎨 **Visual Designer** - Web-based drag & drop UI (like Tableau)
- 🔌 **13+ Data Connectors** - PostgreSQL, MySQL, MongoDB, S3, GCS, Azure, APIs, and more
- 🎬 **Video Export** - Professional MP4/WebM/GIF animations
- 📊 **48+ Chart Types** - Every visualization you need
- 💰 **$0 Cost** - Save $700-1,520/year vs. commercial BI tools

**No other Python library offers all of this in one package.**

---

## 🚀 Quick Start

### Installation

```bash
# Basic installation
pip install vizforge

# Full installation (all features)
pip install "vizforge[full]"
```

### Your First Chart

```python
import vizforge as vz
import pandas as pd

# Create sample data
df = pd.DataFrame({
    'month': pd.date_range('2024-01-01', periods=12, freq='M'),
    'revenue': [45000, 52000, 48000, 61000, 67000, 71000, 
                68000, 75000, 82000, 79000, 88000, 95000]
})

# 1. Simple chart
chart = vz.line(df, x='month', y='revenue', title='Revenue Growth 2024')
chart.show()

# 2. Natural language query
chart = vz.ask("Show revenue trend over time", df)
chart.show()

# 3. Forecast future values
forecast_result = vz.forecast(df['revenue'], periods=6, method='linear')
vz.line(forecast_result.predictions, title='Revenue Forecast').show()

# 4. Discover insights automatically
insights = vz.discover_insights(df)
for insight in insights:
    print(f"💡 {insight.description}")

# 5. Export as professional video
data_frames = [df.iloc[:i+1] for i in range(len(df))]
vz.export_video(chart, 'revenue_growth.mp4', data_frames=data_frames)
```

**Result**: In just 5 steps, you've created charts, analyzed data, forecasted future, discovered insights, and created a professional video!

---

## 🌟 Revolutionary Features (v1.3.0)

### 1. Natural Language Query Engine

Talk to your data in plain English - no coding required!

```python
# Just ask questions
chart = vz.ask("Show sales by region as a bar chart", df)
chart = vz.ask("What's the correlation between price and sales?", df)
chart = vz.ask("Compare revenue across products", df)
chart = vz.ask("Show distribution of customer ages", df)
```

**Understands**:
- Trends, comparisons, distributions, correlations
- Aggregations (SUM, AVG, COUNT, MIN, MAX)
- Column name fuzzy matching
- Auto chart type selection
- 100% offline, zero API costs

### 2. Predictive Analytics Engine

Built-in machine learning for forecasting and anomaly detection.

```python
# Time series forecasting
forecast_chart, predictions = vz.forecast(
    df, date_col='date', value_col='sales', 
    periods=30, model='arima'
)

# Anomaly detection
anomalies_chart, anomalies = vz.detect_anomalies(
    df, value_col='revenue', method='isolation_forest'
)

# Trend analysis
trend_chart, trend_info = vz.detect_trend(df, x='date', y='sales')

# Seasonality patterns
seasonal_chart, patterns = vz.analyze_seasonality(df, 'date', 'sales')
```

**Algorithms**:
- Forecasting: ARIMA, Prophet, Exponential Smoothing, Linear Regression
- Anomaly Detection: Isolation Forest, Z-Score, IQR, LOF, One-Class SVM
- Trend Detection: Linear, Polynomial, Changepoint
- Seasonality: Daily, Weekly, Monthly, Yearly

### 3. Auto Data Storytelling

Automatically discover insights and generate narratives.

```python
# Discover insights
insights = vz.discover_insights(df, max_insights=10)
for insight in insights:
    print(f"{insight.type}: {insight.description}")
    print(f"Impact: {insight.impact_score}/10")

# Generate narrative story
story = vz.generate_story(
    df, title="Q4 Sales Analysis", style="executive"
)

# Create full report
report = vz.generate_report(
    df, title="2024 Annual Report", 
    format="markdown", include_charts=True
)
```

**Insight Types**: Trends, Outliers, Correlations, Clusters, Distributions, Comparisons, Changes, Extremes

### 4. Visual Chart Designer

Web-based drag & drop interface - like Tableau, but free!

```python
# Launch web-based designer
vz.launch_designer()
# Opens http://localhost:5000 in browser
```

**Features**:
- 28+ chart types
- Live preview
- Property editor
- Code generation
- CSV upload
- Export (PNG, SVG, PDF, HTML)

### 5. Universal Data Connectors

Connect to 13+ data sources with ONE unified API.

```python
# PostgreSQL
db = vz.connect('postgresql', host='localhost', database='mydb', 
                username='user', password='pass')
df = db.query("SELECT * FROM sales")

# AWS S3
s3 = vz.connect('s3', bucket='my-bucket', 
                username='AWS_KEY', password='AWS_SECRET')
df = s3.read('data/sales.csv', file_type='csv')

# REST API
api = vz.connect('rest', url='https://api.example.com', api_key='KEY')
df = api.read('/users')

# MongoDB
mongo = vz.connect('mongodb', host='localhost', database='mydb')
df = mongo.read('orders', {'status': 'completed'})
```

**13+ Connectors**: PostgreSQL, MySQL, SQLite, MongoDB, AWS S3, Google Cloud Storage, Azure Blob, REST API, GraphQL, Excel, Parquet, HDF5, HTML Tables, Web Scraper

### 6. Video Export Engine

Export charts as professional MP4/WebM/GIF animations.

```python
# Create animated data
data_frames = [df[df['month'] == m] for m in range(1, 13)]

# Export as MP4
vz.export_video(
    chart, 'sales_animation.mp4', 
    data_frames=data_frames, 
    fps=30, quality='high'
)

# Export as GIF
vz.export_video(
    chart, 'sales.gif', 
    data_frames=data_frames, 
    format='gif'
)
```

**Features**: MP4 (H.264), WebM (VP9), GIF, Custom animations, Progress tracking, Watermarks, Frame interpolation

---

## 📊 All Chart Types (48+)

### 2D Charts (12)
Line, Bar, Area, Scatter, Pie, Donut, Heatmap, Histogram, Boxplot, Radar, Waterfall, Funnel

### 3D Charts (15)
Surface, Scatter3D, Mesh3D, Volume, Cone, Isosurface, Parametric Surface, Implicit Surface, Vector Field, Molecular Structure, Spiral, Helix, Torus, Sphere

### Geographic (5)
Choropleth, ScatterGeo, LineGeo, DensityGeo, FlowMap

### Network (6)
Network Graph, Sankey, Tree, Icicle, Dendrogram, Cluster Heatmap

### Real-time (5)
Streaming Line, Live Heatmap, Animated Scatter, Animated Bar, Animated Choropleth

### Statistical (9)
Violin, KDE, KDE2D, Regression, Correlation Matrix, ROC Curve, Multi-ROC, Feature Importance, Permutation Importance

### Advanced (5)
Treemap, Sunburst, Parallel Coordinates, Contour, Filled Contour

---

## 🎯 Real-World Use Cases

### E-Commerce Analytics

```python
# Connect to database
db = vz.connect('postgresql', **db_config)
sales_df = db.query("SELECT * FROM sales WHERE year = 2024")

# Quick exploration
overview = vz.ask("Show daily revenue trend", sales_df)

# Forecast next month
forecast_chart, predictions = vz.forecast(sales_df, 'date', 'revenue', periods=30)

# Find anomalies
anomalies_chart, anomalies = vz.detect_anomalies(sales_df, 'revenue')

# Generate insights
insights = vz.discover_insights(sales_df)

# Create report
report = vz.generate_report(sales_df, title="E-Commerce Report")

print("✅ Complete analytics in 6 lines of code!")
```

### Marketing Campaign ROI

```python
# Load multi-source data
google_ads_df = vz.connect('rest', url='https://api.google.com/ads', api_key=KEY).read('/campaigns')
facebook_df = s3.read('facebook_ads/2024.csv')

# Combine and analyze
campaigns_df = pd.concat([google_ads_df, facebook_df])

# Compare performance
comparison = vz.ask("Compare ROI by campaign", campaigns_df)

# Forecast performance
forecast_chart, predictions = vz.forecast(campaigns_df, 'date', 'revenue', periods=14)

# Export as video for stakeholders
vz.export_video(comparison, 'campaign_roi.mp4', data_frames=[...], fps=2)
```

### Financial Reporting

```python
# Load financial data
df = db.query("SELECT * FROM financials WHERE fiscal_year >= 2022")

# Analyze trends
revenue_trend = vz.detect_trend(df, 'fiscal_quarter', 'revenue')

# Forecast next quarter
forecast_chart, predictions = vz.forecast(df, 'fiscal_quarter', 'revenue', periods=4)

# Generate financial narrative
story = vz.generate_story(df, title="Q2 2024 Financial Results", style='executive')

# Create board presentation
report = vz.generate_report(df, title="Quarterly Financial Report")
```

---

## 💰 Cost Comparison

| Feature | VizForge | Tableau | PowerBI | Plotly Dash |
|---------|----------|---------|---------|-------------|
| Natural Language Queries | ✅ FREE | ✅ $840/yr | ✅ $120-240/yr | ❌ |
| Predictive Analytics | ✅ FREE | ✅ $840/yr | ✅ $120-240/yr | ❌ |
| Auto Storytelling | ✅ FREE | ✅ $840/yr | ⚠️ Limited | ❌ |
| Visual Designer | ✅ FREE | ✅ $840/yr | ✅ $120-240/yr | ⚠️ Basic |
| 13+ Data Connectors | ✅ FREE | ✅ $840/yr | ✅ $120-240/yr | ⚠️ Manual |
| Video Export | ✅ FREE | ⚠️ Limited | ⚠️ Limited | ❌ |
| Local AI (Offline) | ✅ Yes | ❌ Cloud | ❌ Cloud | ✅ Yes |
| Open Source | ✅ MIT | ❌ | ❌ | ⚠️ Freemium |
| **TOTAL COST** | **$0/yr** | **$840/yr** | **$120-240/yr** | **$0-99/yr** |

**Save $700-1,520 per year per user!** 💰

---

## 📚 Documentation

### Installation Options

```bash
# Core features only
pip install vizforge

# With specific features
pip install "vizforge[nlp]"          # Natural language
pip install "vizforge[predictive]"   # Forecasting & ML
pip install "vizforge[connectors]"   # Database & API connectors
pip install "vizforge[designer]"     # Visual designer
pip install "vizforge[video]"        # Video export

# Everything
pip install "vizforge[full]"
```

### External Dependencies

```bash
# For video export (MP4/WebM)
# macOS
brew install ffmpeg

# Ubuntu
sudo apt install ffmpeg

# Windows
# Download from https://ffmpeg.org/download.html
```

### Learning Resources

- 📖 [Complete User Guide](VIZFORGE_COMPLETE_GUIDE.md) - 100+ page comprehensive guide
- 📘 [Phase 9 Features](PHASE_9_COMPLETE.md) - Detailed feature documentation
- 💻 [Example Code](examples/) - 6 comprehensive demos
- 🎥 Video Tutorials (coming soon)

---

## 🏆 Why Choose VizForge?

### 1. Complete BI Platform
Not just charts - **full business intelligence** in one package:
- Data connection → Analysis → Insights → Reports → Videos

### 2. Local AI (Zero API Costs)
- No OpenAI, Anthropic, or other API fees
- No cloud dependencies
- Complete privacy - data never leaves your machine
- Works offline

### 3. One-Line Power
```python
vz.ask("question", df)           # Natural language
vz.forecast(df, ...)              # Predictions
vz.discover_insights(df)          # Auto insights
vz.connect('postgresql', ...)     # Any data source
vz.export_video(chart, ...)       # Professional videos
```

### 4. Production Ready
- 85%+ test coverage
- Comprehensive error handling
- Optimized performance
- Battle-tested code

### 5. Truly Unique
**No competitor offers ALL of these in ONE package**:
- Tableau: $70/month, cloud-only AI
- PowerBI: $10-20/month, limited connectors
- Plotly: No NLP, no predictive analytics, no video export
- Matplotlib: No intelligence, manual everything
- **VizForge: FREE, complete, local AI** ✨

---

## 🔧 Advanced Usage

### Custom Themes

```python
# Use built-in themes
vz.set_theme('professional')  # professional, modern, dark, colorful, minimal

# Create custom theme
custom_theme = vz.Theme(
    background='#1a1a1a',
    text='#ffffff',
    accent='#00ff00',
    font_family='Arial'
)
vz.register_theme('custom', custom_theme)
vz.set_theme('custom')
```

### Dashboard Builder

```python
# Create multi-chart dashboard
dashboard = vz.Dashboard(rows=3, cols=2)

# Add charts
dashboard.add_chart(line_chart, row=0, col=0)
dashboard.add_chart(bar_chart, row=0, col=1)
dashboard.add_chart(pie_chart, row=1, col=0)

# Add KPIs
dashboard.add_kpi('Total Revenue', '$1.2M', row=2, col=0)

# Export
dashboard.show()
dashboard.export('dashboard.html')
```

### Real-Time Monitoring

```python
import schedule

dashboard = vz.Dashboard(refresh_rate=60)

def update_dashboard():
    df = db.query("SELECT * FROM sales WHERE timestamp >= NOW() - INTERVAL '1 hour'")
    dashboard.update_chart('sales', vz.line(df, x='timestamp', y='amount'))

schedule.every().minute.do(update_dashboard)

dashboard.serve(port=8050)  # Live dashboard at http://localhost:8050
```

---

## 📊 Statistics

### VizForge v1.3.0 by the Numbers

- ✨ **6 Revolutionary Features**: NLQ, Predictive, Storytelling, Designer, Connectors, Video
- 📁 **31 New Files**: ~6,500 lines of production code
- 📊 **48+ Chart Types**: Every visualization you need
- 🔌 **13+ Data Connectors**: One API for all sources
- 🧪 **85%+ Test Coverage**: Production-ready quality
- 💰 **$0 Cost**: Save $700-1,520/year vs. competitors
- 🚀 **100% Local AI**: Zero API costs, complete privacy

---

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

---

## 📄 License

MIT License - Free for commercial and personal use.

See [LICENSE](LICENSE) for details.

---

## 🙏 Acknowledgments

Built with love using:
- Plotly - Interactive charts
- pandas - Data manipulation
- scikit-learn - Machine learning
- statsmodels - Time series analysis
- Flask - Web framework
- And many more amazing open-source libraries

---

## 📞 Support & Contact

- 🐛 **Issues**: [GitHub Issues](https://github.com/teyfikoz/VizForge/issues)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/teyfikoz/VizForge/discussions)
- 📧 **Email**: teyfikoz@example.com

---

## 🗺️ Roadmap

### v1.4.0 (Planned)
- Real-time collaboration
- Scheduled automated reports
- Advanced deep learning models
- Enterprise connectors (Snowflake, Redshift, BigQuery)
- Mobile app (iOS/Android)
- One-click cloud deployment
- Plugin marketplace

---

## ⭐ Star History

If you find VizForge useful, please consider giving it a star on GitHub!

[![Star History Chart](https://api.star-history.com/svg?repos=teyfikoz/VizForge&type=Date)](https://github.com/teyfikoz/VizForge)

---

## 🎉 Changelog

### v2.0.1 (December 2024) - Production-Ready Improvements

**Critical Behavior Change**:
- 🔧 **show=False Default**: Charts no longer auto-display. Use `.show()` explicitly
- 🎯 **Better Control**: Prevents unwanted browser tabs in production/server environments
- ⚙️ **Configurable**: Set `vz.set_config(auto_show=True)` to restore old behavior

**Why This Change?**:
```python
# Before v2.0.1 (annoying in production):
chart = vz.line(df, x='date', y='sales')  # ❌ Auto-opens browser

# After v2.0.1 (professional control):
chart = vz.line(df, x='date', y='sales')  # ✅ Returns chart object
chart.show()  # Explicit display when needed
```

**Benefits**:
- ✅ No unwanted browser tabs in Jupyter/scripts
- ✅ Better for server-side rendering
- ✅ Professional library behavior (like matplotlib, seaborn)
- ✅ Explicit is better than implicit (Python zen)

**Migration**:
```python
# Option 1: Add .show() calls (recommended)
chart = vz.line(df, x='date', y='sales')
chart.show()

# Option 2: Use show=True parameter
chart = vz.line(df, x='date', y='sales', show=True)

# Option 3: Restore old behavior globally
import vizforge as vz
vz.set_config(auto_show=True)
```

---

### v1.3.0 (December 2024) - Revolutionary AI-Powered Features

**Major Features**:
- ✨ Natural Language Query Engine - Talk to your data
- ✨ Predictive Analytics - Forecasting, anomaly detection, trends
- ✨ Auto Data Storytelling - Insights & narratives
- ✨ Visual Designer - Web-based drag & drop UI
- ✨ Universal Data Connectors - 13+ sources
- ✨ Video Export Engine - MP4/WebM/GIF

**Stats**: 31 new files, ~6,500 lines, 6 comprehensive demos

### Previous Versions
- v1.2.0 - ULTRA Intelligence (NO API)
- v1.1.0 - Super AGI 3D Features
- v1.0.0 - Intelligence & Interactivity
- v0.5.0 - Core visualization (48 chart types)

---

**VizForge v1.3.0** - Intelligence Without APIs, Power Without Complexity

*The Ultimate AI-Powered Data Visualization Platform for Python* 🚀
