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:
- Elasticsearch
- MongoDB
- OpenStack Swift
- AWS S3
- OVH Logs Data Platform*
- WebSocket
- File system
* 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).