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

`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

pymupdf

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

If the RAGNA_DEMO_AUTHENTICATION_PASSWORD environment variable is set, the password is checked against that.
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.