HyperbookLM Documentation

HyperbookLM is a research assistant that aggregates diverse sources to provide deep insights. Key capabilities include:

• Multi-Source Ingestion: Scrape web URLs using Hyperbrowser or upload and parse PDF documents client-side.
• Deep Research Analysis:
  • AI Research Summary: Comprehensive summaries with key insights.
  • Interactive Mindmap: Visualizes concept relationships using React Flow.
  • Audio Overview: Podcast-style audio summaries via ElevenLabs.
  • Presentation Slides: Auto-generated slide decks using Google Gemini.
• Interactive Chat: Streaming AI responses for querying your ingested sources.

Follow these steps to set up the HyperbookLM development environment locally:

1. Clone the repository:

   git clone https://github.com/hyperbrowserai/hyperbooklm.git
   cd hyperbooklm

2. Install dependencies using yarn or npm:

   yarn
   # or
   npm install

3. Configure environment variables: Copy the example environment file to create your local configuration:

   cp .env.local.example .env.local

4. Start the development server:

   yarn dev

5. Access the app: Open http://localhost:3000 in your browser.

HyperbookLM requires several API keys to function. Add the following keys to your .env.local file:

# Hyperbrowser API Key
HYPERBROWSER_API_KEY=your_hyperbrowser_key

# OpenAI API Key
OPENAI_API_KEY=your_openai_key

# Google Gemini API Key
GEMINI_API_KEY=your_gemini_key

# ElevenLabs API Key (Optional)
ELEVENLABS_API_KEY=your_elevenlabs_key

If streamChatCompletion fails, it typically throws an error or triggers the onError callback with one of the following issues:

1. Missing API Key: If OPENAI_API_KEY is not set in your environment (e.g., .env.local), the function throws: "OpenAI API key is missing. Please set OPENAI_API_KEY in your .env.local file."
2. API Request Failure: If the OpenAI server returns a non-OK status, the error message will contain the specific error from the OpenAI response (e.g., invalid model, rate limits, or authentication issues).
3. Stream Reader Failure: If the response body cannot be read as a stream, it throws: "Failed to get response reader".

Use the generateSlides function to trigger the generation of a SlideDeck based on a specific notebook and a set of sources. This function makes a POST request to the /api/gemini/slides endpoint.

If the request fails, it throws an error containing the error message returned by the server, or a default message "Failed to generate slides" if no error details are provided.

import { generateSlides } from "./lib/api/gemini";
import { Source } from "./lib/types";

const sources: Source[] = [
  // ... your source objects
];

try {
  const slideDeck = await generateSlides("your-notebook-id", sources);
  console.log("Generated SlideDeck:", slideDeck);
} catch (error) {
  console.error("Error generating slides:", error.message);
}

Use generateOverview to create a NotebookSummary for a specific notebook based on a set of provided sources. This function makes a POST request to /api/gpt/overview.

Parameters:

• notebookId: The unique identifier for the notebook.
• sources: An array of Source objects to be used in the generation process.

Returns: A Promise that resolves to a NotebookSummary object.

Errors: Throws an error if the response is not OK, using the error message provided by the API or defaulting to "Failed to generate overview".

import { generateOverview } from "../lib/api/gpt";

const summary = await generateOverview("my-notebook-id", sourcesArray);

The scrapeWebpage function performs a POST request to the /api/scrape endpoint to extract structured data from a given URL. It returns an object containing the page's title, main content, plain text, and the original URL.

If the request fails, it throws an error containing the error message returned by the server or a fallback status text.

const data = await scrapeWebpage('https://example.com');
// Returns: { title: string; content: string; text: string; url: string; }

Use generateMindmap to create a Mindmap structure for a specific notebook based on a set of provided sources. This function makes a POST request to /api/gpt/mindmap.

Parameters:

• notebookId: The unique identifier for the notebook.
• sources: An array of Source objects to be used in the generation process.

Returns: A Promise that resolves to a Mindmap object.

Errors: Throws an error if the response is not OK, using the error message provided by the API or defaulting to "Failed to generate mindmap".

import { generateMindmap } from "../lib/api/gpt";

const mindmap = await generateMindmap("my-notebook-id", sourcesArray);

Use buildVideoPrompt to construct a VideoPrompt object derived from an existing NotebookSummary. This is useful for preparing data for video generation workflows.

Parameters:

• notebookId: The unique identifier for the notebook.
• summary: The NotebookSummary object containing the bullets to be used.
• durationSec: The desired video duration in seconds. Accepts 30 or 60. Defaults to 30.

Returns: A VideoPrompt object containing the notebook ID, timestamp, duration, the first 5 bullets from the summary as beats, an "informative" style, and voiceOver: false.

import { buildVideoPrompt } from "../lib/api/gpt";

const videoPrompt = buildVideoPrompt(notebookId, summary, 60);

Use buildAudioScript to construct an AudioScript object from a NotebookSummary. This prepares the text for text-to-speech (TTS) services.

Parameters:

• notebookId: The unique identifier for the notebook.
• summary: The NotebookSummary object containing the bullets to be converted to text.
• voiceId: The identifier for the target voice (e.g., from ElevenLabs).

Returns: An AudioScript object. The text is generated by joining all bullets in the summary with spaces. If the resulting text exceeds 2200 characters, it is truncated to the first 2200 characters.

import { buildAudioScript } from "../lib/api/gpt";

const audioScript = buildAudioScript(notebookId, summary, "voice-id-123");