Skip to content

Python API reference

ragna.local_root(path=None)

Get or set the local root directory Ragna uses for storing files.

Defaults to the value of the RAGNA_LOCAL_ROOT environment variable or otherwise to ~/.cache/ragna.

Parameters:

Name Type Description Default
path Optional[Union[str, Path]]

If passed, this is set as new local root directory.

None

Returns:

Type Description
Path

Ragnas local root directory.

ragna.core

Assistant

Abstract base class for assistants used in ragna.core.Chat

answer(messages) abstractmethod

Answer a prompt given the chat history.

Parameters:

Name Type Description Default
messages list[Message]

List of messages in the chat history. The last item is the current user prompt and has the relevant sources attached to it.

required

Returns:

Type Description
Iterator[str]

Answer.

Chat

Tip

This object is usually not instantiated manually, but rather through ragna.core.Rag.chat.

A chat needs to be prepared before prompts can be answered.

Can be used as context manager to automatically invoke prepare:

rag = Rag()

async with rag.chat(
    documents=[path],
    source_storage=ragna.core.RagnaDemoSourceStorage,
    assistant=ragna.core.RagnaDemoAssistant,
) as chat:
    print(await chat.answer("What is Ragna?"))

Parameters:

Name Type Description Default
rag Rag

The RAG workflow this chat is associated with.

required
documents Iterable[Any]

Documents to use. If any item is not a ragna.core.Document, ragna.core.LocalDocument.from_path is invoked on it.

required
source_storage Union[Type[SourceStorage], SourceStorage]

Source storage to use.

required
assistant Union[Type[Assistant], Assistant]

Assistant to use.

required
**params Any

Additional parameters passed to the source storage and assistant.

{}

answer(prompt, *, stream=False) async

Answer a prompt.

Returns:

Type Description
Message

Answer.

Raises:

Type Description
RagnaException

If chat is not prepared.

prepare() async

Prepare the chat.

This stores the documents in the selected source storage. Afterwards prompts can be answered.

Returns:

Type Description
Message

Welcome message.

Raises:

Type Description
RagnaException

If chat is already prepared.

Component

Base class for RAG components.

display_name() classmethod

Returns:

Type Description
str

Component name.

Document

Abstract base class for all documents.

get_handler(name) staticmethod

Get a document handler based on a suffix.

Parameters:

Name Type Description Default
name str

Name of the document.

required

supported_suffixes() staticmethod

Returns:

Type Description
set[str]

Suffixes, i.e. ".txt", that can be handled by the builtin ragna.core.DocumentHandlers.

DocumentHandler

Base class for all document handlers.

extract_pages(document) abstractmethod

Extract pages from a document.

Parameters:

Name Type Description Default
document Document

Document to extract pages from.

required

Returns:

Type Description
Iterator[Page]

Extracted pages.

supported_suffixes() abstractmethod classmethod

Returns:

Type Description
list[str]

Suffixes supported by this document handler.

DocxDocumentHandler

Document handler for .docx documents.

Note

This does not extract text from headers or footers.

Package requirements

LocalDocument

Document class for files on the local file system.

Tip

This object is usually not instantiated manually, but rather through ragna.core.LocalDocument.from_path.

from_path(path, *, id=None, metadata=None, handler=None) classmethod

Create a ragna.core.LocalDocument from a path.

Parameters:

Name Type Description Default
path Union[str, Path]

Local path to the file.

required
id Optional[UUID]

ID of the document. If omitted, one is generated.

None
metadata Optional[dict[str, Any]]

Optional metadata of the document.

None
handler Optional[DocumentHandler]

Document handler. If omitted, a builtin handler is selected based on the suffix of the path.

None

Raises:

Type Description
RagnaException

If metadata is passed and contains a "path" key.

Message

Data class for messages.

Attributes:

Name Type Description
role

The message producer.

sources

The sources used to produce the message.

MessageRole

Message role

Attributes:

Name Type Description
SYSTEM

The message was produced by the system. This includes the welcome message when preparing a new chat as well as error messages.

USER

The message was produced by the user.

ASSISTANT

The message was produced by an assistant.

Page

Dataclass for pages of a document

Attributes:

Name Type Description
text str

Text included in the page.

number Optional[int]

Page number.

PdfDocumentHandler

Document handler for .pdf documents.

Package requirements

PlainTextDocumentHandler

Document handler for plain-text documents. Currently supports .txt and .md extensions.

PptxDocumentHandler

Document handler for .pptx documents.

Package requirements

Rag

RAG workflow.

Tip

This class can be imported from ragna directly, e.g.

from ragna import Rag

chat(*, documents, source_storage, assistant, **params)

Create a new ragna.core.Chat.

Parameters:

Name Type Description Default
documents Iterable[Any]

Documents to use. If any item is not a ragna.core.Document, ragna.core.LocalDocument.from_path is invoked on it.

required
source_storage Union[Type[SourceStorage], SourceStorage]

