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.
- Preview & Presentation
- Features
- Installation
- Quickstart Guide
- Web Dashboard
- AI Narration
- Documentation & Community
See stepcast in action solving real problems with beautiful observability.
Replace this with a
.gifof your terminal runningpython examples/data_etl.py.
Replace this with a screenshot of the
stepcast servedashboard showing a run history.
Replace this with a screenshot showing the
💬AI narration output.
| 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 |
# 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]"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
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Monitor your runs graphically with the built-in local dashboard!
stepcast serve
# → Opens http://localhost:4321 automatically
# → Shows your run history, step details, analyticsStream a live run:
pipe = Pipeline("ETL Job", dashboard=True)
pipe.run() # Watch it run live in your browser!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."
# ✅ Donestepcast 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 codesDive deeper into how stepcast works:
- 📖 Quickstart & Core Concepts
- 📘 Full API Reference
- 📊 Dashboard Guide
- 🤖 AI Narration Setup
- 📓 Colab Integration
- 🛡️ Security Policy
- 📝 Changelog
Contributions are highly welcome! See CONTRIBUTING.md for branch naming conventions, PR processes, and testing standards. We especially welcome translations for the locale files!
Released under the MIT License © 2026.
Built with passion for the global Python community by Suneel Bose K.