Gemini API Integration

Relevant source files

The following files were used as context for generating this wiki page:

• services/geminiService.ts
• hooks/useContentGenerator.ts
• hooks/useNotes.ts
• components/Header.tsx
• components/SmartBoard.tsx
• App.tsx
• types.ts
• constants.ts
• package.json

The Gemini API integration is a cornerstone feature of the Nota application, providing the core AI capabilities that transform YouTube video transcripts into structured, actionable content. It is responsible for two primary functions: surgically cleaning small text snippets for "Margin Notes" and generating a variety of content formats (Twitter threads, LinkedIn posts, etc.) from the full transcript for the "Smart Board". This integration leverages the @google/genai library to interact with the Google Gemini models.

The system is designed to be robust, with error handling that prevents application crashes and provides clear user feedback. API key management is handled through a settings modal, allowing users to securely provide their own Gemini API key, which is validated before use.

Sources: README.md, services/geminiService.ts, package.json:20

Core Architecture

The integration is centered around services/geminiService.ts, which abstracts all interactions with the Gemini API. This service is consumed by custom React hooks (useNotes and useContentGenerator) that manage state and orchestrate the AI generation flows within the application.

Key Components

Component/File	Role
services/geminiService.ts	A centralized service that directly communicates with the Gemini API. It contains all prompts and logic for content generation.
hooks/useNotes.ts	Manages the state for "Margin Notes". Uses geminiService to clean user-selected transcript text.
hooks/useContentGenerator.ts	Manages the state for "Smart Board" content. Orchestrates parallel API calls to geminiService to generate multiple content types.
components/Header.tsx	Contains the UI for users to input and validate their Gemini API key.
components/SmartBoard.tsx	Displays the various forms of content generated by the Gemini API, such as key takeaways, threads, and posts.
App.tsx	The main component that integrates the hooks and UI components, triggering content generation when a video is loaded.
constants.ts	Defines application-wide constants, including limits for AI input length.

Sources: services/geminiService.ts, hooks/useContentGenerator.ts, hooks/useNotes.ts, components/Header.tsx, App.tsx

Gemini Service (geminiService.ts)

This service acts as the sole interface to the Gemini API. It initializes the GoogleGenAI client and exposes several functions for different generation tasks.

The following diagram illustrates the main functions within the geminiService.

This diagram shows how the GoogleGenAI client is used by various exported functions to produce different types of content or perform actions like API key validation.

Sources: services/geminiService.ts

Model and Configuration

All API calls utilize the gemini-2.0-flash model. Each generation function uses specific configuration parameters to tailor the output.

Parameter	Description	Example Value (cleanTranscriptText)
model	The specific Gemini model to use for generation.	'gemini-2.0-flash'
systemInstruction	A prompt that defines the AI's role and task, guiding the structure and tone of the output.	"You are an expert editor..."
maxOutputTokens	The maximum number of tokens the model can generate in its response.	100
temperature	Controls the randomness of the output. Lower values (e.g., 0.3) produce more deterministic responses.	0.3

Sources: services/geminiService.ts:50-57

Generation Functions

The service provides specialized functions, each with a unique system instruction (prompt) to generate a specific content format.

Function	System Instruction Goal	Output Format
cleanTranscriptText	Transform a raw transcript snippet into a concise, clean sentence.	string
generateTwitterThread	Convert a transcript into a 7-10 tweet viral thread.	string[] (parsed from a numbered list)
generateLinkedInPost	Create a professional LinkedIn post with a hook, body, and CTA.	LinkedInPost JSON object
generateBlogOutline	Structure a transcript into an SEO-optimized blog post outline.	BlogOutline JSON object
generateKeyTakeaways	Extract 5-7 actionable key takeaways with emojis.	KeyTakeaway[] JSON array

A generic helper, generateAIContent, is used for functions that expect a JSON response. It handles the API call, cleans the response text (removing markdown code fences), and parses it into a JavaScript object.

Sources: services/geminiService.ts:4-11, services/geminiService.ts:80-92, services/geminiService.ts:153-198

API Key Management

The application requires a user-provided Gemini API key to function. This key is managed through a settings modal and validated against the Gemini API.

The flow for validating an API key is as follows:

1. User opens the Settings modal from the Header component.
2. User enters their API key and clicks "Test Key".
3. The Header component calls validateApiKey from geminiService.
4. validateApiKey makes a minimal test call to the Gemini API (contents: 'test').
5. A boolean true or false is returned to the UI, which updates to show a valid or invalid status.

The following sequence diagram details this process.

Content Generation Flows

There are two primary workflows that trigger interaction with the Gemini API.

1. Margin Note Creation (Transcript Cleaning)

This flow is initiated when a user highlights text in the transcript and requests an AI summary.

1. User selects text in TranscriptColumn, which updates the selection state in App.tsx.
2. The FloatingActionButton appears; user clicks "Analyze".
3. App.tsx calls the addNote function from the useNotes hook.
4. addNote first checks if an API key exists. If not, it opens the settings modal.
5. If a key exists, addNote calls cleanTranscriptText(rawText) from geminiService.
6. geminiService returns the cleaned text.
7. addNote creates a new Note object and saves it to local storage.

This sequence diagram illustrates the creation of a single margin note.

2. Smart Board Content Generation

This flow is automatically triggered when a video's transcript is successfully loaded. It generates all the content for the "Smart Board" in parallel.

The useContentGenerator hook orchestrates this process. When its generateAll function is called, it executes all content generation promises (generateTwitterThread, generateLinkedInPost, etc.) concurrently using Promise.allSettled. This ensures that the failure of one generation task does not block the others. The results are collected into a single ContentOutput object, which is then cached in localStorage to prevent re-generation on subsequent loads of the same video.

The following flowchart shows the process.

Input Constraints

To manage API costs and performance, the application defines limits on the input sent to the Gemini API.

Constant	Value	Description
MAX_INPUT_LENGTH	100,000	Maximum characters for the cleanTranscriptText input.
TRANSCRIPT_SLICE	30,000	The number of characters from the start of the transcript used for generation.
MIN_TRANSCRIPT_LENGTH	500	Minimum transcript length required to trigger Smart Board generation.

Sources: constants.ts:11-15, services/geminiService.ts:26-28, hooks/useContentGenerator.ts:68-71

Summary

The Gemini API is the intelligent engine of the Nota application. It is thoughtfully integrated through a dedicated service (geminiService.ts) that provides a clean, reusable interface for various AI tasks. The system is designed for both specific, user-initiated actions (margin notes) and automated, bulk content creation (Smart Board), with robust error handling, API key management, and performance considerations like parallel execution and local storage caching. This architecture directly enables the project's vision of turning linear video content into "Random Access Intelligence".

Sources: README.md:12-13, services/geminiService.ts