hamel-tools 0.2.0

CLI tools for YouTube transcripts, chapters, and annotated talks

hamel_tools

CLI tools that wrap the hamel Python library for working with YouTube videos and generating content.

Installation

# Install in development mode
pip install -e .

# Or using the Makefile
make install-dev

This installs three CLI commands:

• ai-transcribe - Download YouTube transcripts
• ai-chapters - Generate YouTube chapter summaries
• ai-annotate-talk - Create annotated blog posts from technical talks

Usage

Transcript Tool

# Download transcript with timestamps
ai-transcribe "https://youtu.be/VIDEO_ID"

# Use seconds-only timestamps
ai-transcribe "https://youtu.be/VIDEO_ID" --seconds

# Save to file
ai-transcribe "https://youtu.be/VIDEO_ID" > transcript.txt

Chapter Generator

# Generate chapters (requires GEMINI_API_KEY)
export GEMINI_API_KEY="your-api-key"
ai-chapters "https://youtu.be/VIDEO_ID"

Annotated Talk Generator

# Generate annotated blog post (requires both API keys)
export GEMINI_API_KEY="your-api-key"
export JINA_READER_KEY="your-api-key"

# Basic usage
ai-annotate-talk "https://youtu.be/VIDEO_ID" slides.pdf output_images/

# With custom transcript
ai-annotate-talk "https://youtu.be/VIDEO_ID" slides.pdf output_images/ --transcript transcript.txt

# Save to file
ai-annotate-talk "https://youtu.be/VIDEO_ID" slides.pdf output_images/ --output post.md

Prerequisites

For annotate-talk, you need poppler-utils:

# macOS
brew install poppler

# Ubuntu/Debian
apt-get install poppler-utils

Development

Running Tests

./test.sh

Version Management

The Makefile includes version bump commands that update both pyproject.toml and __init__.py:

# Bump versions
make bump-patch     # 0.1.0 -> 0.1.1
make bump-minor     # 0.1.0 -> 0.2.0  
make bump-major     # 0.1.0 -> 1.0.0

# Create a release (bump + git tag)
make release-patch  # Bumps patch and tags
make release-minor  # Bumps minor and tags
make release-major  # Bumps major and tags

Publishing to PyPI

Setup

1. Install publishing tools:

   make install-publish-tools
   

2. Configure twine (see .pypirc.example):

   cp .pypirc.example ~/.pypirc
   # Edit ~/.pypirc with your PyPI tokens
   

Release Workflow

# 1. Create a release
make release-minor  # or release-patch, release-major

# 2. Push to GitHub
git push && git push --tags

# 3. Build and check
make check

# 4. Upload to PyPI
make test-upload  # Test first
make upload       # Then production

The Makefile uses twine for secure uploads and includes:

• make check - Validates distributions before upload
• make test-upload - Tests on TestPyPI first
• make upload - Publishes to PyPI with confirmation prompt

Architecture

Each tool is implemented as a Typer CLI application that wraps functionality from the hamel library:

• transcribe.py → hamel.yt.transcribe()
• chapters.py → hamel.yt.yt_chapters()
• annotate_talk.py → hamel.writing.generate_annotated_talk_post()

The tools follow a consistent pattern using Typer's app decorator approach without if __name__ == "__main__" blocks.