stepcast 1.0.0

Every Python script deserves a voice. Transparent, narrated pipeline execution.

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.

📖 Table of Contents

• Preview & Presentation
• Features
• Installation
• Quickstart Guide
• Web Dashboard
• AI Narration
• Documentation & Community

---

📸 Preview & Presentation

See stepcast in action solving real problems with beautiful observability.

1. Terminal Output with rich 🖥️

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 📊

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 🤖

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

# 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:

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:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  📡  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!

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

Stream a live run:

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!

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

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

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
• 📘 Full API Reference
• 📊 Dashboard Guide
• 🤖 AI Narration Setup
• 📓 Colab Integration
• 🛡️ Security Policy
• 📝 Changelog

Joining the Project

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

• � Report a Bug
• 💡 Request a Feature
• 💬 Ask a Question

---

📜 License & Attribution

Released under the MIT License © 2026.

Built with passion for the global Python community by Suneel Bose K.