vink 0.1.0__tar.gz

vink-0.1.0/.env.example

@@ -0,0 +1,24 @@
+# Copy to .env and adjust. Every setting is optional.
+# See docs/configuration.md for details.
+
+# Preferred transcript languages, in order (comma-separated language codes).
+VINK_LANGUAGES=en
+
+# Fall back to YouTube's machine translation when no track matches.
+VINK_ALLOW_TRANSLATION=true
+
+# Where generated Markdown files are written.
+VINK_OUTPUT_DIR=output
+
+# Local transcript cache. Leave unset to use the platform's user cache directory.
+# VINK_CACHE_DIR=
+VINK_USE_CACHE=true
+
+# Target length of one chunk, in seconds (used by the MCP get_chunk tool).
+VINK_CHUNK_SECONDS=600
+
+# Network timeout for metadata requests, in seconds.
+VINK_HTTP_TIMEOUT=10
+
+# DEBUG, INFO, WARNING, or ERROR.
+VINK_LOG_LEVEL=WARNING

vink-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,37 @@
+name: Bug report
+description: Something does not work as expected
+labels: [bug]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: What did you expect, and what happened instead?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: The exact command or MCP tool call, and the video URL if it is public.
+      placeholder: uv run vink transcript https://youtu.be/... --lang hi
+    validations:
+      required: true
+  - type: textarea
+    id: output
+    attributes:
+      label: Error output
+      description: Run with `-v` and paste the full output.
+      render: text
+  - type: input
+    id: version
+    attributes:
+      label: vink version
+      placeholder: output of `vink --version`
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: OS and Python version
+      placeholder: macOS 15, Python 3.12

vink-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability
+    about: Please report security issues privately, not as public issues.

vink-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,28 @@
+name: Feature request
+description: Suggest a new capability, format, destination or note style
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What are you trying to do that vink does not support today?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: How would you like it to work? Example commands or output help.
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Transcript source / languages
+        - Output format
+        - Destination (Notion, Obsidian, ...)
+        - Note style / prompts
+        - CLI
+        - MCP server
+        - Other

vink-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,18 @@
+## What
+
+<!-- What does this change do? -->
+
+## Why
+
+<!-- What problem does it solve? Link the issue: Closes #123 -->
+
+## How to test
+
+<!-- Commands or steps a reviewer can run. -->
+
+## Checklist
+
+- [ ] `ruff format`, `ruff check`, `mypy` and `pytest` pass locally
+- [ ] Tests added or updated for new behavior
+- [ ] `CHANGELOG.md` updated under `[Unreleased]` (if user-visible)
+- [ ] Docs updated (README / `docs/`) for new options or behavior

vink-0.1.0/.github/dependabot.yml

@@ -0,0 +1,14 @@
+version: 2
+updates:
+  # youtube-transcript-api tracks YouTube internals; stay current.
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      dev-tools:
+        dependency-type: development
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly

