Metadata-Version: 2.4
Name: pathway-viz
Version: 0.1.3
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: System :: Monitoring
Requires-Dist: pathway>=0.8 ; python_full_version < '3.14' and extra == 'demo'
Requires-Dist: kafka-python-ng>=2.0 ; extra == 'demo'
Requires-Dist: duckdb>=1.0 ; extra == 'demo'
Requires-Dist: pytest>=7.0 ; extra == 'dev'
Requires-Dist: ruff>=0.1 ; extra == 'dev'
Requires-Dist: maturin>=1.0,<2.0 ; extra == 'dev'
Provides-Extra: demo
Provides-Extra: dev
License-File: LICENSE
Summary: The visualization layer for Pathway - real-time dashboards for streaming data
Keywords: streaming,visualization,pathway,kafka,real-time,dashboard
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/mvfolino68/pathway-viz
Project-URL: Repository, https://github.com/mvfolino68/pathway-viz
Project-URL: Documentation, https://github.com/mvfolino68/pathway-viz#readme
Project-URL: Issues, https://github.com/mvfolino68/pathway-viz/issues

# PathwayViz

Real-time dashboards for streaming data pipelines. Zero config, embeddable, fast.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)

## What is PathwayViz?

**Pathway** handles streaming aggregations. **PathwayViz** makes them visible.

```python
import pathway as pw
import pathway_viz as pv

orders = pw.io.kafka.read(...)
totals = orders.reduce(revenue=pw.reducers.sum(pw.this.amount))

pv.stat(totals, "revenue", title="Revenue", unit="$")
pv.start()
pw.run()
```

Open `http://localhost:3000` → live dashboard.

Note: the Python module name is `pathway_viz` (e.g. `import pathway_viz as pv`).

## Quick Start

```bash
pip install pathway-viz
import pathway_viz as pv

pv.stat("revenue", title="Revenue", unit="$")
pv.start()
```

## Installation

```bash
# Basic package (simple demo, no external dependencies)
pip install pathway-viz

# Full demo with Kafka/Redpanda + Pathway + DuckDB
pip install pathway-viz[demo]
```

## Run demos

pathway-viz demo --mode simple # No Docker required
pathway-viz demo # E-commerce demo (requires Docker)

## Scaffold a new project

```bash
pathway-viz init my-dashboard           # Creates a new project

# View templates
pathway-viz templates                   # List available templates
pathway-viz show pipeline               # View pipeline template
pathway-viz show docker-compose         # View Docker compose template
```

## Widgets

| Widget  | Purpose        | Example                                           |
| ------- | -------------- | ------------------------------------------------- |
| `stat`  | Big numbers    | `pv.stat("revenue", title="Revenue", unit="$")`   |
| `chart` | Time series    | `pv.chart("latency", title="Latency", unit="ms")` |
| `gauge` | Bounded values | `pv.gauge("cpu", title="CPU", max_val=100)`       |
| `table` | Live rows      | `pv.table("events", columns=["time", "msg"])`     |

## Embedding

```python
pv.configure(embed=True)
pv.stat("revenue", title="Revenue")
pv.start()
```

```html
<iframe src="http://localhost:3000/embed/revenue"></iframe>
```

## Documentation

For comprehensive guides, see the **[docs/](./docs/)** folder:

- **[Concepts](./docs/concepts.md)** — How PathwayViz, Pathway, and windowing work
- **[Widgets](./docs/widgets.md)** — All widget types with parameters and examples
- **[Persistence](./docs/persistence.md)** — DuckDB, Pathway checkpointing, surviving restarts
- **[Deployment](./docs/deployment.md)** — Docker, Kubernetes, reverse proxy setup
- **[E-commerce Example](./docs/examples/ecommerce.md)** — Kafka + Pathway demo with embedded widgets and optional DuckDB persistence

## Docker

Pre-built images are available on Docker Hub:

```bash
# Pull the image
docker pull mvfolino68/pathway-viz:latest

# Run the simple demo
docker run -p 3000:3000 mvfolino68/pathway-viz pathway-viz demo --mode simple

# Or use your own pipeline
docker run -p 3000:3000 -v $(pwd)/my_pipeline.py:/app/pipeline.py \
  mvfolino68/pathway-viz python /app/pipeline.py
```

## CLI Reference

```bash
pathway-viz demo [--mode simple|pathway] [--port PORT]   # Run demos
pathway-viz init DIRECTORY [--k8s] [--force]             # Scaffold project
pathway-viz show TEMPLATE                                 # Print template
pathway-viz templates                                     # List templates
```

## Architecture

```text
Pathway Pipeline → PathwayViz Python (`pathway_viz`) → Rust WebSocket Server → Browser
                                              ↓
                                      Ring buffers for history
```

The Rust WebSocket server handles high-throughput broadcast without Python GIL bottlenecks.

## License

MIT

