Third-Party Services

Uxie integrates with several third-party services to provide its core functionality. This guide covers setup and configuration for each service.

UploadThing (File Storage)

UploadThing handles PDF file uploads and storage for Uxie.

Setup

Go to UploadThing Dashboard
Sign in and create a new app
Copy your API token from the dashboard
Add to .env:

UPLOADTHING_TOKEN=your-uploadthing-token

Configuration

Uxie’s UploadThing configuration in src/server/uploadthing.ts:

Max File Size

8MB

Maximum PDF file size per upload

Max File Count

Number of files per upload request

Accepted File Types

pdf

Only PDF files are accepted

Plan Limits

Upload limits are enforced based on user’s subscription plan:

const userPlan = session?.user.plan ?? FREE_PLAN;
const allowedDocsCount = PLANS[userPlan].maxDocs;

if (userFilesCount >= allowedDocsCount) {
  throw new Error(
    "You have reached the maximum number of documents allowed for your plan"
  );
}

Upload Flow

Middleware: Checks authentication and plan limits
Upload: File is uploaded to UploadThing servers
Processing: PDF is loaded and page count extracted
Cover Generation: First page is converted to cover image
Database: Document record is created in Prisma

UploadThing automatically handles CDN distribution and provides optimized file delivery.

Pinecone (Vector Database)

Pinecone stores document embeddings for semantic search and chat functionality.

Setup

Go to Pinecone Console
Sign up and create a new index
Index configuration:
- Name: uxie
- Dimensions: 768 (for BAAI/bge-base-en-v1.5 embeddings)
- Metric: cosine
- Environment: Choose your region (e.g., us-east-1-aws)
Copy your API key
Add to .env:

PINECONE_API_KEY=your-pinecone-api-key
PINECONE_ENVIRONMENT=us-east-1-aws

Integration

Uxie uses Pinecone through the LangChain integration:

import { Pinecone } from "@pinecone-database/pinecone";
import { PineconeStore } from "langchain/vectorstores/pinecone";

const getPineconeClient = () => {
  return new Pinecone({
    apiKey: env.PINECONE_API_KEY,
  });
};

const pineconeIndex = getPineconeClient().Index("uxie");

Document Vectorization

When a document is uploaded:

PDF is split into chunks using RecursiveCharacterTextSplitter
Text chunks are embedded using Hugging Face embeddings
Vectors are stored in Pinecone with document metadata
Document is marked as isVectorised: true in database

Make sure your Pinecone index dimensions (768) match your embedding model’s output dimensions.

Metadata Structure

{
  documentId: string,
  pageNumber: number,
  text: string,
  // Additional custom metadata
}

Hugging Face (Embeddings)

Hugging Face provides text embeddings for document vectorization.

Setup

Go to Hugging Face
Sign up and go to Settings > Tokens
Create a new token with read access
Add to .env:

HUGGINGFACE_API_KEY=your-huggingface-api-key

Embedding Model

Uxie uses the BAAI/bge-base-en-v1.5 model:

Dimensions: 768
Max sequence length: 512 tokens
Performance: High-quality embeddings for semantic search
Use case: Document vectorization and similarity search

Implementation

import { InferenceClient } from "@huggingface/inference";

const createHuggingFaceEmbeddings = () => {
  const hf = new InferenceClient(env.HUGGINGFACE_API_KEY);
  
  return new (class extends Embeddings {
    async embedDocuments(texts: string[]): Promise<number[][]> {
      const embeddings = await Promise.all(
        texts.map(async (text) => {
          const result = await hf.featureExtraction({
            model: "BAAI/bge-base-en-v1.5",
            inputs: text,
          });
          return parseEmbeddingResult(result);
        })
      );
      return embeddings;
    }
  })();
};

Hugging Face Inference API has rate limits on the free tier. For production use, consider upgrading or hosting your own embedding model.

Google Gemini (AI Models)

Google’s Gemini models power chat, summarization, and flashcard generation.

Setup

Go to Google AI Studio
Create a new API key
Add to .env:

GOOGLE_GENERATIVE_AI_API_KEY=your-gemini-api-key

Models Used

Gemini 2.5 Flash

Used for:

Document chat (/api/chat/route.ts)
Document summarization (/lib/summarize.ts)
Flashcard generation (/lib/flashcard.ts)
Text completion (/api/completion/route.ts)

Characteristics:

Fast inference
Cost-effective
Good for real-time interactions

import { google } from "@ai-sdk/google";

model: google("gemini-2.5-flash")

Gemini 1.5 Pro

Used for:

Flashcard answer evaluation (/api/evaluate/route.ts)

Characteristics:

Higher reasoning capability
Better for complex analysis
More accurate evaluation

model: google("gemini-1.5-pro")

Usage Example

import { streamText } from "ai";
import { google } from "@ai-sdk/google";

const result = await streamText({
  model: google("gemini-2.5-flash"),
  messages: [
    {
      role: "system",
      content: "You are a helpful document assistant."
    },
    {
      role: "user",
      content: "Summarize this document..."
    }
  ],
});

Gemini API has usage quotas. Monitor your usage in Google AI Studio and upgrade if needed.

Liveblocks (Real-time Collaboration)

Liveblocks enables real-time collaboration features for document annotations and sharing.

Setup

Go to Liveblocks Dashboard
Create a new project
Copy your public API key (not secret key)
Add to .env:

NEXT_PUBLIC_LIVEBLOCKS_PUBLIC_API_KEY=your-liveblocks-public-key

