Ralph

⚙️ The ultimate toolbox for your learning analytics (expect some xAPI ❤️)

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

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

What is an LRS?

A Learning Record Store, or LRS, is a key component in the context of learning analytics and the Experience API (xAPI).

The Experience API (or Tin Can API) is a standard for tracking and reporting learning experiences. In particular, it defines:

• the xAPI format of the learning events. xAPI statements include an actor, a verb, an object as well as contextual information. Here’s an example statement:

  {
      "id": "12345678-1234-5678-1234-567812345678",
      "actor":{
          "mbox":"mailto:xapi@adlnet.gov"
      },
      "verb":{
          "id":"http://adlnet.gov/expapi/verbs/created",
          "display":{
              "en-US":"created"
          }
      },
      "object":{
          "id":"http://example.adlnet.gov/xapi/example/activity"
      }
  }
  

• the Learning Record Store (LRS), is a RESTful API that collects, stores and retrieves these events. Think of it as a learning database that unifies data from various learning platforms and applications. These events can come from an LMS (Moodle, edX), or any other learning component that supports sending xAPI statements to an LRS (e.g. an embedded video player), from various platforms.

xAPI specification version

In Ralph, we’re following the xAPI specification 1.0.3 that you can find here.

For your information, xAPI specification 2.0 is out! It’s not currently supported in Ralph, but you can check it here.

Installation

Install from PyPI

Ralph is distributed as a standard python package; it can be installed via pip or any other python package manager (e.g. Poetry, Pipenv, etc.):

Use a virtual environment for installation

To maintain a clean and controlled environment when installing ralph-malph, consider using a virtual environment.

• Create a virtual environment:

  python3.12 -m venv <path-to-virtual-environment>
  

• Activate the virtual environment:

  source venv/bin/activate
  

If you want to generate xAPI statements from your application and only need to integrate learning statement models in your project, you don’t need to install the backends, cli or lrs extra dependencies, the core library is what you need:

pip install ralph-malph

If you want to use the Ralph LRS server, add the lrs flavour in your installation. You also have to choose the type of backend you will use for LRS data storage (backend-clickhouse,backend-es,backend-mongo).

• Install the core package with the LRS and the Elasticsearch backend. For example:

pip install ralph-malph[backend-es,lrs]

• Add the cli flavour if you want to use the LRS on the command line:

pip install ralph-malph[backend-es,lrs,cli]

• If you want to play around with backends with Ralph as a library, you can install:

pip install ralph-malph[backends]

• If you have various uses for Ralph’s features or would like to discover all the existing functionnalities, it is recommended to install the full package:

pip install ralph-malph[full]

Install from DockerHub

Ralph is distributed as a Docker image. If Docker is installed on your machine, it can be pulled from DockerHub:

docker run --rm -i fundocker/ralph:latest ralph --help

Use a ralph alias in your local environment

Simplify your workflow by creating an alias for easy access to Ralph commands:

alias ralph="docker run --rm -i fundocker/ralph:latest ralph"

LRS specification compliance

WIP.

Contributing to Ralph

If you’re interested in contributing to Ralph, whether it’s by reporting issues, suggesting improvements, or submitting code changes, please head over to our dedicated Contributing to Ralph page. There, you’ll find detailed guidelines and instructions on how to take part in the project.

We look forward to your contributions and appreciate your commitment to making Ralph a more valuable tool for everyone.

Contributors

License

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