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 `prepare`d.

`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 `prepare`d.

`Component`

Base class for RAG components.

Tip

ragna.core.SourceStorage
ragna.core.Assistant

`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

python-docx

`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

pymupdf

`PlainTextDocumentHandler`

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

`PptxDocumentHandler`

Document handler for .pptx documents.

Package requirements

python-pptx

`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.