vink-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,62 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    # Weekly run of the live YouTube tests to catch upstream breakage early.
+    - cron: "0 6 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  checks:
+    name: Lint and type check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+      - run: uv sync --locked
+      - run: uv run ruff format --check .
+      - run: uv run ruff check .
+      - run: uv run mypy
+
+  test:
+    name: Test (Python ${{ matrix.python-version }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+        include:
+          - os: macos-latest
+            python-version: "3.12"
+          - os: windows-latest
+            python-version: "3.12"
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --locked
+      - run: uv run pytest --cov --cov-report=term-missing
+
+  integration:
+    name: Live YouTube tests
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    # Cloud runner IPs are sometimes blocked by YouTube; don't fail the workflow for that.
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+      - run: uv sync --locked
+      - run: uv run pytest -m integration

vink-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,50 @@
+name: Release
+
+# Publishes to PyPI when a version tag (e.g. v0.1.0) is pushed.
+# Uses PyPI trusted publishing (OIDC): no API token is stored in GitHub.
+# One-time setup is described in docs/releasing.md.
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+      - name: Check tag matches package version
+        run: |
+          version=$(uv version --short)
+          if [ "v${version}" != "${GITHUB_REF_NAME}" ]; then
+            echo "Tag ${GITHUB_REF_NAME} does not match pyproject version ${version}" >&2
+            exit 1
+          fi
+      - run: uv sync --locked
+      - run: uv run pytest
+      - run: uv build
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/vink/
+    permissions:
+      id-token: write # required for trusted publishing
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3

vink-0.1.0/.gitignore

@@ -0,0 +1,51 @@
+# ---------------------------------------------------------------------------
+# Internal
+# ---------------------------------------------------------------------------
+# Team engineering standards
+standards/
+
+# ---------------------------------------------------------------------------
+# Python
+# ---------------------------------------------------------------------------
+__pycache__/
+*.py[cod]
+*.so
+*.egg-info/
+.eggs/
+build/
+dist/
+wheels/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Tooling caches
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# ---------------------------------------------------------------------------
+# Project runtime data
+# ---------------------------------------------------------------------------
+# Local transcript cache and generated output
+.vink-cache/
+output/
+
+# Secrets and local config
+.env
+.env.*
+!.env.example
+
+# ---------------------------------------------------------------------------
+# Editors / OS
+# ---------------------------------------------------------------------------
+.vscode/
+.idea/
+*.swp
+.DS_Store

vink-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+# Runs the same checks as CI before each commit.
+# Install once with: uv run pre-commit install
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-format
+        name: ruff format
+        entry: uv run ruff format
+        language: system
+        types: [python]
+      - id: ruff-check
+        name: ruff check
+        entry: uv run ruff check --fix
+        language: system
+        types: [python]
+      - id: mypy
+        name: mypy
+        entry: uv run mypy
+        language: system
+        types: [python]
+        pass_filenames: false

vink-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

vink-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-14
+
+### Added
+
+- `vink transcript` command: fetch a YouTube transcript and save it as Markdown
+  with YAML front matter and clickable timestamps, or print it with `--stdout`.
+- `vink languages` command: list the caption tracks available for a video.
+- Language preferences with fallback (`--lang hi,en`), the special value
+  `original` for the spoken language, and optional YouTube machine translation.
+- Cleaning of caption text into readable paragraphs: sound cues removed,
+  fragments merged, speaker changes and pauses respected.
+- Local transcript cache.
+- MCP server (`vink mcp`) with tools `list_languages`, `get_video_info`,
+  `get_chunk`, `get_transcript`, `save_transcript` and `save_notes`, and a
+  `make_notes` prompt with `detailed-notes` and `clean-transcript` styles.
+- Configuration through `VINK_*` environment variables or a `.env` file.
+- Distribution on PyPI (`uv tool install vink`, `uvx vink mcp`).
+
+[Unreleased]: https://github.com/navinbhagat322/youtube-vink/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/navinbhagat322/youtube-vink/releases/tag/v0.1.0

vink-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,22 @@
+# Code of Conduct
+
+This project adopts the
+[Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/)
+as its code of conduct.
+
+In short: be respectful, assume good intent, welcome newcomers, and keep
+discussion focused on the work. Harassment, personal attacks and
+discriminatory language are not tolerated in any project space: issues, pull
+requests, discussions or chat.
+
+## Reporting
+
+If you experience or witness unacceptable behavior, contact the maintainers
+privately through the contact listed on the repository's GitHub profile, or by
+opening a private security advisory if no other channel is available. All
+reports are reviewed promptly and handled confidentially.
+
+Maintainers may remove, edit or reject contributions that violate this code of
+conduct, and may temporarily or permanently ban contributors for repeated or
+serious violations, following the enforcement guidelines of the Contributor
+Covenant.

vink-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,111 @@
+# Contributing to vink
+
+Thanks for helping. This guide covers setup, the development workflow, and
+the conventions every change follows.
+
+## Development setup
+
+You need Python 3.11+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/navinbhagat322/youtube-vink.git
+cd youtube-vink
+uv sync                      # creates .venv with runtime + dev dependencies
+uv run pre-commit install    # runs format, lint and type checks before each commit
+```
+
+## Running checks
+
+Run the same checks CI runs:
+
+```bash
+uv run ruff format --check .
+uv run ruff check .
+uv run mypy
+uv run pytest --cov
+```
+
+Tests that call real YouTube are excluded by default. Run them with:
+
+```bash
+uv run pytest -m integration
+```
+
+## Project layout
+
+```
+src/vink/
+├── domain/       # immutable models and errors (no I/O, no third-party imports)
+├── ports/        # Protocol interfaces the core depends on
+├── processing/   # pure functions: track selection, cleaning, paragraphs, chunks
+├── services/     # use cases that orchestrate ports and processing
+├── adapters/     # implementations: YouTube, cache, Markdown, local files
+├── interfaces/   # entry points: CLI and MCP server
+├── styles/       # note-style prompt templates (Markdown files)
+├── bootstrap.py  # wires adapters into services
+└── config.py     # typed settings
+```
+
+Read [docs/architecture.md](docs/architecture.md) before making structural
+changes. The key rule is that dependencies point inward: services depend on
+ports, never on adapters.
+
+## Common changes
+
+**Add an output format** (e.g. PDF): implement the `Renderer` protocol in
+`src/vink/adapters/render/`, register it in `bootstrap.py`, and add a golden
+file test in `tests/unit/adapters/`.
+
+**Add a destination** (e.g. Notion): implement the `Sink` protocol in
+`src/vink/adapters/sinks/` and wire it in `bootstrap.py`. Put heavy
+dependencies in an optional extra (`vink[notion]`) and import them inside the
+adapter.
+
+**Add a note style**: add a Markdown file to `src/vink/styles/`. It is
+discovered automatically. Use `{output_language}` where the target language
+belongs.
+
+## Conventions
+
+- **Style:** PEP 8 via `ruff format`, line length 100, Google-style docstrings
+  on all public code, full type hints (`mypy --strict`).
+- **Errors:** raise errors from `vink.domain.errors`. Adapters convert library
+  exceptions with `raise ... from exc`. Messages should tell the user what to
+  do next.
+- **Logging:** `logging.getLogger(__name__)`, never `print()`. Nothing may
+  write to stdout from the MCP server.
+- **Tests:** unit tests never touch the network. Use the fakes in
+  `tests/fakes.py`. Every bug fix starts with a failing test.
+
+## Commits and pull requests
+
+We use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/):
+
+```
+feat(youtube): fall back to auto-generated captions
+fix(processing): keep Devanagari punctuation when merging segments
+docs: explain MCP setup on Windows
+```
+
+Scopes follow the architecture: `domain`, `processing`, `services`, `youtube`,
+`cache`, `render`, `sinks`, `cli`, `mcp`, `config`, `deps`.
+
+Before opening a pull request:
+
+- [ ] All checks above pass.
+- [ ] New behavior has tests.
+- [ ] User-visible changes are noted under `[Unreleased]` in `CHANGELOG.md`.
+- [ ] Docs are updated for new options or behavior.
+
+Keep pull requests small and focused. They are squash-merged, so the PR title
+becomes the commit message.
+
+## Reporting bugs
+
+Open an issue with the video URL (if public), the command you ran, the full
+error output, and `vink --version`. For security issues, see
+[SECURITY.md](SECURITY.md).
+
+## Code of conduct
+
+This project follows the [Code of Conduct](CODE_OF_CONDUCT.md).

vink-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vink contributors
+
+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.