Metadata-Version: 2.4
Name: chalk-pypi
Version: 0.2.2
Summary: Explains lecture slides using Claude. For when you have the slides but not the lecture.
Author: fadli0029
Author-email: fadli0029 <fadlialim0029@gmail.com>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Education
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Dist: anthropic>=0.84.0
Requires-Dist: pymupdf>=1.27.1
Requires-Python: >=3.12
Project-URL: Repository, https://github.com/fadli0029/chalk
Project-URL: Issues, https://github.com/fadli0029/chalk/issues
Description-Content-Type: text/markdown

# chalk

When self-studying university courses (e.g. CMU 15-411, MIT 6.1810), you often
get lecture slides but no lecture videos. The slides alone are rarely
self-contained: professors design them as visual aids for a spoken lecture, not
as standalone reading material. So you scroll through a PDF, hit a slide you
don't understand, and have no way to hear the explanation that was supposed to
go with it.

chalk fills that gap. Point it at a lecture PDF, tell it which slides you're
stuck on, and it generates a professor-style explanation. It reads all prior
slides for context (not just the ones you asked about), so it understands the
narrative arc of the lecture before explaining your target slides.

## Two ways to use it

### Claude Code (recommended)

If you use [Claude Code](https://docs.anthropic.com/en/docs/claude-code),
the `/slides` skill lets Claude read the slide images directly, no API key
needed:

```
/slides lecture.pdf 15
/slides lecture.pdf 10-15
/slides lecture.pdf 3,7,12 What is the connection between these three slides?
```

This extracts pages 1 through the last requested page as PNGs, loads them
into Claude's context, and explains the target slides with full awareness of
everything that came before.

To make `/slides` available:

```sh
chalk --install-skill
```

### Standalone CLI

For terminal use without Claude Code. Requires an
[Anthropic API key](https://console.anthropic.com/):

```sh
export ANTHROPIC_API_KEY="sk-ant-..."

chalk lecture.pdf 15
chalk lecture.pdf 3-7
chalk lecture.pdf 1,3,5
chalk lecture.pdf 1-3,5,7-9
```

The CLI sends all slides from page 1 through your last requested page to
Claude's vision API and streams the explanation to stdout.

Options:

```
--model MODEL       Claude model to use (default: claude-sonnet-4-6)
--prompt PROMPT     Custom prompt (default: "Explain these slides.")
--max-tokens N      Maximum tokens in the response (default: 8192)
```

Examples:

```sh
chalk lecture.pdf 12 --prompt "Summarize the key equations on this slide."
chalk lecture.pdf 1-10 --max-tokens 16384
```

## Installation

Requires Python 3.12+.

```sh
# From PyPI
pip install chalk-pypi
# or
uv tool install chalk-pypi

# From source
uv tool install git+https://github.com/fadli0029/chalk.git
```

## Development

```sh
git clone https://github.com/fadli0029/chalk.git
cd chalk
uv sync

# Run quality checks
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/
uv run mypy
uv run pytest
```

## License

MIT. See [LICENSE](LICENSE).
