youread 0.2.0__tar.gz

youread-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guransh Singh (singhDevs)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

youread-0.2.0/MANIFEST.in

@@ -0,0 +1,12 @@
+exclude .env
+exclude .env.*
+global-exclude *.env
+global-exclude *.env.*
+prune api-test
+prune build
+prune dist
+prune doc
+prune output
+prune venv
+prune .claude
+prune .github

youread-0.2.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: youread
+Version: 0.2.0
+Summary: Convert YouTube videos into comprehensive, reading-optimized markdown articles
+Author: Guransh Singh (singhDevs)
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/singhDevs/YouRead
+Project-URL: Issues, https://github.com/singhDevs/YouRead/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Utilities
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: youtube-transcript-api>=0.6.0
+Requires-Dist: google-genai>=1.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: openai==2.16.0
+Dynamic: license-file
+
+# YouRead
+
+Turn a YouTube video into a readable Markdown article.
+
+Built for people who prefer reading over watching, who got 100s of youtube tabs opened but none watched — technical talks, podcasts, discussions. It goes beyond summaries; the goal is an article detailed enough that you usually don't need to watch the video.
+
+
+## Quick Start
+
+```bash
+pip install .
+youread config set --provider openai --set-api-key
+youread run "https://youtube.com/watch?v=VIDEO_ID"
+```
+
+## Install
+
+Requires Python 3.10+.
+
+```bash
+pip install .
+# or for development:
+pip install -e .
+```
+
+## Configure
+
+YouRead supports OpenAI and Gemini. Defaults:
+
+```yaml
+llm:
+  provider: openai
+  model: gpt-5
+  max_tokens: 8000
+  temperature: 0.3
+output:
+  directory: ./output
+processing:
+  remove_sponsors: true
+```
+
+```bash
+# set provider + model
+youread config set --provider openai --model gpt-5
+# set API key (secure prompt, no echo)
+youread config set --set-api-key
+# view current config
+youread config show
+# check if active provider has a key
+youread config check
+```
+
+Provider/model pairs are validated at save time — `--provider gemini --model gpt-5` is rejected immediately.
+
+## Usage
+
+```bash
+youread run "https://youtube.com/watch?v=VIDEO_ID"
+
+# with options
+youread run "URL" --mode detailed
+youread run "URL" --prompt "Focus on code examples"
+youread run "URL" --model gemini-2.5-flash
+youread run "URL" --no-sponsorblock
+```
+
+| Flag | What it does |
+|------|-------------|
+| `--mode summary\|standard\|detailed` | Article depth (default: standard) |
+| `--prompt "..."` | Custom instructions appended to the system prompt |
+| `--model <name>` | Override configured model for one run |
+| `--no-sponsorblock` | Skip sponsor segment removal |
+
+Output goes to the configured directory (`./output` by default). After generation, YouRead asks whether to open the file.
+
+## Supported Providers
+
+| Provider | Example Model | Env variable |
+|----------|---------------|-------------|
+| OpenAI | `gpt-5` | `OPENAI_API_KEY` |
+| Gemini | `gemini-2.5-flash` | `GEMINI_API_KEY` |
+
+## Limitations
+
+YouRead is transcript-only. It doesn't see video frames, slides, or code on screen.
+
+| Situation | Outcome |
+|-----------|---------|
+| No transcript | Can't process |
+| Auto-generated captions | Quality suffers |
+| Visual-heavy content | Details missed |
+| Code not spoken | Won't appear |
+| Non-English video | English captions only |
+
+For best results, use videos where the speaker explains things verbally.
+
+## Troubleshooting
+
+**`No API key found`** — `youread config check` then `youread config set --set-api-key`.
+
+**`Provider mismatch`** — You paired `--provider gemini` with `--model gpt-5`. Use matching pairs: `openai` + `gpt-5`, `gemini` + `gemini-2.5-flash`.
+
+**`No transcript available`** — Video has no accessible captions.

youread-0.2.0/README.md