Source storage to use.

required
assistant Union[Type[Assistant], Assistant]

Assistant to use.

required
**params Any

Additional parameters passed to the source storage and assistant.

{}

RagnaException

Ragna exception.

Source

Data class for sources stored inside a source storage.

Attributes:

Name Type Description
id str

Unique ID of the source.

document Document

Document this source belongs to.

location str

Location of the source inside the document.

content str

Content of the source.

num_tokens int

Number of tokens of the content.

SourceStorage

retrieve(documents, prompt) abstractmethod

Retrieve sources for a given prompt.

Parameters:

Name Type Description Default
documents list[Document]

Documents to retrieve sources from.

required
prompt str

Prompt to retrieve sources for.

required

Returns:

Type Description
list[Source]

Matching sources for the given prompt ordered by relevance.

store(documents) abstractmethod

Store content of documents.

Parameters:

Name Type Description Default
documents list[Document]

Documents to store.

required

ragna.source_storages

Chroma

Chroma vector database

Required packages

  • chromadb>=0.4.13

LanceDB

LanceDB vector database

Required packages

  • chromadb>=0.4.13
  • lancedb>=0.2
  • pyarrow

RagnaDemoSourceStorage

Demo assistant without requirements.

Note

As the name implies, this source storage is just for demo purposes and cannot retrieve relevant sources for a given prompt. It returns a single ragna.core.Source per stored ragna.core.Document with potentially shortened text extracted from the first ragna.core.Page.

ragna.assistants

ClaudeHaiku

Claude 3 Haiku

Required environment variables

  • ANTHROPIC_API_KEY

Required packages

  • httpx_sse

ClaudeOpus

Claude 3 Opus

Required environment variables

  • ANTHROPIC_API_KEY

Required packages

  • httpx_sse

ClaudeSonnet

Claude 3 Sonnet

Required environment variables

  • ANTHROPIC_API_KEY

Required packages

  • httpx_sse

Command

Cohere Command

Required environment variables

  • COHERE_API_KEY

CommandLight

Cohere Command-Light

Required environment variables

  • COHERE_API_KEY

GeminiPro

Google Gemini Pro

Required environment variables

  • GOOGLE_API_KEY

Required packages

  • ijson

GeminiUltra

Google Gemini Ultra

Required environment variables

  • GOOGLE_API_KEY

Required packages

  • ijson

Gpt35Turbo16k

OpenAI GPT-3.5

Required environment variables

  • OPENAI_API_KEY

Required packages

  • httpx_sse

Gpt4

OpenAI GPT-4

Required environment variables

  • OPENAI_API_KEY

Required packages

  • httpx_sse

Jurassic2Ultra

AI21 Labs Jurassic-2 Ultra

Required environment variables

  • AI21_API_KEY

LlamafileAssistant

llamafile

To use this assistant, start the llamafile server manually. By default, the server is expected at http://localhost:8080. This can be changed with the RAGNA_LLAMAFILE_BASE_URL environment variable.

Required packages

  • httpx_sse

OllamaGemma2B

OllamaLlama2

OllamaLlava

OllamaMistral

OllamaMixtral

OllamaOrcaMini

OllamaPhi2

RagnaDemoAssistant

Demo assistant without requirements.

Note

As the name implies, this assistant is just for demo purposes and cannot answer any questions. By default it replies with the prompt and the given sources.

If you include the phrase "markdown" into your prompt, it will return a Markdown table including emojis.

ragna.deploy

Authentication

Abstract base class for authentication used by the REST API.

create_token(request) abstractmethod async

Authenticate user and create an authorization token.

Parameters:

Name Type Description Default
request Request

Request send to the /token endpoint of the REST API.

required

Returns:

Type Description
str

Authorization token.

get_user(request) abstractmethod async

Parameters:

Name Type Description Default
request Request

Request send to any endpoint of the REST API that requires authorization.

required

Returns:

Type Description
str

Authorized user.

Config

Ragna configuration

RagnaDemoAuthentication

Demo OAuth2 password authentication without requirements.

Danger

As the name implies, this authentication is just for demo purposes and should not be used in production.

create_token(request) async

Authenticate user and create an authorization token.

User name is arbitrary. Authentication is possible in two ways:

  1. If the RAGNA_DEMO_AUTHENTICATION_PASSWORD environment variable is set, the password is checked against that.
  2. Otherwise, the password has to match the user name.

Parameters:

Name Type Description Default
request Request

Request send to the /token endpoint of the REST API. Must include the "username" and "password" as form data.

required

Returns:

Type Description
str

Authorization JWT that expires after one week.

get_user(request) async

Get user from an authorization token.

Token has to be supplied in the Bearer authentication scheme, i.e. including a Authorization: Bearer {token} header.

Parameters:

Name Type Description Default
request Request

Request send to any endpoint of the REST API that requires authorization.

required

Returns:

Type Description
str

Authorized user.