notebooklm 4.7.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e55f36aa3d5bc491e1c271b662aa8897b9629c3e15dbfd9468d9d9016ed2cb7e
+  data.tar.gz: e42aaea281852a835e1929d9de0493cb50c7772667c2a32b292402eaf2377f44
+SHA512:
+  metadata.gz: 56dcb0bacd5ed50bcd92037614d4634e6ca8c3afb1f313abbeaa619672962abd9a35d8bedcdb0f9f6a025e9e254620f7eb581f74ceab16faa50710f69e8b7f90
+  data.tar.gz: 1f9d912626bd6165e6f2caf120148e2a7d63ba330774a9a2bafbdfee38302b6ceb8d48160e8237c3fa2d64bdc2889db292b4d3c44482e9bab088ec0977b511e0

data/README.md

@@ -0,0 +1,155 @@
+# notebooklm
+
+[![Gem Version](https://img.shields.io/gem/v/notebooklm.svg)](https://rubygems.org/gems/notebooklm)
+[![CI](https://github.com/roomi-fields/notebooklm-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/roomi-fields/notebooklm-mcp/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A Ruby client for **Gemini Notebook** (formerly NotebookLM): citation-backed
+answers, passage retrieval, Studio generation, and the whole of a local
+server's REST API as documented methods rather than hashes you have to guess at.
+
+## Features
+
+- **All 56 operations**, generated from the server's OpenAPI specification, so
+  a route added upstream reaches this gem on the release that ships it —
+  rather than whenever someone remembers to add a method.
+- **Every shape documented**: each field the specification describes has a
+  reader with its type, and a field the server adds later is still reachable
+  through `[]` and `to_h`. An unknown shape is never a wall.
+- **Citation-backed answers**: `ask` returns the answer and the quoted passage
+  behind every marker.
+- **Retrieval that spends no allowance**: `search_passages` returns the indexed
+  passages for a query without generating anything.
+- **The indexed text itself**: `read_source` returns what the service actually
+  extracted from a PDF or a page, which the web interface only shows in
+  fragments.
+- **Studio generation** — audio, video, infographic, report, presentation, data
+  table — plus study aids, mind maps, labels and notes.
+- **The UTCP manual**: `get_utcp_manual` returns the document a
+  [UTCP](https://www.utcp.io/) client reads to call the API with no client at
+  all.
+- **Honest absence**: a passage with no offset reads as `nil`, never as `0`.
+  Guessing a zero is how a quotation gets attributed to the top of a long
+  document.
+- **A refusal keeps its words**: the server's own explanation travels in
+  `NotebookLM::Refused`, and a request that never arrived raises a different
+  class from one that was declined — `error.transport?` separates the two.
+- **No runtime dependencies.** Net::HTTP and JSON, nothing else. The tests have
+  no dependencies either.
+
+## Usage
+
+```ruby
+# Gemfile
+gem 'notebooklm', '~> 4.7'
+```
+
+or `gem install notebooklm`.
+
+```ruby
+require 'notebooklm'
+
+client = NotebookLM.local
+
+unless client.get_health.authenticated
+  abort 'no Google session yet — run the setup command once'
+end
+
+notebook = client.list_notebooks.notebooks.first
+
+# Retrieval: the evidence, with no generation allowance spent.
+client.search_passages(id: notebook.id, query: 'ikigai', limit: 5).passages.each do |passage|
+  puts "#{passage.rank} — #{passage.text}"
+end
+
+# Or an answer, with the quotations behind it.
+answer = client.ask(notebook.id, 'How is ikigai defined?')
+puts answer.answer
+answer.citations.each { |citation| puts "  [#{citation.number}] #{citation.source_text}" }
+```
+
+Every operation takes its parameters as keyword arguments under the names the
+specification gives them, and returns a shape whose readers are documented:
+
+```ruby
+client.ask_question(question: 'How is ikigai defined?', notebook_id: notebook.id,
+                    source_format: 'json')
+client.generate_report(id: notebook.id, prompt: 'A literature review')
+client.get_utcp_manual.tools.size # => 56
+```
+
+## It needs a server, and that is deliberate
+
+Google publishes no API for the consumer product. Everything any tool does
+rides on the endpoints the web application itself calls, and those require a
+logged-in Google session. Keeping one means three things that are easy to
+underestimate:
+
+- the session is **bound to the machine** it was created on — copied cookies
+  are refused even while their local expiry still looks valid;
+- Google **expires sessions server-side** while those cookies look fine, so the
+  only reliable check is navigating and seeing where you land;
+- an unpatched automated browser **gets flagged**, and the patches have to be
+  maintained against a moving target.
+
+So this gem owns no browser. It talks to a process that does:
+
+```bash
+npx -y @roomi-fields/notebooklm-mcp                                # the server
+npx -y -p @roomi-fields/notebooklm-mcp notebooklm-mcp-setup-auth   # once
+```
+
+On loopback the server needs no token. As soon as you expose it, it refuses to
+start without one:
+
+```ruby
+client = NotebookLM::Client.new(base: 'http://10.0.0.2:3000', api_key: ENV.fetch('NOTEBOOKLM_API_KEY'))
+```
+
+`NOTEBOOKLM_API_KEY` and `NOTEBOOKLM_BASE_URL` are read from the environment
+when you pass neither. The key is never printed: `inspect` redacts it.
+
+## Errors
+
+```ruby
+begin
+  client.ask(notebook.id, 'How is ikigai defined?')
+rescue NotebookLM::Refused => e
+  warn e.reason                      # the server's own words, for a human
+rescue NotebookLM::TransportError => e
+  retry if (tries += 1) < 3          # nothing arrived; retrying can work
+rescue NotebookLM::ShapeError => e
+  warn "client and server disagree on #{e.route}"
+end
+```
+
+`NotebookLM::EmptyPayload` means the server reported success and sent nothing —
+its contract breach, reported rather than returned as a `nil` for you to trip
+over three lines later.
+
+## Versions
+
+The gem version is the server version it speaks to. There is one release per
+server release, and 4.6 works against a 4.6 server; a mismatch is the one thing
+this gem cannot check for you.
+
+Ruby **3.1** or later.
+
+## Documentation
+
+- [Server documentation](https://notebooklm.roomi-fields.com/)
+- [Driving it from Ruby](https://notebooklm.roomi-fields.com/blog/notebooklm-ruby)
+  — why the gem is shaped this way
+- [REST API reference](https://notebooklm.roomi-fields.com/notebooklm-rest-api)
+
+## License
+
+MIT. See [LICENSE](https://github.com/roomi-fields/notebooklm-mcp/blob/main/LICENSE).
+
+### Contribution
+
+Issues and pull requests go to
+[roomi-fields/notebooklm-mcp](https://github.com/roomi-fields/notebooklm-mcp),
+which holds the server and this gem together. The surface is generated: change
+`deployment/docs/openapi.yaml` and run `npm run ruby:sync`, never
+`lib/notebooklm/generated.rb` by hand.

data/lib/notebooklm/client.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+
+module NotebookLM
+  # A client for one local server.
+  #
+  # Every operation lives in {Operations}, generated from the server's OpenAPI
+  # specification. This class is only the plumbing underneath: where to send a
+  # request, how to carry the token, and how to turn the envelope into either a
+  # shape or an error.
+  #
+  # @example
+  #   client = NotebookLM::Client.new
+  #   client.get_health.authenticated # => true
+  class Client
+    # Where the server listens when nothing says otherwise.
+    DEFAULT_BASE = 'http://127.0.0.1:3000'
+
+    # A question can legitimately take minutes, and Net::HTTP would otherwise
+    # give up after sixty seconds — reporting a timeout for a call that was
+    # working.
+    DEFAULT_READ_TIMEOUT = 300
+
+    # @return [String] the address this client talks to
+    attr_reader :base
+
+    # @param base [String] where the server listens
+    # @param api_key [String, nil] the token the server requires as soon as it
+    #   is exposed beyond loopback. Defaults to `NOTEBOOKLM_API_KEY`, and is
+    #   never printed by {#inspect}.
+    # @param read_timeout [Numeric] how long to wait for one answer
+    # @param open_timeout [Numeric] how long to wait for the connection
+    def initialize(base: nil, api_key: :from_env, read_timeout: DEFAULT_READ_TIMEOUT,
+                   open_timeout: 10)
+      @base = base || ENV['NOTEBOOKLM_BASE_URL'] || DEFAULT_BASE
+      @api_key = api_key == :from_env ? ENV.fetch('NOTEBOOKLM_API_KEY', nil) : api_key
+      raise ApiKeyError if @api_key && @api_key.match?(/[\u0000-\u001f\u007f]/)
+
+      @uri = parse_base(@base)
+      @read_timeout = read_timeout
+      @open_timeout = open_timeout
+      @mutex = Mutex.new
+    end
+
+    # The api key is held here, so a printed client would leak it.
+    def inspect
+      "#<#{self.class.name} base=#{@base.inspect} api_key=#{@api_key ? '<redacted>' : 'nil'}>"
+    end
+
+    # One request, for the generated surface: the route, an optional body, an
+    # optional query block, and the envelope unwrapped.
+    #
+    # `route` is only ever used to say which call could not be read, which is
+    # the difference between "the server changed" and "my code is wrong".
+    #
+    # @api private
+    def call(route, method, path, body: nil, query: nil, enveloped: true)
+      response = perform(route, method, path, body, query)
+      payload = parse(route, response)
+      return payload unless enveloped
+
+      unwrap(route, payload)
+    end
+
+    private
+
+    def parse_base(base)
+      uri = URI.parse(base)
+      raise AddressError, "invalid server address: #{base}" unless uri.is_a?(URI::HTTP)
+
+      uri
+    rescue URI::InvalidURIError => e
+      raise AddressError, "invalid server address: #{base} (#{e.message})"
+    end
+
+    METHODS = {
+      get: Net::HTTP::Get,
+      post: Net::HTTP::Post,
+      put: Net::HTTP::Put,
+      patch: Net::HTTP::Patch,
+      delete: Net::HTTP::Delete
+    }.freeze
+    private_constant :METHODS
+
+    def perform(route, method, path, body, query)
+      target = route_uri(path, query)
+      request = METHODS.fetch(method).new(target)
+      request['Accept'] = 'application/json'
+      request['User-Agent'] = "notebooklm-ruby/#{VERSION}"
+      request['Authorization'] = "Bearer #{@api_key}" if @api_key
+      if body
+        request['Content-Type'] = 'application/json'
+        request.body = JSON.generate(body)
+      end
+      send_request(request)
+    rescue KeyError
+      raise ShapeError.new(route, "no such HTTP method: #{method}")
+    end
+
+    def send_request(request)
+      @mutex.synchronize { http.request(request) }
+    rescue StandardError => e
+      raise TransportError.new(@base, e)
+    end
+
+    # One connection, reused. Net::HTTP is not thread-safe, so the mutex above
+    # serialises calls rather than pretending otherwise.
+    def http
+      return @http if @http&.started?
+
+      @http = Net::HTTP.new(@uri.host, @uri.port)
+      @http.use_ssl = @uri.scheme == 'https'
+      @http.read_timeout = @read_timeout
+      @http.open_timeout = @open_timeout
+      @http.start
+      @http
+    end
+
+    def route_uri(path, query)
+      uri = @uri.merge(path)
+      pairs = (query || {}).reject { |_, value| value.nil? }
+      uri.query = URI.encode_www_form(pairs) unless pairs.empty?
+      uri
+    rescue URI::Error => e
+      raise AddressError, "could not join #{path} onto #{@base} (#{e.message})"
+    end
+
+    def parse(route, response)
+      body = response.body.to_s
+      raise ShapeError.new(route, "the server answered #{response.code} with an empty body") if body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError => e
+      raise ShapeError.new(route, e.message)
+    end
+
+    # The envelope carries the refusal, so the HTTP status is not consulted: a
+    # refused call answers 4xx *and* `success: false`, and the body is the half
+    # that says why.
+    def unwrap(route, payload)
+      raise ShapeError.new(route, 'the answer was not a JSON object') unless payload.is_a?(Hash)
+
+      data = payload['data']
+      reason = payload['error']
+      return data if payload['success'] == true && !data.nil?
+      raise Refused, reason.to_s unless reason.nil?
+
+      raise EmptyPayload, route
+    end
+  end
+end

data/lib/notebooklm/ergonomics.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module NotebookLM
+  # How the quotations behind an answer should come back.
+  #
+  # The wire takes a string; this is the list the server accepts, so a typo
+  # raises here instead of coming back as an answer with no citations.
+  SOURCE_FORMATS = %w[none json inline footnotes expanded].freeze
+
+  # The few helpers the generated surface cannot have.
+  #
+  # Everything else in this gem comes out of the OpenAPI specification, which
+  # is what keeps it complete. A generator cannot know that a question usually
+  # wants its quotations as data, or that the session id of one answer is the
+  # handle for the next — so those live here.
+  #
+  # There are fewer of these than the Rust crate needs, and that is Ruby's
+  # doing: keyword arguments with defaults already read like a builder, so a
+  # request object would add nothing.
+  module Ergonomics
+    # Ask a notebook in the local library, with the quotations returned as
+    # data. The long form is {Operations#ask_question}.
+    #
+    # @param notebook_id [String] a notebook id from {Operations#list_notebooks}
+    # @param question [String] the question, in prose
+    # @param session_id [String, nil] continue an earlier chat instead of
+    #   starting a new one — pass the `session_id` the previous answer carried
+    # @param source_format [String] one of {SOURCE_FORMATS}
+    # @return [AskQuestionData]
+    def ask(notebook_id, question, session_id: nil, source_format: 'json')
+      check_source_format(source_format)
+      ask_question(
+        question: question,
+        notebook_id: notebook_id,
+        session_id: session_id,
+        source_format: source_format
+      )
+    end
+
+    # The same question, against a notebook that is not in the library.
+    #
+    # @param notebook_url [String] the notebook's address
+    # @param question [String] the question, in prose
+    # @param session_id [String, nil] an earlier chat to continue
+    # @param source_format [String] one of {SOURCE_FORMATS}
+    # @return [AskQuestionData]
+    def ask_url(notebook_url, question, session_id: nil, source_format: 'json')
+      check_source_format(source_format)
+      ask_question(
+        question: question,
+        notebook_url: notebook_url,
+        session_id: session_id,
+        source_format: source_format
+      )
+    end
+
+    private
+
+    def check_source_format(format)
+      return if SOURCE_FORMATS.include?(format.to_s)
+
+      raise ArgumentError,
+            "source_format must be one of #{SOURCE_FORMATS.join(', ')}, got #{format.inspect}"
+    end
+  end
+
+  class AskQuestionData
+    # The quotations behind this answer, or an empty list when the question
+    # did not ask for them. Saves callers one hop through `sources`.
+    #
+    # @return [Array<AskQuestionDataSourcesCitationsItem>]
+    def citations
+      sources.citations
+    end
+  end
+
+  class Client
+    include Ergonomics
+  end
+end

data/lib/notebooklm/errors.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module NotebookLM
+  # What can go wrong between a Ruby program and the local server.
+  #
+  # The subclasses separate three situations a single error class usually
+  # blurs: the request never arrived, the server refused the request and said
+  # why, and the server answered in a shape we cannot read. Only the second is
+  # the caller's fault, and only the third is ours.
+  class Error < StandardError
+    # True when retrying could plausibly succeed. A refusal is not retryable:
+    # the server already decided.
+    def transport?
+      false
+    end
+  end
+
+  # The request never completed: nothing listening, a timeout, a broken pipe.
+  class TransportError < Error
+    # @return [String] the address the client was pointed at
+    attr_reader :base
+
+    # @return [StandardError] what the HTTP stack reported
+    attr_reader :cause_error
+
+    def initialize(base, cause_error)
+      @base = base
+      @cause_error = cause_error
+      super("the server at #{base} could not be reached: #{cause_error.message}")
+    end
+
+    def transport?
+      true
+    end
+  end
+
+  # The server answered the envelope with `success: false` and a reason. The
+  # reason is the server's own wording, meant to be shown to a human.
+  class Refused < Error
+    # @return [String] the server's reason
+    attr_reader :reason
+
+    def initialize(reason)
+      @reason = reason
+      super("the server refused the request: #{reason}")
+    end
+  end
+
+  # The server reported success but sent no payload — a contract breach on its
+  # side, reported rather than returned as nil for the caller to trip over.
+  class EmptyPayload < Error
+    def initialize(route)
+      super("the server reported success with no payload for #{route}")
+    end
+  end
+
+  # The body did not match the shape this version of the client expects, which
+  # usually means the client and the server are different versions.
+  class ShapeError < Error
+    # @return [String] which call could not be read
+    attr_reader :route
+
+    def initialize(route, detail)
+      @route = route
+      super("could not read the server's answer to #{route}: #{detail}")
+    end
+  end
+
+  # The base address could not be parsed, or a route could not be joined onto it.
+  class AddressError < Error; end
+
+  # The api key held a byte that cannot travel in an HTTP header. Caught here
+  # rather than sent, because a stray newline in a header is a request
+  # smuggling primitive, not a typo.
+  class ApiKeyError < Error
+    def initialize
+      super('the api key cannot be sent as a header: it holds a newline or a control byte')
+    end
+  end
+end