@@ -0,0 +1,103 @@
+# YouRead
+
+Turn a YouTube video into a readable Markdown article.
+
+Built for people who prefer reading over watching, who got 100s of youtube tabs opened but none watched — technical talks, podcasts, discussions. It goes beyond summaries; the goal is an article detailed enough that you usually don't need to watch the video.
+
+
+## Quick Start
+
+```bash
+pip install .
+youread config set --provider openai --set-api-key
+youread run "https://youtube.com/watch?v=VIDEO_ID"
+```
+
+## Install
+
+Requires Python 3.10+.
+
+```bash
+pip install .
+# or for development:
+pip install -e .
+```
+
+## Configure
+
+YouRead supports OpenAI and Gemini. Defaults:
+
+```yaml
+llm:
+  provider: openai
+  model: gpt-5
+  max_tokens: 8000
+  temperature: 0.3
+output:
+  directory: ./output
+processing:
+  remove_sponsors: true
+```
+
+```bash
+# set provider + model
+youread config set --provider openai --model gpt-5
+# set API key (secure prompt, no echo)
+youread config set --set-api-key
+# view current config
+youread config show
+# check if active provider has a key
+youread config check
+```
+
+Provider/model pairs are validated at save time — `--provider gemini --model gpt-5` is rejected immediately.
+
+## Usage
+
+```bash
+youread run "https://youtube.com/watch?v=VIDEO_ID"
+
+# with options
+youread run "URL" --mode detailed
+youread run "URL" --prompt "Focus on code examples"
+youread run "URL" --model gemini-2.5-flash
+youread run "URL" --no-sponsorblock
+```
+
+| Flag | What it does |
+|------|-------------|
+| `--mode summary\|standard\|detailed` | Article depth (default: standard) |
+| `--prompt "..."` | Custom instructions appended to the system prompt |
+| `--model <name>` | Override configured model for one run |
+| `--no-sponsorblock` | Skip sponsor segment removal |
+
+Output goes to the configured directory (`./output` by default). After generation, YouRead asks whether to open the file.
+
+## Supported Providers
+
+| Provider | Example Model | Env variable |
+|----------|---------------|-------------|
+| OpenAI | `gpt-5` | `OPENAI_API_KEY` |
+| Gemini | `gemini-2.5-flash` | `GEMINI_API_KEY` |
+
+## Limitations
+
+YouRead is transcript-only. It doesn't see video frames, slides, or code on screen.
+
+| Situation | Outcome |
+|-----------|---------|
+| No transcript | Can't process |
+| Auto-generated captions | Quality suffers |
+| Visual-heavy content | Details missed |
+| Code not spoken | Won't appear |
+| Non-English video | English captions only |
+
+For best results, use videos where the speaker explains things verbally.
+
+## Troubleshooting
+
+**`No API key found`** — `youread config check` then `youread config set --set-api-key`.
+
+**`Provider mismatch`** — You paired `--provider gemini` with `--model gpt-5`. Use matching pairs: `openai` + `gpt-5`, `gemini` + `gemini-2.5-flash`.
+
+**`No transcript available`** — Video has no accessible captions.

