Introduction¶

Ralph is a toolbox for your learning analytics, it can be used as a:

library, to read learning events from various backends, (de)serialize or convert them from various standard formats such as xAPI,
command-line interface (CLI), to build data pipelines the UNIX-way™️,
HTTP API server, to collect xAPI statements (learning events) following the ADL LRS standard.

Supported backends¶

As a library or a CLI, you will be able to read and write from/to the following backends:

* read-only backend

The LRS server currently supports the following backends to store learning traces in xAPI format:

Elasticsearch
MongoDB

CLI key concepts¶

At first, Ralph has been designed as a CLI to batch process your logs using base commands and UNIX standard streams (stdin, stdout) to connect them in a pipeline. A base example pipeline may be:

$ ralph read --backend swift my_archive.gzip | \
    gunzip | \
    ralph write --backend es

In this small pipeline, we stream my_archive.gzip content from a Swift container to the standard output (using the read command), uncompress the content (using the gunzip command), and bulk insert logs in an ElasticSearch index (using the write command).

As UNIX is beautiful, Ralph offers many powerful possibilities by combining its commands with other standard commands or command line tools.

Quick start guide¶

Ralph is distributed as a python package and a Docker image.

If you choose to install ralph in your native environment (without using Docker), please make sure that Python 3.11 is installed (and your default python distribution).

Ralph package can be installed from PyPI using the pip tool:

# Create a new virtualenv (optional)
$ python3.11 -m venv venv
$ source venv/bin/activate

# Install the full package (in a virtualenv)
(venv) $ pip install \
    ralph-malph[backend-es,backend-ldp,backend-lrs,backend-mongo,backend-swift,backend-ws,cli,lrs]

# Install only the core package with the Elasticsearch backend and the LRS (in
# a virtualenv)
(venv) $ pip install ralph-malph[backend-es,lrs]

# Test the ralph command (it should be in your PATH)
(venv) $ ralph --help

If you only need to integrate ralph models in your project, you don’t need to install the backends, cli or lrs extra dependencies, the core package is what you need:

# Install the core library (in a virtualenv)
(venv) $ pip install ralph-malph

Alternatively, Docker users can pull the latest ralph image and start playing with it:

# Pull latest docker image and get usage
$ docker run --rm -i fundocker/ralph:latest ralph --help

# Pro tip: define an alias to ease your life
$ alias ralph="docker run --rm -i fundocker/ralph:latest ralph"

Now that ralph can be run from your system, we invite you to explore available commands.

Contributing¶

This project is intended to be community-driven, so please, do not hesitate to get in touch if you have any questions related to our implementation or design decisions.

We try to raise our code quality standards and expect contributors to follow the recommendations from our handbook.

License¶

This work is released under the MIT License (see LICENSE).