From e1f4383e81c95993141bd596908ab5da13698716 Mon Sep 17 00:00:00 2001
From: FUN MOOC Bot <funmoocbot@users.noreply.github.com>
Date: Thu, 30 Nov 2023 16:41:49 +0000
Subject: [PATCH] Deployed ee1dcd9 to master with MkDocs 1.5.3 and mike 2.0.0

---
 master/CHANGELOG/index.html     |   2 ++
 master/api/index.html           |   4 ++--
 master/index.html               |   2 +-
 master/search/search_index.json |   2 +-
 master/sitemap.xml              |  24 ++++++++++++------------
 master/sitemap.xml.gz           | Bin 325 -> 324 bytes
 6 files changed, 18 insertions(+), 16 deletions(-)

diff --git a/master/CHANGELOG/index.html b/master/CHANGELOG/index.html
index 0aed403a1..3038868d9 100644
--- a/master/CHANGELOG/index.html
+++ b/master/CHANGELOG/index.html
@@ -1956,6 +1956,8 @@ <h3 id="added">Added<a class="headerlink" href="#added" title="Permanent link">&
 </ul>
 <h3 id="changed">Changed<a class="headerlink" href="#changed" title="Permanent link">&para;</a></h3>
 <ul>
+<li>Upgrade base python version to 3.12 for the development stack and Docker
+  image</li>
 <li>Upgrade <code>cachetools</code> to <code>5.3.2</code></li>
 <li>Refactor <code>database</code> and <code>storage</code> backends under the unified <code>data</code> backend
 interface [BC]</li>
diff --git a/master/api/index.html b/master/api/index.html
index b1c900555..c078cc22a 100644
--- a/master/api/index.html
+++ b/master/api/index.html
@@ -1657,7 +1657,7 @@ <h3 id="put_xapistatements"><span class="http-put">PUT</span> /xAPI/statements/<
 <div class="tabbed-block">
 <p><div class="language-json highlight"><pre><span></span><code><span id="__span-22-1"><a id="__codelineno-22-1" name="__codelineno-22-1" href="#__codelineno-22-1"></a><span class="p">{</span>
 </span><span id="__span-22-2"><a id="__codelineno-22-2" name="__codelineno-22-2" href="#__codelineno-22-2"></a><span class="w">    </span><span class="nt">&quot;actor&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span>
-</span><span id="__span-22-3"><a id="__codelineno-22-3" name="__codelineno-22-3" href="#__codelineno-22-3"></a><span class="w">    </span><span class="nt">&quot;id&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;80fd65b0-85f8-4b64-a678-bd39624402fe&quot;</span><span class="p">,</span>
+</span><span id="__span-22-3"><a id="__codelineno-22-3" name="__codelineno-22-3" href="#__codelineno-22-3"></a><span class="w">    </span><span class="nt">&quot;id&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;292e8ffe-4ed4-460b-b307-16a7a5c14213&quot;</span><span class="p">,</span>
 </span><span id="__span-22-4"><a id="__codelineno-22-4" name="__codelineno-22-4" href="#__codelineno-22-4"></a><span class="w">    </span><span class="nt">&quot;object&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
 </span><span id="__span-22-5"><a id="__codelineno-22-5" name="__codelineno-22-5" href="#__codelineno-22-5"></a><span class="w">        </span><span class="nt">&quot;id&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;string&quot;</span>
 </span><span id="__span-22-6"><a id="__codelineno-22-6" name="__codelineno-22-6" href="#__codelineno-22-6"></a><span class="w">    </span><span class="p">},</span>
@@ -2333,7 +2333,7 @@ <h3 id="put_xapistatements_1"><span class="http-put">PUT</span> /xAPI/statements
 <div class="tabbed-block">
 <p><div class="language-json highlight"><pre><span></span><code><span id="__span-42-1"><a id="__codelineno-42-1" name="__codelineno-42-1" href="#__codelineno-42-1"></a><span class="p">{</span>
 </span><span id="__span-42-2"><a id="__codelineno-42-2" name="__codelineno-42-2" href="#__codelineno-42-2"></a><span class="w">    </span><span class="nt">&quot;actor&quot;</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span>
-</span><span id="__span-42-3"><a id="__codelineno-42-3" name="__codelineno-42-3" href="#__codelineno-42-3"></a><span class="w">    </span><span class="nt">&quot;id&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;282bcef8-665d-4e92-ac4a-049c5cfb93e4&quot;</span><span class="p">,</span>
+</span><span id="__span-42-3"><a id="__codelineno-42-3" name="__codelineno-42-3" href="#__codelineno-42-3"></a><span class="w">    </span><span class="nt">&quot;id&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;6b700e1f-3e01-4218-85c1-7d3be1b1f319&quot;</span><span class="p">,</span>
 </span><span id="__span-42-4"><a id="__codelineno-42-4" name="__codelineno-42-4" href="#__codelineno-42-4"></a><span class="w">    </span><span class="nt">&quot;object&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
 </span><span id="__span-42-5"><a id="__codelineno-42-5" name="__codelineno-42-5" href="#__codelineno-42-5"></a><span class="w">        </span><span class="nt">&quot;id&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;string&quot;</span>
 </span><span id="__span-42-6"><a id="__codelineno-42-6" name="__codelineno-42-6" href="#__codelineno-42-6"></a><span class="w">    </span><span class="p">},</span>
diff --git a/master/index.html b/master/index.html
index 20f3cf670..012b89588 100644
--- a/master/index.html
+++ b/master/index.html
@@ -944,7 +944,7 @@ <h3 id="install_from_pypi">Install from PyPI<a class="headerlink" href="#install
 <ul>
 <li>
 <p>Create a virtual environment:
-<div class="language-bash highlight"><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>python3.11<span class="w"> </span>-m<span class="w"> </span>venv<span class="w"> </span>&lt;path-to-virtual-environment&gt;
+<div class="language-bash highlight"><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>python3.12<span class="w"> </span>-m<span class="w"> </span>venv<span class="w"> </span>&lt;path-to-virtual-environment&gt;
 </span></code></pre></div></p>
 </li>
 <li>
