Skip to content

Python API reference

ragna.core

Assistant

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

answer(prompt, sources) abstractmethod

Answer a prompt given some sources.

Parameters:

Name Type Description Default
prompt str

Prompt to be answered.

required
sources list[Source]

Sources to use when answering answer the prompt.

required

Returns:

Type Description
str

Answer.

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.

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. Items that are not ragna.core.Documents are passed as positional argument to the configured document class.

Note

The default configuration uses ragna.core.LocalDocument as document class. It accepts a path as positional input to create it. Thus, in this configuration you can pass paths as documents.

required
source_storage Union[Type[SourceStorage], SourceStorage, str]

Source storage to use. If str can be the ragna.core.Component.display_name of any configured source storage.

required
assistant Union[Type[Assistant], Assistant, str]

Assistant to use. If str can be the ragna.core.Component.display_name of any configured assistant.

required
**params Any

Additional parameters passed to the source storage and assistant.

{}

answer(prompt) 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.

Config

Ragna configuration

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.

LocalDocument

__init__(path=None, *, id=None, name=None, metadata=None, handler=None)

Document class for files on the local file system.

Parameters:

Name Type Description Default
path Optional[str | Path]

Path to a file.

None
id Optional[UUID]

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

None
name Optional[str]

Name of the document. If omitted, is inferred from the path or the metadata.

None
metadata Optional[dict[str, Any]]

Metadata of the document. If not included, path will be added under the "path" key.

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 path is omitted and and also not passed as part of metadata.

RagnaException

If path is passed directly and as part of metadata.

Message

Data class for messages.

Attributes:

Name Type Description
content str

The content of the message.

role MessageRole

The message producer.

sources list[Source]

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

Rag

RAG workflow.

Parameters:

Name Type Description Default
config Optional[Config]

Ragna configuration.

None
load_components Optional[bool]

Whether to load the configured components in the current process. If omitted, components will be loaded if a memory queue is configured.

None

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

Create a new ragna.core.Chat.

Parameters:

Name Type Description Default
documents Iterable[Any]

Documents to use. Items that are not ragna.core.Documents are passed as positional argument to the configured document class.

Note

The default configuration uses ragna.core.LocalDocument as document class. It accepts a path as positional input to create it. Thus, in this configuration you can pass paths as documents.

required
source_storage Union[Type[SourceStorage], SourceStorage, str]

Source storage to use. If str can be the ragna.core.Component.display_name of any configured source storage.

required
assistant Union[Type[Assistant], Assistant, str]

Assistant to use. If str can be the ragna.core.Component.display_name of any configured assistant.

required
**params Any

Additional parameters passed to the source storage and assistant.

{}

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.

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

TxtDocumentHandler

Document handler for .txt documents.

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

Claude

Claude

Required environment variables

  • ANTHROPIC_API_KEY

ClaudeInstant

Claude Instant

Required environment variables

  • ANTHROPIC_API_KEY

Gpt35Turbo16k

OpenAI GPT-3.5

Required environment variables

  • OPENAI_API_KEY

Gpt4

OpenAI GPT-4

Required environment variables

  • OPENAI_API_KEY

Mpt30bInstruct

MPT-30B-Instruct

Required environment variables

  • MOSAICML_API_KEY

Mpt7bInstruct

MPT-7B-Instruct

Required environment variables

  • MOSAICML_API_KEY

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.