Metadata-Version: 2.4
Name: code-storyteller
Version: 0.1.0
Summary: Explain code like a story — with analogies, characters, and narrative
Project-URL: Homepage, https://github.com/brijesh-jakkuva/code-storyteller
Project-URL: Repository, https://github.com/brijesh-jakkuva/code-storyteller
Project-URL: Issues, https://github.com/brijesh-jakkuva/code-storyteller/issues
Author-email: Brijesh Kumar Jakkuva <brijeshjakkuva@gmail.com>
License: MIT
License-File: LICENSE
Keywords: anthropic,cli,code-analysis,code-explanation,developer-tools,llm,openrouter,storytelling,tree-sitter
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.34
Requires-Dist: click>=8.1
Requires-Dist: rich>=13.7
Requires-Dist: tree-sitter-go>=0.23
Requires-Dist: tree-sitter-java>=0.23
Requires-Dist: tree-sitter-javascript>=0.23
Requires-Dist: tree-sitter-python>=0.23
Requires-Dist: tree-sitter-rust>=0.23
Requires-Dist: tree-sitter-typescript>=0.23
Requires-Dist: tree-sitter>=0.23
Provides-Extra: export
Requires-Dist: pdf2image>=1.17; extra == 'export'
Requires-Dist: weasyprint>=60; extra == 'export'
Provides-Extra: web
Requires-Dist: fastapi>=0.110; extra == 'web'
Requires-Dist: python-multipart>=0.0.9; extra == 'web'
Requires-Dist: uvicorn>=0.27; extra == 'web'
Description-Content-Type: text/markdown

# 🎬 Code Storyteller

Explain code like a story — with analogies, characters, and narrative.

## Install

```bash
pip install -e .
```

## Setup

```bash
export ANTHROPIC_API_KEY=sk-...
# or for OpenRouter:
export OPENROUTER_API_KEY=sk-or-...
export MODEL=open_router/nvidia/nemotron-3-super-120b-a12b:free
```

## Usage

```bash
# Tell a story about a file
storytell tell auth.py --as heist
storytell tell sort.py --as recipe
storytell tell api.js --as 5yo
storytell tell handler.ts --as pm

# Specific function/class only
storytell tell auth.py --as heist --block validate_token

# Diff — narrate changes between two file versions
storytell diff old.py new.py --as heist

# Explore blocks in a file
storytell explore auth.py

# ASCII structure map
storytell map auth.py

# List styles
storytell styles

# View history (with star ratings)
storytell history

# Rate a past story (1-5)
storytell rate 42 5

# Save an analogy
storytell learn recursion "a story that tells itself"

# View saved analogies
storytell memory
```

## Styles

| Style | Description |
|-------|-------------|
| `heist` | Code as a bank heist movie |
| `recipe` | Code as a cooking recipe |
| `5yo` | Explain like you're 5 years old |
| `pm` | Explain like a product manager |
| `sports` | Code as live sports commentary |

## Options

- `--no-stream` — disable streaming output
- `--block <name>` — target specific function/class
- `--as <style>` — pick story style (default: heist)

## Supported Languages

- Python (`.py`)
- JavaScript (`.js`, `.jsx`)
- TypeScript (`.ts`, `.tsx`)

## Tests

```bash
python3 -m pytest tests/ -v
# 25 tests passing
```

## Usage (continued)

```bash
# Export story as styled PDF/PNG/HTML card
storytell card auth.py --as heist --format pdf
storytell card auth.py --as recipe --format html

# Multi-file project stories
storytell tell ./src/ --as heist
storytell tell ./src/ --as pm --focus main.py

# Launch web dashboard
storytell serve --port 8100
```

Install optional dependencies:

```bash
pip install code-storyteller[export]   # PDF/PNG card export
pip install code-storyteller[web]      # Web dashboard
```

## VS Code Extension

See `vscode/`. Install CLI first, then:

```bash
cd vscode && npm install && npm run compile
# Press F5 in VS Code to launch Extension Development Host
```

## GitHub Action

See `action.yml` and `.github/workflows/storyteller-example.yml`.

## Roadmap

- [x] CLI with 5 story styles
- [x] Code parser (Python, JS, TS) with tree-sitter
- [x] SQLite memory + history
- [x] Diff stories (narrate code changes)
- [x] Rate stories + analogy memory
- [x] ASCII code map
- [x] Story card image export
- [x] VS Code extension
- [x] GitHub Action
- [x] Web dashboard
- [x] Multi-file / project stories