diff --git a/master/search/search_index.json b/master/search/search_index.json
index 6b3656d47..b390ec1d7 100644
--- a/master/search/search_index.json
+++ b/master/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Ralph","text":"<p> \u2699\ufe0f The ultimate toolbox for your learning analytics (expect some xAPI \u2764\ufe0f)  </p> <p> </p> <p>Ralph is a toolbox for your learning analytics, it can be used as a:</p> <ul> <li>LRS, a HTTP API server to collect xAPI statements (learning events), following the ADL LRS standard</li> <li>command-line interface (CLI), to build data pipelines the UNIX-way\u2122\ufe0f,</li> <li>library, to fetch learning events from various backends, (de)serialize or     convert them from and to various standard formats such as     xAPI, or     openedx</li> </ul>"},{"location":"#installation","title":"Installation","text":""},{"location":"#install_from_pypi","title":"Install from PyPI","text":"<p>Ralph is distributed as a standard python package; it can be installed via <code>pip</code> or any other python package manager (e.g. Poetry, Pipenv, etc.):</p> Use a virtual environment for installation <p>To maintain a clean and controlled environment when installing <code>ralph-malph</code>, consider using a virtual environment.</p> <ul> <li> <p>Create a virtual environment: <pre><code>python3.11 -m venv &lt;path-to-virtual-environment&gt;\n</code></pre></p> </li> <li> <p>Activate the virtual environment: <pre><code>source venv/bin/activate\n</code></pre></p> </li> </ul> <p>If you only need to integrate learning statement models feature in your project, you don\u2019t need to install the <code>backends</code>, <code>cli</code> or <code>lrs</code> extra dependencies, the core library is what you need:</p> <pre><code>pip install ralph-malph\n</code></pre> <p>If you want to use the Ralph LRS server, add the <code>lrs</code> flavour in your installation.  You also have to choose the type of backend you will use for LRS data storage (<code>backend-clickhouse</code>,<code>backend-es</code>,<code>backend-mongo</code>).</p> <ul> <li>Install the core package with the LRS and the Elasticsearch backend. For example:</li> </ul> <pre><code>pip install ralph-malph[backend-es,lrs]\n</code></pre> <ul> <li>Add the <code>cli</code> flavour if you want to use the LRS on the command line: </li> </ul> <pre><code>pip install ralph-malph[backend-es,lrs,cli]\n</code></pre> <ul> <li>If you have various uses for Ralph\u2019s features or would like to discover all the existing functionnalities, it is recommended to install the full package: </li> </ul> <pre><code>pip install ralph-malph[backend-clickhouse,backend-es,backend-ldp,backend-lrs,backend-mongo,backend-s3,backend-swift,backend-ws,cli,lrs]\n</code></pre>"},{"location":"#install_from_dockerhub","title":"Install from DockerHub","text":"<p>Ralph is distributed as a Docker image. If Docker is installed on your machine, it can be pulled from DockerHub:</p> <pre><code>docker run --rm -i fundocker/ralph:latest ralph --help\n</code></pre> Use a <code>ralph</code> alias in your local environment <p>Simplify your workflow by creating an alias for easy access to Ralph commands:</p> <pre><code>alias ralph=\"docker run --rm -i fundocker/ralph:latest ralph\"\n</code></pre>"},{"location":"#wip_start_using_ralph","title":"[WIP] Start using Ralph","text":""},{"location":"#contributing_to_ralph","title":"Contributing to Ralph","text":"<p>If you\u2019re interested in contributing to Ralph, whether it\u2019s by reporting issues, suggesting improvements, or submitting code changes, please head over to our dedicated Contributing to Ralph page.  There, you\u2019ll find detailed guidelines and instructions on how to take part in the project.</p> <p>We look forward to your contributions and appreciate your commitment to making Ralph a more valuable tool for everyone.</p>"},{"location":"#contributors","title":"Contributors","text":""},{"location":"#license","title":"License","text":"<p>This work is released under the MIT License (see LICENSE).</p>"},{"location":"CHANGELOG/","title":"Changelog","text":"<p>All notable changes to this project will be documented in this file.</p> <p>The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.</p>"},{"location":"CHANGELOG/#unreleased","title":"Unreleased","text":""},{"location":"CHANGELOG/#added","title":"Added","text":"<ul> <li>Implement Pydantic model for LRS Statements resource query parameters</li> <li>Implement xAPI LMS Profile statements validation</li> <li><code>EdX</code> to <code>xAPI</code> converters for enrollment events</li> <li>Backends: Add <code>Writable</code> and <code>Listable</code> interfaces to distinguish supported   functionalities among <code>data</code> backends</li> <li>Backends: Add <code>get_backends</code> function to automatically discover backends   for CLI and LRS usage</li> </ul>"},{"location":"CHANGELOG/#changed","title":"Changed","text":"<ul> <li>Upgrade <code>cachetools</code> to <code>5.3.2</code></li> <li>Refactor <code>database</code> and <code>storage</code> backends under the unified <code>data</code> backend interface [BC]</li> <li>Refactor LRS <code>query_statements</code> and <code>query_statements_by_ids</code> backends methods under the unified <code>lrs</code> backend interface [BC]</li> <li>Refactor LRS Statements resource query parameters defined for <code>ralph</code> API</li> <li>User credentials must now include an \u201cagent\u201d field which can be created   using the cli</li> <li><code>GET /statements</code> now has \u201cmine\u201d option which matches statements that have an authority field matching that of the user</li> <li>CLI: change <code>push</code> to <code>write</code> and <code>fetch</code> to <code>read</code> [BC]</li> <li>Upgrade <code>fastapi</code> to <code>0.104.1</code></li> <li>Upgrade <code>sentry_sdk</code> to <code>1.34.0</code></li> <li>Upgrade <code>uvicorn</code> to <code>0.24.0.post1</code></li> <li>API: Invalid parameters now return 400 status code</li> <li>API: Forwarding PUT now uses PUT (instead of POST)</li> <li>Models: The xAPI <code>context.contextActivities.category</code> field is now mandatory   in the video and virtual classroom profiles. [BC]</li> <li>Backends: <code>LRSHTTP</code> methods must not be used in <code>asyncio</code> events loop (BC)</li> <li>Add variable to override PVC name in arnold deployment</li> <li>Backends: add <code>max_statements</code> option to <code>AsyncLRSHTTP</code></li> <li>API: Incoming statements are enriched with <code>id</code>, <code>timestamp</code>, <code>stored</code>   and <code>authority</code></li> <li>Backends: update <code>statementId</code> and <code>voidedStatementId</code> to snake_case,   with camelCase alias, in <code>LRSStatementsQuery</code></li> <li>API: Add <code>RALPH_LRS_RESTRICT_BY_AUTHORITY</code> option making <code>?mine=True</code>   implicit</li> <li>CLI: list cli usage strings in alphabetical order</li> <li>API: Add <code>RALPH_LRS_RESTRICT_BY_SCOPE</code> option enabling endpoint access   control by user scopes</li> <li>Backends: Replace reference to a JSON column in ClickHouse with    function calls on the String column [BC]</li> <li>API: enhance \u2018limit\u2019 query parameter\u2019s validation </li> <li>API: Variable <code>RUNSERVER_AUTH_BACKEND</code> becomes <code>RUNSERVER_AUTH_BACKENDS</code>, and   multiple authentication methods are supported simultaneously</li> </ul>"},{"location":"CHANGELOG/#fixed","title":"Fixed","text":"<ul> <li>API: Fix a typo (\u2018attachements\u2019 -&gt; \u2018attachments\u2019) to ensure compliance with     the LRS specification and prevent potential silent bugs.</li> </ul>"},{"location":"CHANGELOG/#removed","title":"Removed","text":"<ul> <li><code>school</code>, <code>course</code>, <code>module</code> context extensions in Edx to xAPI base converter</li> <li><code>name</code> field in <code>VideoActivity</code> xAPI model mistakenly used in <code>video</code> profile</li> <li>drop support for python 3.7</li> </ul>"},{"location":"CHANGELOG/#390_-_2023-07-21","title":"3.9.0 - 2023-07-21","text":""},{"location":"CHANGELOG/#changed_1","title":"Changed","text":"<ul> <li>Upgrade <code>fastapi</code> to <code>0.100.0</code></li> <li>Upgrade <code>sentry_sdk</code> to <code>1.28.1</code></li> <li>Upgrade <code>uvicorn</code> to <code>0.23.0</code></li> <li>Enforce valid IRI for <code>activity</code> parameter in <code>GET /statements</code></li> <li>Change how duplicate xAPI statements are handled for <code>clickhouse</code> backend</li> </ul>"},{"location":"CHANGELOG/#380_-_2023-06-21","title":"3.8.0 - 2023-06-21","text":""},{"location":"CHANGELOG/#added_1","title":"Added","text":"<ul> <li>Implement edX open response assessment events pydantic models</li> <li>Implement edx peer instruction events pydantic models</li> <li>Implement xAPI VideoDownloaded pydantic model   (using xAPI TinCan <code>downloaded</code> verb)</li> </ul>"},{"location":"CHANGELOG/#changed_2","title":"Changed","text":"<ul> <li>Allow to use a query for HTTP backends in the CLI</li> </ul>"},{"location":"CHANGELOG/#370_-_2023-06-13","title":"3.7.0 - 2023-06-13","text":""},{"location":"CHANGELOG/#added_2","title":"Added","text":"<ul> <li>Implement asynchronous <code>async_lrs</code> backend</li> <li>Implement synchronous <code>lrs</code> backend</li> <li>Implement xAPI virtual classroom pydantic models</li> <li>Allow to insert custom endpoint url for S3 service</li> <li>Cache the HTTP Basic auth credentials to improve API response time</li> <li>Support OpenID Connect authentication method</li> </ul>"},{"location":"CHANGELOG/#changed_3","title":"Changed","text":"<ul> <li>Clean xAPI pydantic models naming convention</li> <li>Upgrade <code>fastapi</code> to <code>0.97.0</code></li> <li>Upgrade <code>sentry_sdk</code> to <code>1.25.1</code></li> <li>Set Clickhouse <code>client_options</code> to a dedicated pydantic model</li> <li>Upgrade <code>httpx</code> to <code>0.24.1</code></li> <li>Force a valid (JSON-formatted) IFI to be passed for the <code>/statements</code> GET query <code>agent</code> filtering</li> <li>Upgrade <code>cachetools</code> to <code>5.3.1</code></li> </ul>"},{"location":"CHANGELOG/#removed_1","title":"Removed","text":"<ul> <li><code>verb</code>.<code>display</code> field no longer mandatory in xAPI models and for converter</li> </ul>"},{"location":"CHANGELOG/#360_-_2023-05-17","title":"3.6.0 - 2023-05-17","text":""},{"location":"CHANGELOG/#added_3","title":"Added","text":"<ul> <li>Allow to ignore health check routes for Sentry transactions</li> </ul>"},{"location":"CHANGELOG/#changed_4","title":"Changed","text":"<ul> <li>Upgrade <code>sentry_sdk</code> to <code>1.22.2</code></li> <li>Upgrade <code>uvicorn</code> to <code>0.22.0</code></li> <li>LRS <code>/statements</code> <code>GET</code> method returns a code 400 with certain parameters as per the xAPI specification</li> <li>Use batch/v1 api in cronjob_pipeline manifest</li> <li>Use autoscaling/v2 in HorizontalPodAutoscaler manifest</li> </ul>"},{"location":"CHANGELOG/#fixed_1","title":"Fixed","text":"<ul> <li>Fix the <code>more</code> IRL building in LRS <code>/statements</code> GET requests</li> </ul>"},{"location":"CHANGELOG/#351_-_2023-04-18","title":"3.5.1 - 2023-04-18","text":""},{"location":"CHANGELOG/#changed_5","title":"Changed","text":"<ul> <li>Upgrade <code>httpx</code> to <code>0.24.0</code></li> <li>Upgrade <code>fastapi</code> to <code>0.95.1</code></li> <li>Upgrade <code>sentry_sdk</code> to <code>1.19.1</code></li> <li>Upgrade <code>uvicorn</code> to <code>0.21.1</code></li> </ul>"},{"location":"CHANGELOG/#fixed_2","title":"Fixed","text":"<ul> <li>An issue with starting Ralph in pre-built Docker containers</li> <li>Fix double quoting in ClickHouse backend server parameters</li> <li>An issue Ralph starting when ClickHouse is down</li> </ul>"},{"location":"CHANGELOG/#350_-_2023-03-08","title":"3.5.0 - 2023-03-08","text":""},{"location":"CHANGELOG/#added_4","title":"Added","text":"<ul> <li>Implement PUT verb on statements endpoint</li> <li>Add ClickHouse database backend support</li> </ul>"},{"location":"CHANGELOG/#changed_6","title":"Changed","text":"<ul> <li>Make trailing slashes optional on statements endpoint</li> <li>Upgrade <code>sentry_sdk</code> to <code>1.16.0</code></li> </ul>"},{"location":"CHANGELOG/#340_-_2023-03-01","title":"3.4.0 - 2023-03-01","text":""},{"location":"CHANGELOG/#changed_7","title":"Changed","text":"<ul> <li>Upgrade <code>fastapi</code> to <code>0.92.0</code></li> <li>Upgrade <code>sentry_sdk</code> to <code>1.15.0</code></li> </ul>"},{"location":"CHANGELOG/#fixed_3","title":"Fixed","text":"<ul> <li>Restore sentry integration in the LRS server</li> </ul>"},{"location":"CHANGELOG/#330_-_2023-02-03","title":"3.3.0 - 2023-02-03","text":""},{"location":"CHANGELOG/#added_5","title":"Added","text":"<ul> <li>Restore python 3.7+ support for library usage (models)</li> </ul>"},{"location":"CHANGELOG/#changed_8","title":"Changed","text":"<ul> <li>Allow xAPI extra fields in <code>extensions</code> fields</li> </ul>"},{"location":"CHANGELOG/#321_-_2023-02-01","title":"3.2.1 - 2023-02-01","text":""},{"location":"CHANGELOG/#changed_9","title":"Changed","text":"<ul> <li>Relax required Python version to <code>3.7</code>+</li> </ul>"},{"location":"CHANGELOG/#320_-_2023-01-25","title":"3.2.0 - 2023-01-25","text":""},{"location":"CHANGELOG/#added_6","title":"Added","text":"<ul> <li>Add a new <code>auth</code> subcommand to generate required credentials file for the LRS</li> <li>Implement support for AWS S3 storage backend</li> <li>Add CLI <code>--version</code> option</li> </ul>"},{"location":"CHANGELOG/#changed_10","title":"Changed","text":"<ul> <li>Upgrade <code>fastapi</code> to <code>0.89.1</code></li> <li>Upgrade <code>httpx</code> to <code>0.23.3</code></li> <li>Upgrade <code>sentry_sdk</code> to <code>1.14.0</code></li> <li>Upgrade <code>uvicorn</code> to <code>0.20.0</code></li> <li>Tray: add the <code>ca_certs</code> path for the ES backend client option (LRS)</li> <li>Improve Sentry integration for the LRS</li> <li>Update handbook link to <code>https://handbook.openfun.fr</code></li> <li>Upgrade base python version to 3.11 for the development stack and Docker   image</li> </ul>"},{"location":"CHANGELOG/#fixed_4","title":"Fixed","text":"<ul> <li>Restore ES and Mongo backends ability to use client options</li> </ul>"},{"location":"CHANGELOG/#310_-_2022-11-17","title":"3.1.0 - 2022-11-17","text":""},{"location":"CHANGELOG/#added_7","title":"Added","text":"<ul> <li>EdX to xAPI converters for video events</li> </ul>"},{"location":"CHANGELOG/#changed_11","title":"Changed","text":"<ul> <li>Improve Ralph\u2019s library integration by unpinning dependencies (and prefer   ranges)</li> <li>Upgrade <code>fastapi</code> to <code>0.87.0</code></li> </ul>"},{"location":"CHANGELOG/#removed_2","title":"Removed","text":"<ul> <li>ModelRules constraint</li> </ul>"},{"location":"CHANGELOG/#300_-_2022-10-19","title":"3.0.0 - 2022-10-19","text":""},{"location":"CHANGELOG/#added_8","title":"Added","text":"<ul> <li>Implement edX video browser events pydantic models</li> <li>Create a <code>post</code> endpoint for statements implementing the LRS spec</li> <li>Implement support for the MongoDB database backend</li> <li>Implement support for custom queries when using database backends <code>get</code>   method (used in the <code>fetch</code> command)</li> <li>Add dotenv configuration file support and <code>python-dotenv</code> dependency</li> <li>Add <code>host</code> and <code>port</code> options for the <code>runserver</code> cli command</li> <li>Add support for database selection when running the Ralph LRS server</li> <li>Implement support for xAPI statement forwarding</li> <li>Add database backends <code>status</code> checking</li> <li>Add <code>health</code> LRS router</li> <li>Tray: add LRS server support</li> </ul>"},{"location":"CHANGELOG/#changed_12","title":"Changed","text":"<ul> <li>Migrate to <code>python-legacy</code> handler for <code>mkdocstrings</code> package</li> <li>Upgrade <code>click</code> to <code>8.1.3</code></li> <li>Upgrade <code>elasticsearch</code> to <code>8.3.3</code></li> <li>Upgrade <code>fastapi</code> to <code>0.79.1</code></li> <li>Upgrade <code>ovh</code> to <code>1.0.0</code></li> <li>Upgrade <code>pydantic</code> to <code>1.9.2</code></li> <li>Upgrade <code>pymongo</code> to <code>4.2.0</code></li> <li>Upgrade <code>python-keystoneclient</code> to <code>5.0.0</code></li> <li>Upgrade <code>python-swiftclient</code> to <code>4.0.1</code></li> <li>Upgrade <code>requests</code> to <code>2.28.1</code></li> <li>Upgrade <code>sentry_sdk</code> to <code>1.9.5</code></li> <li>Upgrade <code>uvicorn</code> to <code>0.18.2</code></li> <li>Upgrade <code>websockets</code> to <code>10.3</code></li> <li>Make backends yield results instead of writing to standard streams (BC)</li> <li>Use pydantic settings management instead of global variables in defaults.py</li> <li>Rename backend and parser parameter environment variables (BC)</li> <li>Make project dependencies management more modular for library usage</li> </ul>"},{"location":"CHANGELOG/#removed_3","title":"Removed","text":"<ul> <li>Remove YAML configuration file support and <code>pyyaml</code> dependency (BC)</li> </ul>"},{"location":"CHANGELOG/#fixed_5","title":"Fixed","text":"<ul> <li>Tray: do not create a cronjobs list when no cronjob has been defined</li> <li>Restore history mixin logger</li> </ul>"},{"location":"CHANGELOG/#210_-_2022-04-13","title":"2.1.0 - 2022-04-13","text":""},{"location":"CHANGELOG/#added_9","title":"Added","text":"<ul> <li>Implement edX problem interaction events pydantic models</li> <li>Implement edX textbook interaction events pydantic models</li> <li><code>ws</code> websocket stream backend (compatible with the <code>fetch</code> command)</li> <li>bundle <code>jq</code>, <code>curl</code> and <code>wget</code> in the <code>fundocker/ralph</code> Docker image</li> <li>Tray: enable ralph app deployment command configuration</li> <li>Add a <code>runserver</code> command with basic auth and a <code>Whoami</code> route</li> <li>Create a <code>get</code> endpoint for statements implementing the LRS spec</li> <li>Add optional fields to BaseXapiModel</li> </ul>"},{"location":"CHANGELOG/#changed_13","title":"Changed","text":"<ul> <li>Upgrade <code>uvicorn</code> to <code>0.17.4</code></li> <li>Upgrade <code>elasticsearch</code> to <code>7.17.0</code></li> <li>Upgrade <code>sentry_sdk</code> to <code>1.5.5</code></li> <li>Upgrade <code>fastapi</code> to <code>0.73.0</code></li> <li>Upgrade <code>pyparsing</code> to <code>3.0.7</code></li> <li>Upgrade <code>pydantic</code> to <code>1.9.0</code></li> <li>Upgrade <code>python-keystoneclient</code> to <code>4.4.0</code></li> <li>Upgrade <code>python-swiftclient</code> to <code>3.13.0</code></li> <li>Upgrade <code>pyyaml</code> to <code>6.0</code></li> <li>Upgrade <code>requests</code> to <code>2.27.1</code></li> <li>Upgrade <code>websockets</code> to <code>10.1</code></li> </ul>"},{"location":"CHANGELOG/#201_-_2021-07-15","title":"2.0.1 - 2021-07-15","text":""},{"location":"CHANGELOG/#changed_14","title":"Changed","text":"<ul> <li>Upgrade <code>elasticsearch</code> to <code>7.13.3</code></li> </ul>"},{"location":"CHANGELOG/#fixed_6","title":"Fixed","text":"<ul> <li>Restore elasticsearch backend datastream compatibility for bulk operations</li> </ul>"},{"location":"CHANGELOG/#200_-_2021-07-09","title":"2.0.0 - 2021-07-09","text":""},{"location":"CHANGELOG/#added_10","title":"Added","text":"<ul> <li>xAPI video <code>interacted</code> pydantic models</li> <li>xAPI video <code>terminated</code> pydantic models</li> <li>xAPI video <code>completed</code> pydantic models</li> <li>xAPI video <code>seeked</code> pydantic models</li> <li>xAPI video <code>initialized</code> pydantic models</li> <li>xAPI video <code>paused</code> pydantic models</li> <li><code>convert</code> command to transform edX events to xAPI format</li> <li>EdX to xAPI converters for page <code>viewed</code> and<code>page_close</code> events</li> <li>Implement core event format converter</li> <li>xAPI video <code>played</code> pydantic models</li> <li>xAPI page <code>viewed</code> and page <code>terminated</code> pydantic models</li> <li>Implement edX navigational events pydantic models</li> <li>Implement edX enrollment events pydantic models</li> <li>Install security updates in project Docker images</li> <li>Model selector to retrieve associated pydantic model of a given event</li> <li><code>validate</code> command to lint edX events using pydantic models</li> <li>Support all available bulk operation types for the elasticsearch backend   (create, index, update, delete) using the <code>--es-op-type</code> option</li> </ul>"},{"location":"CHANGELOG/#changed_15","title":"Changed","text":"<ul> <li>Upgrade <code>elasticsearch</code> to <code>7.13.2</code></li> <li>Upgrade <code>python-swiftclient</code> to <code>3.12.0</code></li> <li>Upgrade <code>click</code> to <code>8.0.1</code></li> <li>Upgrade <code>click-option-group</code> to <code>0.5.3</code></li> <li>Upgrade <code>pydantic</code> to <code>1.8.2</code></li> <li>Upgrade <code>sentry_sdk</code> to <code>1.1.0</code></li> <li>Rename edX models</li> <li>Migrate model tests from factories to hypothesis strategies</li> <li>Tray: switch from openshift to k8s (BC)</li> <li>Tray: remove useless deployment probes</li> </ul>"},{"location":"CHANGELOG/#fixed_7","title":"Fixed","text":"<ul> <li>Tray: remove <code>version</code> immutable field in DC selector</li> </ul>"},{"location":"CHANGELOG/#120_-_2021-02-26","title":"1.2.0 - 2021-02-26","text":""},{"location":"CHANGELOG/#added_11","title":"Added","text":"<ul> <li>edX server event pydantic model and factory</li> <li>edX page_close browser event pydantic model and factory</li> <li>Tray: allow to specify a self-generated elasticsearch cluster CA certificate</li> </ul>"},{"location":"CHANGELOG/#fixed_8","title":"Fixed","text":"<ul> <li>Tray: add missing Swift variables in the secret</li> <li>Tray: fix pods anti-affinity selector</li> </ul>"},{"location":"CHANGELOG/#removed_4","title":"Removed","text":"<ul> <li><code>pandas</code> is no longer required</li> </ul>"},{"location":"CHANGELOG/#110_-_2021-02-04","title":"1.1.0 - 2021-02-04","text":""},{"location":"CHANGELOG/#added_12","title":"Added","text":"<ul> <li>Support for Swift storage backend</li> <li>Use the <code>push</code> command <code>--ignore-errors</code> option to ignore ES bulk import   errors</li> <li>The elasticsearch backend now accepts passing all supported client options</li> </ul>"},{"location":"CHANGELOG/#changed_16","title":"Changed","text":"<ul> <li>Upgrade <code>pyyaml</code> to <code>5.4.1</code></li> <li>Upgrade <code>pandas</code> to <code>1.2.1</code></li> </ul>"},{"location":"CHANGELOG/#removed_5","title":"Removed","text":"<ul> <li><code>click_log</code> is no longer required as we are able to configure logging</li> </ul>"},{"location":"CHANGELOG/#100_-_2021-01-13","title":"1.0.0 - 2021-01-13","text":""},{"location":"CHANGELOG/#added_13","title":"Added","text":"<ul> <li>Implement base CLI commands (list, extract, fetch &amp; push) for supported   backends</li> <li>Support for ElasticSearch database backend</li> <li>Support for LDP storage backend</li> <li>Support for FS storage backend</li> <li>Parse (gzipped) tracking logs in GELF format</li> <li>Support for application\u2019s configuration file</li> <li>Add optional sentry integration</li> <li>Distribute Arnold\u2019s tray to deploy Ralph in a k8s cluster as cronjobs</li> </ul>"},{"location":"LICENSE/","title":"License","text":"<p>MIT License</p> <p>Copyright (c) 2020-present France Universit\u00e9 Num\u00e9rique</p> <p>Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \u201cSoftware\u201d), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:</p> <p>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</p> <p>THE SOFTWARE IS PROVIDED \u201cAS IS\u201d, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</p>"},{"location":"UPGRADE/","title":"Upgrade","text":"<p>All instructions to upgrade this project from one release to the next will be documented in this file. Upgrades must be run sequentially, meaning you should not skip minor/major releases while upgrading (fix releases can be skipped).</p> <p>This project adheres to Semantic Versioning.</p>"},{"location":"UPGRADE/#3xx_to_400","title":"3.x.x to 4.0.0","text":""},{"location":"UPGRADE/#upgrade_user_credentials","title":"Upgrade user credentials","text":"<p>To conform to xAPI specifications, we need to represent users as xAPI Agents. You must therefore delete and re-create the credentials file using the updated cli, OR you can modify it directly to add the <code>agents</code> field. The credentials file is located in <code>{ RALPH_APP_DIR }/{ RALPH_AUTH_FILE }</code> (defaults to <code>.ralph/auth.json</code>). Each user profile must follow the following pattern (see this post for examples of valid agent objects) :</p> <p><pre><code>{\n  \"username\": \"USERNAME_UNCHANGED\",\n  \"hash\": \"PASSWORD_HASH_UNCHANGED\",\n  \"scopes\": [ LIST_OF_SCOPES_UNCHANGED ],\n  \"agent\": { A_VALID_AGENT_OBJECT }\n}\n</code></pre> Agent can take one of the following forms, as specified by the xAPI specification: - mbox:  <pre><code>\"agent\": {\n      \"mbox\": \"mailto:john.doe@example.com\"\n}\n</code></pre> - mbox_sha1sum: <pre><code>\"agent\": {\n        \"mbox_sha1sum\": \"ebd31e95054c018b10727ccffd2ef2ec3a016ee9\",\n}\n</code></pre> - openid: <pre><code>\"agent\": {\n      \"openid\": \"http://foo.openid.example.org/\"\n}\n</code></pre> - account: <pre><code>\"agent\": {\n      \"account\": {\n        \"name\": \"simonsAccountName\",\n        \"homePage\": \"http://www.exampleHomePage.com\"\n}\n</code></pre></p> <p>For example here is a valid <code>auth.json</code> file: </p> <pre><code>[\n  {\n    \"username\": \"john.doe@example.com\",\n    \"hash\": \"$2b$12$yBXrzIuRIk6yaft5KUgVFOIPv0PskCCh9PXmF2t7pno.qUZ5LK0D2\",\n    \"scopes\": [\"example_scope\"],\n    \"agent\": {\n      \"mbox\": \"mailto:john.doe@example.com\"\n    }\n  },\n  {\n    \"username\": \"simon.says@example.com\",\n    \"hash\": \"$2b$12$yBXrzIuRIk6yaft5KUgVFOIPv0PskCCh9PXmF2t7pno.qUZ5LK0D2\",\n    \"scopes\": [\"second_scope\", \"third_scope\"],\n    \"agent\": {\n      \"account\": {\n        \"name\": \"simonsAccountName\",\n        \"homePage\": \"http://www.exampleHomePage.com\"\n      }\n    }\n  }\n]\n</code></pre>"},{"location":"UPGRADE/#upgrade_history_syntax","title":"Upgrade history syntax","text":"<p>CLI syntax has been changed from <code>fetch</code> &amp; <code>push</code> to <code>read</code> &amp; <code>write</code> affecting the command history. You must replace the command history after updating: - locate your history file path, which is in <code>{ RALPH_APP_DIR }/history.json</code> (defaults to <code>.ralph/history.json</code>) - run the commands below to update history</p> <pre><code>sed -i 's/\"fetch\"/\"read\"/g' { my_history_file_path }\nsed -i 's/\"push\"/\"write\"/g' { my_history_file_path }\n</code></pre>"},{"location":"UPGRADE/#upgrade_clickhouse_schema","title":"Upgrade ClickHouse schema","text":"<p>If you are using the ClickHouse backend, schema changes have been made to drop the existing JSON column in favor of the String version of the  same data. See this issue  for details. </p> <p>Ralph does not manage the ClickHouse schema, so if you have existing  data you will need to manually alter it as an admin user. Note: this  will rewrite the statements table, which may take a long time if you have many rows. The command to run is:</p> <pre><code>-- If RALPH_BACKENDS__DATA__CLICKHOUSE__DATABASE is 'xapi'\n-- and RALPH_BACKENDS__DATA__CLICKHOUSE__EVENT_TABLE_NAME is 'test'\n\nALTER TABLE xapi.test DROP COLUMN event, RENAME COLUMN event_str to event;\n</code></pre>"},{"location":"commands/","title":"Commands","text":""},{"location":"commands/#ralph","title":"ralph","text":"<p>The cli is a stream-based tool to play with your logs.</p> <p>It offers functionalities to: - Validate or convert learning data in different standards - Read and write learning data to various databases or servers - Manage an instance of a Ralph LRS server</p> <p>Usage:</p> <pre><code>ralph [OPTIONS] COMMAND [ARGS]...\n</code></pre> <p>Options:</p> <pre><code>  -v, --verbosity LVL  Either CRITICAL, ERROR, WARNING, INFO (default) or\n                       DEBUG\n  --version            Show the version and exit.\n  --help               Show this message and exit.\n</code></pre>"},{"location":"commands/#ralph-auth","title":"ralph auth","text":"<p>Generate credentials for LRS HTTP basic authentication.</p> <p>Usage:</p> <pre><code>ralph auth [OPTIONS]\n</code></pre> <p>Options:</p> <pre><code>  -u, --username TEXT             The user for which we generate credentials.\n                                  [required]\n  -p, --password TEXT             The password to encrypt for this user. Will\n                                  be prompted if missing.  [required]\n  -s, --scope TEXT                The user scope(s). This option can be\n                                  provided multiple times.  [required]\n  -M, --agent-ifi-mbox TEXT       The mbox Inverse Functional Identifier of\n                                  the associated agent.\n  -S, --agent-ifi-mbox-sha1sum TEXT\n                                  The mbox-sha1sum Inverse Functional\n                                  Identifier of the associated agent.\n  -O, --agent-ifi-openid TEXT     The openid Inverse Functional Identifier of\n                                  the associated agent.\n  -A, --agent-ifi-account TEXT...\n                                  Input \"{name} {homePage}\". The account\n                                  Inverse Functional Identifier of the\n                                  associated agent.\n  -N, --agent-name TEXT           The name of the associated agent.\n  -w, --write-to-disk             Write new credentials to the LRS\n                                  authentication file.\n  --help                          Show this message and exit.\n</code></pre>"},{"location":"commands/#ralph-convert","title":"ralph convert","text":"<p>Convert input events to a given format.</p> <p>Usage:</p> <pre><code>ralph convert [OPTIONS]\n</code></pre> <p>Options:</p> <pre><code>  From edX to xAPI converter options: \n    -u, --uuid-namespace TEXT     The UUID namespace to use for the `ID` field\n                                  generation\n    -p, --platform-url TEXT       The `actor.account.homePage` to use in the\n                                  xAPI statements  [required]\n  -f, --from [edx]                Input events format to convert  [required]\n  -t, --to [xapi]                 Output events format  [required]\n  -I, --ignore-errors             Continue writing regardless of raised errors\n  -F, --fail-on-unknown           Stop converting at first unknown event\n  --help                          Show this message and exit.\n</code></pre>"},{"location":"commands/#ralph-extract","title":"ralph extract","text":"<p>Extract input events from a container format using a dedicated parser.</p> <p>Usage:</p> <pre><code>ralph extract [OPTIONS]\n</code></pre> <p>Options:</p> <pre><code>  -p, --parser [gelf|es]  Container format parser used to extract events\n                          [required]\n  --help                  Show this message and exit.\n</code></pre>"},{"location":"commands/#ralph-validate","title":"ralph validate","text":"<p>Validate input events of given format.</p> <p>Usage:</p> <pre><code>ralph validate [OPTIONS]\n</code></pre> <p>Options:</p> <pre><code>  -f, --format [edx|xapi]  Input events format to validate  [required]\n  -I, --ignore-errors      Continue validating regardless of raised errors\n  -F, --fail-on-unknown    Stop validating at first unknown event\n  --help                   Show this message and exit.\n</code></pre>"},{"location":"contribute/","title":"Contributing to Ralph","text":"<p>Thank you for considering contributing to Ralph! We appreciate your interest and support. This documentation provides guidelines on how to contribute effectively to our project.</p>"},{"location":"contribute/#issues","title":"Issues","text":"<p>Issues are a valuable way to contribute to Ralph. They can include bug reports, feature requests, and general questions or discussions. When creating or interacting with issues, please keep the following in mind:</p>"},{"location":"contribute/#1_search_for_existing_issues","title":"1. Search for existing issues","text":"<p>Before creating a new issue, search the existing issues to see if your concern has already been raised.  If you find a related issue, you can add your input or follow the discussion. Feel free to engage in discussions, offer help, or provide feedback on existing issues. Your input is valuable in shaping the project\u2019s future.</p>"},{"location":"contribute/#2_creating_a_new_issue","title":"2. Creating a new issue","text":"<p>Use the provided issue template that fits the best to your concern. Provide as much information as possible when writing your issue. Your issue will be reviewed by a project maintainer and you may be offered to open a PR if you want to contribute to the code. If not, and if your issue is relevant, a contributor will apply the changes to the project.  The issue will then be automatically closed when the PR is merged.</p> <p>Issues will be closed by project maintainers if they are deemed invalid.  You can always reopen an issue if you believe it hasn\u2019t been adequately addressed.</p>"},{"location":"contribute/#3_code_of_conduct_in_discussion","title":"3. Code of conduct in discussion","text":"<ul> <li>Be respectful and considerate when participating in discussions.</li> <li>Avoid using offensive language, and maintain a positive and collaborative tone.</li> <li>Stay on topic and avoid derailing discussions.</li> </ul>"},{"location":"contribute/#discussions","title":"Discussions","text":"<p>Discussions in the Ralph repository are a place for open-ended conversations, questions, and general community interactions. Here\u2019s how to effectively use discussions:</p>"},{"location":"contribute/#1_creating_a_discussion","title":"1. Creating a discussion","text":"<ul> <li>Use a clear and concise title that summarizes the topic.</li> <li>In the description, provide context and details regarding the discussion.</li> <li>Use labels to categorize the discussion (e.g., \u201cquestion,\u201d \u201cgeneral discussion,\u201d \u201cannouncements,\u201d etc.).</li> </ul>"},{"location":"contribute/#2_participating_in_discussions","title":"2. Participating in discussions","text":"<ul> <li>Engage in conversations respectfully, respecting others\u2019 opinions.</li> <li>Avoid spamming or making off-topic comments.</li> <li>Help answer questions when you can.</li> </ul>"},{"location":"contribute/#pull_requests_pr","title":"Pull Requests (PR)","text":"<p>Contributing to Ralph through pull requests is a powerful way to advance the project.  If you want to make changes or add new features, please follow these steps to submit a PR:</p>"},{"location":"contribute/#1_fork_the_repository","title":"1. Fork the repository","text":"<p>Begin by forking Ralph project\u2019s repository. </p>"},{"location":"contribute/#2_clone_the_fork","title":"2. Clone the fork","text":"<p>Clone the forked repository to your local machine and change the directory to the project folder using the following commands (replace <code>&lt;your_fork&gt;</code> with your GitHub username):</p> <pre><code>git clone https://github.com/&lt;your_fork&gt;/ralph.git\ncd ralph\n</code></pre>"},{"location":"contribute/#3_create_a_new_branch","title":"3. Create a new branch","text":"<p>Create a new branch for your changes, ideally with a descriptive name:</p> <pre><code>git checkout -b your-new-feature\n</code></pre>"},{"location":"contribute/#4_make_changes","title":"4. Make changes","text":"<p>Implement the changes or additions to the code, ensuring it follows OpenFUN coding and documentation standards.</p> <p>For comprehensive guidance on starting your development journey with Ralph and preparing your pull request, please refer to our dedicated Start developing with Ralph tutorial.</p> <p>When committing your changes, please adhere to OpenFUN commit practices.  Follow the low granularity commit splitting approach and use commit messages based on the Angular commit message guidelines. </p>"},{"location":"contribute/#5_push_changes","title":"5. Push changes","text":"<p>Push your branch to your GitHub repository:</p> <pre><code>git push origin feature/your-new-feature\n</code></pre>"},{"location":"contribute/#6_create_a_pull_request","title":"6. Create a pull request","text":"<p>To initiate a Pull Request (PR), head to Ralph project\u2019s GitHub repository and click on New Pull Request.</p> <p>Set your branch as the source and Ralph project\u2019s <code>master</code> branch as the target.</p> <p>Provide a clear title for your PR and make use of the provided PR body template to document the changes made by your PR. This helps streamline the review process and maintain a well-documented project history.</p>"},{"location":"contribute/#7_review_and_discussion","title":"7. Review and discussion","text":"<p>Ralph project maintainers will review your PR.  Be prepared to make necessary changes or address any feedback.  Patience during this process is appreciated.</p>"},{"location":"contribute/#8_merge","title":"8. Merge","text":"<p>Once your PR is approved, Ralph maintainers will merge your changes into the main project.  Congratulations, you\u2019ve successfully contributed to Ralph! \ud83c\udf89</p>"},{"location":"api/","title":"LRS HTTP server","text":"<p>Ralph comes with an API server that aims to implement the Learning Record Store (LRS) specification (still a work in progress).</p>"},{"location":"api/#getting_started","title":"Getting started","text":"<p>The API server supports the following authentication methods:</p> <ul> <li>HTTP Basic Authentication (default method)</li> <li>OpenID Connect authentication on top of OAuth2.0</li> </ul>"},{"location":"api/#http_basic_authentication","title":"HTTP Basic Authentication","text":"<p>The default method for securing Ralph API server is with HTTP basic authentication.</p> <p>The API server can be started up with the following command:</p> <pre><code>ralph runserver --backend es\n</code></pre> <p>The <code>--backend</code> (or <code>-b</code>) option specifies which database backend to use for LRS data storage and retrieval.  See Ralph\u2019s backends documentation for more details.</p> <p>However, before you can start your API server and make requests against it, you need to set up your credentials.</p>"},{"location":"api/#creating_a_credentials_file","title":"Creating a credentials file","text":"<p>The credentials file is expected to be a valid JSON file. Its location is specified by the <code>RALPH_AUTH_FILE</code> configuration value. By default, <code>ralph</code> will look for the <code>auth.json</code> file in the application directory (see click documentation for details).</p> <p>The expected format is a list of entries (JSON objects) each containing the username, the user\u2019s <code>bcrypt</code> hashed+salted password, scopes they can access, and an <code>agent</code> object used to represent the user in the LRS. The  <code>agent</code> is constrained by LRS specifications, and must use one of four valid  Inverse Functional Identifiers.</p> <pre><code>[\n  {\n    \"username\": \"john.doe@example.com\",\n    \"hash\": \"$2b$12$yBXrzIuRIk6yaft5KUgVFOIPv0PskCCh9PXmF2t7pno.qUZ5LK0D2\",\n    \"scopes\": [\"example_scope\"],\n    \"agent\": {\n      \"mbox\": \"mailto:john.doe@example.com\"\n    }\n  },\n  {\n    \"username\": \"simon.says@example.com\",\n    \"hash\": \"$2b$12$yBXrzIuRIk6yaft5KUgVFOIPv0PskCCh9PXmF2t7pno.qUZ5LK0D2\",\n    \"scopes\": [\"second_scope\", \"third_scope\"],\n    \"agent\": {\n      \"account\": {\n        \"name\": \"simonsAccountName\",\n        \"homePage\": \"http://www.exampleHomePage.com\"\n      }\n    }\n  }\n]\n</code></pre> <p>To create a new user credentials, Ralph\u2019s CLI provides a dedicated command:</p> <pre><code>ralph auth \\\n    --username janedoe \\\n    --password supersecret \\\n    --scope janedoe_scope \\\n    --agent-ifi-mbox mailto:janedoe@example.com \\\n    # or --agent-ifi-mbox-sha1sum ebd31e95054c018b10727ccffd2ef2ec3a016ee9 \\\n    # or --agent-ifi-openid \"http://jane.openid.example.org/\" \\\n    # or --agent-ifi-account exampleAccountname http://www.exampleHomePage.com \\\n    -w\n</code></pre> <p>This command updates your credentials file with the new <code>janedoe</code> user.</p> <p>Note that running this command requires that you installed Ralph with the CLI optional dependencies, e.g. <code>pip install ralph-malph[cli]</code> (which we highly recommend).</p>"},{"location":"api/#making_a_get_request","title":"Making a GET request","text":"<p>The first request that can be answered by the ralph API server is a <code>whoami</code> request, which checks if the user is authenticated and returns their username and permission scopes.</p> <p>Use curl to get <code>http://localhost:8100/whoami</code>:</p> <pre><code>curl http://localhost:8100/whoami\n&lt; HTTP/1.1 401 Unauthorized\n&lt; {\"error\":\"Not authenticated\"}\n</code></pre> <p>Send your username and password to the API server through HTTP Basic Auth:</p> <pre><code>curl --user john.doe@example.com:PASSWORD http://localhost:8100/whoami\n&lt; HTTP/1.1 200 OK\n&lt; {\"scopes\":[\"example_scope\"], \"agent\": {\"mbox\": \"mailto:john.doe@example.com\"}}\n</code></pre>"},{"location":"api/#openid_connect_authentication","title":"OpenID Connect authentication","text":"<p>Ralph LRS API server supports OpenID Connect (OIDC) on top of OAuth 2.0 for authentication and authorization.</p> <p>To enable OIDC auth, you should modify the <code>RALPH_RUNSERVER_AUTH_BACKENDS</code> environment variable by adding (or replacing by) <code>oidc</code>: <pre><code>RALPH_RUNSERVER_AUTH_BACKENDS=basic,oidc\n</code></pre></p> <p>and you should define the <code>RALPH_RUNSERVER_AUTH_OIDC_ISSUER_URI</code> environment variable with your identity provider\u2019s Issuer Identifier URI as follows:</p> <pre><code>RALPH_RUNSERVER_AUTH_OIDC_ISSUER_URI=http://{provider_host}:{provider_port}/auth/realms/{realm_name}\n</code></pre> <p>This address must be accessible to the LRS on startup as it will perform OIDC Discovery to retrieve public keys and other information about the OIDC environment.</p> <p>It is also strongly recommended that you set the optional <code>RALPH_RUNSERVER_AUTH_OIDC_AUDIENCE</code> environment variable to the origin address of the LRS itself (ex. \u201chttp://localhost:8100\u201d) to enable verification that a given token was issued specifically for the LRS.</p>"},{"location":"api/#identity_providers","title":"Identity Providers","text":"<p>OIDC support is currently developed and tested against Keycloak but may work with other identity providers that implement the specification.</p> <p>The Learning analytics playground repository contains a Docker Compose file and configuration for a demo instance of Keycloak with a <code>ralph</code> client.</p>"},{"location":"api/#making_a_get_request_1","title":"Making a GET request","text":"<p>The first request that can be answered by the ralph API server is a <code>whoami</code> request, which checks if the user is authenticated and returns their username and permission scopes.</p> <p>Use curl to get <code>http://localhost:8100/whoami</code>:</p> <pre><code>curl http://localhost:8100/whoami\n&lt; HTTP/1.1 401 Unauthorized\n&lt; {\"detail\":\"Could not validate credentials\"}\n</code></pre> <p>With the Keycloak instance running, use curl to get access token from Keycloak:</p> <pre><code>curl --request POST 'http://localhost:8080/auth/realms/fun-mooc/protocol/openid-connect/token' \\\n--header 'Content-Type: application/x-www-form-urlencoded' \\\n--data-urlencode 'client_id=ralph' \\\n--data-urlencode 'client_secret=super-secret' \\\n--data-urlencode 'username=ralph_admin' \\\n--data-urlencode 'password=funfunfun' \\\n--data-urlencode 'grant_type=password'\n</code></pre> <p>which outputs (tokens truncated for example purpose):</p> <pre><code>{ \n  \"access_token\":\"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJSTWlLM\",\n  \"expires_in\":300,\n  \"refresh_expires_in\":1800,\n  \"refresh_token\":\"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI4MDc5NjExM\",\n  \"token_type\":\"Bearer\",\n  \"not-before-policy\":0,\n  \"session_state\":\"22a36735-e35f-496b-a243-152d32ebff45\",\n  \"scope\":\"profile email\"\n}\n</code></pre> <p>Send the access token to the API server as a Bearer header:</p> <pre><code>curl http://localhost:8100/whoami --header \"Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJSTWlLM\"\n&lt; HTTP/1.1 200 OK\n&lt; {\"username\":\"ralph_admin\",\"scopes\":[\"all\"]}\n</code></pre>"},{"location":"api/#security","title":"Security","text":"<p>By default, all authenticated users have full read and write access to the server. You may use the options below to restrict behavior.</p>"},{"location":"api/#filtering_results_by_authority_multitenancy","title":"Filtering results by authority (multitenancy)","text":"<p>In Ralph LRS, all incoming statements are assigned an <code>authority</code> (or ownership) derived from the user that makes the call. You may restrict read access to users \u201cown\u201d statements (thus enabling multitenancy) by setting the following environment variable: </p> <pre><code>RALPH_LRS_RESTRICT_BY_AUTHORITY = True # Default: False\n</code></pre> <p>WARNING: Two accounts with different credentials may share the same <code>authority</code> meaning they can access the same statements. It is the administrators responsability to ensure that <code>authority</code> is properly assigned.</p> <p>NB: If not using \u201cscopes\u201d, or for users with limited \u201cscopes\u201d, using this option will make the use of option <code>?mine=True</code> implicit when fetching statement.</p>"},{"location":"api/#scopes","title":"Scopes","text":"<p>In Ralph, users are assigned scopes which may be used to restrict endpoint access or  functionalities. You may enable this option by setting the following environment variable:</p> <pre><code>RALPH_LRS_RESTRICT_BY_SCOPES = True # Default: False\n</code></pre> <p>Valid scopes are a slight variation on those proposed by the xAPI specification:</p> <ul> <li>statements/write</li> <li>statements/read/mine</li> <li>statements/read</li> <li>state/write</li> <li>state/read</li> <li>define</li> <li>profile/write</li> <li>profile/read</li> <li>all/read</li> <li>all</li> </ul>"},{"location":"api/#forwarding_statements","title":"Forwarding statements","text":"<p>Ralph\u2019s API server can be configured to forward xAPI statements it receives to other LRSes.</p> <p>To configure statement forwarding, you need to create a <code>.env</code> file in the current directory and define the <code>RALPH_XAPI_FORWARDINGS</code> variable or define the <code>RALPH_XAPI_FORWARDINGS</code> environment variable.</p> <p>The value of the <code>RALPH_XAPI_FORWARDINGS</code> variable should be a JSON encoded list of dictionaries where each dictionary defines a forwarding configuration and consists of the following key/value pairs:</p> key value type description <code>is_active</code> <code>boolean</code> Specifies whether or not this forwarding configuration should take effect. <code>url</code> <code>URL</code> Specifies the endpoint URL where forwarded statements should be send. <code>basic_username</code> <code>string</code> Specifies the basic auth username. <code>basic_password</code> <code>string</code> Specifies the basic auth password. <code>max_retries</code> <code>number</code> Specifies the number of times a failed forwarding request should be retried. <code>timeout</code> <code>number</code> Specifies the duration in seconds of network inactivity leading to a timeout. <p>Note that for a forwarding configuration to be valid it is required that all key/value pairs are defined.</p> <p>Example of a valid forwarding configuration:</p> <pre><code>RALPH_XAPI_FORWARDINGS='\n[\n  {\n    \"is_active\": true,\n    \"url\": \"http://lrs1.example.com/xAPI/statements/\",\n    \"basic_username\": \"admin1@example.com\",\n    \"basic_password\": \"PASSWORD1\",\n    \"max_retries\": 1,\n    \"timeout\": 5\n  },\n  {\n    \"is_active\": true,\n    \"url\": \"http://lrs2.example.com/xAPI/statements/\",\n    \"basic_username\": \"admin2@example.com\",\n    \"basic_password\": \"PASSWORD2\",\n    \"max_retries\": 5,\n    \"timeout\": 0.2\n  }\n]\n'\n</code></pre>"},{"location":"api/#sentry_configuration","title":"Sentry configuration","text":"<p>Ralph provides Sentry integration to monitor its LRS server and its CLI. To activate Sentry integration, one should define the following environment variables:</p> <pre><code>RALPH_SENTRY_DSN={PROTOCOL}://{PUBLIC_KEY}:{SECRET_KEY}@{HOST}{PATH}/{PROJECT_ID}\nRALPH_EXECUTION_ENVIRONMENT=development\n</code></pre> <p>The Sentry DSN (Data Source Name) can be found in your project settings from Sentry application. The execution environment should reflect the environment Ralph has been deployed in (e.g. <code>production</code>).</p> <p>You may also want to monitor the performance of Ralph by configuring the CLI and LRS traces sample rates: <pre><code>RALPH_SENTRY_CLI_TRACES_SAMPLE_RATE=0.1\nRALPH_SENTRY_LRS_TRACES_SAMPLE_RATE=0.3\n</code></pre></p> <p>Note that a sampling rate of <code>1.0</code> means 100% of transactions are sent to sentry and <code>0.1</code> only 10%.</p> <p>If you want to lower noisy transactions (e.g. in a Kubernetes cluster), you can disable health checks related ones:</p> <pre><code>RALPH_SENTRY_IGNORE_HEALTH_CHECKS=True\n</code></pre>"},{"location":"api/#additional_configuration","title":"Additional configuration","text":""},{"location":"api/#http_basic_auth_caching","title":"HTTP Basic auth caching","text":"<p>HTTP Basic auth implementation uses the secure and standard bcrypt algorithm to hash/salt passwords before storing them. This implementation comes with a performance cost. To speed up requests, credentials are stored in an LRU cache with a <code>Time To Live</code>. To configure this cache, you can define the following environment variables:</p> <ul> <li>the maximum number of entries in the cache. Select a value greater than the maximum number of individual user credentials, for better performance. Defaults to 100. </li> </ul> <p><pre><code>RALPH_AUTH_CACHE_MAX_SIZE=100\n</code></pre> - the <code>Time To Live</code> of the cache entries in seconds. Defaults to 3600s.</p> <pre><code>RALPH_AUTH_CACHE_TTL=3600\n</code></pre>"},{"location":"api/#api_documentation","title":"API documentation","text":""},{"location":"api/#fastapi_010","title":"FastAPI 0.1.0","text":""},{"location":"api/#endpoints","title":"Endpoints","text":""},{"location":"api/#get_xapistatements","title":"GET /xAPI/statements/","text":"<p>Get</p> Description <p>Read a single xAPI Statement or multiple xAPI Statements.</p> <p>LRS Specification: https://github.com/adlnet/xAPI-Spec/blob/1.0.3/xAPI- Communication.md#213-get-statements</p> <p>Input parameters</p> Parameter In Type Default Nullable Description <code>HTTPBasic</code> header string N/A No Basic authentication <code>HTTPBasic</code> header string N/A No Basic authentication <code>activity</code> query string No Filter, only return Statements for which the Object of the Statement is an Activity with the specified id <code>agent</code> query string No Filter, only return Statements for which the specified Agent or Group is the Actor or Object of the Statement <code>ascending</code> query boolean False No If \"true\", return results in ascending order of stored time <code>attachments</code> query boolean False No **Not implemented** If \"true\", the LRS uses the multipart response format and includes all attachments as described previously. If \"false\", the LRS sends the prescribed response with Content-Type application/json and does not send attachment data. <code>format</code> query string exact No **Not implemented** If \"ids\", only include minimum information necessary in Agent, Activity, Verb and Group Objects to identify them. For Anonymous Groups this means including the minimum information needed to identify each member. If \"exact\", return Agent, Activity, Verb and Group Objects populated exactly as they were when the Statement was received. An LRS requesting Statements for the purpose of importing them would use a format of \"exact\" in order to maintain Statement Immutability. If \"canonical\", return Activity Objects and Verbs populated with the canonical definition of the Activity Objects and Display of the Verbs as determined by the LRS, after applying the language filtering process defined below, and return the original Agent and Group Objects as in \"exact\" mode. <code>limit</code> query integer 100 No Maximum number of Statements to return. 0 indicates return the maximum the server will allow <code>mine</code> query boolean False No If \"true\", return only the results for which the authority matches the \"agent\" associated to the user that is making the query. <code>pit_id</code> query string No Point-in-time ID to ensure consistency of search requests through multiple pages.NB: for internal use, not part of the LRS specification. <code>registration</code> query string No **Not implemented** Filter, only return Statements matching the specified registration id <code>related_activities</code> query boolean False No **Not implemented** Apply the Activity filter broadly. Include Statements for which the Object, any of the context Activities, or any of those properties in a contained SubStatement match the Activity parameter, instead of that parameter's normal behaviour <code>related_agents</code> query boolean False No **Not implemented** Apply the Agent filter broadly. Include Statements for which the Actor, Object, Authority, Instructor, Team, or any of these properties in a contained SubStatement match the Agent parameter, instead of that parameter's normal behaviour. <code>search_after</code> query string No Sorting data to allow pagination through large number of search results. NB: for internal use, not part of the LRS specification. <code>since</code> query string No Only Statements stored since the specified Timestamp (exclusive) are returned <code>statementId</code> query string No Id of Statement to fetch <code>until</code> query string No Only Statements stored at or before the specified Timestamp are returned <code>verb</code> query string No Filter, only return Statements matching the specified Verb id <code>voidedStatementId</code> query string No **Not implemented** Id of voided Statement to fetch <p> Response 200 OK </p> application/json Schema of the response body <pre><code>{\n    \"type\": \"object\",\n    \"title\": \"Response Get Xapi Statements  Get\"\n}\n</code></pre> <p> Response 422 Unprocessable Entity </p> application/json <p><pre><code>{\n    \"detail\": [\n        {\n            \"loc\": [\n                null\n            ],\n            \"msg\": \"string\",\n            \"type\": \"string\"\n        }\n    ]\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"properties\": {\n        \"detail\": {\n            \"items\": {\n                \"$ref\": \"#/components/schemas/ValidationError\"\n            },\n            \"type\": \"array\",\n            \"title\": \"Detail\"\n        }\n    },\n    \"type\": \"object\",\n    \"title\": \"HTTPValidationError\"\n}\n</code></pre>"},{"location":"api/#put_xapistatements","title":"PUT /xAPI/statements/","text":"<p>Put</p> Description <p>Store a single statement as a single member of a set.</p> <p>LRS Specification: https://github.com/adlnet/xAPI-Spec/blob/1.0.3/xAPI- Communication.md#211-put-statements</p> <p>Input parameters</p> Parameter In Type Default Nullable Description <code>HTTPBasic</code> header string N/A No Basic authentication <code>HTTPBasic</code> header string N/A No Basic authentication <code>statementId</code> query string No <p>Request body</p> application/json <p><pre><code>{\n    \"actor\": null,\n    \"id\": \"80fd65b0-85f8-4b64-a678-bd39624402fe\",\n    \"object\": {\n        \"id\": \"string\"\n    },\n    \"verb\": {\n        \"id\": \"string\"\n    }\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the request body <pre><code>{\n    \"properties\": {\n        \"actor\": {\n            \"anyOf\": [\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiAgentWithMbox\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiAgentWithMboxSha1Sum\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiAgentWithOpenId\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiAgentWithAccount\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiAnonymousGroup\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiIdentifiedGroupWithMbox\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiIdentifiedGroupWithMboxSha1Sum\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiIdentifiedGroupWithOpenId\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiIdentifiedGroupWithAccount\"\n                }\n            ],\n            \"title\": \"Actor\"\n        },\n        \"id\": {\n            \"type\": \"string\",\n            \"format\": \"uuid\",\n            \"title\": \"Id\"\n        },\n        \"object\": {\n            \"$ref\": \"#/components/schemas/LaxObjectField\"\n        },\n        \"verb\": {\n            \"$ref\": \"#/components/schemas/LaxVerbField\"\n        }\n    },\n    \"type\": \"object\",\n    \"required\": [\n        \"actor\",\n        \"object\",\n        \"verb\"\n    ],\n    \"title\": \"LaxStatement\",\n    \"description\": \"Pydantic model for lax statement.\\n\\nIt accepts without validating all fields beyond the bare minimum required to\\nqualify an object as an XAPI statement.\"\n}\n</code></pre> <p> Response 204 No Content </p> <p> Response 400 Bad Request </p> application/json <p><pre><code>{\n    \"detail\": \"string\"\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"properties\": {\n        \"detail\": {\n            \"type\": \"string\",\n            \"title\": \"Detail\"\n        }\n    },\n    \"type\": \"object\",\n    \"required\": [\n        \"detail\"\n    ],\n    \"title\": \"ErrorDetail\",\n    \"description\": \"Pydantic model for errors raised detail.\\n\\nType for return value for errors raised in API endpoints.\\nUseful for OpenAPI documentation generation.\"\n}\n</code></pre> <p> Response 409 Conflict </p> application/json <p><pre><code>{\n    \"detail\": \"string\"\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"properties\": {\n        \"detail\": {\n            \"type\": \"string\",\n            \"title\": \"Detail\"\n        }\n    },\n    \"type\": \"object\",\n    \"required\": [\n        \"detail\"\n    ],\n    \"title\": \"ErrorDetail\",\n    \"description\": \"Pydantic model for errors raised detail.\\n\\nType for return value for errors raised in API endpoints.\\nUseful for OpenAPI documentation generation.\"\n}\n</code></pre> <p> Response 422 Unprocessable Entity </p> application/json <p><pre><code>{\n    \"detail\": [\n        {\n            \"loc\": [\n                null\n            ],\n            \"msg\": \"string\",\n            \"type\": \"string\"\n        }\n    ]\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"properties\": {\n        \"detail\": {\n            \"items\": {\n                \"$ref\": \"#/components/schemas/ValidationError\"\n            },\n            \"type\": \"array\",\n            \"title\": \"Detail\"\n        }\n    },\n    \"type\": \"object\",\n    \"title\": \"HTTPValidationError\"\n}\n</code></pre>"},{"location":"api/#post_xapistatements","title":"POST /xAPI/statements/","text":"<p>Post</p> Description <p>Store a set of statements (or a single statement as a single member of a set).</p> <p>NB: at this time, using POST to make a GET request, is not supported. LRS Specification: https://github.com/adlnet/xAPI-Spec/blob/1.0.3/xAPI- Communication.md#212-post-statements</p> <p>Input parameters</p> Parameter In Type Default Nullable Description <code>HTTPBasic</code> header string N/A No Basic authentication <code>HTTPBasic</code> header string N/A No Basic authentication <p>Request body</p> application/json Schema of the request body <pre><code>{\n    \"anyOf\": [\n        {\n            \"$ref\": \"#/components/schemas/LaxStatement\"\n        },\n        {\n            \"items\": {\n                \"$ref\": \"#/components/schemas/LaxStatement\"\n            },\n            \"type\": \"array\"\n        }\n    ],\n    \"title\": \"Statements\"\n}\n</code></pre> <p> Response 200 OK </p> application/json <p><pre><code>[\n    null\n]\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"items\": {},\n    \"type\": \"array\",\n    \"title\": \"Response Post Xapi Statements  Post\"\n}\n</code></pre> <p> Response 400 Bad Request </p> application/json <p><pre><code>{\n    \"detail\": \"string\"\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"properties\": {\n        \"detail\": {\n            \"type\": \"string\",\n            \"title\": \"Detail\"\n        }\n    },\n    \"type\": \"object\",\n    \"required\": [\n        \"detail\"\n    ],\n    \"title\": \"ErrorDetail\",\n    \"description\": \"Pydantic model for errors raised detail.\\n\\nType for return value for errors raised in API endpoints.\\nUseful for OpenAPI documentation generation.\"\n}\n</code></pre> <p> Response 409 Conflict </p> application/json <p><pre><code>{\n    \"detail\": \"string\"\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"properties\": {\n        \"detail\": {\n            \"type\": \"string\",\n            \"title\": \"Detail\"\n        }\n    },\n    \"type\": \"object\",\n    \"required\": [\n        \"detail\"\n    ],\n    \"title\": \"ErrorDetail\",\n    \"description\": \"Pydantic model for errors raised detail.\\n\\nType for return value for errors raised in API endpoints.\\nUseful for OpenAPI documentation generation.\"\n}\n</code></pre> <p> Response 422 Unprocessable Entity </p> application/json <p><pre><code>{\n    \"detail\": [\n        {\n            \"loc\": [\n                null\n            ],\n            \"msg\": \"string\",\n            \"type\": \"string\"\n        }\n    ]\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"properties\": {\n        \"detail\": {\n            \"items\": {\n                \"$ref\": \"#/components/schemas/ValidationError\"\n            },\n            \"type\": \"array\",\n            \"title\": \"Detail\"\n        }\n    },\n    \"type\": \"object\",\n    \"title\": \"HTTPValidationError\"\n}\n</code></pre>"},{"location":"api/#get_xapistatements_1","title":"GET /xAPI/statements","text":"<p>Get</p> Description <p>Read a single xAPI Statement or multiple xAPI Statements.</p> <p>LRS Specification: https://github.com/adlnet/xAPI-Spec/blob/1.0.3/xAPI- Communication.md#213-get-statements</p> <p>Input parameters</p> Parameter In Type Default Nullable Description <code>HTTPBasic</code> header string N/A No Basic authentication <code>HTTPBasic</code> header string N/A No Basic authentication <code>activity</code> query string No Filter, only return Statements for which the Object of the Statement is an Activity with the specified id <code>agent</code> query string No Filter, only return Statements for which the specified Agent or Group is the Actor or Object of the Statement <code>ascending</code> query boolean False No If \"true\", return results in ascending order of stored time <code>attachments</code> query boolean False No **Not implemented** If \"true\", the LRS uses the multipart response format and includes all attachments as described previously. If \"false\", the LRS sends the prescribed response with Content-Type application/json and does not send attachment data. <code>format</code> query string exact No **Not implemented** If \"ids\", only include minimum information necessary in Agent, Activity, Verb and Group Objects to identify them. For Anonymous Groups this means including the minimum information needed to identify each member. If \"exact\", return Agent, Activity, Verb and Group Objects populated exactly as they were when the Statement was received. An LRS requesting Statements for the purpose of importing them would use a format of \"exact\" in order to maintain Statement Immutability. If \"canonical\", return Activity Objects and Verbs populated with the canonical definition of the Activity Objects and Display of the Verbs as determined by the LRS, after applying the language filtering process defined below, and return the original Agent and Group Objects as in \"exact\" mode. <code>limit</code> query integer 100 No Maximum number of Statements to return. 0 indicates return the maximum the server will allow <code>mine</code> query boolean False No If \"true\", return only the results for which the authority matches the \"agent\" associated to the user that is making the query. <code>pit_id</code> query string No Point-in-time ID to ensure consistency of search requests through multiple pages.NB: for internal use, not part of the LRS specification. <code>registration</code> query string No **Not implemented** Filter, only return Statements matching the specified registration id <code>related_activities</code> query boolean False No **Not implemented** Apply the Activity filter broadly. Include Statements for which the Object, any of the context Activities, or any of those properties in a contained SubStatement match the Activity parameter, instead of that parameter's normal behaviour <code>related_agents</code> query boolean False No **Not implemented** Apply the Agent filter broadly. Include Statements for which the Actor, Object, Authority, Instructor, Team, or any of these properties in a contained SubStatement match the Agent parameter, instead of that parameter's normal behaviour. <code>search_after</code> query string No Sorting data to allow pagination through large number of search results. NB: for internal use, not part of the LRS specification. <code>since</code> query string No Only Statements stored since the specified Timestamp (exclusive) are returned <code>statementId</code> query string No Id of Statement to fetch <code>until</code> query string No Only Statements stored at or before the specified Timestamp are returned <code>verb</code> query string No Filter, only return Statements matching the specified Verb id <code>voidedStatementId</code> query string No **Not implemented** Id of voided Statement to fetch <p> Response 200 OK </p> application/json Schema of the response body <pre><code>{\n    \"type\": \"object\",\n    \"title\": \"Response Get Xapi Statements Get\"\n}\n</code></pre> <p> Response 422 Unprocessable Entity </p> application/json <p><pre><code>{\n    \"detail\": [\n        {\n            \"loc\": [\n                null\n            ],\n            \"msg\": \"string\",\n            \"type\": \"string\"\n        }\n    ]\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"properties\": {\n        \"detail\": {\n            \"items\": {\n                \"$ref\": \"#/components/schemas/ValidationError\"\n            },\n            \"type\": \"array\",\n            \"title\": \"Detail\"\n        }\n    },\n    \"type\": \"object\",\n    \"title\": \"HTTPValidationError\"\n}\n</code></pre>"},{"location":"api/#put_xapistatements_1","title":"PUT /xAPI/statements","text":"<p>Put</p> Description <p>Store a single statement as a single member of a set.</p> <p>LRS Specification: https://github.com/adlnet/xAPI-Spec/blob/1.0.3/xAPI- Communication.md#211-put-statements</p> <p>Input parameters</p> Parameter In Type Default Nullable Description <code>HTTPBasic</code> header string N/A No Basic authentication <code>HTTPBasic</code> header string N/A No Basic authentication <code>statementId</code> query string No <p>Request body</p> application/json <p><pre><code>{\n    \"actor\": null,\n    \"id\": \"282bcef8-665d-4e92-ac4a-049c5cfb93e4\",\n    \"object\": {\n        \"id\": \"string\"\n    },\n    \"verb\": {\n        \"id\": \"string\"\n    }\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the request body <pre><code>{\n    \"properties\": {\n        \"actor\": {\n            \"anyOf\": [\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiAgentWithMbox\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiAgentWithMboxSha1Sum\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiAgentWithOpenId\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiAgentWithAccount\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiAnonymousGroup\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiIdentifiedGroupWithMbox\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiIdentifiedGroupWithMboxSha1Sum\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiIdentifiedGroupWithOpenId\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiIdentifiedGroupWithAccount\"\n                }\n            ],\n            \"title\": \"Actor\"\n        },\n        \"id\": {\n            \"type\": \"string\",\n            \"format\": \"uuid\",\n            \"title\": \"Id\"\n        },\n        \"object\": {\n            \"$ref\": \"#/components/schemas/LaxObjectField\"\n        },\n        \"verb\": {\n            \"$ref\": \"#/components/schemas/LaxVerbField\"\n        }\n    },\n    \"type\": \"object\",\n    \"required\": [\n        \"actor\",\n        \"object\",\n        \"verb\"\n    ],\n    \"title\": \"LaxStatement\",\n    \"description\": \"Pydantic model for lax statement.\\n\\nIt accepts without validating all fields beyond the bare minimum required to\\nqualify an object as an XAPI statement.\"\n}\n</code></pre> <p> Response 204 No Content </p> <p> Response 400 Bad Request </p> application/json <p><pre><code>{\n    \"detail\": \"string\"\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"properties\": {\n        \"detail\": {\n            \"type\": \"string\",\n            \"title\": \"Detail\"\n        }\n    },\n    \"type\": \"object\",\n    \"required\": [\n        \"detail\"\n    ],\n    \"title\": \"ErrorDetail\",\n    \"description\": \"Pydantic model for errors raised detail.\\n\\nType for return value for errors raised in API endpoints.\\nUseful for OpenAPI documentation generation.\"\n}\n</code></pre> <p> Response 409 Conflict </p> application/json <p><pre><code>{\n    \"detail\": \"string\"\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"properties\": {\n        \"detail\": {\n            \"type\": \"string\",\n            \"title\": \"Detail\"\n        }\n    },\n    \"type\": \"object\",\n    \"required\": [\n        \"detail\"\n    ],\n    \"title\": \"ErrorDetail\",\n    \"description\": \"Pydantic model for errors raised detail.\\n\\nType for return value for errors raised in API endpoints.\\nUseful for OpenAPI documentation generation.\"\n}\n</code></pre> <p> Response 422 Unprocessable Entity </p> application/json <p><pre><code>{\n    \"detail\": [\n        {\n            \"loc\": [\n                null\n            ],\n            \"msg\": \"string\",\n            \"type\": \"string\"\n        }\n    ]\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"properties\": {\n        \"detail\": {\n            \"items\": {\n                \"$ref\": \"#/components/schemas/ValidationError\"\n            },\n            \"type\": \"array\",\n            \"title\": \"Detail\"\n        }\n    },\n    \"type\": \"object\",\n    \"title\": \"HTTPValidationError\"\n}\n</code></pre>"},{"location":"api/#post_xapistatements_1","title":"POST /xAPI/statements","text":"<p>Post</p> Description <p>Store a set of statements (or a single statement as a single member of a set).</p> <p>NB: at this time, using POST to make a GET request, is not supported. LRS Specification: https://github.com/adlnet/xAPI-Spec/blob/1.0.3/xAPI- Communication.md#212-post-statements</p> <p>Input parameters</p> Parameter In Type Default Nullable Description <code>HTTPBasic</code> header string N/A No Basic authentication <code>HTTPBasic</code> header string N/A No Basic authentication <p>Request body</p> application/json Schema of the request body <pre><code>{\n    \"anyOf\": [\n        {\n            \"$ref\": \"#/components/schemas/LaxStatement\"\n        },\n        {\n            \"items\": {\n                \"$ref\": \"#/components/schemas/LaxStatement\"\n            },\n            \"type\": \"array\"\n        }\n    ],\n    \"title\": \"Statements\"\n}\n</code></pre> <p> Response 200 OK </p> application/json <p><pre><code>[\n    null\n]\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"items\": {},\n    \"type\": \"array\",\n    \"title\": \"Response Post Xapi Statements Post\"\n}\n</code></pre> <p> Response 400 Bad Request </p> application/json <p><pre><code>{\n    \"detail\": \"string\"\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"properties\": {\n        \"detail\": {\n            \"type\": \"string\",\n            \"title\": \"Detail\"\n        }\n    },\n    \"type\": \"object\",\n    \"required\": [\n        \"detail\"\n    ],\n    \"title\": \"ErrorDetail\",\n    \"description\": \"Pydantic model for errors raised detail.\\n\\nType for return value for errors raised in API endpoints.\\nUseful for OpenAPI documentation generation.\"\n}\n</code></pre> <p> Response 409 Conflict </p> application/json <p><pre><code>{\n    \"detail\": \"string\"\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"properties\": {\n        \"detail\": {\n            \"type\": \"string\",\n            \"title\": \"Detail\"\n        }\n    },\n    \"type\": \"object\",\n    \"required\": [\n        \"detail\"\n    ],\n    \"title\": \"ErrorDetail\",\n    \"description\": \"Pydantic model for errors raised detail.\\n\\nType for return value for errors raised in API endpoints.\\nUseful for OpenAPI documentation generation.\"\n}\n</code></pre> <p> Response 422 Unprocessable Entity </p> application/json <p><pre><code>{\n    \"detail\": [\n        {\n            \"loc\": [\n                null\n            ],\n            \"msg\": \"string\",\n            \"type\": \"string\"\n        }\n    ]\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"properties\": {\n        \"detail\": {\n            \"items\": {\n                \"$ref\": \"#/components/schemas/ValidationError\"\n            },\n            \"type\": \"array\",\n            \"title\": \"Detail\"\n        }\n    },\n    \"type\": \"object\",\n    \"title\": \"HTTPValidationError\"\n}\n</code></pre>"},{"location":"api/#get_lbheartbeat","title":"GET /lbheartbeat","text":"<p>Lbheartbeat</p> Description <p>Load balancer heartbeat.</p> <p>Return a 200 when the server is running.</p> <p> Response 200 OK </p> application/json Schema of the response body"},{"location":"api/#get_heartbeat","title":"GET /heartbeat","text":"<p>Heartbeat</p> Description <p>Application heartbeat.</p> <p>Return a 200 if all checks are successful.</p> <p> Response 200 OK </p> application/json Schema of the response body"},{"location":"api/#get_whoami","title":"GET /whoami","text":"<p>Whoami</p> Description <p>Return the current user\u2019s username along with their scopes.</p> <p>Input parameters</p> Parameter In Type Default Nullable Description <code>HTTPBasic</code> header string N/A No Basic authentication <p> Response 200 OK </p> application/json Schema of the response body <pre><code>{\n    \"type\": \"object\",\n    \"title\": \"Response Whoami Whoami Get\"\n}\n</code></pre>"},{"location":"api/#schemas","title":"Schemas","text":""},{"location":"api/#basexapiaccount","title":"BaseXapiAccount","text":"Name Type <code>homePage</code> string <code>name</code> string"},{"location":"api/#basexapiagentwithaccount","title":"BaseXapiAgentWithAccount","text":"Name Type <code>account</code> BaseXapiAccount <code>name</code> string <code>objectType</code> string"},{"location":"api/#basexapiagentwithmbox","title":"BaseXapiAgentWithMbox","text":"Name Type <code>mbox</code> string <code>name</code> string <code>objectType</code> string"},{"location":"api/#basexapiagentwithmboxsha1sum","title":"BaseXapiAgentWithMboxSha1Sum","text":"Name Type <code>mbox_sha1sum</code> string <code>name</code> string <code>objectType</code> string"},{"location":"api/#basexapiagentwithopenid","title":"BaseXapiAgentWithOpenId","text":"Name Type <code>name</code> string <code>objectType</code> string <code>openid</code> string(uri)"},{"location":"api/#basexapianonymousgroup","title":"BaseXapiAnonymousGroup","text":"Name Type <code>member</code> Array&lt;&gt; <code>name</code> string <code>objectType</code> string"},{"location":"api/#basexapiidentifiedgroupwithaccount","title":"BaseXapiIdentifiedGroupWithAccount","text":"Name Type <code>account</code> BaseXapiAccount <code>member</code> Array&lt;&gt; <code>name</code> string <code>objectType</code> string"},{"location":"api/#basexapiidentifiedgroupwithmbox","title":"BaseXapiIdentifiedGroupWithMbox","text":"Name Type <code>mbox</code> string <code>member</code> Array&lt;&gt; <code>name</code> string <code>objectType</code> string"},{"location":"api/#basexapiidentifiedgroupwithmboxsha1sum","title":"BaseXapiIdentifiedGroupWithMboxSha1Sum","text":"Name Type <code>mbox_sha1sum</code> string <code>member</code> Array&lt;&gt; <code>name</code> string <code>objectType</code> string"},{"location":"api/#basexapiidentifiedgroupwithopenid","title":"BaseXapiIdentifiedGroupWithOpenId","text":"Name Type <code>member</code> Array&lt;&gt; <code>name</code> string <code>objectType</code> string <code>openid</code> string(uri)"},{"location":"api/#errordetail","title":"ErrorDetail","text":"Name Type <code>detail</code> string"},{"location":"api/#httpvalidationerror","title":"HTTPValidationError","text":"Name Type <code>detail</code> Array&lt;ValidationError&gt;"},{"location":"api/#laxobjectfield","title":"LaxObjectField","text":"Name Type <code>id</code> string(uri)"},{"location":"api/#laxstatement","title":"LaxStatement","text":"Name Type <code>actor</code> <code>id</code> string(uuid) <code>object</code> LaxObjectField <code>verb</code> LaxVerbField"},{"location":"api/#laxverbfield","title":"LaxVerbField","text":"Name Type <code>id</code> string(uri)"},{"location":"api/#validationerror","title":"ValidationError","text":"Name Type <code>loc</code> Array&lt;&gt; <code>msg</code> string <code>type</code> string"},{"location":"api/#security_schemes","title":"Security schemes","text":"Name Type Scheme Description HTTPBasic http basic"},{"location":"backends/","title":"Backends for data storage","text":"<p>Ralph supports various backends that can be accessed to read from or write to (learning events or random data). Implemented backends are listed below along with their configuration parameters.  If your favourite data storage method is missing, feel free to submit your implementation or get in touch!</p>"},{"location":"backends/#key_concepts","title":"Key concepts","text":"<p>Each backend has its own parameter requirements. These parameters can be set as command line options or environment variables; the later is the recommended solution for sensitive data such as service credentials. For example, the <code>os_username</code> (OpenStack user name) parameter of the OpenStack Swift backend, can be set as a command line option using <code>swift</code> as the option prefix (and replacing underscores in its name by dashes):</p> <pre><code>ralph list --backend swift --swift-os-username johndoe # [...] more options\n</code></pre> <p>Alternatively, this parameter can be set as an environment variable (in upper case, prefixed by the program name, e.g. <code>RALPH_</code>):</p> <pre><code>export RALPH_BACKENDS__DATA__SWIFT__OS_USERNAME=\"johndoe\"\nralph list --backend swift # [...] more options\n</code></pre> <p>The general patterns for backend parameters are:</p> <ul> <li><code>--{{ backend_name }}-{{ parameter | underscore_to_dash }}</code> for command options, and,</li> <li><code>RALPH_BACKENDS__{{ backend_type | uppercase }}__{{ backend_name | uppercase }}__{{ parameter | uppercase }}</code> for environment variables, where the <code>backend_type</code> is one of <code>DATA</code>, <code>LRS</code> and <code>STREAM</code>.</li> </ul>"},{"location":"backends/#elasticsearch","title":"Elasticsearch","text":"<p>Elasticsearch backend is mostly used for indexation purpose (as a datalake) but it can also be used to fetch indexed data from it.</p> <p>Elasticsearch data backend default configuration.</p> <p>Attributes:</p> Name Type Description <code>ALLOW_YELLOW_STATUS</code> <code>bool</code> <p>Whether to consider Elasticsearch yellow health status to be ok.</p> <code>CLIENT_OPTIONS</code> <code>dict</code> <p>A dictionary of valid options for the Elasticsearch class initialization.</p> <code>DEFAULT_CHUNK_SIZE</code> <code>int</code> <p>The default chunk size for reading batches of documents.</p> <code>DEFAULT_INDEX</code> <code>str</code> <p>The default index to use for querying Elasticsearch.</p> <code>HOSTS</code> <code>str or tuple</code> <p>The comma-separated list of Elasticsearch nodes to connect to.</p> <code>LOCALE_ENCODING</code> <code>str</code> <p>The encoding used for reading/writing documents.</p> <code>POINT_IN_TIME_KEEP_ALIVE</code> <code>str</code> <p>The duration for which Elasticsearch should keep a point in time alive.</p> <code>REFRESH_AFTER_WRITE</code> <code>str or bool</code> <p>Whether the Elasticsearch index should be refreshed after the write operation.</p>"},{"location":"backends/#mongodb","title":"MongoDB","text":"<p>MongoDB backend is mostly used for indexation purpose (as a datalake) but it can also be used to fetch collections of documents from it.</p> <p>MongoDB data backend default configuration.</p> <p>Attributes:</p> Name Type Description <code>CONNECTION_URI</code> <code>str</code> <p>The MongoDB connection URI.</p> <code>DEFAULT_DATABASE</code> <code>str</code> <p>The MongoDB database to connect to.</p> <code>DEFAULT_COLLECTION</code> <code>str</code> <p>The MongoDB database collection to get objects from.</p> <code>CLIENT_OPTIONS</code> <code>MongoClientOptions</code> <p>A dictionary of MongoDB client options.</p> <code>DEFAULT_CHUNK_SIZE</code> <code>int</code> <p>The default chunk size to use when none is provided.</p> <code>LOCALE_ENCODING</code> <code>str</code> <p>The locale encoding to use when none is provided.</p>"},{"location":"backends/#clickhouse","title":"ClickHouse","text":"<p>The ClickHouse backend can be used as a data lake and to fetch collections of documents from it.</p> <p>Represent the ClickHouse data backend default configuration.</p> <p>Attributes:</p> Name Type Description <code>HOST</code> <code>str</code> <p>ClickHouse server host to connect to.</p> <code>PORT</code> <code>int</code> <p>ClickHouse server port to connect to.</p> <code>DATABASE</code> <code>str</code> <p>ClickHouse database to connect to.</p> <code>EVENT_TABLE_NAME</code> <code>str</code> <p>Table where events live.</p> <code>USERNAME</code> <code>str</code> <p>ClickHouse username to connect as (optional).</p> <code>PASSWORD</code> <code>str</code> <p>Password for the given ClickHouse username (optional).</p> <code>CLIENT_OPTIONS</code> <code>ClickHouseClientOptions</code> <p>A dictionary of valid options for the ClickHouse client connection.</p> <code>DEFAULT_CHUNK_SIZE</code> <code>int</code> <p>The default chunk size for reading/writing.</p> <code>LOCALE_ENCODING</code> <code>str</code> <p>The locale encoding to use when none is provided.</p>"},{"location":"backends/#ovh_-_log_data_platform_ldp","title":"OVH - Log Data Platform (LDP)","text":"<p>LDP is a nice service built by OVH on top of Graylog to follow, analyse and store your logs. Learning events (aka tracking logs) can be stored in GELF format using this backend.</p> <p>Read-only backend</p> <p>For now the LDP backend is read-only as we consider that it is mostly used to collect primary logs and not as a Ralph target. Feel free to get in touch to prove us wrong, or better: submit your proposal for the <code>write</code> method implementation.</p> <p>To access OVH\u2019s LDP API, you need to register Ralph as an authorized application and generate an application key, an application secret and a consumer key.</p> <p>While filling the registration form available at: eu.api.ovh.com/createToken/, be sure to give an appropriate validity time span to your token and allow only GET requests on the <code>/dbaas/logs/*</code> path.</p> <p>OVH LDP (Log Data Platform) data backend default configuration.</p> <p>Attributes:</p> Name Type Description <code>APPLICATION_KEY</code> <code>str</code> <p>The OVH API application key (AK).</p> <code>APPLICATION_SECRET</code> <code>str</code> <p>The OVH API application secret (AS).</p> <code>CONSUMER_KEY</code> <code>str</code> <p>The OVH API consumer key (CK).</p> <code>DEFAULT_STREAM_ID</code> <code>str</code> <p>The default stream identifier to query.</p> <code>ENDPOINT</code> <code>str</code> <p>The OVH API endpoint.</p> <code>REQUEST_TIMEOUT</code> <code>int</code> <p>HTTP request timeout in seconds.</p> <code>SERVICE_NAME</code> <code>str</code> <p>The default LDP account name.</p> <p>For more information about OVH\u2019s API client parameters, please refer to the project\u2019s documentation: github.com/ovh/python-ovh.</p>"},{"location":"backends/#openstack_swift","title":"OpenStack Swift","text":"<p>Swift is the OpenStack object storage service. This storage backend is fully supported (read and write operations) to stream and store log archives.</p> <p>Parameters correspond to a standard authentication using OpenStack Keystone service and configuration to work with the target container.</p> <p>Represent the SWIFT data backend default configuration.</p> <p>Attributes:</p> Name Type Description <code>AUTH_URL</code> <code>str</code> <p>The authentication URL.</p> <code>USERNAME</code> <code>str</code> <p>The name of the openstack swift user.</p> <code>PASSWORD</code> <code>str</code> <p>The password of the openstack swift user.</p> <code>IDENTITY_API_VERSION</code> <code>str</code> <p>The keystone API version to authenticate to.</p> <code>TENANT_ID</code> <code>str</code> <p>The identifier of the tenant of the container.</p> <code>TENANT_NAME</code> <code>str</code> <p>The name of the tenant of the container.</p> <code>PROJECT_DOMAIN_NAME</code> <code>str</code> <p>The project domain name.</p> <code>REGION_NAME</code> <code>str</code> <p>The region where the container is.</p> <code>OBJECT_STORAGE_URL</code> <code>str</code> <p>The default storage URL.</p> <code>USER_DOMAIN_NAME</code> <code>str</code> <p>The user domain name.</p> <code>DEFAULT_CONTAINER</code> <code>str</code> <p>The default target container.</p> <code>LOCALE_ENCODING</code> <code>str</code> <p>The encoding used for reading/writing documents.</p>"},{"location":"backends/#amazon_s3","title":"Amazon S3","text":"<p>S3 is the Amazon Simple Storage Service. This storage backend is fully supported (read and write operations) to stream and store log archives.</p> <p>Parameters correspond to a standard authentication with AWS CLI  and configuration to work with the target bucket.</p> <p>S3 data backend default configuration.</p> <p>Attributes:</p> Name Type Description <code>ACCESS_KEY_ID</code> <code>str</code> <p>The access key id for the S3 account.</p> <code>SECRET_ACCESS_KEY</code> <code>str</code> <p>The secret key for the S3 account.</p> <code>SESSION_TOKEN</code> <code>str</code> <p>The session token for the S3 account.</p> <code>ENDPOINT_URL</code> <code>str</code> <p>The endpoint URL of the S3.</p> <code>DEFAULT_REGION</code> <code>str</code> <p>The default region used in instantiating the client.</p> <code>DEFAULT_BUCKET_NAME</code> <code>str</code> <p>The default bucket name targeted.</p> <code>DEFAULT_CHUNK_SIZE</code> <code>str</code> <p>The default chunk size for reading and writing objects.</p> <code>LOCALE_ENCODING</code> <code>str</code> <p>The encoding used for writing dictionaries to objects.</p>"},{"location":"backends/#file_system","title":"File system","text":"<p>The file system backend is a dummy template that can be used to develop your own backend.  It is a \u201cdummy\u201d backend as it is not intended for practical use (UNIX <code>ls</code> and <code>cat</code> would be more practical).</p> <p>The only required parameter is the <code>path</code> we want to list or stream content from.</p> <p>FileSystem data backend default configuration.</p> <p>Attributes:</p> Name Type Description <code>DEFAULT_CHUNK_SIZE</code> <code>int</code> <p>The default chunk size for reading files.</p> <code>DEFAULT_DIRECTORY_PATH</code> <code>str or Path</code> <p>The default target directory path where to perform list, read and write operations.</p> <code>DEFAULT_QUERY_STRING</code> <code>str</code> <p>The default query string to match files for the read operation.</p> <code>LOCALE_ENCODING</code> <code>str</code> <p>The encoding used for writing dictionaries to files.</p> <p>The ClickHouse client options supported in Ralph can be found in these locations:</p> <ul> <li>Python driver specific</li> <li>General ClickHouse client settings</li> </ul>"},{"location":"backends/#learning_record_store_lrs_-_http_backend_interface","title":"Learning Record Store (LRS) - HTTP backend interface","text":"<p>Warning</p> <p><code>HTTP</code> backend type will soon be merged into the <code>Data</code> backend type.</p> <p>PR #521 prepares <code>Data</code> backend alignments with <code>HTTP</code> backend <code>read</code> method signature</p> <p>The LRS backend is used to store and retrieve xAPI statements from various systems that follow the xAPI specification (such as our own Ralph LRS, which can be run from this package).  LRS systems are mostly used in e-learning infrastructures.</p> <p>LRS HTTP backend default configuration.</p> <p>Attributes:</p> Name Type Description <code>BASE_URL</code> <code>AnyHttpUrl</code> <p>LRS server URL.</p> <code>USERNAME</code> <code>str</code> <p>Basic auth username for LRS authentication.</p> <code>PASSWORD</code> <code>str</code> <p>Basic auth password for LRS authentication.</p> <code>HEADERS</code> <code>dict</code> <p>Headers defined for the LRS server connection.</p> <code>STATUS_ENDPOINT</code> <code>str</code> <p>Endpoint used to check server status.</p> <code>STATEMENTS_ENDPOINT</code> <code>str</code> <p>Default endpoint for LRS statements resource.</p>"},{"location":"backends/#websocket_-_stream_backend_interface","title":"WebSocket - Stream backend interface","text":"<p>The webSocket backend is read-only and can be used to get real-time events.</p> <p>If you use OVH\u2019s Logs Data Platform (LDP), you can retrieve a WebSocket URI to test your data stream by following instructions from the official documentation.</p> <p>Websocket stream backend default configuration.</p> <p>Attributes:</p> Name Type Description <code>URI</code> <code>str</code> <p>The URI to connect to.</p>"},{"location":"models/","title":"Learning statement models","text":"<p>The learning statement models validation and conversion tools in Ralph empower you to work with an LRS and ensure the quality of xAPI statements. These features not only enhance the integrity of your learning data but also facilitate integration and compliance with industry standards.</p> <p>This section provides insights into the supported models, their conversion, and validation.</p>"},{"location":"models/#supported_statements","title":"Supported statements","text":"<p>Learning statement models encompass a wide array of xAPI and OpenEdx statement types, ensuring comprehensive support for your e-learning data.</p> <ol> <li> <p>xAPI statements models:</p> <ul> <li>LMS</li> <li>Video</li> <li>Virtual classroom</li> </ul> </li> <li> <p>OpenEdx statements models:</p> <ul> <li>Enrollment</li> <li>Navigational</li> <li>Open Reponse Assessment</li> <li>Peer instruction</li> <li>Problem interaction</li> <li>Textbook interaction</li> <li>Video interaction</li> </ul> </li> </ol>"},{"location":"models/#statements_validation","title":"Statements validation","text":"<p>In learning analytics, the validation of statements takes on significant importance.  These statements, originating from diverse sources, systems or applications, must align with specific standards such as xAPI for the best known.  The validation process becomes essential in ensuring that these statements meet the required standards, facilitating data quality and reliability. </p> <p>Ralph allows you to automate the validation process in your production stack.  OpenEdx related events and xAPI statements are supported.</p> <p>Warning</p> <p>For now, validation is effective only with supported learning statement models on Ralph. About xAPI statements, an issue is open to extend validation to any xAPI statement.</p> <p>Check out tutorials to test the validation feature:</p> <ul> <li><code>validate</code> with Ralph as a CLI</li> <li><code>validate</code> with Ralph as a library</li> </ul>"},{"location":"models/#statements_conversion","title":"Statements conversion","text":"<p>Ralph currently supports conversion from OpenEdx learning events to xAPI statements. Here is the up-to-date conversion sets availables: </p> FROM TO edx.course.enrollment.activated registered to a course edx.course.enrollment.deactivated unregistered to a course load_video/edx.video.loaded initialized a video play_video/edx.video.played played a video pause_video/edx.video.paused paused a video stop_video/edx.video.stopped terminated a video seek_video/edx.video.position.changed seeked in a video <p>Check out tutorials to test the conversion feature:</p> <ul> <li><code>convert</code> with Ralph as a CLI</li> <li><code>convert</code> with Ralph as a library</li> </ul>"},{"location":"tutorials/cli/","title":"How to use Ralph as a CLI ?","text":"<p>WIP.</p>"},{"location":"tutorials/cli/#prerequisites","title":"Prerequisites","text":"<ul> <li>Ralph should be properly installed to be used as a <code>CLI</code>. Follow Installation section for more information</li> <li>[Recommended] To easily manipulate JSON streams, please install <code>jq</code> on your machine</li> </ul>"},{"location":"tutorials/cli/#validate_command","title":"<code>validate</code> command","text":"<p>In this tutorial, we\u2019ll walk you through the process of using <code>validate</code> command to check the validity of xAPI statements. </p>"},{"location":"tutorials/cli/#with_an_invalid_xapi_statement","title":"With an invalid xAPI statement","text":"<p>First, let\u2019s test the <code>validate</code> command with a dummy <code>JSON</code> string.</p> <ul> <li>Create in the terminal a dummy statement as follows: </li> </ul> <pre><code>invalid_statement='{\"foo\": \"invalid xapi\"}'\n</code></pre> <ul> <li>Run validation on this statement with this command:</li> </ul> <pre><code>echo \"$invalid_statement\" | ralph validate -f xapi \n</code></pre> <ul> <li>You should observe the following output from the terminal:</li> </ul> <pre><code>INFO     ralph.cli Validating xapi events (ignore_errors=False | fail-on-unknown=False)\nERROR    ralph.models.validator No matching pydantic model found for input event\nINFO     ralph.models.validator Total events: 1, Invalid events: 1\n</code></pre>"},{"location":"tutorials/cli/#with_a_valid_xapi_statement","title":"With a valid xAPI statement","text":"<p>Now, let\u2019s test the <code>validate</code> command with a valid xAPI statement.</p> <p>The tutorial is made on a <code>completed video</code> xAPI statement.</p> Info <p>According to the specification, an xAPI statement to be valid should contain, at least the three following fields:</p> <ul> <li>an <code>actor</code> (with a correct IFI), </li> <li>a <code>verb</code> (with an <code>id</code> property), </li> <li>an <code>object</code> (with an <code>id</code> property).</li> </ul> <ul> <li>Create in the terminal a valid xAPI statement as follows: </li> </ul> <pre><code>valid_statement='{\"actor\": {\"mbox\": \"mailto:johndoe@example.com\", \"name\": \"John Doe\"}, \"verb\": {\"id\": \"http://adlnet.gov/expapi/verbs/completed\"}, \"object\": {\"id\": \"http://example.com/video/001-introduction\"}, \"timestamp\": \"2023-10-31T15:30:00Z\"}'\n</code></pre> <ul> <li>Run validation on this statement with this command:</li> </ul> <pre><code>echo \"$valid_statement\" | bin/ralph validate -f xapi \n</code></pre> <ul> <li>You should observe the following output from the terminal: </li> </ul> <pre><code>INFO     ralph.cli Validating xapi events (ignore_errors=False | fail-on-unknown=False)\nINFO     ralph.models.validator Total events: 1, Invalid events: 1\n</code></pre>"},{"location":"tutorials/cli/#convert_command","title":"<code>convert</code> command","text":"<p>In this tutorial, you\u2019ll learn how to convert OpenEdx events into xAPI statements with Ralph. </p> <p>Note</p> <p>Please note that this feature is currently only supported for a set of OpenEdx events.  When converting Edx events to xAPI statements, always refer to the list of supported event types to ensure accurate and successful conversion.</p> <p>For this example, let\u2019s choose the <code>page_close</code> OpenEdx event that is converted into a <code>terminated a page</code> xAPI statement.</p> <ul> <li>Create in the terminal a <code>page_close</code> OpenEdx event as follows: </li> </ul> <pre><code>edx_statements={\"username\": \"\", \"ip\": \"0.0.0.0\", \"agent\": \"0\", \"host\": \"0\", \"referer\": \"\", \"accept_language\": \"0\", \"context\": {\"course_id\": \"\", \"course_user_tags\": null, \"module\": null, \"org_id\": \"0\", \"path\": \".\", \"user_id\": null}, \"time\": \"2000-01-01T00:00:00\", \"page\": \"http://A.ac/\", \"event_source\": \"browser\", \"session\": \"\", \"event\": \"{}\", \"event_type\": \"page_close\", \"name\": \"page_close\"}\n</code></pre> <ul> <li>Convert this statement into a <code>terminated a page</code> statement with this command:</li> </ul> <pre><code>echo \"$edx_statements\" | \\ \nralph convert \\\n    --platform-url \"http://lms-example.com\" \\\n    --uuid-namespace \"ee241f8b-174f-5bdb-bae9-c09de5fe017f\" \\\n    --from edx \\\n    --to xapi | \\\n    jq\n</code></pre> <ul> <li>You should observe the following output from the terminal: </li> </ul> <pre><code>INFO     ralph.cli Converting edx events to xapi format (ignore_errors=False | fail-on-unknown=False)\nINFO     ralph.models.converter Total events: 1, Invalid events: 0\n{\n  \"id\": \"8670c7d4-5485-52bd-b10a-a8ae27a51501\",\n  \"actor\": {\n    \"account\": {\n      \"homePage\": \"http://lms-example.com\",\n      \"name\": \"anonymous\"\n    }\n  },\n  \"verb\": {\n    \"id\": \"http://adlnet.gov/expapi/verbs/terminated\"\n  },\n  \"object\": {\n    \"id\": \"http://A.ac/\",\n    \"definition\": {\n      \"type\": \"http://activitystrea.ms/schema/1.0/page\"\n    }\n  },\n  \"timestamp\": \"2000-01-01T00:00:00\",\n  \"version\": \"1.0.0\"\n}\n</code></pre> <p>\ud83c\udf89 Congratulations! You just have converted an event generated from OpenEdx LMS to a standardised xAPI statement! </p> Store locally converted statements <p>To stored the converted statements locally on your machine, send the output of the <code>convert</code> command to a <code>JSON</code> file as follows: <pre><code>echo \"$edx_statements\" | \\ \nralph convert \\\n    --platform-url \"http://lms-example.com\" \\\n    --uuid-namespace \"ee241f8b-174f-5bdb-bae9-c09de5fe017f\" \\\n    --from edx \\\n    --to xapi \\\n    &gt; converted_event.json\n</code></pre></p>"},{"location":"tutorials/development_contributing/","title":"How to start developing with Ralph?","text":""},{"location":"tutorials/development_contributing/#prepare_your_environment","title":"Prepare your environment","text":"<p>Welcome to our developer contribution guidelines!  If you\u2019re interested in contributing to our project, there are a few prerequisites to get you started.  Ralph development environment is containerized with Docker for consistency. Before diving in, ensure you have the following installed:</p> <ul> <li>Docker Engine</li> <li>Docker Compose</li> <li>make</li> </ul>"},{"location":"tutorials/development_contributing/#bootstrap_ralph_for_development","title":"Bootstrap Ralph for development","text":"<p>To start playing with <code>ralph</code>, you should first <code>bootstrap</code> using:</p> <pre><code>make bootstrap\n</code></pre> <p>Once the project has been bootstrapped, you may want to edit generated <code>.env</code> file to set up available backend parameters that will be injected into the running container as environment variables to configure Ralph (see backends documentation):</p> <pre><code># Elasticsearch backend\nRALPH_BACKENDS__LRS__ES__HOSTS=http://elasticsearch:9200\nRALPH_BACKENDS__LRS__ES__INDEX=statements\nRALPH_BACKENDS__LRS__ES__TEST_HOSTS=http://elasticsearch:9200\nRALPH_BACKENDS__LRS__ES__TEST_INDEX=test-index\n\n# [...]\n</code></pre> Uncomment lines to define environment variables <p>Lines starting with a <code>#</code> are considered as commented and thus will have no effect while running Ralph.</p>"},{"location":"tutorials/development_contributing/#working_with_backends","title":"Working with backends","text":"<p>To configure the backends, we provide default parameters in the <code>.env.dist</code> template which is copied to the <code>.env</code> file when bootstrapping the project for the first time.  You can uncomment them so that they are properly injected in running containers.</p> <p>In order to run the Elasticsearch backend locally on GNU/Linux operating systems, ensure that your virtual memory limits are not too low and increase them if needed by typing this command from your terminal (as <code>root</code> or using <code>sudo</code>):</p> <p><code>sysctl -w vm.max_map_count=262144</code></p> <p>Reference: https://www.elastic.co/guide/en/elasticsearch/reference/master/vm-max-map-count.html</p> <p>Once configured, start the backend container using:</p> <pre><code>make run-[BACKEND]\n</code></pre> <p>Substitute <code>[BACKEND]</code> by the backend name, e.g. <code>es</code> for Elasticsearch or <code>swift</code> for OpenStack Swift:</p> <pre><code># Start Elasticsearch backend\nmake run-es\n# Start Swift backend\nmake run-swift\n# Start Mongo backend\nmake run-mongo\n# Start ClickHouse backend\nmake run-clickhouse\n# Start all backends\nmake run-all\n</code></pre> <p>Disk space for Elasticsearch</p> <p>Ensure that you have at least 10% of available disk space on your machine to run Elasticsearch. </p> <p>Now that you have started at least the <code>elasticsearch</code> and <code>swift</code> backends, it\u2019s time to play with them:</p> <pre><code># Store a JSON file in the Swift backend\necho '{\"id\": 1, \"foo\": \"bar\"}' | \\\n    ./bin/ralph write -b swift -t foo.json\n\n# Check that we have created a new JSON file in the Swift backend\nbin/ralph list -b swift\n&gt;&gt;&gt; foo.json\n\n# Read the content of the JSON file and index it in Elasticsearch\nbin/ralph read -b swift -t foo.json | \\\n    bin/ralph write -b es\n\n# Check that we have properly indexed the JSON file in Elasticsearch\nbin/ralph read -b es\n&gt;&gt;&gt; {\"id\": 1, \"foo\": \"bar\"}\n</code></pre>"},{"location":"tutorials/development_contributing/#wip_working_with_the_lrs","title":"[WIP] Working with the LRS","text":""},{"location":"tutorials/development_contributing/#working_with_ralphs_tray","title":"Working with Ralph\u2019s tray","text":"<p>Ralph is distributed along with its tray (a deployable package for Kubernetes clusters using Arnold). If you intend to work on this tray, please refer to Arnold\u2019s documentation first.</p>"},{"location":"tutorials/development_contributing/#prerequisites","title":"Prerequisites","text":"<ul> <li>Kubectl (&gt;<code>v.1.23.5</code>):   This CLI is used to communicate with the running Kubernetes instance you   will use.</li> <li>k3d (&gt;<code>v.5.0.0</code>): This tool is used to set up   and run a lightweight Kubernetes cluster, in order to have a local   environment (it is required to complete quickstart instructions below to   avoid depending on an existing Kubernetes cluster).</li> <li>curl is required by Arnold\u2019s CLI.</li> <li>gnupg to encrypt Ansible vaults passwords and   collaborate with your team.</li> </ul>"},{"location":"tutorials/development_contributing/#create_a_local_k3d_cluster","title":"Create a local <code>k3d</code> cluster","text":"<p>To create (or run) a local kubernetes cluster, we use <code>k3d</code>. The cluster\u2019s bootstrapping should be run via:</p> <pre><code>make k3d-cluster\n</code></pre> <p>Running a k3d-cluster locally supposes that the 80 and 443 ports of your machine are available, so that the ingresses created for your project responds properly. If one or both ports are already used by another service running on your machine, the <code>make k3d-cluster</code> command may fail.</p> <p>You can check that your cluster is running using the <code>k3d cluster</code> command:</p> <pre><code>k3d cluster list\n</code></pre> <p>You should expect the following output:</p> <pre><code>NAME     SERVERS   AGENTS   LOADBALANCER\nralph    1/1       0/0      true\n</code></pre> <p>As you can see, we are running a single node cluster called <code>ralph</code>.</p>"},{"location":"tutorials/development_contributing/#bootstrap_an_arnold_project","title":"Bootstrap an Arnold project","text":"<p>Once your Kubernetes cluster is running, you need to create a standard Arnold project describing applications and environments you need to deploy:</p> <pre><code>make arnold-bootstrap\n</code></pre> <p>Once bootstrapped, Arnold should have created a <code>group_vars</code> directory.</p> <p>Run the following command to discover the directory tree.</p> <pre><code>tree group_vars\n</code></pre> <p>The output should be as follows: <pre><code>group_vars\n\u251c\u2500\u2500 common\n\u2514\u2500\u2500 customer\n    \u2514\u2500\u2500 ralph\n        \u251c\u2500\u2500 development\n        \u2502\u00a0\u00a0 \u251c\u2500\u2500 main.yml\n        \u2502\u00a0\u00a0 \u2514\u2500\u2500 secrets\n        \u2502\u00a0\u00a0     \u251c\u2500\u2500 databases.vault.yml\n        \u2502\u00a0\u00a0     \u251c\u2500\u2500 elasticsearch.vault.yml\n        \u2502\u00a0\u00a0     \u2514\u2500\u2500 ralph.vault.yml\n        \u2514\u2500\u2500 main.yml\n\n5 directories, 5 files\n</code></pre></p> <p>To create the LRS credentials file, you need to provide a list of accounts allowed to request the LRS in Ralph\u2019s vault:</p> <pre><code># Setup your kubernetes environment\nsource .k3d-cluster.env.sh\n\n# Decrypt the vault\nbin/arnold -d -c ralph -e development -- vault -a ralph decrypt\n</code></pre> <p>Edit the vault file to add a new account for the <code>foo</code> user with the <code>bar</code> password and a relevant scope:</p> <pre><code># group_vars/customer/ralph/development/secrets/ralph.vault.yml\n#\n# [...]\n#\n# LRS\nLRS_AUTH:\n  - username: \"foo\"\n    hash: \"$2b$12$lCggI749U6TrzK7Qyr7xGe1KVSAXdPjtkMew.BD6lzIk//T5YSb72\"\n    scopes:\n      - \"all\"\n</code></pre> <p>The password hash has been generated using <code>bcrypt</code> as explained in the API user guide.</p> <p>And finally (re-)encrypt Ralph\u2019s vault:</p> <pre><code>bin/arnold -d -c ralph -e development -- vault -a ralph encrypt\n</code></pre> <p>You are now ready to create the related Kubernetes Secret while initializing Arnold project in the next step.</p>"},{"location":"tutorials/development_contributing/#prepare_working_namespace","title":"Prepare working namespace","text":"<p>You are now ready to create required Kubernetes objects to start working on Ralph\u2019s deployment:</p> <pre><code>make arnold-init\n</code></pre> <p>At this point an Elasticsearch cluster should be running on your Kubernetes cluster:</p> <pre><code>kubectl -n development-ralph get -l app=elasticsearch pod\nNAME                                         READY   STATUS      RESTARTS   AGE\nelasticsearch-node-0                         1/1     Running     0          69s\nelasticsearch-node-1                         1/1     Running     0          69s\nelasticsearch-node-2                         1/1     Running     0          69s\nes-index-template-j-221010-09h25m24s-nx5qz   0/1     Completed   0          49s\n</code></pre> <p>We are now ready to deploy Ralph to Kubernetes!</p>"},{"location":"tutorials/development_contributing/#deploy_code_repeat","title":"Deploy, code, repeat","text":"<p>To test your local docker image, you need to build it and publish it to the local kubernetes cluster docker registry using the <code>k3d-push</code> Makefile rule:</p> <pre><code>make k3d-push\n</code></pre> <p>Note</p> <p>Each time you modify Ralph\u2019s application or its Docker image, you will need to make this update.</p> <p>Now that your Docker image is published, it\u2019s time to deploy it!</p> <pre><code>make arnold-deploy\n</code></pre> <p>To test this deployment, let\u2019s try to make an authenticated request to the LRS:</p> <pre><code>curl -sLk \\\n  --user foo:bar \\\n  \"https://$(\\\n      kubectl -n development-ralph \\\n      get \\\n      ingress/ralph-app-current \\\n      -o jsonpath='{.spec.rules[0].host}')/whoami\"\n</code></pre> <p>And why not send test statements from Potsie\u2019s repository:</p> <pre><code>curl -sL \\\n  https://github.com/openfun/potsie/raw/main/fixtures/elasticsearch/lrs.json.gz | \\\ngunzip | \\\nhead -n 100 | \\\njq -s . | \\\nsed \"s/@timestamp/timestamp/g\" | \\\ncurl -sLk \\\n  --user foo:bar \\\n  -X POST \\\n  -H \"Content-Type: application/json\" \\\n  \"https://$(\\\n      kubectl -n development-ralph \\\n      get \\\n      ingress/ralph-app-current \\\n      -o jsonpath='{.spec.rules[0].host}')/xAPI/statements/\" \\\n  -d @-\n</code></pre> <p>Install <code>jq</code></p> <p>This example requires <code>jq</code> command to serialize the request payload (xAPI statements). When dealing with JSON data, we strongly recommend installing it to manipulate them from the command line.</p>"},{"location":"tutorials/development_contributing/#perform_arnolds_operations","title":"Perform Arnold\u2019s operations","text":"<p>If you want to run the <code>bin/arnold</code> script to run specific Arnold commands, you must ensure that your environment is properly set and that Arnold runs in development mode (i.e. using the <code>-d</code> flag):</p> <pre><code>source .k3d-cluster.env.sh\nbin/arnold -d -c ralph -e development -- vault -a ralph view\n</code></pre>"},{"location":"tutorials/development_contributing/#stop_k3d_cluster","title":"Stop <code>k3d</code> cluster","text":"<p>When finished to work on the Tray, you can stop the <code>k3d</code> cluster using the <code>k3d-stop</code> helper:</p> <pre><code>make k3d-stop\n</code></pre>"},{"location":"tutorials/development_contributing/#test_your_development","title":"Test your development","text":"<p>To run tests on your code, either use the <code>test</code> Make target or the <code>bin/pytest</code> script to pass specific arguments to the test runner:</p> <pre><code># Run all tests\nmake test\n\n# Run pytest with options\nbin/pytest -x -k mixins\n\n# Run pytest with options and more debugging logs\nbin/pytest tests/api -x -vvv -s --log-level=DEBUG -k mixins\n</code></pre>"},{"location":"tutorials/development_contributing/#lint_your_code","title":"Lint your code","text":"<p>To lint your code, either use the <code>lint</code> meta target or one of the linting tools we use:</p> <pre><code># Run all linters\nmake lint\n\n# Run ruff linter\nmake lint-ruff\n\n# Run ruff linter and resolve fixable errors\nmake lint-ruff-fix\n\n# List available linters\nmake help | grep lint-\n</code></pre>"},{"location":"tutorials/development_contributing/#document_your_modification","title":"Document your modification","text":"<p>In case you need to document your code, use the following targets:</p> <pre><code># Build documentation site\nmake docs-build\n\n# Run mkdocs live server for dev docs\nmake docs-serve\n</code></pre>"},{"location":"tutorials/library/","title":"How to use Ralph as a library ?","text":"<p>WIP.</p>"},{"location":"tutorials/library/#validate_method","title":"<code>validate</code> method","text":"<p>WIP.</p>"},{"location":"tutorials/library/#convert_method","title":"<code>convert</code> method","text":"<p>WIP.</p>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Ralph","text":"<p> \u2699\ufe0f The ultimate toolbox for your learning analytics (expect some xAPI \u2764\ufe0f)  </p> <p> </p> <p>Ralph is a toolbox for your learning analytics, it can be used as a:</p> <ul> <li>LRS, a HTTP API server to collect xAPI statements (learning events), following the ADL LRS standard</li> <li>command-line interface (CLI), to build data pipelines the UNIX-way\u2122\ufe0f,</li> <li>library, to fetch learning events from various backends, (de)serialize or     convert them from and to various standard formats such as     xAPI, or     openedx</li> </ul>"},{"location":"#installation","title":"Installation","text":""},{"location":"#install_from_pypi","title":"Install from PyPI","text":"<p>Ralph is distributed as a standard python package; it can be installed via <code>pip</code> or any other python package manager (e.g. Poetry, Pipenv, etc.):</p> Use a virtual environment for installation <p>To maintain a clean and controlled environment when installing <code>ralph-malph</code>, consider using a virtual environment.</p> <ul> <li> <p>Create a virtual environment: <pre><code>python3.12 -m venv &lt;path-to-virtual-environment&gt;\n</code></pre></p> </li> <li> <p>Activate the virtual environment: <pre><code>source venv/bin/activate\n</code></pre></p> </li> </ul> <p>If you only need to integrate learning statement models feature in your project, you don\u2019t need to install the <code>backends</code>, <code>cli</code> or <code>lrs</code> extra dependencies, the core library is what you need:</p> <pre><code>pip install ralph-malph\n</code></pre> <p>If you want to use the Ralph LRS server, add the <code>lrs</code> flavour in your installation.  You also have to choose the type of backend you will use for LRS data storage (<code>backend-clickhouse</code>,<code>backend-es</code>,<code>backend-mongo</code>).</p> <ul> <li>Install the core package with the LRS and the Elasticsearch backend. For example:</li> </ul> <pre><code>pip install ralph-malph[backend-es,lrs]\n</code></pre> <ul> <li>Add the <code>cli</code> flavour if you want to use the LRS on the command line: </li> </ul> <pre><code>pip install ralph-malph[backend-es,lrs,cli]\n</code></pre> <ul> <li>If you have various uses for Ralph\u2019s features or would like to discover all the existing functionnalities, it is recommended to install the full package: </li> </ul> <pre><code>pip install ralph-malph[backend-clickhouse,backend-es,backend-ldp,backend-lrs,backend-mongo,backend-s3,backend-swift,backend-ws,cli,lrs]\n</code></pre>"},{"location":"#install_from_dockerhub","title":"Install from DockerHub","text":"<p>Ralph is distributed as a Docker image. If Docker is installed on your machine, it can be pulled from DockerHub:</p> <pre><code>docker run --rm -i fundocker/ralph:latest ralph --help\n</code></pre> Use a <code>ralph</code> alias in your local environment <p>Simplify your workflow by creating an alias for easy access to Ralph commands:</p> <pre><code>alias ralph=\"docker run --rm -i fundocker/ralph:latest ralph\"\n</code></pre>"},{"location":"#wip_start_using_ralph","title":"[WIP] Start using Ralph","text":""},{"location":"#contributing_to_ralph","title":"Contributing to Ralph","text":"<p>If you\u2019re interested in contributing to Ralph, whether it\u2019s by reporting issues, suggesting improvements, or submitting code changes, please head over to our dedicated Contributing to Ralph page.  There, you\u2019ll find detailed guidelines and instructions on how to take part in the project.</p> <p>We look forward to your contributions and appreciate your commitment to making Ralph a more valuable tool for everyone.</p>"},{"location":"#contributors","title":"Contributors","text":""},{"location":"#license","title":"License","text":"<p>This work is released under the MIT License (see LICENSE).</p>"},{"location":"CHANGELOG/","title":"Changelog","text":"<p>All notable changes to this project will be documented in this file.</p> <p>The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.</p>"},{"location":"CHANGELOG/#unreleased","title":"Unreleased","text":""},{"location":"CHANGELOG/#added","title":"Added","text":"<ul> <li>Implement Pydantic model for LRS Statements resource query parameters</li> <li>Implement xAPI LMS Profile statements validation</li> <li><code>EdX</code> to <code>xAPI</code> converters for enrollment events</li> <li>Backends: Add <code>Writable</code> and <code>Listable</code> interfaces to distinguish supported   functionalities among <code>data</code> backends</li> <li>Backends: Add <code>get_backends</code> function to automatically discover backends   for CLI and LRS usage</li> </ul>"},{"location":"CHANGELOG/#changed","title":"Changed","text":"<ul> <li>Upgrade base python version to 3.12 for the development stack and Docker   image</li> <li>Upgrade <code>cachetools</code> to <code>5.3.2</code></li> <li>Refactor <code>database</code> and <code>storage</code> backends under the unified <code>data</code> backend interface [BC]</li> <li>Refactor LRS <code>query_statements</code> and <code>query_statements_by_ids</code> backends methods under the unified <code>lrs</code> backend interface [BC]</li> <li>Refactor LRS Statements resource query parameters defined for <code>ralph</code> API</li> <li>User credentials must now include an \u201cagent\u201d field which can be created   using the cli</li> <li><code>GET /statements</code> now has \u201cmine\u201d option which matches statements that have an authority field matching that of the user</li> <li>CLI: change <code>push</code> to <code>write</code> and <code>fetch</code> to <code>read</code> [BC]</li> <li>Upgrade <code>fastapi</code> to <code>0.104.1</code></li> <li>Upgrade <code>sentry_sdk</code> to <code>1.34.0</code></li> <li>Upgrade <code>uvicorn</code> to <code>0.24.0.post1</code></li> <li>API: Invalid parameters now return 400 status code</li> <li>API: Forwarding PUT now uses PUT (instead of POST)</li> <li>Models: The xAPI <code>context.contextActivities.category</code> field is now mandatory   in the video and virtual classroom profiles. [BC]</li> <li>Backends: <code>LRSHTTP</code> methods must not be used in <code>asyncio</code> events loop (BC)</li> <li>Add variable to override PVC name in arnold deployment</li> <li>Backends: add <code>max_statements</code> option to <code>AsyncLRSHTTP</code></li> <li>API: Incoming statements are enriched with <code>id</code>, <code>timestamp</code>, <code>stored</code>   and <code>authority</code></li> <li>Backends: update <code>statementId</code> and <code>voidedStatementId</code> to snake_case,   with camelCase alias, in <code>LRSStatementsQuery</code></li> <li>API: Add <code>RALPH_LRS_RESTRICT_BY_AUTHORITY</code> option making <code>?mine=True</code>   implicit</li> <li>CLI: list cli usage strings in alphabetical order</li> <li>API: Add <code>RALPH_LRS_RESTRICT_BY_SCOPE</code> option enabling endpoint access   control by user scopes</li> <li>Backends: Replace reference to a JSON column in ClickHouse with    function calls on the String column [BC]</li> <li>API: enhance \u2018limit\u2019 query parameter\u2019s validation </li> <li>API: Variable <code>RUNSERVER_AUTH_BACKEND</code> becomes <code>RUNSERVER_AUTH_BACKENDS</code>, and   multiple authentication methods are supported simultaneously</li> </ul>"},{"location":"CHANGELOG/#fixed","title":"Fixed","text":"<ul> <li>API: Fix a typo (\u2018attachements\u2019 -&gt; \u2018attachments\u2019) to ensure compliance with     the LRS specification and prevent potential silent bugs.</li> </ul>"},{"location":"CHANGELOG/#removed","title":"Removed","text":"<ul> <li><code>school</code>, <code>course</code>, <code>module</code> context extensions in Edx to xAPI base converter</li> <li><code>name</code> field in <code>VideoActivity</code> xAPI model mistakenly used in <code>video</code> profile</li> <li>drop support for python 3.7</li> </ul>"},{"location":"CHANGELOG/#390_-_2023-07-21","title":"3.9.0 - 2023-07-21","text":""},{"location":"CHANGELOG/#changed_1","title":"Changed","text":"<ul> <li>Upgrade <code>fastapi</code> to <code>0.100.0</code></li> <li>Upgrade <code>sentry_sdk</code> to <code>1.28.1</code></li> <li>Upgrade <code>uvicorn</code> to <code>0.23.0</code></li> <li>Enforce valid IRI for <code>activity</code> parameter in <code>GET /statements</code></li> <li>Change how duplicate xAPI statements are handled for <code>clickhouse</code> backend</li> </ul>"},{"location":"CHANGELOG/#380_-_2023-06-21","title":"3.8.0 - 2023-06-21","text":""},{"location":"CHANGELOG/#added_1","title":"Added","text":"<ul> <li>Implement edX open response assessment events pydantic models</li> <li>Implement edx peer instruction events pydantic models</li> <li>Implement xAPI VideoDownloaded pydantic model   (using xAPI TinCan <code>downloaded</code> verb)</li> </ul>"},{"location":"CHANGELOG/#changed_2","title":"Changed","text":"<ul> <li>Allow to use a query for HTTP backends in the CLI</li> </ul>"},{"location":"CHANGELOG/#370_-_2023-06-13","title":"3.7.0 - 2023-06-13","text":""},{"location":"CHANGELOG/#added_2","title":"Added","text":"<ul> <li>Implement asynchronous <code>async_lrs</code> backend</li> <li>Implement synchronous <code>lrs</code> backend</li> <li>Implement xAPI virtual classroom pydantic models</li> <li>Allow to insert custom endpoint url for S3 service</li> <li>Cache the HTTP Basic auth credentials to improve API response time</li> <li>Support OpenID Connect authentication method</li> </ul>"},{"location":"CHANGELOG/#changed_3","title":"Changed","text":"<ul> <li>Clean xAPI pydantic models naming convention</li> <li>Upgrade <code>fastapi</code> to <code>0.97.0</code></li> <li>Upgrade <code>sentry_sdk</code> to <code>1.25.1</code></li> <li>Set Clickhouse <code>client_options</code> to a dedicated pydantic model</li> <li>Upgrade <code>httpx</code> to <code>0.24.1</code></li> <li>Force a valid (JSON-formatted) IFI to be passed for the <code>/statements</code> GET query <code>agent</code> filtering</li> <li>Upgrade <code>cachetools</code> to <code>5.3.1</code></li> </ul>"},{"location":"CHANGELOG/#removed_1","title":"Removed","text":"<ul> <li><code>verb</code>.<code>display</code> field no longer mandatory in xAPI models and for converter</li> </ul>"},{"location":"CHANGELOG/#360_-_2023-05-17","title":"3.6.0 - 2023-05-17","text":""},{"location":"CHANGELOG/#added_3","title":"Added","text":"<ul> <li>Allow to ignore health check routes for Sentry transactions</li> </ul>"},{"location":"CHANGELOG/#changed_4","title":"Changed","text":"<ul> <li>Upgrade <code>sentry_sdk</code> to <code>1.22.2</code></li> <li>Upgrade <code>uvicorn</code> to <code>0.22.0</code></li> <li>LRS <code>/statements</code> <code>GET</code> method returns a code 400 with certain parameters as per the xAPI specification</li> <li>Use batch/v1 api in cronjob_pipeline manifest</li> <li>Use autoscaling/v2 in HorizontalPodAutoscaler manifest</li> </ul>"},{"location":"CHANGELOG/#fixed_1","title":"Fixed","text":"<ul> <li>Fix the <code>more</code> IRL building in LRS <code>/statements</code> GET requests</li> </ul>"},{"location":"CHANGELOG/#351_-_2023-04-18","title":"3.5.1 - 2023-04-18","text":""},{"location":"CHANGELOG/#changed_5","title":"Changed","text":"<ul> <li>Upgrade <code>httpx</code> to <code>0.24.0</code></li> <li>Upgrade <code>fastapi</code> to <code>0.95.1</code></li> <li>Upgrade <code>sentry_sdk</code> to <code>1.19.1</code></li> <li>Upgrade <code>uvicorn</code> to <code>0.21.1</code></li> </ul>"},{"location":"CHANGELOG/#fixed_2","title":"Fixed","text":"<ul> <li>An issue with starting Ralph in pre-built Docker containers</li> <li>Fix double quoting in ClickHouse backend server parameters</li> <li>An issue Ralph starting when ClickHouse is down</li> </ul>"},{"location":"CHANGELOG/#350_-_2023-03-08","title":"3.5.0 - 2023-03-08","text":""},{"location":"CHANGELOG/#added_4","title":"Added","text":"<ul> <li>Implement PUT verb on statements endpoint</li> <li>Add ClickHouse database backend support</li> </ul>"},{"location":"CHANGELOG/#changed_6","title":"Changed","text":"<ul> <li>Make trailing slashes optional on statements endpoint</li> <li>Upgrade <code>sentry_sdk</code> to <code>1.16.0</code></li> </ul>"},{"location":"CHANGELOG/#340_-_2023-03-01","title":"3.4.0 - 2023-03-01","text":""},{"location":"CHANGELOG/#changed_7","title":"Changed","text":"<ul> <li>Upgrade <code>fastapi</code> to <code>0.92.0</code></li> <li>Upgrade <code>sentry_sdk</code> to <code>1.15.0</code></li> </ul>"},{"location":"CHANGELOG/#fixed_3","title":"Fixed","text":"<ul> <li>Restore sentry integration in the LRS server</li> </ul>"},{"location":"CHANGELOG/#330_-_2023-02-03","title":"3.3.0 - 2023-02-03","text":""},{"location":"CHANGELOG/#added_5","title":"Added","text":"<ul> <li>Restore python 3.7+ support for library usage (models)</li> </ul>"},{"location":"CHANGELOG/#changed_8","title":"Changed","text":"<ul> <li>Allow xAPI extra fields in <code>extensions</code> fields</li> </ul>"},{"location":"CHANGELOG/#321_-_2023-02-01","title":"3.2.1 - 2023-02-01","text":""},{"location":"CHANGELOG/#changed_9","title":"Changed","text":"<ul> <li>Relax required Python version to <code>3.7</code>+</li> </ul>"},{"location":"CHANGELOG/#320_-_2023-01-25","title":"3.2.0 - 2023-01-25","text":""},{"location":"CHANGELOG/#added_6","title":"Added","text":"<ul> <li>Add a new <code>auth</code> subcommand to generate required credentials file for the LRS</li> <li>Implement support for AWS S3 storage backend</li> <li>Add CLI <code>--version</code> option</li> </ul>"},{"location":"CHANGELOG/#changed_10","title":"Changed","text":"<ul> <li>Upgrade <code>fastapi</code> to <code>0.89.1</code></li> <li>Upgrade <code>httpx</code> to <code>0.23.3</code></li> <li>Upgrade <code>sentry_sdk</code> to <code>1.14.0</code></li> <li>Upgrade <code>uvicorn</code> to <code>0.20.0</code></li> <li>Tray: add the <code>ca_certs</code> path for the ES backend client option (LRS)</li> <li>Improve Sentry integration for the LRS</li> <li>Update handbook link to <code>https://handbook.openfun.fr</code></li> <li>Upgrade base python version to 3.11 for the development stack and Docker   image</li> </ul>"},{"location":"CHANGELOG/#fixed_4","title":"Fixed","text":"<ul> <li>Restore ES and Mongo backends ability to use client options</li> </ul>"},{"location":"CHANGELOG/#310_-_2022-11-17","title":"3.1.0 - 2022-11-17","text":""},{"location":"CHANGELOG/#added_7","title":"Added","text":"<ul> <li>EdX to xAPI converters for video events</li> </ul>"},{"location":"CHANGELOG/#changed_11","title":"Changed","text":"<ul> <li>Improve Ralph\u2019s library integration by unpinning dependencies (and prefer   ranges)</li> <li>Upgrade <code>fastapi</code> to <code>0.87.0</code></li> </ul>"},{"location":"CHANGELOG/#removed_2","title":"Removed","text":"<ul> <li>ModelRules constraint</li> </ul>"},{"location":"CHANGELOG/#300_-_2022-10-19","title":"3.0.0 - 2022-10-19","text":""},{"location":"CHANGELOG/#added_8","title":"Added","text":"<ul> <li>Implement edX video browser events pydantic models</li> <li>Create a <code>post</code> endpoint for statements implementing the LRS spec</li> <li>Implement support for the MongoDB database backend</li> <li>Implement support for custom queries when using database backends <code>get</code>   method (used in the <code>fetch</code> command)</li> <li>Add dotenv configuration file support and <code>python-dotenv</code> dependency</li> <li>Add <code>host</code> and <code>port</code> options for the <code>runserver</code> cli command</li> <li>Add support for database selection when running the Ralph LRS server</li> <li>Implement support for xAPI statement forwarding</li> <li>Add database backends <code>status</code> checking</li> <li>Add <code>health</code> LRS router</li> <li>Tray: add LRS server support</li> </ul>"},{"location":"CHANGELOG/#changed_12","title":"Changed","text":"<ul> <li>Migrate to <code>python-legacy</code> handler for <code>mkdocstrings</code> package</li> <li>Upgrade <code>click</code> to <code>8.1.3</code></li> <li>Upgrade <code>elasticsearch</code> to <code>8.3.3</code></li> <li>Upgrade <code>fastapi</code> to <code>0.79.1</code></li> <li>Upgrade <code>ovh</code> to <code>1.0.0</code></li> <li>Upgrade <code>pydantic</code> to <code>1.9.2</code></li> <li>Upgrade <code>pymongo</code> to <code>4.2.0</code></li> <li>Upgrade <code>python-keystoneclient</code> to <code>5.0.0</code></li> <li>Upgrade <code>python-swiftclient</code> to <code>4.0.1</code></li> <li>Upgrade <code>requests</code> to <code>2.28.1</code></li> <li>Upgrade <code>sentry_sdk</code> to <code>1.9.5</code></li> <li>Upgrade <code>uvicorn</code> to <code>0.18.2</code></li> <li>Upgrade <code>websockets</code> to <code>10.3</code></li> <li>Make backends yield results instead of writing to standard streams (BC)</li> <li>Use pydantic settings management instead of global variables in defaults.py</li> <li>Rename backend and parser parameter environment variables (BC)</li> <li>Make project dependencies management more modular for library usage</li> </ul>"},{"location":"CHANGELOG/#removed_3","title":"Removed","text":"<ul> <li>Remove YAML configuration file support and <code>pyyaml</code> dependency (BC)</li> </ul>"},{"location":"CHANGELOG/#fixed_5","title":"Fixed","text":"<ul> <li>Tray: do not create a cronjobs list when no cronjob has been defined</li> <li>Restore history mixin logger</li> </ul>"},{"location":"CHANGELOG/#210_-_2022-04-13","title":"2.1.0 - 2022-04-13","text":""},{"location":"CHANGELOG/#added_9","title":"Added","text":"<ul> <li>Implement edX problem interaction events pydantic models</li> <li>Implement edX textbook interaction events pydantic models</li> <li><code>ws</code> websocket stream backend (compatible with the <code>fetch</code> command)</li> <li>bundle <code>jq</code>, <code>curl</code> and <code>wget</code> in the <code>fundocker/ralph</code> Docker image</li> <li>Tray: enable ralph app deployment command configuration</li> <li>Add a <code>runserver</code> command with basic auth and a <code>Whoami</code> route</li> <li>Create a <code>get</code> endpoint for statements implementing the LRS spec</li> <li>Add optional fields to BaseXapiModel</li> </ul>"},{"location":"CHANGELOG/#changed_13","title":"Changed","text":"<ul> <li>Upgrade <code>uvicorn</code> to <code>0.17.4</code></li> <li>Upgrade <code>elasticsearch</code> to <code>7.17.0</code></li> <li>Upgrade <code>sentry_sdk</code> to <code>1.5.5</code></li> <li>Upgrade <code>fastapi</code> to <code>0.73.0</code></li> <li>Upgrade <code>pyparsing</code> to <code>3.0.7</code></li> <li>Upgrade <code>pydantic</code> to <code>1.9.0</code></li> <li>Upgrade <code>python-keystoneclient</code> to <code>4.4.0</code></li> <li>Upgrade <code>python-swiftclient</code> to <code>3.13.0</code></li> <li>Upgrade <code>pyyaml</code> to <code>6.0</code></li> <li>Upgrade <code>requests</code> to <code>2.27.1</code></li> <li>Upgrade <code>websockets</code> to <code>10.1</code></li> </ul>"},{"location":"CHANGELOG/#201_-_2021-07-15","title":"2.0.1 - 2021-07-15","text":""},{"location":"CHANGELOG/#changed_14","title":"Changed","text":"<ul> <li>Upgrade <code>elasticsearch</code> to <code>7.13.3</code></li> </ul>"},{"location":"CHANGELOG/#fixed_6","title":"Fixed","text":"<ul> <li>Restore elasticsearch backend datastream compatibility for bulk operations</li> </ul>"},{"location":"CHANGELOG/#200_-_2021-07-09","title":"2.0.0 - 2021-07-09","text":""},{"location":"CHANGELOG/#added_10","title":"Added","text":"<ul> <li>xAPI video <code>interacted</code> pydantic models</li> <li>xAPI video <code>terminated</code> pydantic models</li> <li>xAPI video <code>completed</code> pydantic models</li> <li>xAPI video <code>seeked</code> pydantic models</li> <li>xAPI video <code>initialized</code> pydantic models</li> <li>xAPI video <code>paused</code> pydantic models</li> <li><code>convert</code> command to transform edX events to xAPI format</li> <li>EdX to xAPI converters for page <code>viewed</code> and<code>page_close</code> events</li> <li>Implement core event format converter</li> <li>xAPI video <code>played</code> pydantic models</li> <li>xAPI page <code>viewed</code> and page <code>terminated</code> pydantic models</li> <li>Implement edX navigational events pydantic models</li> <li>Implement edX enrollment events pydantic models</li> <li>Install security updates in project Docker images</li> <li>Model selector to retrieve associated pydantic model of a given event</li> <li><code>validate</code> command to lint edX events using pydantic models</li> <li>Support all available bulk operation types for the elasticsearch backend   (create, index, update, delete) using the <code>--es-op-type</code> option</li> </ul>"},{"location":"CHANGELOG/#changed_15","title":"Changed","text":"<ul> <li>Upgrade <code>elasticsearch</code> to <code>7.13.2</code></li> <li>Upgrade <code>python-swiftclient</code> to <code>3.12.0</code></li> <li>Upgrade <code>click</code> to <code>8.0.1</code></li> <li>Upgrade <code>click-option-group</code> to <code>0.5.3</code></li> <li>Upgrade <code>pydantic</code> to <code>1.8.2</code></li> <li>Upgrade <code>sentry_sdk</code> to <code>1.1.0</code></li> <li>Rename edX models</li> <li>Migrate model tests from factories to hypothesis strategies</li> <li>Tray: switch from openshift to k8s (BC)</li> <li>Tray: remove useless deployment probes</li> </ul>"},{"location":"CHANGELOG/#fixed_7","title":"Fixed","text":"<ul> <li>Tray: remove <code>version</code> immutable field in DC selector</li> </ul>"},{"location":"CHANGELOG/#120_-_2021-02-26","title":"1.2.0 - 2021-02-26","text":""},{"location":"CHANGELOG/#added_11","title":"Added","text":"<ul> <li>edX server event pydantic model and factory</li> <li>edX page_close browser event pydantic model and factory</li> <li>Tray: allow to specify a self-generated elasticsearch cluster CA certificate</li> </ul>"},{"location":"CHANGELOG/#fixed_8","title":"Fixed","text":"<ul> <li>Tray: add missing Swift variables in the secret</li> <li>Tray: fix pods anti-affinity selector</li> </ul>"},{"location":"CHANGELOG/#removed_4","title":"Removed","text":"<ul> <li><code>pandas</code> is no longer required</li> </ul>"},{"location":"CHANGELOG/#110_-_2021-02-04","title":"1.1.0 - 2021-02-04","text":""},{"location":"CHANGELOG/#added_12","title":"Added","text":"<ul> <li>Support for Swift storage backend</li> <li>Use the <code>push</code> command <code>--ignore-errors</code> option to ignore ES bulk import   errors</li> <li>The elasticsearch backend now accepts passing all supported client options</li> </ul>"},{"location":"CHANGELOG/#changed_16","title":"Changed","text":"<ul> <li>Upgrade <code>pyyaml</code> to <code>5.4.1</code></li> <li>Upgrade <code>pandas</code> to <code>1.2.1</code></li> </ul>"},{"location":"CHANGELOG/#removed_5","title":"Removed","text":"<ul> <li><code>click_log</code> is no longer required as we are able to configure logging</li> </ul>"},{"location":"CHANGELOG/#100_-_2021-01-13","title":"1.0.0 - 2021-01-13","text":""},{"location":"CHANGELOG/#added_13","title":"Added","text":"<ul> <li>Implement base CLI commands (list, extract, fetch &amp; push) for supported   backends</li> <li>Support for ElasticSearch database backend</li> <li>Support for LDP storage backend</li> <li>Support for FS storage backend</li> <li>Parse (gzipped) tracking logs in GELF format</li> <li>Support for application\u2019s configuration file</li> <li>Add optional sentry integration</li> <li>Distribute Arnold\u2019s tray to deploy Ralph in a k8s cluster as cronjobs</li> </ul>"},{"location":"LICENSE/","title":"License","text":"<p>MIT License</p> <p>Copyright (c) 2020-present France Universit\u00e9 Num\u00e9rique</p> <p>Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \u201cSoftware\u201d), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:</p> <p>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</p> <p>THE SOFTWARE IS PROVIDED \u201cAS IS\u201d, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</p>"},{"location":"UPGRADE/","title":"Upgrade","text":"<p>All instructions to upgrade this project from one release to the next will be documented in this file. Upgrades must be run sequentially, meaning you should not skip minor/major releases while upgrading (fix releases can be skipped).</p> <p>This project adheres to Semantic Versioning.</p>"},{"location":"UPGRADE/#3xx_to_400","title":"3.x.x to 4.0.0","text":""},{"location":"UPGRADE/#upgrade_user_credentials","title":"Upgrade user credentials","text":"<p>To conform to xAPI specifications, we need to represent users as xAPI Agents. You must therefore delete and re-create the credentials file using the updated cli, OR you can modify it directly to add the <code>agents</code> field. The credentials file is located in <code>{ RALPH_APP_DIR }/{ RALPH_AUTH_FILE }</code> (defaults to <code>.ralph/auth.json</code>). Each user profile must follow the following pattern (see this post for examples of valid agent objects) :</p> <p><pre><code>{\n  \"username\": \"USERNAME_UNCHANGED\",\n  \"hash\": \"PASSWORD_HASH_UNCHANGED\",\n  \"scopes\": [ LIST_OF_SCOPES_UNCHANGED ],\n  \"agent\": { A_VALID_AGENT_OBJECT }\n}\n</code></pre> Agent can take one of the following forms, as specified by the xAPI specification: - mbox:  <pre><code>\"agent\": {\n      \"mbox\": \"mailto:john.doe@example.com\"\n}\n</code></pre> - mbox_sha1sum: <pre><code>\"agent\": {\n        \"mbox_sha1sum\": \"ebd31e95054c018b10727ccffd2ef2ec3a016ee9\",\n}\n</code></pre> - openid: <pre><code>\"agent\": {\n      \"openid\": \"http://foo.openid.example.org/\"\n}\n</code></pre> - account: <pre><code>\"agent\": {\n      \"account\": {\n        \"name\": \"simonsAccountName\",\n        \"homePage\": \"http://www.exampleHomePage.com\"\n}\n</code></pre></p> <p>For example here is a valid <code>auth.json</code> file: </p> <pre><code>[\n  {\n    \"username\": \"john.doe@example.com\",\n    \"hash\": \"$2b$12$yBXrzIuRIk6yaft5KUgVFOIPv0PskCCh9PXmF2t7pno.qUZ5LK0D2\",\n    \"scopes\": [\"example_scope\"],\n    \"agent\": {\n      \"mbox\": \"mailto:john.doe@example.com\"\n    }\n  },\n  {\n    \"username\": \"simon.says@example.com\",\n    \"hash\": \"$2b$12$yBXrzIuRIk6yaft5KUgVFOIPv0PskCCh9PXmF2t7pno.qUZ5LK0D2\",\n    \"scopes\": [\"second_scope\", \"third_scope\"],\n    \"agent\": {\n      \"account\": {\n        \"name\": \"simonsAccountName\",\n        \"homePage\": \"http://www.exampleHomePage.com\"\n      }\n    }\n  }\n]\n</code></pre>"},{"location":"UPGRADE/#upgrade_history_syntax","title":"Upgrade history syntax","text":"<p>CLI syntax has been changed from <code>fetch</code> &amp; <code>push</code> to <code>read</code> &amp; <code>write</code> affecting the command history. You must replace the command history after updating: - locate your history file path, which is in <code>{ RALPH_APP_DIR }/history.json</code> (defaults to <code>.ralph/history.json</code>) - run the commands below to update history</p> <pre><code>sed -i 's/\"fetch\"/\"read\"/g' { my_history_file_path }\nsed -i 's/\"push\"/\"write\"/g' { my_history_file_path }\n</code></pre>"},{"location":"UPGRADE/#upgrade_clickhouse_schema","title":"Upgrade ClickHouse schema","text":"<p>If you are using the ClickHouse backend, schema changes have been made to drop the existing JSON column in favor of the String version of the  same data. See this issue  for details. </p> <p>Ralph does not manage the ClickHouse schema, so if you have existing  data you will need to manually alter it as an admin user. Note: this  will rewrite the statements table, which may take a long time if you have many rows. The command to run is:</p> <pre><code>-- If RALPH_BACKENDS__DATA__CLICKHOUSE__DATABASE is 'xapi'\n-- and RALPH_BACKENDS__DATA__CLICKHOUSE__EVENT_TABLE_NAME is 'test'\n\nALTER TABLE xapi.test DROP COLUMN event, RENAME COLUMN event_str to event;\n</code></pre>"},{"location":"commands/","title":"Commands","text":""},{"location":"commands/#ralph","title":"ralph","text":"<p>The cli is a stream-based tool to play with your logs.</p> <p>It offers functionalities to: - Validate or convert learning data in different standards - Read and write learning data to various databases or servers - Manage an instance of a Ralph LRS server</p> <p>Usage:</p> <pre><code>ralph [OPTIONS] COMMAND [ARGS]...\n</code></pre> <p>Options:</p> <pre><code>  -v, --verbosity LVL  Either CRITICAL, ERROR, WARNING, INFO (default) or\n                       DEBUG\n  --version            Show the version and exit.\n  --help               Show this message and exit.\n</code></pre>"},{"location":"commands/#ralph-auth","title":"ralph auth","text":"<p>Generate credentials for LRS HTTP basic authentication.</p> <p>Usage:</p> <pre><code>ralph auth [OPTIONS]\n</code></pre> <p>Options:</p> <pre><code>  -u, --username TEXT             The user for which we generate credentials.\n                                  [required]\n  -p, --password TEXT             The password to encrypt for this user. Will\n                                  be prompted if missing.  [required]\n  -s, --scope TEXT                The user scope(s). This option can be\n                                  provided multiple times.  [required]\n  -M, --agent-ifi-mbox TEXT       The mbox Inverse Functional Identifier of\n                                  the associated agent.\n  -S, --agent-ifi-mbox-sha1sum TEXT\n                                  The mbox-sha1sum Inverse Functional\n                                  Identifier of the associated agent.\n  -O, --agent-ifi-openid TEXT     The openid Inverse Functional Identifier of\n                                  the associated agent.\n  -A, --agent-ifi-account TEXT...\n                                  Input \"{name} {homePage}\". The account\n                                  Inverse Functional Identifier of the\n                                  associated agent.\n  -N, --agent-name TEXT           The name of the associated agent.\n  -w, --write-to-disk             Write new credentials to the LRS\n                                  authentication file.\n  --help                          Show this message and exit.\n</code></pre>"},{"location":"commands/#ralph-convert","title":"ralph convert","text":"<p>Convert input events to a given format.</p> <p>Usage:</p> <pre><code>ralph convert [OPTIONS]\n</code></pre> <p>Options:</p> <pre><code>  From edX to xAPI converter options: \n    -u, --uuid-namespace TEXT     The UUID namespace to use for the `ID` field\n                                  generation\n    -p, --platform-url TEXT       The `actor.account.homePage` to use in the\n                                  xAPI statements  [required]\n  -f, --from [edx]                Input events format to convert  [required]\n  -t, --to [xapi]                 Output events format  [required]\n  -I, --ignore-errors             Continue writing regardless of raised errors\n  -F, --fail-on-unknown           Stop converting at first unknown event\n  --help                          Show this message and exit.\n</code></pre>"},{"location":"commands/#ralph-extract","title":"ralph extract","text":"<p>Extract input events from a container format using a dedicated parser.</p> <p>Usage:</p> <pre><code>ralph extract [OPTIONS]\n</code></pre> <p>Options:</p> <pre><code>  -p, --parser [gelf|es]  Container format parser used to extract events\n                          [required]\n  --help                  Show this message and exit.\n</code></pre>"},{"location":"commands/#ralph-validate","title":"ralph validate","text":"<p>Validate input events of given format.</p> <p>Usage:</p> <pre><code>ralph validate [OPTIONS]\n</code></pre> <p>Options:</p> <pre><code>  -f, --format [edx|xapi]  Input events format to validate  [required]\n  -I, --ignore-errors      Continue validating regardless of raised errors\n  -F, --fail-on-unknown    Stop validating at first unknown event\n  --help                   Show this message and exit.\n</code></pre>"},{"location":"contribute/","title":"Contributing to Ralph","text":"<p>Thank you for considering contributing to Ralph! We appreciate your interest and support. This documentation provides guidelines on how to contribute effectively to our project.</p>"},{"location":"contribute/#issues","title":"Issues","text":"<p>Issues are a valuable way to contribute to Ralph. They can include bug reports, feature requests, and general questions or discussions. When creating or interacting with issues, please keep the following in mind:</p>"},{"location":"contribute/#1_search_for_existing_issues","title":"1. Search for existing issues","text":"<p>Before creating a new issue, search the existing issues to see if your concern has already been raised.  If you find a related issue, you can add your input or follow the discussion. Feel free to engage in discussions, offer help, or provide feedback on existing issues. Your input is valuable in shaping the project\u2019s future.</p>"},{"location":"contribute/#2_creating_a_new_issue","title":"2. Creating a new issue","text":"<p>Use the provided issue template that fits the best to your concern. Provide as much information as possible when writing your issue. Your issue will be reviewed by a project maintainer and you may be offered to open a PR if you want to contribute to the code. If not, and if your issue is relevant, a contributor will apply the changes to the project.  The issue will then be automatically closed when the PR is merged.</p> <p>Issues will be closed by project maintainers if they are deemed invalid.  You can always reopen an issue if you believe it hasn\u2019t been adequately addressed.</p>"},{"location":"contribute/#3_code_of_conduct_in_discussion","title":"3. Code of conduct in discussion","text":"<ul> <li>Be respectful and considerate when participating in discussions.</li> <li>Avoid using offensive language, and maintain a positive and collaborative tone.</li> <li>Stay on topic and avoid derailing discussions.</li> </ul>"},{"location":"contribute/#discussions","title":"Discussions","text":"<p>Discussions in the Ralph repository are a place for open-ended conversations, questions, and general community interactions. Here\u2019s how to effectively use discussions:</p>"},{"location":"contribute/#1_creating_a_discussion","title":"1. Creating a discussion","text":"<ul> <li>Use a clear and concise title that summarizes the topic.</li> <li>In the description, provide context and details regarding the discussion.</li> <li>Use labels to categorize the discussion (e.g., \u201cquestion,\u201d \u201cgeneral discussion,\u201d \u201cannouncements,\u201d etc.).</li> </ul>"},{"location":"contribute/#2_participating_in_discussions","title":"2. Participating in discussions","text":"<ul> <li>Engage in conversations respectfully, respecting others\u2019 opinions.</li> <li>Avoid spamming or making off-topic comments.</li> <li>Help answer questions when you can.</li> </ul>"},{"location":"contribute/#pull_requests_pr","title":"Pull Requests (PR)","text":"<p>Contributing to Ralph through pull requests is a powerful way to advance the project.  If you want to make changes or add new features, please follow these steps to submit a PR:</p>"},{"location":"contribute/#1_fork_the_repository","title":"1. Fork the repository","text":"<p>Begin by forking Ralph project\u2019s repository. </p>"},{"location":"contribute/#2_clone_the_fork","title":"2. Clone the fork","text":"<p>Clone the forked repository to your local machine and change the directory to the project folder using the following commands (replace <code>&lt;your_fork&gt;</code> with your GitHub username):</p> <pre><code>git clone https://github.com/&lt;your_fork&gt;/ralph.git\ncd ralph\n</code></pre>"},{"location":"contribute/#3_create_a_new_branch","title":"3. Create a new branch","text":"<p>Create a new branch for your changes, ideally with a descriptive name:</p> <pre><code>git checkout -b your-new-feature\n</code></pre>"},{"location":"contribute/#4_make_changes","title":"4. Make changes","text":"<p>Implement the changes or additions to the code, ensuring it follows OpenFUN coding and documentation standards.</p> <p>For comprehensive guidance on starting your development journey with Ralph and preparing your pull request, please refer to our dedicated Start developing with Ralph tutorial.</p> <p>When committing your changes, please adhere to OpenFUN commit practices.  Follow the low granularity commit splitting approach and use commit messages based on the Angular commit message guidelines. </p>"},{"location":"contribute/#5_push_changes","title":"5. Push changes","text":"<p>Push your branch to your GitHub repository:</p> <pre><code>git push origin feature/your-new-feature\n</code></pre>"},{"location":"contribute/#6_create_a_pull_request","title":"6. Create a pull request","text":"<p>To initiate a Pull Request (PR), head to Ralph project\u2019s GitHub repository and click on New Pull Request.</p> <p>Set your branch as the source and Ralph project\u2019s <code>master</code> branch as the target.</p> <p>Provide a clear title for your PR and make use of the provided PR body template to document the changes made by your PR. This helps streamline the review process and maintain a well-documented project history.</p>"},{"location":"contribute/#7_review_and_discussion","title":"7. Review and discussion","text":"<p>Ralph project maintainers will review your PR.  Be prepared to make necessary changes or address any feedback.  Patience during this process is appreciated.</p>"},{"location":"contribute/#8_merge","title":"8. Merge","text":"<p>Once your PR is approved, Ralph maintainers will merge your changes into the main project.  Congratulations, you\u2019ve successfully contributed to Ralph! \ud83c\udf89</p>"},{"location":"api/","title":"LRS HTTP server","text":"<p>Ralph comes with an API server that aims to implement the Learning Record Store (LRS) specification (still a work in progress).</p>"},{"location":"api/#getting_started","title":"Getting started","text":"<p>The API server supports the following authentication methods:</p> <ul> <li>HTTP Basic Authentication (default method)</li> <li>OpenID Connect authentication on top of OAuth2.0</li> </ul>"},{"location":"api/#http_basic_authentication","title":"HTTP Basic Authentication","text":"<p>The default method for securing Ralph API server is with HTTP basic authentication.</p> <p>The API server can be started up with the following command:</p> <pre><code>ralph runserver --backend es\n</code></pre> <p>The <code>--backend</code> (or <code>-b</code>) option specifies which database backend to use for LRS data storage and retrieval.  See Ralph\u2019s backends documentation for more details.</p> <p>However, before you can start your API server and make requests against it, you need to set up your credentials.</p>"},{"location":"api/#creating_a_credentials_file","title":"Creating a credentials file","text":"<p>The credentials file is expected to be a valid JSON file. Its location is specified by the <code>RALPH_AUTH_FILE</code> configuration value. By default, <code>ralph</code> will look for the <code>auth.json</code> file in the application directory (see click documentation for details).</p> <p>The expected format is a list of entries (JSON objects) each containing the username, the user\u2019s <code>bcrypt</code> hashed+salted password, scopes they can access, and an <code>agent</code> object used to represent the user in the LRS. The  <code>agent</code> is constrained by LRS specifications, and must use one of four valid  Inverse Functional Identifiers.</p> <pre><code>[\n  {\n    \"username\": \"john.doe@example.com\",\n    \"hash\": \"$2b$12$yBXrzIuRIk6yaft5KUgVFOIPv0PskCCh9PXmF2t7pno.qUZ5LK0D2\",\n    \"scopes\": [\"example_scope\"],\n    \"agent\": {\n      \"mbox\": \"mailto:john.doe@example.com\"\n    }\n  },\n  {\n    \"username\": \"simon.says@example.com\",\n    \"hash\": \"$2b$12$yBXrzIuRIk6yaft5KUgVFOIPv0PskCCh9PXmF2t7pno.qUZ5LK0D2\",\n    \"scopes\": [\"second_scope\", \"third_scope\"],\n    \"agent\": {\n      \"account\": {\n        \"name\": \"simonsAccountName\",\n        \"homePage\": \"http://www.exampleHomePage.com\"\n      }\n    }\n  }\n]\n</code></pre> <p>To create a new user credentials, Ralph\u2019s CLI provides a dedicated command:</p> <pre><code>ralph auth \\\n    --username janedoe \\\n    --password supersecret \\\n    --scope janedoe_scope \\\n    --agent-ifi-mbox mailto:janedoe@example.com \\\n    # or --agent-ifi-mbox-sha1sum ebd31e95054c018b10727ccffd2ef2ec3a016ee9 \\\n    # or --agent-ifi-openid \"http://jane.openid.example.org/\" \\\n    # or --agent-ifi-account exampleAccountname http://www.exampleHomePage.com \\\n    -w\n</code></pre> <p>This command updates your credentials file with the new <code>janedoe</code> user.</p> <p>Note that running this command requires that you installed Ralph with the CLI optional dependencies, e.g. <code>pip install ralph-malph[cli]</code> (which we highly recommend).</p>"},{"location":"api/#making_a_get_request","title":"Making a GET request","text":"<p>The first request that can be answered by the ralph API server is a <code>whoami</code> request, which checks if the user is authenticated and returns their username and permission scopes.</p> <p>Use curl to get <code>http://localhost:8100/whoami</code>:</p> <pre><code>curl http://localhost:8100/whoami\n&lt; HTTP/1.1 401 Unauthorized\n&lt; {\"error\":\"Not authenticated\"}\n</code></pre> <p>Send your username and password to the API server through HTTP Basic Auth:</p> <pre><code>curl --user john.doe@example.com:PASSWORD http://localhost:8100/whoami\n&lt; HTTP/1.1 200 OK\n&lt; {\"scopes\":[\"example_scope\"], \"agent\": {\"mbox\": \"mailto:john.doe@example.com\"}}\n</code></pre>"},{"location":"api/#openid_connect_authentication","title":"OpenID Connect authentication","text":"<p>Ralph LRS API server supports OpenID Connect (OIDC) on top of OAuth 2.0 for authentication and authorization.</p> <p>To enable OIDC auth, you should modify the <code>RALPH_RUNSERVER_AUTH_BACKENDS</code> environment variable by adding (or replacing by) <code>oidc</code>: <pre><code>RALPH_RUNSERVER_AUTH_BACKENDS=basic,oidc\n</code></pre></p> <p>and you should define the <code>RALPH_RUNSERVER_AUTH_OIDC_ISSUER_URI</code> environment variable with your identity provider\u2019s Issuer Identifier URI as follows:</p> <pre><code>RALPH_RUNSERVER_AUTH_OIDC_ISSUER_URI=http://{provider_host}:{provider_port}/auth/realms/{realm_name}\n</code></pre> <p>This address must be accessible to the LRS on startup as it will perform OIDC Discovery to retrieve public keys and other information about the OIDC environment.</p> <p>It is also strongly recommended that you set the optional <code>RALPH_RUNSERVER_AUTH_OIDC_AUDIENCE</code> environment variable to the origin address of the LRS itself (ex. \u201chttp://localhost:8100\u201d) to enable verification that a given token was issued specifically for the LRS.</p>"},{"location":"api/#identity_providers","title":"Identity Providers","text":"<p>OIDC support is currently developed and tested against Keycloak but may work with other identity providers that implement the specification.</p> <p>The Learning analytics playground repository contains a Docker Compose file and configuration for a demo instance of Keycloak with a <code>ralph</code> client.</p>"},{"location":"api/#making_a_get_request_1","title":"Making a GET request","text":"<p>The first request that can be answered by the ralph API server is a <code>whoami</code> request, which checks if the user is authenticated and returns their username and permission scopes.</p> <p>Use curl to get <code>http://localhost:8100/whoami</code>:</p> <pre><code>curl http://localhost:8100/whoami\n&lt; HTTP/1.1 401 Unauthorized\n&lt; {\"detail\":\"Could not validate credentials\"}\n</code></pre> <p>With the Keycloak instance running, use curl to get access token from Keycloak:</p> <pre><code>curl --request POST 'http://localhost:8080/auth/realms/fun-mooc/protocol/openid-connect/token' \\\n--header 'Content-Type: application/x-www-form-urlencoded' \\\n--data-urlencode 'client_id=ralph' \\\n--data-urlencode 'client_secret=super-secret' \\\n--data-urlencode 'username=ralph_admin' \\\n--data-urlencode 'password=funfunfun' \\\n--data-urlencode 'grant_type=password'\n</code></pre> <p>which outputs (tokens truncated for example purpose):</p> <pre><code>{ \n  \"access_token\":\"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJSTWlLM\",\n  \"expires_in\":300,\n  \"refresh_expires_in\":1800,\n  \"refresh_token\":\"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI4MDc5NjExM\",\n  \"token_type\":\"Bearer\",\n  \"not-before-policy\":0,\n  \"session_state\":\"22a36735-e35f-496b-a243-152d32ebff45\",\n  \"scope\":\"profile email\"\n}\n</code></pre> <p>Send the access token to the API server as a Bearer header:</p> <pre><code>curl http://localhost:8100/whoami --header \"Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJSTWlLM\"\n&lt; HTTP/1.1 200 OK\n&lt; {\"username\":\"ralph_admin\",\"scopes\":[\"all\"]}\n</code></pre>"},{"location":"api/#security","title":"Security","text":"<p>By default, all authenticated users have full read and write access to the server. You may use the options below to restrict behavior.</p>"},{"location":"api/#filtering_results_by_authority_multitenancy","title":"Filtering results by authority (multitenancy)","text":"<p>In Ralph LRS, all incoming statements are assigned an <code>authority</code> (or ownership) derived from the user that makes the call. You may restrict read access to users \u201cown\u201d statements (thus enabling multitenancy) by setting the following environment variable: </p> <pre><code>RALPH_LRS_RESTRICT_BY_AUTHORITY = True # Default: False\n</code></pre> <p>WARNING: Two accounts with different credentials may share the same <code>authority</code> meaning they can access the same statements. It is the administrators responsability to ensure that <code>authority</code> is properly assigned.</p> <p>NB: If not using \u201cscopes\u201d, or for users with limited \u201cscopes\u201d, using this option will make the use of option <code>?mine=True</code> implicit when fetching statement.</p>"},{"location":"api/#scopes","title":"Scopes","text":"<p>In Ralph, users are assigned scopes which may be used to restrict endpoint access or  functionalities. You may enable this option by setting the following environment variable:</p> <pre><code>RALPH_LRS_RESTRICT_BY_SCOPES = True # Default: False\n</code></pre> <p>Valid scopes are a slight variation on those proposed by the xAPI specification:</p> <ul> <li>statements/write</li> <li>statements/read/mine</li> <li>statements/read</li> <li>state/write</li> <li>state/read</li> <li>define</li> <li>profile/write</li> <li>profile/read</li> <li>all/read</li> <li>all</li> </ul>"},{"location":"api/#forwarding_statements","title":"Forwarding statements","text":"<p>Ralph\u2019s API server can be configured to forward xAPI statements it receives to other LRSes.</p> <p>To configure statement forwarding, you need to create a <code>.env</code> file in the current directory and define the <code>RALPH_XAPI_FORWARDINGS</code> variable or define the <code>RALPH_XAPI_FORWARDINGS</code> environment variable.</p> <p>The value of the <code>RALPH_XAPI_FORWARDINGS</code> variable should be a JSON encoded list of dictionaries where each dictionary defines a forwarding configuration and consists of the following key/value pairs:</p> key value type description <code>is_active</code> <code>boolean</code> Specifies whether or not this forwarding configuration should take effect. <code>url</code> <code>URL</code> Specifies the endpoint URL where forwarded statements should be send. <code>basic_username</code> <code>string</code> Specifies the basic auth username. <code>basic_password</code> <code>string</code> Specifies the basic auth password. <code>max_retries</code> <code>number</code> Specifies the number of times a failed forwarding request should be retried. <code>timeout</code> <code>number</code> Specifies the duration in seconds of network inactivity leading to a timeout. <p>Note that for a forwarding configuration to be valid it is required that all key/value pairs are defined.</p> <p>Example of a valid forwarding configuration:</p> <pre><code>RALPH_XAPI_FORWARDINGS='\n[\n  {\n    \"is_active\": true,\n    \"url\": \"http://lrs1.example.com/xAPI/statements/\",\n    \"basic_username\": \"admin1@example.com\",\n    \"basic_password\": \"PASSWORD1\",\n    \"max_retries\": 1,\n    \"timeout\": 5\n  },\n  {\n    \"is_active\": true,\n    \"url\": \"http://lrs2.example.com/xAPI/statements/\",\n    \"basic_username\": \"admin2@example.com\",\n    \"basic_password\": \"PASSWORD2\",\n    \"max_retries\": 5,\n    \"timeout\": 0.2\n  }\n]\n'\n</code></pre>"},{"location":"api/#sentry_configuration","title":"Sentry configuration","text":"<p>Ralph provides Sentry integration to monitor its LRS server and its CLI. To activate Sentry integration, one should define the following environment variables:</p> <pre><code>RALPH_SENTRY_DSN={PROTOCOL}://{PUBLIC_KEY}:{SECRET_KEY}@{HOST}{PATH}/{PROJECT_ID}\nRALPH_EXECUTION_ENVIRONMENT=development\n</code></pre> <p>The Sentry DSN (Data Source Name) can be found in your project settings from Sentry application. The execution environment should reflect the environment Ralph has been deployed in (e.g. <code>production</code>).</p> <p>You may also want to monitor the performance of Ralph by configuring the CLI and LRS traces sample rates: <pre><code>RALPH_SENTRY_CLI_TRACES_SAMPLE_RATE=0.1\nRALPH_SENTRY_LRS_TRACES_SAMPLE_RATE=0.3\n</code></pre></p> <p>Note that a sampling rate of <code>1.0</code> means 100% of transactions are sent to sentry and <code>0.1</code> only 10%.</p> <p>If you want to lower noisy transactions (e.g. in a Kubernetes cluster), you can disable health checks related ones:</p> <pre><code>RALPH_SENTRY_IGNORE_HEALTH_CHECKS=True\n</code></pre>"},{"location":"api/#additional_configuration","title":"Additional configuration","text":""},{"location":"api/#http_basic_auth_caching","title":"HTTP Basic auth caching","text":"<p>HTTP Basic auth implementation uses the secure and standard bcrypt algorithm to hash/salt passwords before storing them. This implementation comes with a performance cost. To speed up requests, credentials are stored in an LRU cache with a <code>Time To Live</code>. To configure this cache, you can define the following environment variables:</p> <ul> <li>the maximum number of entries in the cache. Select a value greater than the maximum number of individual user credentials, for better performance. Defaults to 100. </li> </ul> <p><pre><code>RALPH_AUTH_CACHE_MAX_SIZE=100\n</code></pre> - the <code>Time To Live</code> of the cache entries in seconds. Defaults to 3600s.</p> <pre><code>RALPH_AUTH_CACHE_TTL=3600\n</code></pre>"},{"location":"api/#api_documentation","title":"API documentation","text":""},{"location":"api/#fastapi_010","title":"FastAPI 0.1.0","text":""},{"location":"api/#endpoints","title":"Endpoints","text":""},{"location":"api/#get_xapistatements","title":"GET /xAPI/statements/","text":"<p>Get</p> Description <p>Read a single xAPI Statement or multiple xAPI Statements.</p> <p>LRS Specification: https://github.com/adlnet/xAPI-Spec/blob/1.0.3/xAPI- Communication.md#213-get-statements</p> <p>Input parameters</p> Parameter In Type Default Nullable Description <code>HTTPBasic</code> header string N/A No Basic authentication <code>HTTPBasic</code> header string N/A No Basic authentication <code>activity</code> query string No Filter, only return Statements for which the Object of the Statement is an Activity with the specified id <code>agent</code> query string No Filter, only return Statements for which the specified Agent or Group is the Actor or Object of the Statement <code>ascending</code> query boolean False No If \"true\", return results in ascending order of stored time <code>attachments</code> query boolean False No **Not implemented** If \"true\", the LRS uses the multipart response format and includes all attachments as described previously. If \"false\", the LRS sends the prescribed response with Content-Type application/json and does not send attachment data. <code>format</code> query string exact No **Not implemented** If \"ids\", only include minimum information necessary in Agent, Activity, Verb and Group Objects to identify them. For Anonymous Groups this means including the minimum information needed to identify each member. If \"exact\", return Agent, Activity, Verb and Group Objects populated exactly as they were when the Statement was received. An LRS requesting Statements for the purpose of importing them would use a format of \"exact\" in order to maintain Statement Immutability. If \"canonical\", return Activity Objects and Verbs populated with the canonical definition of the Activity Objects and Display of the Verbs as determined by the LRS, after applying the language filtering process defined below, and return the original Agent and Group Objects as in \"exact\" mode. <code>limit</code> query integer 100 No Maximum number of Statements to return. 0 indicates return the maximum the server will allow <code>mine</code> query boolean False No If \"true\", return only the results for which the authority matches the \"agent\" associated to the user that is making the query. <code>pit_id</code> query string No Point-in-time ID to ensure consistency of search requests through multiple pages.NB: for internal use, not part of the LRS specification. <code>registration</code> query string No **Not implemented** Filter, only return Statements matching the specified registration id <code>related_activities</code> query boolean False No **Not implemented** Apply the Activity filter broadly. Include Statements for which the Object, any of the context Activities, or any of those properties in a contained SubStatement match the Activity parameter, instead of that parameter's normal behaviour <code>related_agents</code> query boolean False No **Not implemented** Apply the Agent filter broadly. Include Statements for which the Actor, Object, Authority, Instructor, Team, or any of these properties in a contained SubStatement match the Agent parameter, instead of that parameter's normal behaviour. <code>search_after</code> query string No Sorting data to allow pagination through large number of search results. NB: for internal use, not part of the LRS specification. <code>since</code> query string No Only Statements stored since the specified Timestamp (exclusive) are returned <code>statementId</code> query string No Id of Statement to fetch <code>until</code> query string No Only Statements stored at or before the specified Timestamp are returned <code>verb</code> query string No Filter, only return Statements matching the specified Verb id <code>voidedStatementId</code> query string No **Not implemented** Id of voided Statement to fetch <p> Response 200 OK </p> application/json Schema of the response body <pre><code>{\n    \"type\": \"object\",\n    \"title\": \"Response Get Xapi Statements  Get\"\n}\n</code></pre> <p> Response 422 Unprocessable Entity </p> application/json <p><pre><code>{\n    \"detail\": [\n        {\n            \"loc\": [\n                null\n            ],\n            \"msg\": \"string\",\n            \"type\": \"string\"\n        }\n    ]\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"properties\": {\n        \"detail\": {\n            \"items\": {\n                \"$ref\": \"#/components/schemas/ValidationError\"\n            },\n            \"type\": \"array\",\n            \"title\": \"Detail\"\n        }\n    },\n    \"type\": \"object\",\n    \"title\": \"HTTPValidationError\"\n}\n</code></pre>"},{"location":"api/#put_xapistatements","title":"PUT /xAPI/statements/","text":"<p>Put</p> Description <p>Store a single statement as a single member of a set.</p> <p>LRS Specification: https://github.com/adlnet/xAPI-Spec/blob/1.0.3/xAPI- Communication.md#211-put-statements</p> <p>Input parameters</p> Parameter In Type Default Nullable Description <code>HTTPBasic</code> header string N/A No Basic authentication <code>HTTPBasic</code> header string N/A No Basic authentication <code>statementId</code> query string No <p>Request body</p> application/json <p><pre><code>{\n    \"actor\": null,\n    \"id\": \"292e8ffe-4ed4-460b-b307-16a7a5c14213\",\n    \"object\": {\n        \"id\": \"string\"\n    },\n    \"verb\": {\n        \"id\": \"string\"\n    }\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the request body <pre><code>{\n    \"properties\": {\n        \"actor\": {\n            \"anyOf\": [\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiAgentWithMbox\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiAgentWithMboxSha1Sum\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiAgentWithOpenId\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiAgentWithAccount\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiAnonymousGroup\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiIdentifiedGroupWithMbox\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiIdentifiedGroupWithMboxSha1Sum\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiIdentifiedGroupWithOpenId\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiIdentifiedGroupWithAccount\"\n                }\n            ],\n            \"title\": \"Actor\"\n        },\n        \"id\": {\n            \"type\": \"string\",\n            \"format\": \"uuid\",\n            \"title\": \"Id\"\n        },\n        \"object\": {\n            \"$ref\": \"#/components/schemas/LaxObjectField\"\n        },\n        \"verb\": {\n            \"$ref\": \"#/components/schemas/LaxVerbField\"\n        }\n    },\n    \"type\": \"object\",\n    \"required\": [\n        \"actor\",\n        \"object\",\n        \"verb\"\n    ],\n    \"title\": \"LaxStatement\",\n    \"description\": \"Pydantic model for lax statement.\\n\\nIt accepts without validating all fields beyond the bare minimum required to\\nqualify an object as an XAPI statement.\"\n}\n</code></pre> <p> Response 204 No Content </p> <p> Response 400 Bad Request </p> application/json <p><pre><code>{\n    \"detail\": \"string\"\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"properties\": {\n        \"detail\": {\n            \"type\": \"string\",\n            \"title\": \"Detail\"\n        }\n    },\n    \"type\": \"object\",\n    \"required\": [\n        \"detail\"\n    ],\n    \"title\": \"ErrorDetail\",\n    \"description\": \"Pydantic model for errors raised detail.\\n\\nType for return value for errors raised in API endpoints.\\nUseful for OpenAPI documentation generation.\"\n}\n</code></pre> <p> Response 409 Conflict </p> application/json <p><pre><code>{\n    \"detail\": \"string\"\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"properties\": {\n        \"detail\": {\n            \"type\": \"string\",\n            \"title\": \"Detail\"\n        }\n    },\n    \"type\": \"object\",\n    \"required\": [\n        \"detail\"\n    ],\n    \"title\": \"ErrorDetail\",\n    \"description\": \"Pydantic model for errors raised detail.\\n\\nType for return value for errors raised in API endpoints.\\nUseful for OpenAPI documentation generation.\"\n}\n</code></pre> <p> Response 422 Unprocessable Entity </p> application/json <p><pre><code>{\n    \"detail\": [\n        {\n            \"loc\": [\n                null\n            ],\n            \"msg\": \"string\",\n            \"type\": \"string\"\n        }\n    ]\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"properties\": {\n        \"detail\": {\n            \"items\": {\n                \"$ref\": \"#/components/schemas/ValidationError\"\n            },\n            \"type\": \"array\",\n            \"title\": \"Detail\"\n        }\n    },\n    \"type\": \"object\",\n    \"title\": \"HTTPValidationError\"\n}\n</code></pre>"},{"location":"api/#post_xapistatements","title":"POST /xAPI/statements/","text":"<p>Post</p> Description <p>Store a set of statements (or a single statement as a single member of a set).</p> <p>NB: at this time, using POST to make a GET request, is not supported. LRS Specification: https://github.com/adlnet/xAPI-Spec/blob/1.0.3/xAPI- Communication.md#212-post-statements</p> <p>Input parameters</p> Parameter In Type Default Nullable Description <code>HTTPBasic</code> header string N/A No Basic authentication <code>HTTPBasic</code> header string N/A No Basic authentication <p>Request body</p> application/json Schema of the request body <pre><code>{\n    \"anyOf\": [\n        {\n            \"$ref\": \"#/components/schemas/LaxStatement\"\n        },\n        {\n            \"items\": {\n                \"$ref\": \"#/components/schemas/LaxStatement\"\n            },\n            \"type\": \"array\"\n        }\n    ],\n    \"title\": \"Statements\"\n}\n</code></pre> <p> Response 200 OK </p> application/json <p><pre><code>[\n    null\n]\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"items\": {},\n    \"type\": \"array\",\n    \"title\": \"Response Post Xapi Statements  Post\"\n}\n</code></pre> <p> Response 400 Bad Request </p> application/json <p><pre><code>{\n    \"detail\": \"string\"\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"properties\": {\n        \"detail\": {\n            \"type\": \"string\",\n            \"title\": \"Detail\"\n        }\n    },\n    \"type\": \"object\",\n    \"required\": [\n        \"detail\"\n    ],\n    \"title\": \"ErrorDetail\",\n    \"description\": \"Pydantic model for errors raised detail.\\n\\nType for return value for errors raised in API endpoints.\\nUseful for OpenAPI documentation generation.\"\n}\n</code></pre> <p> Response 409 Conflict </p> application/json <p><pre><code>{\n    \"detail\": \"string\"\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"properties\": {\n        \"detail\": {\n            \"type\": \"string\",\n            \"title\": \"Detail\"\n        }\n    },\n    \"type\": \"object\",\n    \"required\": [\n        \"detail\"\n    ],\n    \"title\": \"ErrorDetail\",\n    \"description\": \"Pydantic model for errors raised detail.\\n\\nType for return value for errors raised in API endpoints.\\nUseful for OpenAPI documentation generation.\"\n}\n</code></pre> <p> Response 422 Unprocessable Entity </p> application/json <p><pre><code>{\n    \"detail\": [\n        {\n            \"loc\": [\n                null\n            ],\n            \"msg\": \"string\",\n            \"type\": \"string\"\n        }\n    ]\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"properties\": {\n        \"detail\": {\n            \"items\": {\n                \"$ref\": \"#/components/schemas/ValidationError\"\n            },\n            \"type\": \"array\",\n            \"title\": \"Detail\"\n        }\n    },\n    \"type\": \"object\",\n    \"title\": \"HTTPValidationError\"\n}\n</code></pre>"},{"location":"api/#get_xapistatements_1","title":"GET /xAPI/statements","text":"<p>Get</p> Description <p>Read a single xAPI Statement or multiple xAPI Statements.</p> <p>LRS Specification: https://github.com/adlnet/xAPI-Spec/blob/1.0.3/xAPI- Communication.md#213-get-statements</p> <p>Input parameters</p> Parameter In Type Default Nullable Description <code>HTTPBasic</code> header string N/A No Basic authentication <code>HTTPBasic</code> header string N/A No Basic authentication <code>activity</code> query string No Filter, only return Statements for which the Object of the Statement is an Activity with the specified id <code>agent</code> query string No Filter, only return Statements for which the specified Agent or Group is the Actor or Object of the Statement <code>ascending</code> query boolean False No If \"true\", return results in ascending order of stored time <code>attachments</code> query boolean False No **Not implemented** If \"true\", the LRS uses the multipart response format and includes all attachments as described previously. If \"false\", the LRS sends the prescribed response with Content-Type application/json and does not send attachment data. <code>format</code> query string exact No **Not implemented** If \"ids\", only include minimum information necessary in Agent, Activity, Verb and Group Objects to identify them. For Anonymous Groups this means including the minimum information needed to identify each member. If \"exact\", return Agent, Activity, Verb and Group Objects populated exactly as they were when the Statement was received. An LRS requesting Statements for the purpose of importing them would use a format of \"exact\" in order to maintain Statement Immutability. If \"canonical\", return Activity Objects and Verbs populated with the canonical definition of the Activity Objects and Display of the Verbs as determined by the LRS, after applying the language filtering process defined below, and return the original Agent and Group Objects as in \"exact\" mode. <code>limit</code> query integer 100 No Maximum number of Statements to return. 0 indicates return the maximum the server will allow <code>mine</code> query boolean False No If \"true\", return only the results for which the authority matches the \"agent\" associated to the user that is making the query. <code>pit_id</code> query string No Point-in-time ID to ensure consistency of search requests through multiple pages.NB: for internal use, not part of the LRS specification. <code>registration</code> query string No **Not implemented** Filter, only return Statements matching the specified registration id <code>related_activities</code> query boolean False No **Not implemented** Apply the Activity filter broadly. Include Statements for which the Object, any of the context Activities, or any of those properties in a contained SubStatement match the Activity parameter, instead of that parameter's normal behaviour <code>related_agents</code> query boolean False No **Not implemented** Apply the Agent filter broadly. Include Statements for which the Actor, Object, Authority, Instructor, Team, or any of these properties in a contained SubStatement match the Agent parameter, instead of that parameter's normal behaviour. <code>search_after</code> query string No Sorting data to allow pagination through large number of search results. NB: for internal use, not part of the LRS specification. <code>since</code> query string No Only Statements stored since the specified Timestamp (exclusive) are returned <code>statementId</code> query string No Id of Statement to fetch <code>until</code> query string No Only Statements stored at or before the specified Timestamp are returned <code>verb</code> query string No Filter, only return Statements matching the specified Verb id <code>voidedStatementId</code> query string No **Not implemented** Id of voided Statement to fetch <p> Response 200 OK </p> application/json Schema of the response body <pre><code>{\n    \"type\": \"object\",\n    \"title\": \"Response Get Xapi Statements Get\"\n}\n</code></pre> <p> Response 422 Unprocessable Entity </p> application/json <p><pre><code>{\n    \"detail\": [\n        {\n            \"loc\": [\n                null\n            ],\n            \"msg\": \"string\",\n            \"type\": \"string\"\n        }\n    ]\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"properties\": {\n        \"detail\": {\n            \"items\": {\n                \"$ref\": \"#/components/schemas/ValidationError\"\n            },\n            \"type\": \"array\",\n            \"title\": \"Detail\"\n        }\n    },\n    \"type\": \"object\",\n    \"title\": \"HTTPValidationError\"\n}\n</code></pre>"},{"location":"api/#put_xapistatements_1","title":"PUT /xAPI/statements","text":"<p>Put</p> Description <p>Store a single statement as a single member of a set.</p> <p>LRS Specification: https://github.com/adlnet/xAPI-Spec/blob/1.0.3/xAPI- Communication.md#211-put-statements</p> <p>Input parameters</p> Parameter In Type Default Nullable Description <code>HTTPBasic</code> header string N/A No Basic authentication <code>HTTPBasic</code> header string N/A No Basic authentication <code>statementId</code> query string No <p>Request body</p> application/json <p><pre><code>{\n    \"actor\": null,\n    \"id\": \"6b700e1f-3e01-4218-85c1-7d3be1b1f319\",\n    \"object\": {\n        \"id\": \"string\"\n    },\n    \"verb\": {\n        \"id\": \"string\"\n    }\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the request body <pre><code>{\n    \"properties\": {\n        \"actor\": {\n            \"anyOf\": [\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiAgentWithMbox\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiAgentWithMboxSha1Sum\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiAgentWithOpenId\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiAgentWithAccount\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiAnonymousGroup\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiIdentifiedGroupWithMbox\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiIdentifiedGroupWithMboxSha1Sum\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiIdentifiedGroupWithOpenId\"\n                },\n                {\n                    \"$ref\": \"#/components/schemas/BaseXapiIdentifiedGroupWithAccount\"\n                }\n            ],\n            \"title\": \"Actor\"\n        },\n        \"id\": {\n            \"type\": \"string\",\n            \"format\": \"uuid\",\n            \"title\": \"Id\"\n        },\n        \"object\": {\n            \"$ref\": \"#/components/schemas/LaxObjectField\"\n        },\n        \"verb\": {\n            \"$ref\": \"#/components/schemas/LaxVerbField\"\n        }\n    },\n    \"type\": \"object\",\n    \"required\": [\n        \"actor\",\n        \"object\",\n        \"verb\"\n    ],\n    \"title\": \"LaxStatement\",\n    \"description\": \"Pydantic model for lax statement.\\n\\nIt accepts without validating all fields beyond the bare minimum required to\\nqualify an object as an XAPI statement.\"\n}\n</code></pre> <p> Response 204 No Content </p> <p> Response 400 Bad Request </p> application/json <p><pre><code>{\n    \"detail\": \"string\"\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"properties\": {\n        \"detail\": {\n            \"type\": \"string\",\n            \"title\": \"Detail\"\n        }\n    },\n    \"type\": \"object\",\n    \"required\": [\n        \"detail\"\n    ],\n    \"title\": \"ErrorDetail\",\n    \"description\": \"Pydantic model for errors raised detail.\\n\\nType for return value for errors raised in API endpoints.\\nUseful for OpenAPI documentation generation.\"\n}\n</code></pre> <p> Response 409 Conflict </p> application/json <p><pre><code>{\n    \"detail\": \"string\"\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"properties\": {\n        \"detail\": {\n            \"type\": \"string\",\n            \"title\": \"Detail\"\n        }\n    },\n    \"type\": \"object\",\n    \"required\": [\n        \"detail\"\n    ],\n    \"title\": \"ErrorDetail\",\n    \"description\": \"Pydantic model for errors raised detail.\\n\\nType for return value for errors raised in API endpoints.\\nUseful for OpenAPI documentation generation.\"\n}\n</code></pre> <p> Response 422 Unprocessable Entity </p> application/json <p><pre><code>{\n    \"detail\": [\n        {\n            \"loc\": [\n                null\n            ],\n            \"msg\": \"string\",\n            \"type\": \"string\"\n        }\n    ]\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"properties\": {\n        \"detail\": {\n            \"items\": {\n                \"$ref\": \"#/components/schemas/ValidationError\"\n            },\n            \"type\": \"array\",\n            \"title\": \"Detail\"\n        }\n    },\n    \"type\": \"object\",\n    \"title\": \"HTTPValidationError\"\n}\n</code></pre>"},{"location":"api/#post_xapistatements_1","title":"POST /xAPI/statements","text":"<p>Post</p> Description <p>Store a set of statements (or a single statement as a single member of a set).</p> <p>NB: at this time, using POST to make a GET request, is not supported. LRS Specification: https://github.com/adlnet/xAPI-Spec/blob/1.0.3/xAPI- Communication.md#212-post-statements</p> <p>Input parameters</p> Parameter In Type Default Nullable Description <code>HTTPBasic</code> header string N/A No Basic authentication <code>HTTPBasic</code> header string N/A No Basic authentication <p>Request body</p> application/json Schema of the request body <pre><code>{\n    \"anyOf\": [\n        {\n            \"$ref\": \"#/components/schemas/LaxStatement\"\n        },\n        {\n            \"items\": {\n                \"$ref\": \"#/components/schemas/LaxStatement\"\n            },\n            \"type\": \"array\"\n        }\n    ],\n    \"title\": \"Statements\"\n}\n</code></pre> <p> Response 200 OK </p> application/json <p><pre><code>[\n    null\n]\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"items\": {},\n    \"type\": \"array\",\n    \"title\": \"Response Post Xapi Statements Post\"\n}\n</code></pre> <p> Response 400 Bad Request </p> application/json <p><pre><code>{\n    \"detail\": \"string\"\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"properties\": {\n        \"detail\": {\n            \"type\": \"string\",\n            \"title\": \"Detail\"\n        }\n    },\n    \"type\": \"object\",\n    \"required\": [\n        \"detail\"\n    ],\n    \"title\": \"ErrorDetail\",\n    \"description\": \"Pydantic model for errors raised detail.\\n\\nType for return value for errors raised in API endpoints.\\nUseful for OpenAPI documentation generation.\"\n}\n</code></pre> <p> Response 409 Conflict </p> application/json <p><pre><code>{\n    \"detail\": \"string\"\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"properties\": {\n        \"detail\": {\n            \"type\": \"string\",\n            \"title\": \"Detail\"\n        }\n    },\n    \"type\": \"object\",\n    \"required\": [\n        \"detail\"\n    ],\n    \"title\": \"ErrorDetail\",\n    \"description\": \"Pydantic model for errors raised detail.\\n\\nType for return value for errors raised in API endpoints.\\nUseful for OpenAPI documentation generation.\"\n}\n</code></pre> <p> Response 422 Unprocessable Entity </p> application/json <p><pre><code>{\n    \"detail\": [\n        {\n            \"loc\": [\n                null\n            ],\n            \"msg\": \"string\",\n            \"type\": \"string\"\n        }\n    ]\n}\n</code></pre> \u26a0\ufe0f This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</p> Schema of the response body <pre><code>{\n    \"properties\": {\n        \"detail\": {\n            \"items\": {\n                \"$ref\": \"#/components/schemas/ValidationError\"\n            },\n            \"type\": \"array\",\n            \"title\": \"Detail\"\n        }\n    },\n    \"type\": \"object\",\n    \"title\": \"HTTPValidationError\"\n}\n</code></pre>"},{"location":"api/#get_lbheartbeat","title":"GET /lbheartbeat","text":"<p>Lbheartbeat</p> Description <p>Load balancer heartbeat.</p> <p>Return a 200 when the server is running.</p> <p> Response 200 OK </p> application/json Schema of the response body"},{"location":"api/#get_heartbeat","title":"GET /heartbeat","text":"<p>Heartbeat</p> Description <p>Application heartbeat.</p> <p>Return a 200 if all checks are successful.</p> <p> Response 200 OK </p> application/json Schema of the response body"},{"location":"api/#get_whoami","title":"GET /whoami","text":"<p>Whoami</p> Description <p>Return the current user\u2019s username along with their scopes.</p> <p>Input parameters</p> Parameter In Type Default Nullable Description <code>HTTPBasic</code> header string N/A No Basic authentication <p> Response 200 OK </p> application/json Schema of the response body <pre><code>{\n    \"type\": \"object\",\n    \"title\": \"Response Whoami Whoami Get\"\n}\n</code></pre>"},{"location":"api/#schemas","title":"Schemas","text":""},{"location":"api/#basexapiaccount","title":"BaseXapiAccount","text":"Name Type <code>homePage</code> string <code>name</code> string"},{"location":"api/#basexapiagentwithaccount","title":"BaseXapiAgentWithAccount","text":"Name Type <code>account</code> BaseXapiAccount <code>name</code> string <code>objectType</code> string"},{"location":"api/#basexapiagentwithmbox","title":"BaseXapiAgentWithMbox","text":"Name Type <code>mbox</code> string <code>name</code> string <code>objectType</code> string"},{"location":"api/#basexapiagentwithmboxsha1sum","title":"BaseXapiAgentWithMboxSha1Sum","text":"Name Type <code>mbox_sha1sum</code> string <code>name</code> string <code>objectType</code> string"},{"location":"api/#basexapiagentwithopenid","title":"BaseXapiAgentWithOpenId","text":"Name Type <code>name</code> string <code>objectType</code> string <code>openid</code> string(uri)"},{"location":"api/#basexapianonymousgroup","title":"BaseXapiAnonymousGroup","text":"Name Type <code>member</code> Array&lt;&gt; <code>name</code> string <code>objectType</code> string"},{"location":"api/#basexapiidentifiedgroupwithaccount","title":"BaseXapiIdentifiedGroupWithAccount","text":"Name Type <code>account</code> BaseXapiAccount <code>member</code> Array&lt;&gt; <code>name</code> string <code>objectType</code> string"},{"location":"api/#basexapiidentifiedgroupwithmbox","title":"BaseXapiIdentifiedGroupWithMbox","text":"Name Type <code>mbox</code> string <code>member</code> Array&lt;&gt; <code>name</code> string <code>objectType</code> string"},{"location":"api/#basexapiidentifiedgroupwithmboxsha1sum","title":"BaseXapiIdentifiedGroupWithMboxSha1Sum","text":"Name Type <code>mbox_sha1sum</code> string <code>member</code> Array&lt;&gt; <code>name</code> string <code>objectType</code> string"},{"location":"api/#basexapiidentifiedgroupwithopenid","title":"BaseXapiIdentifiedGroupWithOpenId","text":"Name Type <code>member</code> Array&lt;&gt; <code>name</code> string <code>objectType</code> string <code>openid</code> string(uri)"},{"location":"api/#errordetail","title":"ErrorDetail","text":"Name Type <code>detail</code> string"},{"location":"api/#httpvalidationerror","title":"HTTPValidationError","text":"Name Type <code>detail</code> Array&lt;ValidationError&gt;"},{"location":"api/#laxobjectfield","title":"LaxObjectField","text":"Name Type <code>id</code> string(uri)"},{"location":"api/#laxstatement","title":"LaxStatement","text":"Name Type <code>actor</code> <code>id</code> string(uuid) <code>object</code> LaxObjectField <code>verb</code> LaxVerbField"},{"location":"api/#laxverbfield","title":"LaxVerbField","text":"Name Type <code>id</code> string(uri)"},{"location":"api/#validationerror","title":"ValidationError","text":"Name Type <code>loc</code> Array&lt;&gt; <code>msg</code> string <code>type</code> string"},{"location":"api/#security_schemes","title":"Security schemes","text":"Name Type Scheme Description HTTPBasic http basic"},{"location":"backends/","title":"Backends for data storage","text":"<p>Ralph supports various backends that can be accessed to read from or write to (learning events or random data). Implemented backends are listed below along with their configuration parameters.  If your favourite data storage method is missing, feel free to submit your implementation or get in touch!</p>"},{"location":"backends/#key_concepts","title":"Key concepts","text":"<p>Each backend has its own parameter requirements. These parameters can be set as command line options or environment variables; the later is the recommended solution for sensitive data such as service credentials. For example, the <code>os_username</code> (OpenStack user name) parameter of the OpenStack Swift backend, can be set as a command line option using <code>swift</code> as the option prefix (and replacing underscores in its name by dashes):</p> <pre><code>ralph list --backend swift --swift-os-username johndoe # [...] more options\n</code></pre> <p>Alternatively, this parameter can be set as an environment variable (in upper case, prefixed by the program name, e.g. <code>RALPH_</code>):</p> <pre><code>export RALPH_BACKENDS__DATA__SWIFT__OS_USERNAME=\"johndoe\"\nralph list --backend swift # [...] more options\n</code></pre> <p>The general patterns for backend parameters are:</p> <ul> <li><code>--{{ backend_name }}-{{ parameter | underscore_to_dash }}</code> for command options, and,</li> <li><code>RALPH_BACKENDS__{{ backend_type | uppercase }}__{{ backend_name | uppercase }}__{{ parameter | uppercase }}</code> for environment variables, where the <code>backend_type</code> is one of <code>DATA</code>, <code>LRS</code> and <code>STREAM</code>.</li> </ul>"},{"location":"backends/#elasticsearch","title":"Elasticsearch","text":"<p>Elasticsearch backend is mostly used for indexation purpose (as a datalake) but it can also be used to fetch indexed data from it.</p> <p>Elasticsearch data backend default configuration.</p> <p>Attributes:</p> Name Type Description <code>ALLOW_YELLOW_STATUS</code> <code>bool</code> <p>Whether to consider Elasticsearch yellow health status to be ok.</p> <code>CLIENT_OPTIONS</code> <code>dict</code> <p>A dictionary of valid options for the Elasticsearch class initialization.</p> <code>DEFAULT_CHUNK_SIZE</code> <code>int</code> <p>The default chunk size for reading batches of documents.</p> <code>DEFAULT_INDEX</code> <code>str</code> <p>The default index to use for querying Elasticsearch.</p> <code>HOSTS</code> <code>str or tuple</code> <p>The comma-separated list of Elasticsearch nodes to connect to.</p> <code>LOCALE_ENCODING</code> <code>str</code> <p>The encoding used for reading/writing documents.</p> <code>POINT_IN_TIME_KEEP_ALIVE</code> <code>str</code> <p>The duration for which Elasticsearch should keep a point in time alive.</p> <code>REFRESH_AFTER_WRITE</code> <code>str or bool</code> <p>Whether the Elasticsearch index should be refreshed after the write operation.</p>"},{"location":"backends/#mongodb","title":"MongoDB","text":"<p>MongoDB backend is mostly used for indexation purpose (as a datalake) but it can also be used to fetch collections of documents from it.</p> <p>MongoDB data backend default configuration.</p> <p>Attributes:</p> Name Type Description <code>CONNECTION_URI</code> <code>str</code> <p>The MongoDB connection URI.</p> <code>DEFAULT_DATABASE</code> <code>str</code> <p>The MongoDB database to connect to.</p> <code>DEFAULT_COLLECTION</code> <code>str</code> <p>The MongoDB database collection to get objects from.</p> <code>CLIENT_OPTIONS</code> <code>MongoClientOptions</code> <p>A dictionary of MongoDB client options.</p> <code>DEFAULT_CHUNK_SIZE</code> <code>int</code> <p>The default chunk size to use when none is provided.</p> <code>LOCALE_ENCODING</code> <code>str</code> <p>The locale encoding to use when none is provided.</p>"},{"location":"backends/#clickhouse","title":"ClickHouse","text":"<p>The ClickHouse backend can be used as a data lake and to fetch collections of documents from it.</p> <p>Represent the ClickHouse data backend default configuration.</p> <p>Attributes:</p> Name Type Description <code>HOST</code> <code>str</code> <p>ClickHouse server host to connect to.</p> <code>PORT</code> <code>int</code> <p>ClickHouse server port to connect to.</p> <code>DATABASE</code> <code>str</code> <p>ClickHouse database to connect to.</p> <code>EVENT_TABLE_NAME</code> <code>str</code> <p>Table where events live.</p> <code>USERNAME</code> <code>str</code> <p>ClickHouse username to connect as (optional).</p> <code>PASSWORD</code> <code>str</code> <p>Password for the given ClickHouse username (optional).</p> <code>CLIENT_OPTIONS</code> <code>ClickHouseClientOptions</code> <p>A dictionary of valid options for the ClickHouse client connection.</p> <code>DEFAULT_CHUNK_SIZE</code> <code>int</code> <p>The default chunk size for reading/writing.</p> <code>LOCALE_ENCODING</code> <code>str</code> <p>The locale encoding to use when none is provided.</p>"},{"location":"backends/#ovh_-_log_data_platform_ldp","title":"OVH - Log Data Platform (LDP)","text":"<p>LDP is a nice service built by OVH on top of Graylog to follow, analyse and store your logs. Learning events (aka tracking logs) can be stored in GELF format using this backend.</p> <p>Read-only backend</p> <p>For now the LDP backend is read-only as we consider that it is mostly used to collect primary logs and not as a Ralph target. Feel free to get in touch to prove us wrong, or better: submit your proposal for the <code>write</code> method implementation.</p> <p>To access OVH\u2019s LDP API, you need to register Ralph as an authorized application and generate an application key, an application secret and a consumer key.</p> <p>While filling the registration form available at: eu.api.ovh.com/createToken/, be sure to give an appropriate validity time span to your token and allow only GET requests on the <code>/dbaas/logs/*</code> path.</p> <p>OVH LDP (Log Data Platform) data backend default configuration.</p> <p>Attributes:</p> Name Type Description <code>APPLICATION_KEY</code> <code>str</code> <p>The OVH API application key (AK).</p> <code>APPLICATION_SECRET</code> <code>str</code> <p>The OVH API application secret (AS).</p> <code>CONSUMER_KEY</code> <code>str</code> <p>The OVH API consumer key (CK).</p> <code>DEFAULT_STREAM_ID</code> <code>str</code> <p>The default stream identifier to query.</p> <code>ENDPOINT</code> <code>str</code> <p>The OVH API endpoint.</p> <code>REQUEST_TIMEOUT</code> <code>int</code> <p>HTTP request timeout in seconds.</p> <code>SERVICE_NAME</code> <code>str</code> <p>The default LDP account name.</p> <p>For more information about OVH\u2019s API client parameters, please refer to the project\u2019s documentation: github.com/ovh/python-ovh.</p>"},{"location":"backends/#openstack_swift","title":"OpenStack Swift","text":"<p>Swift is the OpenStack object storage service. This storage backend is fully supported (read and write operations) to stream and store log archives.</p> <p>Parameters correspond to a standard authentication using OpenStack Keystone service and configuration to work with the target container.</p> <p>Represent the SWIFT data backend default configuration.</p> <p>Attributes:</p> Name Type Description <code>AUTH_URL</code> <code>str</code> <p>The authentication URL.</p> <code>USERNAME</code> <code>str</code> <p>The name of the openstack swift user.</p> <code>PASSWORD</code> <code>str</code> <p>The password of the openstack swift user.</p> <code>IDENTITY_API_VERSION</code> <code>str</code> <p>The keystone API version to authenticate to.</p> <code>TENANT_ID</code> <code>str</code> <p>The identifier of the tenant of the container.</p> <code>TENANT_NAME</code> <code>str</code> <p>The name of the tenant of the container.</p> <code>PROJECT_DOMAIN_NAME</code> <code>str</code> <p>The project domain name.</p> <code>REGION_NAME</code> <code>str</code> <p>The region where the container is.</p> <code>OBJECT_STORAGE_URL</code> <code>str</code> <p>The default storage URL.</p> <code>USER_DOMAIN_NAME</code> <code>str</code> <p>The user domain name.</p> <code>DEFAULT_CONTAINER</code> <code>str</code> <p>The default target container.</p> <code>LOCALE_ENCODING</code> <code>str</code> <p>The encoding used for reading/writing documents.</p>"},{"location":"backends/#amazon_s3","title":"Amazon S3","text":"<p>S3 is the Amazon Simple Storage Service. This storage backend is fully supported (read and write operations) to stream and store log archives.</p> <p>Parameters correspond to a standard authentication with AWS CLI  and configuration to work with the target bucket.</p> <p>S3 data backend default configuration.</p> <p>Attributes:</p> Name Type Description <code>ACCESS_KEY_ID</code> <code>str</code> <p>The access key id for the S3 account.</p> <code>SECRET_ACCESS_KEY</code> <code>str</code> <p>The secret key for the S3 account.</p> <code>SESSION_TOKEN</code> <code>str</code> <p>The session token for the S3 account.</p> <code>ENDPOINT_URL</code> <code>str</code> <p>The endpoint URL of the S3.</p> <code>DEFAULT_REGION</code> <code>str</code> <p>The default region used in instantiating the client.</p> <code>DEFAULT_BUCKET_NAME</code> <code>str</code> <p>The default bucket name targeted.</p> <code>DEFAULT_CHUNK_SIZE</code> <code>str</code> <p>The default chunk size for reading and writing objects.</p> <code>LOCALE_ENCODING</code> <code>str</code> <p>The encoding used for writing dictionaries to objects.</p>"},{"location":"backends/#file_system","title":"File system","text":"<p>The file system backend is a dummy template that can be used to develop your own backend.  It is a \u201cdummy\u201d backend as it is not intended for practical use (UNIX <code>ls</code> and <code>cat</code> would be more practical).</p> <p>The only required parameter is the <code>path</code> we want to list or stream content from.</p> <p>FileSystem data backend default configuration.</p> <p>Attributes:</p> Name Type Description <code>DEFAULT_CHUNK_SIZE</code> <code>int</code> <p>The default chunk size for reading files.</p> <code>DEFAULT_DIRECTORY_PATH</code> <code>str or Path</code> <p>The default target directory path where to perform list, read and write operations.</p> <code>DEFAULT_QUERY_STRING</code> <code>str</code> <p>The default query string to match files for the read operation.</p> <code>LOCALE_ENCODING</code> <code>str</code> <p>The encoding used for writing dictionaries to files.</p> <p>The ClickHouse client options supported in Ralph can be found in these locations:</p> <ul> <li>Python driver specific</li> <li>General ClickHouse client settings</li> </ul>"},{"location":"backends/#learning_record_store_lrs_-_http_backend_interface","title":"Learning Record Store (LRS) - HTTP backend interface","text":"<p>Warning</p> <p><code>HTTP</code> backend type will soon be merged into the <code>Data</code> backend type.</p> <p>PR #521 prepares <code>Data</code> backend alignments with <code>HTTP</code> backend <code>read</code> method signature</p> <p>The LRS backend is used to store and retrieve xAPI statements from various systems that follow the xAPI specification (such as our own Ralph LRS, which can be run from this package).  LRS systems are mostly used in e-learning infrastructures.</p> <p>LRS HTTP backend default configuration.</p> <p>Attributes:</p> Name Type Description <code>BASE_URL</code> <code>AnyHttpUrl</code> <p>LRS server URL.</p> <code>USERNAME</code> <code>str</code> <p>Basic auth username for LRS authentication.</p> <code>PASSWORD</code> <code>str</code> <p>Basic auth password for LRS authentication.</p> <code>HEADERS</code> <code>dict</code> <p>Headers defined for the LRS server connection.</p> <code>STATUS_ENDPOINT</code> <code>str</code> <p>Endpoint used to check server status.</p> <code>STATEMENTS_ENDPOINT</code> <code>str</code> <p>Default endpoint for LRS statements resource.</p>"},{"location":"backends/#websocket_-_stream_backend_interface","title":"WebSocket - Stream backend interface","text":"<p>The webSocket backend is read-only and can be used to get real-time events.</p> <p>If you use OVH\u2019s Logs Data Platform (LDP), you can retrieve a WebSocket URI to test your data stream by following instructions from the official documentation.</p> <p>Websocket stream backend default configuration.</p> <p>Attributes:</p> Name Type Description <code>URI</code> <code>str</code> <p>The URI to connect to.</p>"},{"location":"models/","title":"Learning statement models","text":"<p>The learning statement models validation and conversion tools in Ralph empower you to work with an LRS and ensure the quality of xAPI statements. These features not only enhance the integrity of your learning data but also facilitate integration and compliance with industry standards.</p> <p>This section provides insights into the supported models, their conversion, and validation.</p>"},{"location":"models/#supported_statements","title":"Supported statements","text":"<p>Learning statement models encompass a wide array of xAPI and OpenEdx statement types, ensuring comprehensive support for your e-learning data.</p> <ol> <li> <p>xAPI statements models:</p> <ul> <li>LMS</li> <li>Video</li> <li>Virtual classroom</li> </ul> </li> <li> <p>OpenEdx statements models:</p> <ul> <li>Enrollment</li> <li>Navigational</li> <li>Open Reponse Assessment</li> <li>Peer instruction</li> <li>Problem interaction</li> <li>Textbook interaction</li> <li>Video interaction</li> </ul> </li> </ol>"},{"location":"models/#statements_validation","title":"Statements validation","text":"<p>In learning analytics, the validation of statements takes on significant importance.  These statements, originating from diverse sources, systems or applications, must align with specific standards such as xAPI for the best known.  The validation process becomes essential in ensuring that these statements meet the required standards, facilitating data quality and reliability. </p> <p>Ralph allows you to automate the validation process in your production stack.  OpenEdx related events and xAPI statements are supported.</p> <p>Warning</p> <p>For now, validation is effective only with supported learning statement models on Ralph. About xAPI statements, an issue is open to extend validation to any xAPI statement.</p> <p>Check out tutorials to test the validation feature:</p> <ul> <li><code>validate</code> with Ralph as a CLI</li> <li><code>validate</code> with Ralph as a library</li> </ul>"},{"location":"models/#statements_conversion","title":"Statements conversion","text":"<p>Ralph currently supports conversion from OpenEdx learning events to xAPI statements. Here is the up-to-date conversion sets availables: </p> FROM TO edx.course.enrollment.activated registered to a course edx.course.enrollment.deactivated unregistered to a course load_video/edx.video.loaded initialized a video play_video/edx.video.played played a video pause_video/edx.video.paused paused a video stop_video/edx.video.stopped terminated a video seek_video/edx.video.position.changed seeked in a video <p>Check out tutorials to test the conversion feature:</p> <ul> <li><code>convert</code> with Ralph as a CLI</li> <li><code>convert</code> with Ralph as a library</li> </ul>"},{"location":"tutorials/cli/","title":"How to use Ralph as a CLI ?","text":"<p>WIP.</p>"},{"location":"tutorials/cli/#prerequisites","title":"Prerequisites","text":"<ul> <li>Ralph should be properly installed to be used as a <code>CLI</code>. Follow Installation section for more information</li> <li>[Recommended] To easily manipulate JSON streams, please install <code>jq</code> on your machine</li> </ul>"},{"location":"tutorials/cli/#validate_command","title":"<code>validate</code> command","text":"<p>In this tutorial, we\u2019ll walk you through the process of using <code>validate</code> command to check the validity of xAPI statements. </p>"},{"location":"tutorials/cli/#with_an_invalid_xapi_statement","title":"With an invalid xAPI statement","text":"<p>First, let\u2019s test the <code>validate</code> command with a dummy <code>JSON</code> string.</p> <ul> <li>Create in the terminal a dummy statement as follows: </li> </ul> <pre><code>invalid_statement='{\"foo\": \"invalid xapi\"}'\n</code></pre> <ul> <li>Run validation on this statement with this command:</li> </ul> <pre><code>echo \"$invalid_statement\" | ralph validate -f xapi \n</code></pre> <ul> <li>You should observe the following output from the terminal:</li> </ul> <pre><code>INFO     ralph.cli Validating xapi events (ignore_errors=False | fail-on-unknown=False)\nERROR    ralph.models.validator No matching pydantic model found for input event\nINFO     ralph.models.validator Total events: 1, Invalid events: 1\n</code></pre>"},{"location":"tutorials/cli/#with_a_valid_xapi_statement","title":"With a valid xAPI statement","text":"<p>Now, let\u2019s test the <code>validate</code> command with a valid xAPI statement.</p> <p>The tutorial is made on a <code>completed video</code> xAPI statement.</p> Info <p>According to the specification, an xAPI statement to be valid should contain, at least the three following fields:</p> <ul> <li>an <code>actor</code> (with a correct IFI), </li> <li>a <code>verb</code> (with an <code>id</code> property), </li> <li>an <code>object</code> (with an <code>id</code> property).</li> </ul> <ul> <li>Create in the terminal a valid xAPI statement as follows: </li> </ul> <pre><code>valid_statement='{\"actor\": {\"mbox\": \"mailto:johndoe@example.com\", \"name\": \"John Doe\"}, \"verb\": {\"id\": \"http://adlnet.gov/expapi/verbs/completed\"}, \"object\": {\"id\": \"http://example.com/video/001-introduction\"}, \"timestamp\": \"2023-10-31T15:30:00Z\"}'\n</code></pre> <ul> <li>Run validation on this statement with this command:</li> </ul> <pre><code>echo \"$valid_statement\" | bin/ralph validate -f xapi \n</code></pre> <ul> <li>You should observe the following output from the terminal: </li> </ul> <pre><code>INFO     ralph.cli Validating xapi events (ignore_errors=False | fail-on-unknown=False)\nINFO     ralph.models.validator Total events: 1, Invalid events: 1\n</code></pre>"},{"location":"tutorials/cli/#convert_command","title":"<code>convert</code> command","text":"<p>In this tutorial, you\u2019ll learn how to convert OpenEdx events into xAPI statements with Ralph. </p> <p>Note</p> <p>Please note that this feature is currently only supported for a set of OpenEdx events.  When converting Edx events to xAPI statements, always refer to the list of supported event types to ensure accurate and successful conversion.</p> <p>For this example, let\u2019s choose the <code>page_close</code> OpenEdx event that is converted into a <code>terminated a page</code> xAPI statement.</p> <ul> <li>Create in the terminal a <code>page_close</code> OpenEdx event as follows: </li> </ul> <pre><code>edx_statements={\"username\": \"\", \"ip\": \"0.0.0.0\", \"agent\": \"0\", \"host\": \"0\", \"referer\": \"\", \"accept_language\": \"0\", \"context\": {\"course_id\": \"\", \"course_user_tags\": null, \"module\": null, \"org_id\": \"0\", \"path\": \".\", \"user_id\": null}, \"time\": \"2000-01-01T00:00:00\", \"page\": \"http://A.ac/\", \"event_source\": \"browser\", \"session\": \"\", \"event\": \"{}\", \"event_type\": \"page_close\", \"name\": \"page_close\"}\n</code></pre> <ul> <li>Convert this statement into a <code>terminated a page</code> statement with this command:</li> </ul> <pre><code>echo \"$edx_statements\" | \\ \nralph convert \\\n    --platform-url \"http://lms-example.com\" \\\n    --uuid-namespace \"ee241f8b-174f-5bdb-bae9-c09de5fe017f\" \\\n    --from edx \\\n    --to xapi | \\\n    jq\n</code></pre> <ul> <li>You should observe the following output from the terminal: </li> </ul> <pre><code>INFO     ralph.cli Converting edx events to xapi format (ignore_errors=False | fail-on-unknown=False)\nINFO     ralph.models.converter Total events: 1, Invalid events: 0\n{\n  \"id\": \"8670c7d4-5485-52bd-b10a-a8ae27a51501\",\n  \"actor\": {\n    \"account\": {\n      \"homePage\": \"http://lms-example.com\",\n      \"name\": \"anonymous\"\n    }\n  },\n  \"verb\": {\n    \"id\": \"http://adlnet.gov/expapi/verbs/terminated\"\n  },\n  \"object\": {\n    \"id\": \"http://A.ac/\",\n    \"definition\": {\n      \"type\": \"http://activitystrea.ms/schema/1.0/page\"\n    }\n  },\n  \"timestamp\": \"2000-01-01T00:00:00\",\n  \"version\": \"1.0.0\"\n}\n</code></pre> <p>\ud83c\udf89 Congratulations! You just have converted an event generated from OpenEdx LMS to a standardised xAPI statement! </p> Store locally converted statements <p>To stored the converted statements locally on your machine, send the output of the <code>convert</code> command to a <code>JSON</code> file as follows: <pre><code>echo \"$edx_statements\" | \\ \nralph convert \\\n    --platform-url \"http://lms-example.com\" \\\n    --uuid-namespace \"ee241f8b-174f-5bdb-bae9-c09de5fe017f\" \\\n    --from edx \\\n    --to xapi \\\n    &gt; converted_event.json\n</code></pre></p>"},{"location":"tutorials/development_contributing/","title":"How to start developing with Ralph?","text":""},{"location":"tutorials/development_contributing/#prepare_your_environment","title":"Prepare your environment","text":"<p>Welcome to our developer contribution guidelines!  If you\u2019re interested in contributing to our project, there are a few prerequisites to get you started.  Ralph development environment is containerized with Docker for consistency. Before diving in, ensure you have the following installed:</p> <ul> <li>Docker Engine</li> <li>Docker Compose</li> <li>make</li> </ul>"},{"location":"tutorials/development_contributing/#bootstrap_ralph_for_development","title":"Bootstrap Ralph for development","text":"<p>To start playing with <code>ralph</code>, you should first <code>bootstrap</code> using:</p> <pre><code>make bootstrap\n</code></pre> <p>Once the project has been bootstrapped, you may want to edit generated <code>.env</code> file to set up available backend parameters that will be injected into the running container as environment variables to configure Ralph (see backends documentation):</p> <pre><code># Elasticsearch backend\nRALPH_BACKENDS__LRS__ES__HOSTS=http://elasticsearch:9200\nRALPH_BACKENDS__LRS__ES__INDEX=statements\nRALPH_BACKENDS__LRS__ES__TEST_HOSTS=http://elasticsearch:9200\nRALPH_BACKENDS__LRS__ES__TEST_INDEX=test-index\n\n# [...]\n</code></pre> Uncomment lines to define environment variables <p>Lines starting with a <code>#</code> are considered as commented and thus will have no effect while running Ralph.</p>"},{"location":"tutorials/development_contributing/#working_with_backends","title":"Working with backends","text":"<p>To configure the backends, we provide default parameters in the <code>.env.dist</code> template which is copied to the <code>.env</code> file when bootstrapping the project for the first time.  You can uncomment them so that they are properly injected in running containers.</p> <p>In order to run the Elasticsearch backend locally on GNU/Linux operating systems, ensure that your virtual memory limits are not too low and increase them if needed by typing this command from your terminal (as <code>root</code> or using <code>sudo</code>):</p> <p><code>sysctl -w vm.max_map_count=262144</code></p> <p>Reference: https://www.elastic.co/guide/en/elasticsearch/reference/master/vm-max-map-count.html</p> <p>Once configured, start the backend container using:</p> <pre><code>make run-[BACKEND]\n</code></pre> <p>Substitute <code>[BACKEND]</code> by the backend name, e.g. <code>es</code> for Elasticsearch or <code>swift</code> for OpenStack Swift:</p> <pre><code># Start Elasticsearch backend\nmake run-es\n# Start Swift backend\nmake run-swift\n# Start Mongo backend\nmake run-mongo\n# Start ClickHouse backend\nmake run-clickhouse\n# Start all backends\nmake run-all\n</code></pre> <p>Disk space for Elasticsearch</p> <p>Ensure that you have at least 10% of available disk space on your machine to run Elasticsearch. </p> <p>Now that you have started at least the <code>elasticsearch</code> and <code>swift</code> backends, it\u2019s time to play with them:</p> <pre><code># Store a JSON file in the Swift backend\necho '{\"id\": 1, \"foo\": \"bar\"}' | \\\n    ./bin/ralph write -b swift -t foo.json\n\n# Check that we have created a new JSON file in the Swift backend\nbin/ralph list -b swift\n&gt;&gt;&gt; foo.json\n\n# Read the content of the JSON file and index it in Elasticsearch\nbin/ralph read -b swift -t foo.json | \\\n    bin/ralph write -b es\n\n# Check that we have properly indexed the JSON file in Elasticsearch\nbin/ralph read -b es\n&gt;&gt;&gt; {\"id\": 1, \"foo\": \"bar\"}\n</code></pre>"},{"location":"tutorials/development_contributing/#wip_working_with_the_lrs","title":"[WIP] Working with the LRS","text":""},{"location":"tutorials/development_contributing/#working_with_ralphs_tray","title":"Working with Ralph\u2019s tray","text":"<p>Ralph is distributed along with its tray (a deployable package for Kubernetes clusters using Arnold). If you intend to work on this tray, please refer to Arnold\u2019s documentation first.</p>"},{"location":"tutorials/development_contributing/#prerequisites","title":"Prerequisites","text":"<ul> <li>Kubectl (&gt;<code>v.1.23.5</code>):   This CLI is used to communicate with the running Kubernetes instance you   will use.</li> <li>k3d (&gt;<code>v.5.0.0</code>): This tool is used to set up   and run a lightweight Kubernetes cluster, in order to have a local   environment (it is required to complete quickstart instructions below to   avoid depending on an existing Kubernetes cluster).</li> <li>curl is required by Arnold\u2019s CLI.</li> <li>gnupg to encrypt Ansible vaults passwords and   collaborate with your team.</li> </ul>"},{"location":"tutorials/development_contributing/#create_a_local_k3d_cluster","title":"Create a local <code>k3d</code> cluster","text":"<p>To create (or run) a local kubernetes cluster, we use <code>k3d</code>. The cluster\u2019s bootstrapping should be run via:</p> <pre><code>make k3d-cluster\n</code></pre> <p>Running a k3d-cluster locally supposes that the 80 and 443 ports of your machine are available, so that the ingresses created for your project responds properly. If one or both ports are already used by another service running on your machine, the <code>make k3d-cluster</code> command may fail.</p> <p>You can check that your cluster is running using the <code>k3d cluster</code> command:</p> <pre><code>k3d cluster list\n</code></pre> <p>You should expect the following output:</p> <pre><code>NAME     SERVERS   AGENTS   LOADBALANCER\nralph    1/1       0/0      true\n</code></pre> <p>As you can see, we are running a single node cluster called <code>ralph</code>.</p>"},{"location":"tutorials/development_contributing/#bootstrap_an_arnold_project","title":"Bootstrap an Arnold project","text":"<p>Once your Kubernetes cluster is running, you need to create a standard Arnold project describing applications and environments you need to deploy:</p> <pre><code>make arnold-bootstrap\n</code></pre> <p>Once bootstrapped, Arnold should have created a <code>group_vars</code> directory.</p> <p>Run the following command to discover the directory tree.</p> <pre><code>tree group_vars\n</code></pre> <p>The output should be as follows: <pre><code>group_vars\n\u251c\u2500\u2500 common\n\u2514\u2500\u2500 customer\n    \u2514\u2500\u2500 ralph\n        \u251c\u2500\u2500 development\n        \u2502\u00a0\u00a0 \u251c\u2500\u2500 main.yml\n        \u2502\u00a0\u00a0 \u2514\u2500\u2500 secrets\n        \u2502\u00a0\u00a0     \u251c\u2500\u2500 databases.vault.yml\n        \u2502\u00a0\u00a0     \u251c\u2500\u2500 elasticsearch.vault.yml\n        \u2502\u00a0\u00a0     \u2514\u2500\u2500 ralph.vault.yml\n        \u2514\u2500\u2500 main.yml\n\n5 directories, 5 files\n</code></pre></p> <p>To create the LRS credentials file, you need to provide a list of accounts allowed to request the LRS in Ralph\u2019s vault:</p> <pre><code># Setup your kubernetes environment\nsource .k3d-cluster.env.sh\n\n# Decrypt the vault\nbin/arnold -d -c ralph -e development -- vault -a ralph decrypt\n</code></pre> <p>Edit the vault file to add a new account for the <code>foo</code> user with the <code>bar</code> password and a relevant scope:</p> <pre><code># group_vars/customer/ralph/development/secrets/ralph.vault.yml\n#\n# [...]\n#\n# LRS\nLRS_AUTH:\n  - username: \"foo\"\n    hash: \"$2b$12$lCggI749U6TrzK7Qyr7xGe1KVSAXdPjtkMew.BD6lzIk//T5YSb72\"\n    scopes:\n      - \"all\"\n</code></pre> <p>The password hash has been generated using <code>bcrypt</code> as explained in the API user guide.</p> <p>And finally (re-)encrypt Ralph\u2019s vault:</p> <pre><code>bin/arnold -d -c ralph -e development -- vault -a ralph encrypt\n</code></pre> <p>You are now ready to create the related Kubernetes Secret while initializing Arnold project in the next step.</p>"},{"location":"tutorials/development_contributing/#prepare_working_namespace","title":"Prepare working namespace","text":"<p>You are now ready to create required Kubernetes objects to start working on Ralph\u2019s deployment:</p> <pre><code>make arnold-init\n</code></pre> <p>At this point an Elasticsearch cluster should be running on your Kubernetes cluster:</p> <pre><code>kubectl -n development-ralph get -l app=elasticsearch pod\nNAME                                         READY   STATUS      RESTARTS   AGE\nelasticsearch-node-0                         1/1     Running     0          69s\nelasticsearch-node-1                         1/1     Running     0          69s\nelasticsearch-node-2                         1/1     Running     0          69s\nes-index-template-j-221010-09h25m24s-nx5qz   0/1     Completed   0          49s\n</code></pre> <p>We are now ready to deploy Ralph to Kubernetes!</p>"},{"location":"tutorials/development_contributing/#deploy_code_repeat","title":"Deploy, code, repeat","text":"<p>To test your local docker image, you need to build it and publish it to the local kubernetes cluster docker registry using the <code>k3d-push</code> Makefile rule:</p> <pre><code>make k3d-push\n</code></pre> <p>Note</p> <p>Each time you modify Ralph\u2019s application or its Docker image, you will need to make this update.</p> <p>Now that your Docker image is published, it\u2019s time to deploy it!</p> <pre><code>make arnold-deploy\n</code></pre> <p>To test this deployment, let\u2019s try to make an authenticated request to the LRS:</p> <pre><code>curl -sLk \\\n  --user foo:bar \\\n  \"https://$(\\\n      kubectl -n development-ralph \\\n      get \\\n      ingress/ralph-app-current \\\n      -o jsonpath='{.spec.rules[0].host}')/whoami\"\n</code></pre> <p>And why not send test statements from Potsie\u2019s repository:</p> <pre><code>curl -sL \\\n  https://github.com/openfun/potsie/raw/main/fixtures/elasticsearch/lrs.json.gz | \\\ngunzip | \\\nhead -n 100 | \\\njq -s . | \\\nsed \"s/@timestamp/timestamp/g\" | \\\ncurl -sLk \\\n  --user foo:bar \\\n  -X POST \\\n  -H \"Content-Type: application/json\" \\\n  \"https://$(\\\n      kubectl -n development-ralph \\\n      get \\\n      ingress/ralph-app-current \\\n      -o jsonpath='{.spec.rules[0].host}')/xAPI/statements/\" \\\n  -d @-\n</code></pre> <p>Install <code>jq</code></p> <p>This example requires <code>jq</code> command to serialize the request payload (xAPI statements). When dealing with JSON data, we strongly recommend installing it to manipulate them from the command line.</p>"},{"location":"tutorials/development_contributing/#perform_arnolds_operations","title":"Perform Arnold\u2019s operations","text":"<p>If you want to run the <code>bin/arnold</code> script to run specific Arnold commands, you must ensure that your environment is properly set and that Arnold runs in development mode (i.e. using the <code>-d</code> flag):</p> <pre><code>source .k3d-cluster.env.sh\nbin/arnold -d -c ralph -e development -- vault -a ralph view\n</code></pre>"},{"location":"tutorials/development_contributing/#stop_k3d_cluster","title":"Stop <code>k3d</code> cluster","text":"<p>When finished to work on the Tray, you can stop the <code>k3d</code> cluster using the <code>k3d-stop</code> helper:</p> <pre><code>make k3d-stop\n</code></pre>"},{"location":"tutorials/development_contributing/#test_your_development","title":"Test your development","text":"<p>To run tests on your code, either use the <code>test</code> Make target or the <code>bin/pytest</code> script to pass specific arguments to the test runner:</p> <pre><code># Run all tests\nmake test\n\n# Run pytest with options\nbin/pytest -x -k mixins\n\n# Run pytest with options and more debugging logs\nbin/pytest tests/api -x -vvv -s --log-level=DEBUG -k mixins\n</code></pre>"},{"location":"tutorials/development_contributing/#lint_your_code","title":"Lint your code","text":"<p>To lint your code, either use the <code>lint</code> meta target or one of the linting tools we use:</p> <pre><code># Run all linters\nmake lint\n\n# Run ruff linter\nmake lint-ruff\n\n# Run ruff linter and resolve fixable errors\nmake lint-ruff-fix\n\n# List available linters\nmake help | grep lint-\n</code></pre>"},{"location":"tutorials/development_contributing/#document_your_modification","title":"Document your modification","text":"<p>In case you need to document your code, use the following targets:</p> <pre><code># Build documentation site\nmake docs-build\n\n# Run mkdocs live server for dev docs\nmake docs-serve\n</code></pre>"},{"location":"tutorials/library/","title":"How to use Ralph as a library ?","text":"<p>WIP.</p>"},{"location":"tutorials/library/#validate_method","title":"<code>validate</code> method","text":"<p>WIP.</p>"},{"location":"tutorials/library/#convert_method","title":"<code>convert</code> method","text":"<p>WIP.</p>"}]}
\ No newline at end of file
diff --git a/master/sitemap.xml b/master/sitemap.xml
index 1e8af8535..94301bbdc 100644
--- a/master/sitemap.xml
+++ b/master/sitemap.xml
@@ -2,62 +2,62 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
     <url>
          <loc>https://openfun.github.io/ralph/latest/</loc>
