Surreal Slides

Surreal Slides is a CLI tool for indexing and querying presentation files using AI. It parses slides into structured data with LlamaParse, stores them in a SurrealDB database, and exposes an agentic interface for natural language information retrieval across your presentation library.

What It Does

The tool works in two phases:

1. Preprocessing & Indexing

When you load a directory of presentations, each file goes through an AI-powered pipeline:

• Parsing: Raw slide content is extracted as text using LlamaParse.
• Structured extraction: Claude extracts structured data from each presentation according to this schema:

class Slide(BaseModel):
    slide_num: int       # Slide number
    summary: str         # AI-generated summary of the slide's content

class Presentation(BaseModel):
    title: str           # Presentation title
    slides: list[Slide]  # Ordered list of slides with summaries

• Storage: Each presentation and its slides are stored in SurrealDB using a hybrid relational/document model: the presentation is a top-level record, with its slides stored as embedded documents within it. This enables both structured queries (e.g. fetch slide 5 of presentation X) and document-style retrieval (e.g. get the full content of a presentation).

2. Agentic Querying

Once your presentations are indexed, you can query them using natural language through a Claude-powered agent. The agent is backed by an MCP server that exposes four tools over the database:

Tool	Description
list_all_files	List all indexed presentations with their slide ranges
get_full_content	Retrieve the full parsed text of a presentation
get_slide_summary	Get the AI-generated summary of a specific slide
get_many_slides_summaries	Get summaries for multiple slides at once

The agent uses these tools to navigate your presentations, cross-reference content, and answer questions — without you needing to know which file or slide contains the information.

Installation

Install from GitHub:

uv tool install git+https://github.com/run-llama/surreal-slides
slides --help # test installation

Install from source:

git clone https://github.com/run-llama/surreal-slides
cd surreal-slides/
uv pip install -e .

This will install a binary named slides.

Set Up

SurrealDB

Install the SurrealDB CLI:

curl -sSf https://install.surrealdb.com | sh

Run a SurrealDB instance locally (with on-disk backup):

surreal start --user root --pass some-password rocksdb://slides.db

Or run directly with Docker:

docker run --rm --pull always -p 8000:8000 -v $(pwd)/mydata:/mydata surrealdb/surrealdb:latest start --user root --pass some-password rocksdb:mydatabase.db

Environment Variables

You will need the following environment variables set up within your environment:

• SURREALDB_URL (defaults to ws://localhost:8000): connection URL for SurrealDB
• SURREALDB_USER (defaults to root): user for SurrealDB authentication
• SURREALDB_NS (defaults to main): namespace to use within the SurrealDB instance
• SURREALDB_DB (defaults to main): database to use within the namespace
• SURREALDB_PASSWORD (required): password for SurrealDB authentication
• ANTHROPIC_API_KEY (required): Anthropic key to run the agent
• LLAMA_CLOUD_API_KEY (required): LlamaCloud API key to parse and extract data from documents to load into the database

You can set up the necessary environment variables for slides to run with the setup wizard:

slides setup --user user --url 'ws://localhost:8000' --namespace 'slides' --database 'slides'

You will also be prompted to provide the SurrealDB database password (--password option from CLI), an Anthropic API key (--anthropic-key from CLI) and a LlamaCloud API key (--llama-cloud-key from CLI).

Loading Documents

Once SurrealDB is ready and the environment is configured, you can load all the documents into the database with:

slides load path/to/directory

This will load all the files contained in the directory (not recursively).

You can also optionally specify:

• --concurrent: maximum number of concurrent requests to run
• --verbose/--no-verbose: activate/deactivate verbose logging
• --allow-duplicates/--no-allow-duplicates: allow or disallow re-processing for a file already present within the database

Running the agent

The agent is built on top of the [Claude Agent SDK].

You can run the agent through:

slides run "your prompt"

Optionally providing a --session-id to resume a previous session.

During the session, the terminal will display all the steps taken by the agent through rich messages, as in this example:

License

This project is provided under MIT License.