Metadata-Version: 2.4
Name: stepcast
Version: 1.0.0
Summary: Every Python script deserves a voice. Transparent, narrated pipeline execution.
Project-URL: Homepage, https://github.com/bosekarmegam/stepcast
Project-URL: Repository, https://github.com/bosekarmegam/stepcast
Project-URL: Bug Tracker, https://github.com/bosekarmegam/stepcast/issues
Project-URL: Documentation, https://github.com/bosekarmegam/stepcast/blob/main/docs/index.md
Author-email: Suneel Bose K <bosekarmegam@github.com>
License: MIT License
        
        Copyright (c) 2026 Suneel Bose K (https://github.com/bosekarmegam)
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: automation,cli,devtools,logging,pipeline,workflow
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Logging
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Provides-Extra: all
Requires-Dist: fastapi>=0.100; extra == 'all'
Requires-Dist: google-auth-oauthlib>=1.0; extra == 'all'
Requires-Dist: google-auth>=2.0; extra == 'all'
Requires-Dist: google-generativeai>=0.5; extra == 'all'
Requires-Dist: rich>=13.0; extra == 'all'
Requires-Dist: uvicorn>=0.23; extra == 'all'
Requires-Dist: websockets>=11.0; extra == 'all'
Provides-Extra: colab
Requires-Dist: google-auth-oauthlib>=1.0; extra == 'colab'
Requires-Dist: google-auth>=2.0; extra == 'colab'
Provides-Extra: dashboard
Requires-Dist: fastapi>=0.100; extra == 'dashboard'
Requires-Dist: uvicorn>=0.23; extra == 'dashboard'
Requires-Dist: websockets>=11.0; extra == 'dashboard'
Provides-Extra: dev
Requires-Dist: black>=23; extra == 'dev'
Requires-Dist: click>=8.0; extra == 'dev'
Requires-Dist: httpx>=0.24; extra == 'dev'
Requires-Dist: mypy>=1.5; extra == 'dev'
Requires-Dist: pre-commit>=3; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest-cov>=4; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Provides-Extra: gemini
Requires-Dist: google-generativeai>=0.5; extra == 'gemini'
Provides-Extra: rich
Requires-Dist: rich>=13.0; extra == 'rich'
Description-Content-Type: text/markdown

<div align="center">

<!-- SOCIAL PREVIEW IMAGE PLACEHOLDER -->
<!-- Replace the URL below with your actual repository social preview image or logo -->
<img src="https://via.placeholder.com/800x400/1e1e1e/ffffff?text=stepcast+|+Python+Pipelines" alt="stepcast - Python Pipelines, Narrated" width="800"/>

<br/>

> **Every Python script deserves a voice.**

`stepcast` wraps any Python function in a named, observable step. When a pipeline runs, each step announces itself — label, live output, duration, pass/fail — in the terminal, Colab notebook, or your local web dashboard. 

**Zero required dependencies. Works on every OS. Readable by everyone.**

<br/>

[![PyPI version](https://img.shields.io/pypi/v/stepcast.svg?style=for-the-badge&color=blue)](https://pypi.org/project/stepcast/)
[![Python](https://img.shields.io/pypi/pyversions/stepcast.svg?style=for-the-badge&logo=python&logoColor=white)](https://pypi.org/project/stepcast/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
[![Build Status](https://img.shields.io/github/actions/workflow/status/bosekarmegam/stepcast/ci.yml?style=for-the-badge&logo=github)](https://github.com/bosekarmegam/stepcast/actions)

</div>

<br/>

## 📖 Table of Contents
- [Preview & Presentation](#-preview--presentation)
- [Features](#-features)
- [Installation](#-installation)
- [Quickstart Guide](#-quickstart-guide)
- [Web Dashboard](#-web-dashboard)
- [AI Narration](#-gemini-ai-narration)
- [Documentation & Community](#-documentation--community)

---

## 📸 Preview & Presentation

See `stepcast` in action solving real problems with beautiful observability.

### 1. Terminal Output with `rich` 🖥️
<!-- GIF/Image Placeholder: Show the beautiful rich terminal output running a pipeline -->
> *Replace this with a `.gif` of your terminal running `python examples/data_etl.py`.*
> 
> `![Terminal Preview](docs/assets/terminal_preview.gif)`

### 2. Local Live Dashboard 📊
<!-- GIF/Image Placeholder: Show the web dashboard live streaming -->
> *Replace this with a screenshot of the `stepcast serve` dashboard showing a run history.*
> 
> `![Dashboard Preview](docs/assets/dashboard_preview.png)`

### 3. AI Step Narration 🤖
<!-- GIF/Image Placeholder: Show the AI narration text in terminal -->
> *Replace this with a screenshot showing the `💬` AI narration output.*
> 
> `![AI Narration](docs/assets/ai_narration.png)`

---

## ✨ Features

| Feature | Details |
|---------|---------|
| 📡 **Live output streaming** | Every `print()` inside a step streams to terminal in real time |
| ✅ **Pass / ❌ Fail / ⏭ Skip** | Clear visual status with timing for every step |
| 🔄 **Retry with backoff** | `retries=3, retry_delay=2.0` with exponential backoff |
| ⏱️ **Timeout enforcement** | Per-step timeout raises `StepFailedError` cleanly |
| 💨 **Dry run mode** | Preview all steps without executing anything |
| 🤖 **Gemini AI narration** | Optional: explains what each step did in plain English |
| 🌐 **Local web dashboard** | `stepcast serve` → run history at `localhost:4321` |
| 🐳 **Docker self-hosted** | One command team dashboard (`docker-compose up`) |
| 📓 **Google Colab** | Native auth + save to Drive |
| 🎨 **Rich support** | Beautiful spinners + colour when `rich` is installed |
| 🌍 **i18n ready** | All strings in locale files, community-translated |
| 🔒 **Zero dep core** | Pure stdlib — `pip install stepcast` just works |

---

## � Installation

```bash
# Core library (zero dependencies)
pip install stepcast

# Add beautiful terminal formatting
pip install "stepcast[rich]"

# Add the local web dashboard
pip install "stepcast[dashboard]"

# Add AI narration using Google Gemini
pip install "stepcast[gemini]"

# Install everything!
pip install "stepcast[all]"
```

---

## 🚀 Quickstart Guide

Building an observable pipeline takes seconds:

```python
from stepcast import Pipeline

pipe = Pipeline("My First Pipeline")

@pipe.step("Download data", retries=2)
def download():
    print("Fetching records...")
    return [1, 2, 3]

@pipe.step("Process data")
def process(data: list):
    result = sum(data)
    print(f"Sum = {result}")
    return result

@pipe.step("Save results", skip_if=lambda: False)
def save(total: int):
    print(f"Saving total: {total}")

report = pipe.run()
print(report.summary())
```

**What you see in the terminal:**
```text
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  📡  My First Pipeline
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ▶  Download data...
     → Fetching records...
  ✅  Done  (0.01s)

  ▶  Process data...
     → Sum = 6
  ✅  Done  (0.00s)

  ▶  Save results...
     → Saving total: 6
  ✅  Done  (0.00s)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✅  3 of 3 steps passed   Total: 0.01s
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

---

## 🌐 Web Dashboard

Monitor your runs graphically with the built-in local dashboard!

```bash
stepcast serve
# → Opens http://localhost:4321 automatically
# → Shows your run history, step details, analytics
```

**Stream a live run:**
```python
pipe = Pipeline("ETL Job", dashboard=True)
pipe.run()  # Watch it run live in your browser!
```

---

## 🤖 Gemini AI Narration

`stepcast` can use **Google Gemini 2.5 Flash** to automatically summarize what your code did in plain English. Ideal for long builds or sharing logs with non-technical team members!

```bash
# Get your free key from Google AI Studio
export STEPCAST_GEMINI_API_KEY="AIza..."
```

```python
pipe = Pipeline("Data Cruncher", narrate=True)
# Terminal Output:
#   ▶  Clean Dataset...
#      💬 "The pipeline removed 45 invalid rows and imputed missing values in 1.2s."
#   ✅  Done
```

---

## 🩺 Powerful CLI tools

```bash
stepcast version         # Print installed version
stepcast doctor          # Diagnose your environment (Python, OS, packages, keys)
stepcast config set gemini_api_key YOUR_KEY
stepcast run script.py   # Run a pipeline and ensure proper exit codes
```

---

## � Documentation & Community

Dive deeper into how `stepcast` works:

- 📖 **[Quickstart & Core Concepts](docs/quickstart.md)**
- 📘 **[Full API Reference](docs/api_reference.md)**
- 📊 **[Dashboard Guide](docs/dashboard.md)**
- 🤖 **[AI Narration Setup](docs/gemini_narration.md)**
- 📓 **[Colab Integration](docs/colab_guide.md)**
- 🛡️ **[Security Policy](SECURITY.md)**
- 📝 **[Changelog](CHANGELOG.md)**

### Joining the Project

Contributions are highly welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for branch naming conventions, PR processes, and testing standards. We especially welcome translations for the locale files!

- � [Report a Bug](https://github.com/bosekarmegam/stepcast/issues)
- 💡 [Request a Feature](https://github.com/bosekarmegam/stepcast/discussions)
- 💬 [Ask a Question](https://github.com/bosekarmegam/stepcast/discussions)

---

## 📜 License & Attribution

<div align="center">

Released under the [MIT License](LICENSE) © 2026.

Built with passion for the global Python community by **[Suneel Bose K](https://github.com/bosekarmegam)**.

</div>