-         <lastmod>2023-11-24</lastmod>
+         <lastmod>2023-11-30</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://openfun.github.io/ralph/latest/CHANGELOG/</loc>
-         <lastmod>2023-11-24</lastmod>
+         <lastmod>2023-11-30</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://openfun.github.io/ralph/latest/LICENSE/</loc>
-         <lastmod>2023-11-24</lastmod>
+         <lastmod>2023-11-30</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://openfun.github.io/ralph/latest/UPGRADE/</loc>
-         <lastmod>2023-11-24</lastmod>
+         <lastmod>2023-11-30</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://openfun.github.io/ralph/latest/commands/</loc>
-         <lastmod>2023-11-24</lastmod>
+         <lastmod>2023-11-30</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://openfun.github.io/ralph/latest/contribute/</loc>
-         <lastmod>2023-11-24</lastmod>
+         <lastmod>2023-11-30</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://openfun.github.io/ralph/latest/api/</loc>
-         <lastmod>2023-11-24</lastmod>
+         <lastmod>2023-11-30</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://openfun.github.io/ralph/latest/backends/</loc>
-         <lastmod>2023-11-24</lastmod>
+         <lastmod>2023-11-30</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://openfun.github.io/ralph/latest/models/</loc>
-         <lastmod>2023-11-24</lastmod>
+         <lastmod>2023-11-30</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://openfun.github.io/ralph/latest/tutorials/cli/</loc>
-         <lastmod>2023-11-24</lastmod>
+         <lastmod>2023-11-30</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://openfun.github.io/ralph/latest/tutorials/development_contributing/</loc>
-         <lastmod>2023-11-24</lastmod>
+         <lastmod>2023-11-30</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://openfun.github.io/ralph/latest/tutorials/library/</loc>
-         <lastmod>2023-11-24</lastmod>
+         <lastmod>2023-11-30</lastmod>
          <changefreq>daily</changefreq>
     </url>
 </urlset>
