stepcast 1.0.1

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

� 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