youread-0.2.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "youread"
+version = "0.2.0"
+description = "Convert YouTube videos into comprehensive, reading-optimized markdown articles"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [
+    {name = "Guransh Singh (singhDevs)"},
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Operating System :: OS Independent",
+    "Topic :: Utilities",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+dependencies = [
+    "youtube-transcript-api>=0.6.0",
+    "google-genai>=1.0.0",
+    "python-dotenv>=1.0.0",
+    "pyyaml>=6.0",
+    "typer>=0.9.0",
+    "rich>=13.0.0",
+    "openai==2.16.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/singhDevs/YouRead"
+Issues = "https://github.com/singhDevs/YouRead/issues"
+
+[project.scripts]
+youread = "youread.main:app"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+youread = ["config/settings.yaml", "prompts/*.md", "prompts/modes/*.md"]

youread-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

youread-0.2.0/src/youread/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

youread-0.2.0/src/youread/article_generator.py

@@ -0,0 +1,201 @@
+"""Article generation using LLM providers."""
+
+import math
+
+from pathlib import Path
+from typing import Optional, Literal
+from importlib.resources import files
+
+from .models import VideoInfo
+from .providers import call_llm
+
+
+# Valid mode choices
+ArticleMode = Literal["summary", "standard", "detailed"]
+
+# Reading speed for technical content (words per minute)
+# 150 WPM is realistic for technical/educational material requiring comprehension
+TECHNICAL_WPM = 150
+
+
+def calculate_reading_time(text: str, wpm: int = TECHNICAL_WPM) -> str:
+    """Calculate reading time from text content.
+
+    Args:
+        text: The article text to measure.
+        wpm: Words per minute reading speed.
+
+    Returns:
+        Formatted reading time string (e.g., "~5 min read").
+    """
+    # Count words (split on whitespace)
+    word_count = len(text.split())
+
+    # Calculate minutes, round up to nearest minute
+    minutes = math.ceil(word_count / wpm)
+
+    return f"~{minutes} min read"
+
+
+def insert_reading_time(article: str) -> str:
+    """Replace the reading time placeholder with calculated reading time.
+
+    Args:
+        article: The generated article with READING_TIME_PLACEHOLDER.
+
+    Returns:
+        Article with accurate reading time inserted.
+    """
+    reading_time = calculate_reading_time(article)
+    return article.replace("READING_TIME_PLACEHOLDER", reading_time)
+
+
+def load_prompt(prompt_path: Optional[Path] = None) -> str:
+    """Load a prompt from file.
+
+    Args:
+        prompt_path: Path to the prompt file. Defaults to prompts/system_prompt_v2.md.
+
+    Returns:
+        The prompt content as a string.
+    """
+    if prompt_path is None:
+        prompt_path = files("youread.prompts") / "system_prompt_v2.md"
+
+    if hasattr(prompt_path, 'read_text'):
+        return prompt_path.read_text(encoding="utf-8")
+
+    path = Path(prompt_path)
+    if not path.exists():
+        raise FileNotFoundError(f"Prompt file not found: {prompt_path}")
+
+    return path.read_text(encoding="utf-8")
+
+
+def load_mode_prompt(mode: ArticleMode) -> str:
+    """Load the mode-specific prompt fragment.
+
+    Args:
+        mode: The article generation mode (summary, standard, detailed).
+
+    Returns:
+        The mode prompt content as a string.
+    """
+    mode_path = files("youread.prompts.modes") / f"{mode}.md"
+
+    if hasattr(mode_path, 'read_text'):
+        return mode_path.read_text(encoding="utf-8")
+
+    path = Path(mode_path)
+    if not path.exists():
+        raise FileNotFoundError(f"Mode prompt file not found: {mode_path}")
+
+    return path.read_text(encoding="utf-8")
+
+
+def compose_system_prompt(
+    mode: ArticleMode = "standard",
+    custom_prompt: Optional[str] = None,
+    video_id: Optional[str] = None,
+) -> str:
+    """Compose the full system prompt from base + mode + custom.
+
+    Args:
+        mode: The article generation mode.
+        custom_prompt: Optional user-provided custom instructions.
+        video_id: Optional video ID for constructing the source URL.
+
+    Returns:
+        The composed system prompt.
+    """
+    # Load base prompt
+    base_prompt = load_prompt()
+
+    # Load mode-specific instructions
+    mode_instructions = load_mode_prompt(mode)
+
+    # Replace the mode placeholder
+    prompt = base_prompt.replace("{{MODE_INSTRUCTIONS}}", mode_instructions)
+
+    # Replace video URL placeholder if video_id provided
+    if video_id:
+        video_url = f"https://youtube.com/watch?v={video_id}"
+        prompt = prompt.replace("VIDEO_URL_PLACEHOLDER", video_url)
+
+    # Append custom prompt if provided
+    if custom_prompt:
+        custom_section = f"""
+<custom_instructions>
+The user has provided the following additional instructions. Follow them while maintaining the core quality standards:
+
+{custom_prompt}
+</custom_instructions>
+"""
+        prompt += custom_section
+
+    return prompt
+
+
+def generate_article(
+    transcript_text: str,
+    video_info: VideoInfo,
+    provider: str,
+    api_key: str,
+    video_id: Optional[str] = None,
+    model: str = "gpt-5",
+    max_tokens: int = 8000,
+    temperature: float = 0.3,
+    mode: ArticleMode = "standard",
+    custom_prompt: Optional[str] = None,
+) -> str:
+    """Generate a readable article from a video transcript.
+
+    Args:
+        transcript_text: The full transcript text.
+        video_info: Video metadata (title, channel).
+        provider: LLM provider name (e.g., "openai", "gemini").
+        api_key: API key for the provider.
+        video_id: Video ID for source link.
+        model: Model identifier to use.
+        max_tokens: Maximum tokens in the response.
+        temperature: Sampling temperature (0.0-1.0).
+        mode: Article generation mode (summary, standard, detailed).
+        custom_prompt: Optional custom instructions from user.
+
+    Returns:
+        The generated article as markdown text.
+
+    Raises:
+        Exception: If the API call fails.
+    """
+    # Compose the system prompt
+    system_prompt = compose_system_prompt(
+        mode=mode,
+        custom_prompt=custom_prompt,
+        video_id=video_id,
+    )
+
+    # Build the user prompt with context
+    user_prompt = f"""## Video Information
+**Title:** {video_info.title}
+**Channel:** {video_info.channel}
+
+## Transcript
+{transcript_text}
+"""
+
+    # Generate the article via provider dispatch
+    raw_response = call_llm(
+        provider=provider,
+        api_key=api_key,
+        model=model,
+        system_prompt=system_prompt,
+        user_prompt=user_prompt,
+        max_tokens=max_tokens,
+        temperature=temperature,
+    )
+
+    # Calculate and insert accurate reading time
+    article = insert_reading_time(raw_response)
+
+    return article

youread-0.2.0/src/youread/config/settings.yaml

@@ -0,0 +1,9 @@
+llm:
+  provider: openai
+  model: gpt-5
+  max_tokens: 8000
+  temperature: 0.3
+output:
+  directory: ./output
+processing:
+  remove_sponsors: true

youread-0.2.0/src/youread/exceptions.py

@@ -0,0 +1,45 @@
+"""Custom exceptions for YouRead."""
+
+
+class YouReadError(Exception):
+    """Base exception for all YouRead errors."""
+    pass
+
+
+class InvalidURLError(YouReadError):
+    def __init__(self, url: str) -> None:
+        self.url = url
+        super().__init__(f"Invalid YouTube URL: {url}")
+
+
+class TranscriptNotFoundError(YouReadError):
+    def __init__(self, video_id: str) -> None:
+        self.video_id = video_id
+        super().__init__(f"No transcript available for video: {video_id}")
+
+
+class VideoNotFoundError(YouReadError):
+    def __init__(self, video_id: str) -> None:
+        self.video_id = video_id
+        super().__init__(f"Video not found or unavailable: {video_id}")
+
+
+class UnsupportedProviderError(YouReadError):
+    def __init__(self, provider: str, supported: list[str]) -> None:
+        self.provider = provider
+        self.supported = supported
+        super().__init__(
+            f"Unsupported provider '{provider}'. "
+            f"Supported: {', '.join(supported)}"
+        )
+
+
+class APIKeyMissingError(YouReadError):
+    def __init__(self, provider: str) -> None:
+        self.provider = provider
+        env_var = f"{provider.upper()}_API_KEY"
+        super().__init__(
+            f"API key for '{provider}' not found. "
+            f"Save {env_var} to YouRead's managed .env file, or use: "
+            f"youread config set --provider {provider} --set-api-key"
+        )