\ No newline at end of file
diff --git a/master/sitemap.xml.gz b/master/sitemap.xml.gz
index bb6c711736f1a07e750ce6abaaad7ccaf14c5863..f7219564efdc162d8685a595521534c1c9487fea 100644
GIT binary patch
literal 324
zcmV-K0lWSmiwFozyJ%$s|8r?{Wo=<_E_iKh0M(XJZ-XEdh2Q%tjPHuJFWaIvP3PQ_
zrdzi5c|p8YG6V<Ly8ioN+cdr}OZ2_~Cx^pF2!Uw%Qw!$^+HfUfH}nJ70m)RsWf{Bs
z-II6cE|Xc*YGD8!YnCQ<E5zo3kgn@|!x3uQ7+>j<7*^SVAy<(E{=J*b99w<BrFX7K
zD3<go#>S`y<e`;*$+2p4pDUuNXeuHof<Y3I-aMR34c4ki=D~d7g`u|ytmUc=Y^<WP
zgoB3fq@Y}!A~H}eP~=AS2fp?5YMZ5-*KG8po0oOE{YXd8xqr*vSC8Z8WU8*IEX)Kz
zC2F3x2%|@(4Ie#YPT3bs;oR-AAjXf0Eh^2aC1rw7h_-+u2-Vae@$+`Y?87;sEeM`#
Ws!#t<d~WO)BKZYmc!Z;J2mk<dkfC4z

literal 325
zcmV-L0lNMliwFp>=U`<5|8r?{Wo=<_E_iKh0M(XJZ-XEdh2Q%tjPFWyd)OAWX*%bY
zG~KeU&kN$Mk|8*_*7e^H+oth-S)%s^I5`|XLI^~QpISHv(1t4+yMaG<9gs{FT$ZuB
z`*`y1+(j~rS}hEqW6jdUZiU!95Yly>Z#Y6t8{;co62mGxFytbVxqt5_GsjjRaPFNd
z5{e~#im@@O0l9CbUvjM4+~<mDDw>K2ieQjLq&E-eQiHWBl5ig0ctPNWx7Kpe1~yhv
zS;Ah!cT!L;ju9CsXDD)|`UBtUdAZ5b^=meI()G(K-E7m*bMD@<_vPdGIhm?!Dho3K
zP>Gu7EyCzgX~Rd)m{axzQ#g0KEQs-AVv9<1YDt;k6QV8P075l2Nc_BBG5c^%XbXbp
Xn(E{K6Q3IUg-Ct@O6+%latHtbThyF8