storytime

storytime turns Python execution into human-readable stories and can also execute a constrained narrative DSL.

Status

This is an early MVP. The current implementation focuses on:

• @narrate for traced function execution
• Story and Step models with plain, markdown, JSON, and ELI5 output
• session() for lightweight interactive tracing
• run_story() for a simple narrative DSL
• describe() for semantic hook registration

Install

pip install .

For development:

python3 -m unittest discover -s tests

Quick Start

from storytime import narrate

@narrate(style="markdown")
def process(values):
    total = 0
    for value in values:
        total += value
    return total

story = process([1, 2, 3])
print(story.to_markdown())

DSL Example

from storytime import run_story

story = run_story(
    """
    Start with users
    Keep only active users
    Group by region
    Return the result
    """,
    context={
        "users": [
            {"name": "Ada", "active": True, "region": "US"},
            {"name": "Linus", "active": False, "region": "EU"},
        ]
    },
)

Examples

See examples/basic_usage.py.

Run it from the repository root with:

python3 examples/basic_usage.py

Publish

Manual PyPI publishing from your machine:

python3 -m pip install --upgrade build twine setuptools wheel
python3 -m build
python3 -m twine check dist/*
python3 -m twine upload dist/*

Before uploading:

• make sure the package name is available on PyPI
• run python3 -m unittest discover -s tests
• review the generated files in dist/

Limitations

• Tracing is heuristic and intentionally lightweight
• The DSL is keyword-driven, not general natural language
• Async behavior and deeper semantic analysis are not implemented yet