yapbook 0.1.0__tar.gz

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

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ["3.10", "3.12"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      # Core deps + dev tools only: the test suite runs entirely on fakes —
+      # no docling, kokoro, whisper, winrt, or audio hardware required.
+      - run: pip install -e ".[dev]"
+      - run: ruff check src tests
+      - run: pytest -q

yapbook-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Editors
+.vscode/
+.idea/
+
+# Never commit book content, audio, or models.
+# Real user data lives under the platformdirs user-data dir, not the repo,
+# but belt-and-suspenders in case someone points YAPBOOK_DATA_DIR here:
+*.pdf
+*.epub
+*.wav
+*.mp3
+*.flac
+*.onnx
+*.gguf
+*.pt
+*.pth
+*.safetensors
+# Public-domain test fixtures are the only exception:
+!tests/fixtures/**

yapbook-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,262 @@
+# yapbook — Architecture
+
+**One sentence:** yapbook turns a textbook PDF you own into a natural-voice audiobook that
+plays through your earbuds, and when you tap play/pause it listens to your spoken question,
+answers it *from the book, at the exact spot you were listening to*, and resumes.
+
+Everything runs on your machine. No accounts, no uploads, no meters.
+
+This document is the build contract. Every design decision below exists because the naive
+alternative was tested and found broken; the "why" notes are load-bearing — do not
+"simplify" them away.
+
+---
+
+## 1. The loop
+
+```
+ ┌────────────────────────────────────────────────────────────────────┐
+ │  PLAY   Kokoro narrates chapter segments through earbuds (A2DP)    │
+ │    │                                                               │
+ │  TAP    earbud tap = media play/pause → yapbook (registered as the  │
+ │    │    system Now Playing app) pauses and arms the mic            │
+ │  ASK    LAPTOP mic records; Silero VAD endpoints; faster-whisper   │
+ │    │    transcribes with chapter jargon as initial_prompt          │
+ │  ANSWER Ollama answers from the chapter context that was KV-       │
+ │    │    prewarmed during playback, grounded at the playhead;       │
+ │    │    sentences stream into Kokoro as they generate              │
+ │  RESUME playback continues from the same segment                   │
+ └────────────────────────────────────────────────────────────────────┘
+```
+
+Target: 3–6 s from end-of-question to first spoken answer word, on CPU.
+
+## 2. Module map
+
+```
+src/yapbook/
+  types.py       shared dataclasses (Segment, Chapter, BookManifest, PlaybackPosition)
+  config.py      platformdirs data dir, config.toml load/save, YAPBOOK_DATA_DIR override
+  cli.py         argparse CLI: add / listen / books / doctor
+  doctor.py      environment probes (see §9)
+  session.py     the orchestrating state machine for the loop above
+  ingest/
+    pipeline.py  PDF → KB via docling element-level routing
+    mathspeak.py LaTeX → spoken English (rule-based + optional LLM polish)
+    figures.py   VLM description of cropped figure images via Ollama
+    kb.py        KB read/write (book.json + chapters/chNNN.jsonl)
+  audio/
+    tts.py       Kokoro synthesis (lazy-loaded), per-segment WAV cache
+    player.py    sounddevice playback queue + continuous position persistence
+  tap/
+    base.py      TapListener protocol + TapEvent
+    windows_smtc.py   winrt SMTC media session (Windows)
+    macos_nowplaying.py  pyobjc MPRemoteCommandCenter (macOS)
+    hotkey.py    cross-platform fallback (Ctrl+Space) — no media session
+    factory.py   choose the right listener per OS with graceful fallback
+  listen/
+    recorder.py  laptop-mic capture (16 kHz mono) + Silero VAD endpointing
+    stt.py       faster-whisper small.en int8 transcription
+  qa/
+    ollama_client.py  HTTP client for localhost:11434, explicit num_ctx, health probe
+    context.py   chapter-scoped append-only context window + KV prewarm
+    answer.py    prompt assembly + sentence-streaming answers
+```
+
+Heavy imports (torch, kokoro, faster_whisper, docling, winrt, pyobjc) are **lazy** —
+imported inside functions, never at module top level. `yapbook doctor`, `yapbook books`,
+and the test suite must run on a machine with none of the extras installed.
+
+## 3. Ingest (`yapbook add book.pdf`)
+
+**Why not a page-level text/image gatekeeper:** on born-digital textbooks it is dead code —
+in testing, 143/143 figure-bearing pages of a standard ML textbook had selectable text, so a
+"page has text → skip VLM" rule means the VLM never fires and every figure is lost.
+**Why not raw text extraction:** LaTeX math extracts as garbled symbol soup that TTS reads
+as "aitch … at … I" — measured word-error rates on equations in mainstream read-aloud tools
+are 0.51–0.62 (MathReader, arXiv 2501.07088). Math handling is yapbook's headline feature,
+not an edge case.
+
+Pipeline (docling, element-level):
+
+1. `docling` converts the PDF with layout labels per element: `text`, `section_header`,
+   `formula`, `picture`, `caption`, `code`, `page_header`/`page_footer`/`footnote`.
+2. Routing:
+   - `text`/`section_header`/`caption` → cleaned prose segments (`kind=text|heading`).
+   - `formula` → docling's LaTeX (CodeFormula model) stored as `source_text`;
+     `mathspeak.verbalize()` produces `spoken_text`. Both are kept: the QA LLM sees LaTeX,
+     the TTS speaks English.
+   - `picture` → cropped image → `figures.describe()` (Ollama VLM `qwen3-vl:8b-instruct`, fallback
+     `qwen3-vl:4b-instruct`/`2b-instruct` for low RAM; the bare non-instruct tags are THINKING builds that return empty responses). Constraints: temperature 0, hard max-token cap,
+     n-gram repetition detector on output, and the prompt forbids transcribing equations
+     inside figures (describe what the figure *shows*). Emitted as
+     `kind=figure` with `spoken_text = "Figure: <description>"`.
+   - `page_header`/`page_footer` → dropped. `footnote` → appended at chapter end.
+   - `code` → `kind=code`; spoken as a short paraphrase line ("Code listing: …" from its
+     caption/first comment), full text kept in `source_text` for the QA LLM.
+3. Chapters are split on top-level `section_header` elements; each chapter also gets a
+   `jargon` list (distinctive capitalized/technical terms, frequency-ranked) used later as
+   the STT `initial_prompt`.
+4. Output (see §8 for location):
+   - `book.json` — `BookManifest`
+   - `chapters/chNNN.jsonl` — one `Segment` JSON per line, in narration order.
+
+Segments are sentence-sized for prose (split on sentence boundaries, merged to ≥ ~120
+chars so the TTS cache isn't thousands of tiny files), one per formula/figure.
+
+`mathspeak` is rule-based first (Greek letters, sub/superscripts, fractions, sums,
+products, integrals, expectations, norms, gradients, common ML operators), with an
+optional Ollama polish pass at ingest time for equations above a complexity threshold
+(cached in the KB — never at listen time). It must degrade gracefully: unknown LaTeX
+falls back to a cleaned literal reading, never an exception.
+
+## 4. Audio out (`audio/`)
+
+- Kokoro-82M (`af_heart` default voice), Apache-2.0. Speed is applied via Kokoro's
+  synthesis-time `speed` parameter (default 1.1). **Never resample to change speed**
+  (chipmunk artifact).
+- Phonemization: `espeakng-loader` pip wheel + `phonemizer-fork` — never require a system
+  espeak-ng install (the Windows .msi + env-var dance is the #1 Kokoro install failure).
+  espeak-ng is misaki's out-of-dictionary fallback and IS needed for ML jargon.
+- Synthesis is per-segment, written to the audio cache (`audio-cache/chNNN/SSSSS.wav`),
+  with a small look-ahead worker (synthesize N+1, N+2 while N plays). Cache hits skip
+  synthesis entirely — re-listening is instant and free.
+- Playback: `sounddevice` OutputStream, one short-lived stream per segment run. On any
+  PortAudio error: close, re-scan devices, reopen (PortAudio has no hotplug; Bluetooth
+  earbuds appear/disappear as endpoints).
+- `PlaybackPosition` (book, chapter, segment) is persisted to `positions.json` with an
+  atomic write **on every segment boundary and on every pause** — a crash may never lose
+  the user's place. That file is the playhead the QA engine grounds on.
+
+## 5. Tap capture (`tap/`)
+
+**Why not a keyboard listener:** earbud taps are *media-transport* events, not keystrokes.
+On macOS they route via MediaRemote to the current "Now Playing" app — pynput never sees
+them, and if no app claims Now Playing, the tap launches Apple Music over your session.
+On Windows a passive hook still lets Spotify/the browser grab the same tap.
+
+So yapbook registers as a **real media session**:
+
+- **Windows** (`windows_smtc.py`): modern `winrt-*` modular packages (the monolithic
+  `winsdk` package is deprecated). A `Windows.Media.Playback.MediaPlayer` with
+  `CommandManager` disabled-then-configured exposes SMTC; handle Play/Pause/Toggle
+  button events; publish title/artist ("yapbook — <book title>") and playback status so
+  the OS routes earbud taps to us.
+- **macOS** (`macos_nowplaying.py`): pyobjc `MPNowPlayingInfoCenter` +
+  `MPRemoteCommandCenter` (togglePlayPauseCommand etc.). Requires an NSRunLoop pump on a
+  dedicated thread. This kills any need for the Accessibility permission. Keep
+  `MPNowPlayingInfoPropertyPlaybackRate` and `DefaultPlaybackRate` in lockstep with the
+  actual (1.1×) rate, or Bluetooth pause commands can be dropped.
+- **Fallback** (`hotkey.py`): Ctrl+Space global hotkey for setups where media routing
+  is broken; selected explicitly or when the native listener fails to initialize.
+
+The listener surfaces a single `TapEvent` stream; `session.py` interprets it
+(pause→ask vs resume) — listeners carry no session logic.
+
+## 6. Voice in (`listen/`)
+
+**Why the laptop mic, not the earbud mic:** opening a Bluetooth headset mic switches the
+whole headset from A2DP (stereo, high quality) to HFP/SCO — playback collapses to mono
+8–16 kHz with a 1–3 s glitch on each switch, and Windows 11 is notorious for getting stuck
+in Hands-Free mode afterwards (Microsoft's own guidance: use a different mic). The user is
+in the same room as the laptop (kitchen counter, desk); the laptop mic hears them fine and
+playback quality never degrades.
+
+- Default input: system default *non-Bluetooth* input device (prefer built-in mic when the
+  default input is the earbuds' Hands-Free endpoint; warn once). `--earbud-mic` opts in to
+  the HFP tradeoff explicitly.
+- Capture 16 kHz mono via sounddevice InputStream.
+- Endpointing: Silero VAD (bundled with faster-whisper) — stop after ~1.2 s trailing
+  silence, hard cap 30 s.
+- STT: `faster-whisper` `small.en` int8 (~1–3 s for a 10 s clip on CPU). `initial_prompt`
+  is seeded with the current chapter's `jargon` list so "RLHF", "KL penalty", "logits"
+  transcribe correctly.
+
+## 7. QA (`qa/`)
+
+**Why not "stuff the whole book in the prompt":** a 300–600 page book is 156k–390k tokens
+— over every local model's window — and Ollama's default context on <24 GiB VRAM machines
+is 4k with **silent truncation from the front**, so naive stuffing yields a model that has
+only seen the last few pages and answers confidently from the wrong place. 50k tokens of
+context ≈ 2–8 min of CPU prefill — unusable per-question.
+
+Design:
+
+- **Chapter-scoped, append-only context.** The conversation context is: a fixed system
+  prompt + the current chapter's segments *up to the playhead* (append-only as playback
+  advances) + the Q&A turns. Append-only matters: it preserves llama.cpp's prefix KV
+  cache, so each new question only prefills the delta.
+- **KV prewarm during playback.** While a segment plays, `context.py` sends the grown
+  context to Ollama with `"prompt": ""`-style warm requests so the KV cache is already hot
+  when the tap comes. Result: tap-to-first-word stays in the 3–6 s budget on CPU.
+- Brain: `qwen3:4b-instruct` (Apache-2.0, non-thinking variant — never a thinking
+  model; latency budget). `num_ctx` set **explicitly** (default 16384); at session start,
+  assert the planned chapter context fits and log the token count (never trust silent
+  defaults).
+- Cross-chapter questions ("how does this relate to chapter 2?") are detected by a cheap
+  heuristic (mentions of other chapters / "earlier in the book") and answered via optional
+  embedding retrieval (nomic-embed-text + a flat numpy index built at ingest) spliced in
+  as a clearly-delimited RETRIEVED block — appended, never prepended (prefix cache).
+- Grounding rule in the system prompt: answer *at the listener's position* — "what did it
+  just say?" refers to the last ~3 segments; never spoil content past the playhead unless
+  asked explicitly.
+- Answers are capped at 2–4 spoken sentences and stream sentence-by-sentence into Kokoro
+  — first sentence speaks while the rest generates.
+
+## 8. Data locations (`config.py`)
+
+All user data lives under `platformdirs.user_data_dir("yapbook")` (override:
+`YAPBOOK_DATA_DIR`):
+
+```
+yapbook/
+  config.toml
+  positions.json
+  books/<slug>/
+    book.json
+    chapters/chNNN.jsonl
+    audio-cache/chNNN/SSSSS.wav
+    figures/…png            (cropped, for re-description)
+```
+
+**Never inside the repo/install dir**: the KB markdown and audio cache are derivative
+copies of a copyrighted book. `.gitignore` is not a privacy mechanism; the data dir is.
+
+## 9. Doctor (`yapbook doctor`)
+
+Probes, each with a one-line PASS/FAIL/SKIP and a fix hint:
+
+1. Python version, OS, yapbook version.
+2. Ollama reachable at `localhost:11434`; required models pulled (brain, VLM, embed) —
+   exact pinned tags; VRAM/RAM estimate note.
+3. Kokoro importable; espeakng-loader data path resolves; 1-word test synth (optional).
+4. faster-whisper importable; `small.en` model present or downloadable note.
+5. Input devices: list; flag when the default input is a Bluetooth Hands-Free endpoint.
+6. Output devices: list; flag when no output device.
+7. macOS: mic permission status. Windows: note SMTC availability.
+8. Data dir writable; disk-space note (~10–12 GB for the full model set, stated plainly).
+
+## 10. Licensing & posture
+
+- Code: Apache-2.0.
+- Models (all weights downloaded by the user at first run, never redistributed):
+  | Component | Model | License |
+  |---|---|---|
+  | TTS | Kokoro-82M | Apache-2.0 |
+  | Brain | qwen3:4b-instruct | Apache-2.0 |
+  | VLM | qwen3-vl (8b/4b/2b instruct) | Apache-2.0 |
+  | STT | faster-whisper small.en | MIT (weights: OpenAI Whisper, MIT) |
+  | Embeddings (optional) | nomic-embed-text | Apache-2.0 |
+  - Deliberately avoided: Qwen2.5-VL-3B (research-only license), Llama 3.x (non-OSI).
+- Disclaimer (README, ebook2audiobook-style): for personal use with books you lawfully
+  own; no DRM circumvention; the project makes **no legal claims** — never the words
+  "legal" or "fair use" in docs.
+- Test fixtures: public-domain text only, with a CI size check.
+
+## 11. Non-goals (v0.x)
+
+- No cloud fallback of any kind. No accounts, no telemetry.
+- No mobile app; a phone-reachable playback story (local-network PWA/stream) is a
+  candidate for v0.3+, tracked in the README roadmap.
+- No EPUB ingest in v0.1 (PDF first; EPUB is a docling flag away and lands v0.2).
+- No wake word; the tap (or hotkey) is the only trigger.

yapbook-0.1.0/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+## 0.1.0 — 2026-07-27
+
+First release: the full loop works end to end on real hardware — verified with
+Bluetooth earbuds against Sutton & Barto's *Reinforcement Learning* (548 pages,
+9,000+ segments, 382 formulas, 160 figures).
+
+### The loop
+- `yapbook add book.pdf` — one-time ingest: docling element routing, LaTeX
+  formulas verbalized tutor-style ("the expectation over x of…"), figures
+  described by a local vision model, per-chapter jargon for the STT.
+- `yapbook listen book` — Kokoro narration through your earbuds as a real OS
+  media session (SMTC). Tap to pause + ask a question out loud; the answer is
+  grounded at your exact listening position and playback auto-resumes.
+- Follow-up window after each answer ("Any other questions?"), earcons when
+  the mic opens and when speech is captured, double-tap segment skip,
+  triple-tap replay, chapter auto-advance with spoken announcements.
+- `yapbook config` / `yapbook voices` / `--voice` / `--speed`; user
+  pronunciation lexicon (`pronunciations.toml`) on top of built-in ML/STEM
+  defaults.
+- `yapbook add 2501.07088` — arXiv papers by id or URL (PDF + title fetched
+  from the export API), the fastest way to try the math verbalization.
+- `yapbook-mcp` — an MCP server for Claude and other MCP clients:
+  list books, check your position, ask position-grounded questions, queue
+  new papers.
+- `yapbook ask book "question"` — the same position-grounded Q&A as a plain
+  CLI command, for scripts and shell-first agents.
+- A portable agent skill (`integrations/skill/yapbook/SKILL.md`) — one file
+  that works in Claude Code, OpenClaw, and Codex CLI; plus per-host MCP
+  setup notes (Claude Desktop, Odysseus) in `integrations/`.
+- `yapbook podcast book [--serve]` — export one episode per chapter + an RSS
+  feed; `--serve` publishes it on your WiFi so any podcast app can subscribe
+  (offline downloads, background play, lock-screen controls). MP3 via the
+  `podcast` extra (lameenc), WAV fallback without it; episodes are keyed to
+  voice/speed so a settings change never leaves mixed-voice episodes behind.
+- `yapbook ui` — a local web UI (the `ui` extra: Flask + qrcode). Drag-drop
+  ingest with live background-job progress, library with positions, chapter
+  skip-list checkboxes, preview generation/reading, one-click podcast export
+  with a scan-with-your-phone QR code, and a Listen button that opens the
+  earbud session in its own console. Binds 127.0.0.1 only and rejects
+  foreign Host/Origin (DNS-rebinding/CSRF hardening); the LAN sees nothing
+  but the podcast feed, only while shared. One HTML file, no JS build step.
+- MCP `add_book` (via `add_ref`) now reports pipeline progress through the
+  same seam the UI uses and auto-marks back matter, matching the CLI.
+- Beyond PDFs: `yapbook add` ingests EPUB, DOCX, PPTX, HTML, and Markdown
+  through the same docling pipeline and element routing (the PDF path keeps
+  its formula/figure enrichment; other formats use docling's native readers).
+- `yapbook preview book` — browse by ear: a spoken ~30-second summary per
+  chapter, generated locally from the chapter's own KB text and cached per
+  brain model (`--text` prints for scripts/agents; `--chapter N` for one;
+  explicit chapters preview even when marked skip).
+- `yapbook skip book` — per-chapter skip lists honored by both `listen`
+  (auto-advance passes over them, announced) and `podcast` (excluded from the
+  feed). Back matter is auto-detected by title at ingest (References,
+  Bibliography, Acknowledgments, Index, …) with conservative matching —
+  "Reference Frames" is a physics chapter, not back matter — and
+  Introductions are never auto-marked. Playback-only: the KB keeps every
+  chapter for Q&A. An explicit `--chapter` always plays, even a skipped one.
+- 100% local: Ollama (Qwen3) + faster-whisper + Kokoro. No accounts, no
+  uploads, no telemetry.
+
+### Notable fixes made along the way (the sharp edges we hit so you don't)
+- The bare `qwen3-vl:8b` Ollama tag is the *thinking* build: it burns the
+  whole `num_predict` budget on hidden reasoning and returns empty
+  descriptions. yapbook pins the `-instruct` tags and refuses to accept an
+  empty description silently.
+- On Windows, initializing WinRT/COM (the media session) before torch's first
+  import makes `c10.dll` fail to load (WinError 1114). `listen` preloads the
+  native ML runtimes on the main thread, first.
+- Bluetooth sinks pop when the audio device is re-acquired per utterance; a
+  persistent output stream is reused across narration, answers, and earcons.
+- Re-ingesting a book invalidates its narration cache (cached WAVs are keyed
+  by position, and positions renumber).
+- OCR'd formulas can loop (`\exp(\exp(\exp(…` ×24); spoken math collapses
+  degenerate repetition, drops content-free alignment fragments, and caps a
+  single formula's speech at ~40 s.
+- Laptop mic is the default question input — opening the earbud mic would
+  collapse the whole headset to phone-quality HFP audio (`--earbud-mic` to
+  opt in anyway).

yapbook-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.