Use the public key (prefixed with NEXT_PUBLIC_) since it will be exposed to the client. Never use the secret key in client-side code.

Configuration

Liveblocks is configured in liveblocks.config.ts:

import { createClient } from "@liveblocks/client";
import { createRoomContext } from "@liveblocks/react";

const client = createClient({
  publicApiKey: env.NEXT_PUBLIC_LIVEBLOCKS_PUBLIC_API_KEY,
});

export const {
  RoomProvider,
  useMyPresence,
  useOthers,
  // ... other hooks
} = createRoomContext(client);

Features Enabled

Presence: See who else is viewing the document
Live cursors: Track user positions in real-time
Collaboration: Multiple users editing annotations
Comments: Real-time commenting on documents

Usage

import { RoomProvider } from "@/liveblocks.config";

function DocumentViewer({ documentId }) {
  return (
    <RoomProvider id={documentId}>
      {/* Your collaborative features */}
    </RoomProvider>
  );
}

Liveblocks automatically handles connection management, reconnection, and conflict resolution.

Service Comparison

Service	Purpose	Pricing Tier	Rate Limits
UploadThing	File storage	Free: 2GB storage	100 uploads/month (free)
Pinecone	Vector database	Free: 1 index	100K vectors (free)
Hugging Face	Embeddings	Free API	Rate limited
Google Gemini	AI models	Pay per token	Generous free quota
Liveblocks	Real-time sync	Free: 100 MAU	Unlimited rooms (free)

MAU = Monthly Active Users. Liveblocks counts users who connect to a room in a given month.

Cost Optimization Tips

UploadThing

Compress PDFs before upload when possible
Delete unused documents to free up storage
Consider upgrading for production use

Pinecone

Use namespace filtering to reduce vector count
Delete old document vectors when documents are removed
Monitor index size in Pinecone dashboard

Hugging Face

Cache embeddings for frequently accessed documents
Batch embedding requests when possible
Consider self-hosting for high-volume use

Google Gemini

Use Gemini 2.5 Flash for most operations (cheaper)
Reserve Gemini 1.5 Pro for complex tasks
Implement token limits on user inputs
Cache common responses when appropriate

Liveblocks

Clean up inactive rooms periodically
Use presence awareness to optimize updates
Monitor MAU usage in dashboard

Environment Variables Summary

.env

# UploadThing
UPLOADTHING_TOKEN=your-uploadthing-token

# Pinecone
PINECONE_API_KEY=your-pinecone-api-key
PINECONE_ENVIRONMENT=us-east-1-aws

# Hugging Face
HUGGINGFACE_API_KEY=your-huggingface-api-key

# Google Gemini
GOOGLE_GENERATIVE_AI_API_KEY=your-gemini-api-key

# Liveblocks
NEXT_PUBLIC_LIVEBLOCKS_PUBLIC_API_KEY=your-liveblocks-public-key

Testing Your Configuration

Verify each service is configured correctly:

UploadThing

# Try uploading a test PDF through the UI
# Check UploadThing dashboard for successful uploads

Pinecone

import { getPineconeClient } from "@/lib/pinecone";

const client = getPineconeClient();
const indexes = await client.listIndexes();
console.log(indexes); // Should include "uxie"

Hugging Face

import { InferenceClient } from "@huggingface/inference";

const hf = new InferenceClient(process.env.HUGGINGFACE_API_KEY);
const result = await hf.featureExtraction({
  model: "sentence-transformers/all-MiniLM-L6-v2",
  inputs: "test",
});
console.log(result); // Should return array of numbers

Google Gemini

import { google } from "@ai-sdk/google";
import { generateText } from "ai";

const result = await generateText({
  model: google("gemini-2.5-flash"),
  prompt: "Say hello",
});
console.log(result.text); // Should return a greeting

Liveblocks

// Check browser console for successful connection
// Should see: "Liveblocks: Connected to room"

Get Started

Core Features

Advanced Features

Configuration

​UploadThing (File Storage)

​Setup

​Configuration

​Plan Limits

​Upload Flow

​Pinecone (Vector Database)

​Setup

​Integration

​Document Vectorization

​Metadata Structure

​Hugging Face (Embeddings)

​Setup

​Embedding Model

​Implementation

​Google Gemini (AI Models)

​Setup

​Models Used

​Usage Example

​Liveblocks (Real-time Collaboration)

​Setup

​Configuration

​Features Enabled

​Usage

​Service Comparison

​Cost Optimization Tips

​UploadThing

​Pinecone

​Hugging Face

​Google Gemini

​Liveblocks

​Environment Variables Summary

​Testing Your Configuration

​UploadThing

​Pinecone

​Hugging Face

​Google Gemini

​Liveblocks

Build docs developers (and LLMs) love

UploadThing (File Storage)

Setup

Configuration

Plan Limits

Upload Flow

Pinecone (Vector Database)

Setup

Integration

Document Vectorization

Metadata Structure

Hugging Face (Embeddings)

Setup

Embedding Model

Implementation

Google Gemini (AI Models)

Setup

Models Used

Usage Example

Liveblocks (Real-time Collaboration)

Setup

Configuration

Features Enabled

Usage

Service Comparison

Cost Optimization Tips

UploadThing

Pinecone

Hugging Face

Google Gemini

Liveblocks

Environment Variables Summary

Testing Your Configuration

UploadThing

Pinecone

Hugging Face

Google Gemini

Liveblocks