Metadata-Version: 2.4
Name: tadalabz-storytime
Version: 1.0.0
Summary: Turn Python execution into structured human-readable stories.
Author-email: tadalabz@gmail.com
License-Expression: LicenseRef-Storytime-License-1.0
Keywords: python,tracing,explainability,dsl,narrative
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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

```bash
pip install .
```

For development:

```bash
python3 -m unittest discover -s tests
```

## Quick Start

```python
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

```python
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`](examples/basic_usage.py).

Run it from the repository root with:

```bash
python3 examples/basic_usage.py
```

## Publish

Manual PyPI publishing from your machine:

```bash
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
