From 1fa13a4e61fd9cd1a223f4263456fd9c59180be1 Mon Sep 17 00:00:00 2001
From: FUN MOOC Bot <funmoocbot@users.noreply.github.com>
Date: Mon, 8 Apr 2024 15:20:22 +0000
Subject: [PATCH] Deployed 02b0d47 to dev with MkDocs 1.5.3 and mike 2.0.0

---
 dev/CHANGELOG/index.html     |  25 ++++++++++++++++++++++---
 dev/features/api/index.html  |   4 ++--
 dev/search/search_index.json |   2 +-
 dev/sitemap.xml.gz           | Bin 396 -> 396 bytes
 4 files changed, 25 insertions(+), 6 deletions(-)

diff --git a/dev/CHANGELOG/index.html b/dev/CHANGELOG/index.html
index d98cbb1c6..e6a86564c 100644
--- a/dev/CHANGELOG/index.html
+++ b/dev/CHANGELOG/index.html
@@ -1126,7 +1126,16 @@
     </span>
   </a>
   
-    <nav class="md-nav" aria-label="Unreleased">
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#420_-_2024-04-08" class="md-nav__link">
+    <span class="md-ellipsis">
+      4.2.0 - 2024-04-08
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="4.2.0 - 2024-04-08">
       <ul class="md-nav__list">
         
           <li class="md-nav__item">
@@ -1981,7 +1990,16 @@
     </span>
   </a>
   
-    <nav class="md-nav" aria-label="Unreleased">
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#420_-_2024-04-08" class="md-nav__link">
+    <span class="md-ellipsis">
+      4.2.0 - 2024-04-08
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="4.2.0 - 2024-04-08">
       <ul class="md-nav__list">
         
           <li class="md-nav__item">
@@ -2790,7 +2808,8 @@ <h1 id="changelog">Changelog<a class="headerlink" href="#changelog" title="Perma
 <p>The format is based on <a href="https://keepachangelog.com/en/1.0.0/">Keep a Changelog</a>,
 and this project adheres to
 <a href="https://semver.org/spec/v2.0.0.html">Semantic Versioning</a>.</p>
-<h2 id="unreleased"><a href="https://github.com/openfun/ralph/compare/v4.1.0...main">Unreleased</a><a class="headerlink" href="#unreleased" title="Permanent link">&para;</a></h2>
+<h2 id="unreleased"><a href="https://github.com/openfun/ralph/compare/v4.2.0...main">Unreleased</a><a class="headerlink" href="#unreleased" title="Permanent link">&para;</a></h2>
+<h2 id="420_-_2024-04-08"><a href="https://github.com/openfun/ralph/compare/v4.1.0...v4.2.0">4.2.0</a> - 2024-04-08<a class="headerlink" href="#420_-_2024-04-08" title="Permanent link">&para;</a></h2>
 <h3 id="added">Added<a class="headerlink" href="#added" title="Permanent link">&para;</a></h3>
 <ul>
 <li>Models: Add Edx teams-related events support</li>
diff --git a/dev/features/api/index.html b/dev/features/api/index.html
index 6ce64b3a5..9ee8580f0 100644
--- a/dev/features/api/index.html
+++ b/dev/features/api/index.html
@@ -1533,7 +1533,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-3-1"><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a><span class="p">{</span>
 </span><span id="__span-3-2"><a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-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-3-3"><a id="__codelineno-3-3" name="__codelineno-3-3" href="#__codelineno-3-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;f0e5435b-ecdb-4229-beef-15160422cc2f&quot;</span><span class="p">,</span>
+</span><span id="__span-3-3"><a id="__codelineno-3-3" name="__codelineno-3-3" href="#__codelineno-3-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;dcdd0906-53b3-463e-99df-192b963a8f28&quot;</span><span class="p">,</span>
 </span><span id="__span-3-4"><a id="__codelineno-3-4" name="__codelineno-3-4" href="#__codelineno-3-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-3-5"><a id="__codelineno-3-5" name="__codelineno-3-5" href="#__codelineno-3-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-3-6"><a id="__codelineno-3-6" name="__codelineno-3-6" href="#__codelineno-3-6"></a><span class="w">    </span><span class="p">},</span>
@@ -2209,7 +2209,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-23-1"><a id="__codelineno-23-1" name="__codelineno-23-1" href="#__codelineno-23-1"></a><span class="p">{</span>
 </span><span id="__span-23-2"><a id="__codelineno-23-2" name="__codelineno-23-2" href="#__codelineno-23-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-23-3"><a id="__codelineno-23-3" name="__codelineno-23-3" href="#__codelineno-23-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;f2dbe95e-7e75-467c-87c9-c6172932af50&quot;</span><span class="p">,</span>
+</span><span id="__span-23-3"><a id="__codelineno-23-3" name="__codelineno-23-3" href="#__codelineno-23-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;2f1e28e8-5663-4e4d-a1a2-a45463b4564a&quot;</span><span class="p">,</span>
 </span><span id="__span-23-4"><a id="__codelineno-23-4" name="__codelineno-23-4" href="#__codelineno-23-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-23-5"><a id="__codelineno-23-5" name="__codelineno-23-5" href="#__codelineno-23-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-23-6"><a id="__codelineno-23-6" name="__codelineno-23-6" href="#__codelineno-23-6"></a><span class="w">    </span><span class="p">},</span>
diff --git a/dev/search/search_index.json b/dev/search/search_index.json
index 5f0547e75..a2ff52867 100644
--- a/dev/search/search_index.json
+++ b/dev/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, an 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":"#what_is_an_lrs","title":"What is an LRS?","text":"<p>A Learning Record Store, or LRS, is a key component in the context of learning analytics and the Experience API (xAPI).</p> <p>The Experience API (or Tin Can API) is a standard for tracking and reporting learning experiences.  In particular, it defines:</p> <ul> <li>the xAPI format of the learning events. xAPI statements include an <code>actor</code>, a <code>verb</code>, an <code>object</code> as well as contextual information. Here\u2019s an example statement:  <pre><code>{\n    \"id\": \"12345678-1234-5678-1234-567812345678\",\n    \"actor\":{\n        \"mbox\":\"mailto:xapi@adlnet.gov\"\n    },\n    \"verb\":{\n        \"id\":\"http://adlnet.gov/expapi/verbs/created\",\n        \"display\":{\n            \"en-US\":\"created\"\n        }\n    },\n    \"object\":{\n        \"id\":\"http://example.adlnet.gov/xapi/example/activity\"\n    }\n}\n</code></pre></li> <li>the Learning Record Store (LRS), is a RESTful API that collects, stores and retrieves these events. Think of it as a learning database that unifies data from various learning platforms and applications.  These events can come from an LMS (Moodle, edX), or any other learning component that supports sending xAPI statements to an LRS (e.g. an embedded video player), from various platforms.</li> </ul> <p>xAPI specification version</p> <p>In Ralph, we\u2019re following the xAPI specification 1.0.3 that you can find here.</p> <p>For your information, xAPI specification 2.0 is out! It\u2019s not currently supported in Ralph, but you can check it here.</p>"},{"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 want to generate xAPI statements from your application and only need to integrate learning statement models 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 want to play around with backends with Ralph as a library, you can install: </li> </ul> <pre><code>pip install ralph-malph[backends]\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[full]\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":"#lrs_specification_compliance","title":"LRS specification compliance","text":"<p>WIP.</p>"},{"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>Models: Add Edx teams-related events support</li> <li>Models: Add Edx notes events support</li> <li>Models: Add Edx certificate events support</li> <li>Models: Add Edx bookmark (renamed Course Resource) events support</li> <li>Models: Add Edx poll and survey events support</li> <li>Models: Add Edx Course Content Completion events support</li> <li>Models: Add Edx drag and drop events support</li> <li>Models: Add Edx cohort events support</li> <li>Models: Add Edx content library interaction events support</li> <li>Backends: Add <code>ralph.backends.data</code> and <code>ralph.backends.lrs</code> entry points   to discover backends from plugins.</li> </ul>"},{"location":"CHANGELOG/#changed","title":"Changed","text":"<ul> <li>Backends: the first argument of the <code>get_backends</code> method now requires a list   of <code>EntryPoints</code>, each pointing to a backend class, instead of a tuple of   packages containing backends.</li> <li>API: The <code>RUNSERVER_BACKEND</code> configuration value is no longer validated to   point to an existing backend.</li> </ul>"},{"location":"CHANGELOG/#fixed","title":"Fixed","text":"<ul> <li>LRS: Fix querying on <code>activity</code> when LRS contains statements with an object   lacking a <code>objectType</code> attribute</li> </ul>"},{"location":"CHANGELOG/#410_-_2024-02-12","title":"4.1.0 - 2024-02-12","text":""},{"location":"CHANGELOG/#added_1","title":"Added","text":"<ul> <li>Add LRS multitenancy support for user-specific target storage</li> </ul>"},{"location":"CHANGELOG/#changed_1","title":"Changed","text":"<ul> <li><code>query_statements</code> and <code>query_statements_by_ids</code> methods can now take an optional user-specific target</li> </ul>"},{"location":"CHANGELOG/#fixed_1","title":"Fixed","text":"<ul> <li>Backends: switch LRSStatementsQuery since/until field types to iso 8601 string</li> </ul>"},{"location":"CHANGELOG/#removed","title":"Removed","text":"<ul> <li>Removed <code>event_table_name</code> attribute of the ClickHouse data backend</li> </ul>"},{"location":"CHANGELOG/#400_-_2024-01-23","title":"4.0.0 - 2024-01-23","text":""},{"location":"CHANGELOG/#added_2","title":"Added","text":"<ul> <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>max_statements</code> option to data backends <code>read</code> method</li> <li>Backends: Add <code>prefetch</code> option to async data backends <code>read</code> method</li> <li>Backends: Add <code>concurrency</code> option to async data backends <code>write</code> method</li> <li>Backends: Add <code>get_backends</code> function to automatically discover backends   for CLI and LRS usage</li> <li>Backends: Add client options for WSDataBackend</li> <li>Backends: Add <code>READ_CHUNK_SIZE</code> and <code>WRITE_CHUNK_SIZE</code> data backend settings</li> <li>Models: Implement Pydantic model for LRS Statements resource query parameters</li> <li>Models: Implement xAPI LMS Profile statements validation</li> <li>Models: Add <code>EdX</code> to <code>xAPI</code> converters for enrollment events</li> <li>Project: Add aliases for <code>ralph-malph</code> extra dependencies: <code>backends</code> and   <code>full</code></li> </ul>"},{"location":"CHANGELOG/#changed_2","title":"Changed","text":"<ul> <li>Arnold: Add variable to override PVC name in arnold deployment</li> <li>API: <code>GET /statements</code> now has \u201cmine\u201d option which matches statements that   have an authority field matching that of the user</li> <li>API: Invalid parameters now return 400 status code</li> <li>API: Forwarding PUT now uses PUT (instead of POST)</li> <li>API: Incoming statements are enriched with <code>id</code>, <code>timestamp</code>, <code>stored</code>   and <code>authority</code></li> <li>API: Add <code>RALPH_LRS_RESTRICT_BY_AUTHORITY</code> option making <code>?mine=True</code>   implicit</li> <li>API: Add <code>RALPH_LRS_RESTRICT_BY_SCOPE</code> option enabling endpoint access   control by user scopes</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> <li>Backends: Refactor LRS Statements resource query parameters defined for   <code>ralph</code> API</li> <li>Backends: Refactor <code>database</code>, <code>storage</code>, <code>http</code> and <code>stream</code> backends under   the unified <code>data</code> backend interface [BC]</li> <li>Backends: 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>Backends: Update <code>statementId</code> and <code>voidedStatementId</code> to snake_case,   with camelCase alias, in <code>LRSStatementsQuery</code></li> <li>Backends: Replace reference to a JSON column in ClickHouse with   function calls on the String column [BC]</li> <li>CLI: User credentials must now include an \u201cagent\u201d field which can be created   using the cli</li> <li>CLI: Change <code>push</code> to <code>write</code> and <code>fetch</code> to <code>read</code> [BC]</li> <li>CLI: Change <code>-c --chunk-size</code> option to <code>-s --chunk-size</code> [BC]</li> <li>CLI: Change websocket backend name <code>-b ws</code> to <code>-b async_ws</code> along with it\u2019s   uri option <code>--ws-uri</code> to <code>--async-ws-uri</code> [BC]</li> <li>CLI: List cli usage strings in alphabetical order</li> <li>CLI: Change backend configuration environment variable prefixes from   <code>RALPH_BACKENDS__{{DATABASE|HTTP|STORAGE|STREAM}}__{{BACKEND}}__{{OPTION}}</code>   to <code>RALPH_BACKENDS__DATA__{{BACKEND}}__{{OPTION}}</code></li> <li>Models: The xAPI <code>context.contextActivities.category</code> field is now mandatory   in the video and virtual classroom profiles. [BC]</li> <li>Upgrade base python version to 3.12 for the development stack and Docker   image</li> <li>Upgrade <code>bcrypt</code> to <code>4.1.2</code></li> <li>Upgrade <code>cachetools</code> to <code>5.3.2</code></li> <li>Upgrade <code>fastapi</code> to <code>0.108.0</code></li> <li>Upgrade <code>sentry_sdk</code> to <code>1.39.1</code></li> <li>Upgrade <code>uvicorn</code> to <code>0.25.0</code></li> </ul>"},{"location":"CHANGELOG/#fixed_2","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_1","title":"Removed","text":"<ul> <li>Project: Drop support for Python 3.7</li> <li>Models: Remove <code>school</code>, <code>course</code>, <code>module</code> context extensions in Edx to xAPI   base converter</li> <li>Models: Remove <code>name</code> field in <code>VideoActivity</code> xAPI model mistakenly used in   <code>video</code> profile</li> <li>CLI: Remove <code>DEFAULT_BACKEND_CHUNK_SIZE</code> environment variable configuration</li> </ul>"},{"location":"CHANGELOG/#390_-_2023-07-21","title":"3.9.0 - 2023-07-21","text":""},{"location":"CHANGELOG/#changed_3","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_3","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_4","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_4","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_5","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_2","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_5","title":"Added","text":"<ul> <li>Allow to ignore health check routes for Sentry transactions</li> </ul>"},{"location":"CHANGELOG/#changed_6","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_3","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_7","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_4","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_6","title":"Added","text":"<ul> <li>Implement PUT verb on statements endpoint</li> <li>Add ClickHouse database backend support</li> </ul>"},{"location":"CHANGELOG/#changed_8","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_9","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_5","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_7","title":"Added","text":"<ul> <li>Restore python 3.7+ support for library usage (models)</li> </ul>"},{"location":"CHANGELOG/#changed_10","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_11","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_8","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_12","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_6","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_9","title":"Added","text":"<ul> <li>EdX to xAPI converters for video events</li> </ul>"},{"location":"CHANGELOG/#changed_13","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_3","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_10","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_14","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_4","title":"Removed","text":"<ul> <li>Remove YAML configuration file support and <code>pyyaml</code> dependency (BC)</li> </ul>"},{"location":"CHANGELOG/#fixed_7","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_11","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_15","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_16","title":"Changed","text":"<ul> <li>Upgrade <code>elasticsearch</code> to <code>7.13.3</code></li> </ul>"},{"location":"CHANGELOG/#fixed_8","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_12","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_17","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_9","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_13","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_10","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_5","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_14","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_18","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_6","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_15","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/#3x_to_4y","title":"3.x to 4.y","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_ralph_cli_usage","title":"Upgrade Ralph CLI usage","text":"<p>If you are using Ralph\u2019s CLI, the following changes may affect you:</p> <ul> <li>The <code>ralph fetch</code> command changed to <code>ralph read</code></li> <li>The <code>-b ws</code> backend option changed to <code>-b async_ws</code><ul> <li>The corresponding <code>--ws-uri</code> option changed to <code>--async-ws-uri</code></li> </ul> </li> <li>The <code>-c --chunk-size</code> option changed to <code>-s --chunk-size</code></li> <li> <p>The <code>DEFAULT_BACKEND_CHUNK_SIZE</code> environment variable configuration is removed in     favor of allowing each backend to define their own defaults:</p> Backend Environment variable for default (read) chunk size async_es/es RALPH_BACKENDS__DATA__ES__READ_CHUNK_SIZE=500 async_lrs/lrs RALPH_BACKENDS__DATA__LRS__READ_CHUNK_SIZE=500 async_mongo/mongo RALPH_BACKENDS__DATA__MONGO__READ_CHUNK_SIZE=500 clickhouse RALPH_BACKENDS__DATA__CLICKHOUSE__READ_CHUNK_SIZE=500 fs RALPH_BACKENDS__DATA__FS__READ_CHUNK_SIZE=4096 ldp RALPH_BACKENDS__DATA__LDP__READ_CHUNK_SIZE=4096 s3 RALPH_BACKENDS__DATA__S3__READ_CHUNK_SIZE=4096 swift RALPH_BACKENDS__DATA__SWIFT__READ_CHUNK_SIZE=4096 </li> <li> <p>The <code>ralph push</code> command changed to <code>ralph write</code></p> </li> <li>The <code>-c --chunk-size</code> option changed to <code>-s --chunk-size</code></li> <li> <p>The <code>DEFAULT_BACKEND_CHUNK_SIZE</code> environment variable configuration is removed in     favor of allowing each backend to define their own defaults:</p> Backend Environment variable for default (write) chunk size async_es/es RALPH_BACKENDS__DATA__ES__WRITE_CHUNK_SIZE=500 async_lrs/lrs RALPH_BACKENDS__DATA__LRS__WRITE_CHUNK_SIZE=500 async_mongo/mongo RALPH_BACKENDS__DATA__MONGO__WRITE_CHUNK_SIZE=500 clickhouse RALPH_BACKENDS__DATA__CLICKHOUSE__WRITE_CHUNK_SIZE=500 fs RALPH_BACKENDS__DATA__FS__WRITE_CHUNK_SIZE=4096 ldp RALPH_BACKENDS__DATA__LDP__WRITE_CHUNK_SIZE=4096 s3 RALPH_BACKENDS__DATA__S3__WRITE_CHUNK_SIZE=4096 swift RALPH_BACKENDS__DATA__SWIFT__WRITE_CHUNK_SIZE=4096 </li> <li> <p>Environment variables used to configure backend options for CLI usage   (read/write/list commands) changed their prefix:   <code>RALPH_BACKENDS__{{DATABASE or HTTP or STORAGE or STREAM}}__{{BACKEND}}__{{OPTION}}</code>   changed to   <code>RALPH_BACKENDS__DATA__{{BACKEND}}__{{OPTION}}</code></p> </li> <li>Environment variables used to configure backend options for LRS usage   (runserver command) changed their prefix:   <code>RALPH_BACKENDS__{{DATABASE}}__{{BACKEND}}__{{OPTION}}</code>   changed to   <code>RALPH_BACKENDS__LRS__{{BACKEND}}__{{OPTION}}</code></li> </ul>"},{"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_ralph_library_usage_backends","title":"Upgrade Ralph library usage (backends)","text":"<p>If you use Ralph\u2019s backends in your application, the following changes might affect you:</p> <p>Backends from <code>ralph.backends.database</code>, <code>ralph.backends.http</code>, <code>ralph.backends.stream</code>, and <code>ralph.backends.storage</code> packages have moved to a single <code>ralph.backends.data</code> package.</p> Ralph v3 (database/http/storage/stream) backends Ralph v4 data backends <code>ralph.backends.database.clickhouse.ClickHouseDatabase</code> <code>ralph.backends.data.clickhouse.ClickHouseDataBackend</code> <code>ralph.backends.database.es.ESDatabase</code> <code>ralph.backends.data.es.ESDataBackend</code> <code>ralph.backends.database.mongo.MongoDatabase</code> <code>ralph.backends.data.mongo.MongoDataBackend</code> <code>ralph.backends.http.async_lrs.AsyncLRSHTTP</code> <code>ralph.backends.data.async_lrs.AsyncLRSDataBackend</code> <code>ralph.backends.http.lrs.LRSHTTP</code> <code>ralph.backends.data.lrs.LRSDataBackend</code> <code>ralph.backends.storage.fs.FSStorage</code> <code>ralph.backends.data.fs.FSDataBackend</code> <code>ralph.backends.storage.ldp.LDPStorage</code> <code>ralph.backends.data.ldp.LDPDataBackend</code> <code>ralph.backends.storage.s3.S3Storage</code> <code>ralph.backends.data.s3.S3DataBackend</code> <code>ralph.backends.storage.swift.SwiftStorage</code> <code>ralph.backends.data.swift.SwiftDataBackend</code> <code>ralph.backends.stream.ws.WSStream</code> <code>ralph.backends.data.async_ws.AsyncWSDataBackend</code> <p>LRS-specific <code>query_statements</code> and <code>query_statements_by_ids</code> database backend methods have moved to a dedicated <code>ralph.backends.lrs.BaseLRSBackend</code> interface that extends the data backend interface with these two methods.</p> <p>The <code>query_statements_by_ids</code> method return type changed to <code>Iterator[dict]</code>.</p> Ralph v3 database backends for lrs usage Ralph v4 LRS data backends <code>ralph.backends.database.clickhouse.ClickHouseDatabase</code> <code>ralph.backends.lrs.clickhouse.ClickHouseLRSBackend</code> <code>ralph.backends.database.es.ESDatabase</code> <code>ralph.backends.lrs.es.ESLRSBackend</code> <code>ralph.backends.database.mongo.MongoDatabase</code> <code>ralph.backends.lrs.mongo.MongoLRSBackend</code> <p>Backend interface differences</p> <ul> <li>Data backends are read-only by default</li> <li>Data backends that support write operations inherit from the   <code>ralph.backends.data.base.Writable</code> interface</li> <li>Data backends that support list operations inherit from the   <code>ralph.backends.data.base.Listable</code> interface</li> <li>Data backends that support LRS operations   (<code>query_statements</code>/<code>query_statements_by_ids</code>) inherit from the   <code>ralph.backends.lrs.BaseLRSBackend</code> interface</li> <li><code>__init__(self, **kwargs)</code> changed to <code>__init__(self, settings: DataBackendSettings)</code>   where each DataBackend defines it\u2019s own Settings object   For example the <code>FSDataBackend</code> uses <code>FSDataBackendSettings</code></li> <li><code>stream</code> and <code>get</code> methods changed to <code>read</code></li> <li><code>put</code> methods changed to <code>write</code></li> </ul> <p>Backend usage migration example</p> <p>Ralph v3 using <code>ESDatabase</code>:</p> <pre><code>from ralph.conf import ESClientOptions\nfrom ralph.backends.database.es import ESDatabase, ESQuery\n\n# Instantiate the backend.\nbackend = ESDatabase(\n  hosts=\"localhost\",\n  index=\"statements\"\n  client_options=ESClientOptions(verify_certs=False)\n)\n# Read records from backend.\nquery = ESQuery(query={\"query\": {\"term\": {\"modulo\": 0}}})\nes_statements = list(backend.get(query))\n\n# Write records to backend.\nbackend.put([{\"id\": 1}])\n</code></pre> <p>Ralph v4 using <code>ESDataBackend</code>:</p> <pre><code>from ralph.backends.data.es import (\n  ESClientOptions,\n  ESDataBackend,\n  ESDataBackendSettings,\n  ESQuery,\n)\n\n# Instantiate the backend.\nsettings = ESDataBackendSettings(\n  HOSTS=\"localhost\",\n  INDEX=\"statements\",\n  CLIENT_OPTIONS=ESClientOptions(verify_certs=False)\n)\nbackend = ESDataBackend(settings)\n\n# Read records from backend.\nquery = ESQuery(query={\"term\": {\"modulo\": 0}})\nes_statements = list(backend.read(query))\n\n# Write records to backend.\nbackend.write([{\"id\": 1}])\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  -t, --target TEXT               The target location where statements are\n                                  stored for the user.\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>main</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":"features/api/","title":"LRS HTTP server","text":"<p>Ralph implements the Learning Record Store (LRS) specification defined by ADL.</p> <p>Ralph LRS, based on FastAPI, has the following key features:</p> <ul> <li>Supports of multiple databases through different backends</li> <li>Secured with multiple authentication methods</li> <li>Supports multitenancy</li> <li>Enables the Total Learning Architecture with statements forwarding</li> <li>Monitored thanks to the Sentry integration</li> </ul>"},{"location":"features/api/#api_documentation","title":"API documentation","text":""},{"location":"features/api/#fastapi_010","title":"FastAPI 0.1.0","text":""},{"location":"features/api/#endpoints","title":"Endpoints","text":""},{"location":"features/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":"features/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\": \"f0e5435b-ecdb-4229-beef-15160422cc2f\",\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":"features/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":"features/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":"features/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\": \"f2dbe95e-7e75-467c-87c9-c6172932af50\",\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":"features/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":"features/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":"features/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":"features/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":"features/api/#schemas","title":"Schemas","text":""},{"location":"features/api/#basexapiaccount","title":"BaseXapiAccount","text":"Name Type <code>homePage</code> string <code>name</code> string"},{"location":"features/api/#basexapiagentwithaccount","title":"BaseXapiAgentWithAccount","text":"Name Type <code>account</code> BaseXapiAccount <code>name</code> string <code>objectType</code> string"},{"location":"features/api/#basexapiagentwithmbox","title":"BaseXapiAgentWithMbox","text":"Name Type <code>mbox</code> string <code>name</code> string <code>objectType</code> string"},{"location":"features/api/#basexapiagentwithmboxsha1sum","title":"BaseXapiAgentWithMboxSha1Sum","text":"Name Type <code>mbox_sha1sum</code> string <code>name</code> string <code>objectType</code> string"},{"location":"features/api/#basexapiagentwithopenid","title":"BaseXapiAgentWithOpenId","text":"Name Type <code>name</code> string <code>objectType</code> string <code>openid</code> string(uri)"},{"location":"features/api/#basexapianonymousgroup","title":"BaseXapiAnonymousGroup","text":"Name Type <code>member</code> Array&lt;&gt; <code>name</code> string <code>objectType</code> string"},{"location":"features/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":"features/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":"features/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":"features/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":"features/api/#errordetail","title":"ErrorDetail","text":"Name Type <code>detail</code> string"},{"location":"features/api/#httpvalidationerror","title":"HTTPValidationError","text":"Name Type <code>detail</code> Array&lt;ValidationError&gt;"},{"location":"features/api/#laxobjectfield","title":"LaxObjectField","text":"Name Type <code>id</code> string(uri)"},{"location":"features/api/#laxstatement","title":"LaxStatement","text":"Name Type <code>actor</code> <code>id</code> string(uuid) <code>object</code> LaxObjectField <code>verb</code> LaxVerbField"},{"location":"features/api/#laxverbfield","title":"LaxVerbField","text":"Name Type <code>id</code> string(uri)"},{"location":"features/api/#validationerror","title":"ValidationError","text":"Name Type <code>loc</code> Array&lt;&gt; <code>msg</code> string <code>type</code> string"},{"location":"features/api/#security_schemes","title":"Security schemes","text":"Name Type Scheme Description HTTPBasic http basic"},{"location":"features/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":"features/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__DATA__{{ backend_name | uppercase }}__{{ parameter | uppercase }}</code> for environment variables.</li> </ul>"},{"location":"features/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_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>READ_CHUNK_SIZE</code> <code>int</code> <p>The default chunk size for reading batches of documents.</p> <code>REFRESH_AFTER_WRITE</code> <code>str or bool</code> <p>Whether the Elasticsearch index should be refreshed after the write operation.</p> <code>WRITE_CHUNK_SIZE</code> <code>int</code> <p>The default chunk size for writing batches of documents.</p>"},{"location":"features/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>LOCALE_ENCODING</code> <code>str</code> <p>The locale encoding to use when none is provided.</p> <code>READ_CHUNK_SIZE</code> <code>int</code> <p>The default chunk size for reading batches of documents.</p> <code>WRITE_CHUNK_SIZE</code> <code>int</code> <p>The default chunk size for writing batches of documents.</p>"},{"location":"features/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>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>LOCALE_ENCODING</code> <code>str</code> <p>The locale encoding to use when none is provided.</p> <code>READ_CHUNK_SIZE</code> <code>int</code> <p>The default chunk size for reading.</p> <code>WRITE_CHUNK_SIZE</code> <code>int</code> <p>The default chunk size for writing.</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":"features/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>READ_CHUNK_SIZE</code> <code>str</code> <p>The default chunk size for reading archives.</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":"features/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>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> <code>READ_CHUNK_SIZE</code> <code>str</code> <p>The default chunk size for reading objects.</p> <code>WRITE_CHUNK_SIZE</code> <code>str</code> <p>The default chunk size for writing objects.</p>"},{"location":"features/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>LOCALE_ENCODING</code> <code>str</code> <p>The encoding used for writing dictionaries to objects.</p> <code>READ_CHUNK_SIZE</code> <code>str</code> <p>The default chunk size for reading objects.</p> <code>WRITE_CHUNK_SIZE</code> <code>str</code> <p>The default chunk size for writing objects.</p>"},{"location":"features/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_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> <code>READ_CHUNK_SIZE</code> <code>int</code> <p>The default chunk size for reading files.</p> <code>WRITE_CHUNK_SIZE</code> <code>int</code> <p>The default chunk size for writing files.</p>"},{"location":"features/backends/#learning_record_store_lrs","title":"Learning Record Store (LRS)","text":"<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 data 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>LOCALE_ENCODING</code> <code>str</code> <p>The encoding used for reading statements.</p> <code>READ_CHUNK_SIZE</code> <code>int</code> <p>The default chunk size for reading statements.</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> <code>WRITE_CHUNK_SIZE</code> <code>int</code> <p>The default chunk size for writing statements.</p>"},{"location":"features/backends/#websocket","title":"WebSocket","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 data backend default configuration.</p> <p>Attributes:</p> Name Type Description <code>CLIENT_OPTIONS</code> <code>dict</code> <p>A dictionary of valid options for the websocket client connection. See <code>WSClientOptions</code>.</p> <code>URI</code> <code>str</code> <p>The URI to connect to.</p> <p>Client options for <code>websockets.connection</code>.</p> <p>For mode details, see the websockets.connection documentation</p> <p>Attributes:</p> Name Type Description <code>close_timeout</code> <code>float</code> <p>Timeout for opening the connection in seconds.</p> <code>compression</code> <code>str</code> <p>Per-message compression (deflate) is activated by default. Setting it to <code>None</code> disables compression.</p> <code>max_size</code> <code>int</code> <p>Maximum size of incoming messages in bytes. Setting it to <code>None</code> disables the limit.</p> <code>max_queue</code> <code>int</code> <p>Maximum number of incoming messages in receive buffer. Setting it to <code>None</code> disables the limit.</p> <code>open_timeout</code> <code>float</code> <p>Timeout for opening the connection in seconds. Setting it to <code>None</code> disables the timeout.</p> <code>origin</code> <code>str</code> <p>Value of the <code>Origin</code> header, for servers that require it.</p> <code>ping_interval</code> <code>float</code> <p>Delay between keepalive pings in seconds. Setting it to <code>None</code> disables keepalive pings.</p> <code>ping_timeout</code> <code>float</code> <p>Timeout for keepalive pings in seconds. Setting it to <code>None</code> disables timeouts.</p> <code>read_limit</code> <code>int</code> <p>High-water mark of read buffer in bytes.</p> <code>user_agent_header</code> <code>str</code> <p>Value of  the <code>User-Agent</code> request header. It defaults to \u201cPython/x.y.z websockets/X.Y\u201d. Setting it to <code>None</code> removes the header.</p> <code>write_limit</code> <code>int</code> <p>High-water mark of write buffer in bytes.</p>"},{"location":"features/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":"features/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":"features/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":"features/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_guide/","title":"Development guide","text":"<p>Welcome to our developer contribution guidelines!</p> <p>You should know that we would be glad to help you contribute to Ralph! Here\u2019s our Discord to contact us easily.</p>"},{"location":"tutorials/development_guide/#preparation","title":"Preparation","text":"<p>Prerequisites</p> <p>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> <p>Info</p> <p>In this tutorial, and even more generally in others tutorials, we tend to use Elasticsearch backend. Note that you can do the same with another LRS backend implemented in Ralph.</p> <p>To start playing with <code>ralph</code>, you should first <code>bootstrap</code> using:</p> <pre><code>make bootstrap\n</code></pre> <p>When bootstrapping the project for the first time, the <code>env.dist</code> template file is copied to the <code>.env</code> file. You may want to edit the 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> <p>Default configuration in <code>.env</code> file</p> <p>Defaults are provided for some environment variables that you can use by uncommenting them.</p>"},{"location":"tutorials/development_guide/#backends","title":"Backends","text":"<p>Virtual memory for Elasticsearch</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>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>Once configured, start the database container using the following command, substituting <code>[BACKEND]</code> by the backend name (e.g. <code>es</code> for Elasticsearch):</p> <pre><code>make run-[BACKEND]\n</code></pre> <p>You can also start other services with the following commands: <pre><code>make run-es\nmake run-swift\nmake run-mongo\nmake run-clickhouse\n# Start all backends\nmake run-all\n</code></pre></p> <p>Now that you have started the <code>elasticsearch</code> and <code>swift</code> backends, it\u2019s time to play with them with Ralph CLI:</p> <p>We can store a JSON file in the Swift backend: <pre><code>echo '{\"id\": 1, \"foo\": \"bar\"}' | \\\n    ./bin/ralph write -b swift -t foo.json\n</code></pre></p> <p>We can check that we have created a new JSON file in the Swift backend: <pre><code>bin/ralph list -b swift\n&gt;&gt;&gt; foo.json\n</code></pre></p> <p>Let\u2019s read the content of the JSON file and index it in Elasticsearch <pre><code>bin/ralph read -b swift -t foo.json | \\\n    bin/ralph write -b es\n</code></pre></p> <p>We can now check that we have properly indexed the JSON file in Elasticsearch <pre><code>bin/ralph read -b es\n&gt;&gt;&gt; {\"id\": 1, \"foo\": \"bar\"}\n</code></pre></p>"},{"location":"tutorials/development_guide/#wip_lrs","title":"[WIP] LRS","text":""},{"location":"tutorials/development_guide/#tray","title":"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> <p>Prerequisites</p> <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_guide/#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_guide/#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 LRS 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_guide/#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_guide/#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>Let\u2019s also send some test statements:</p> <pre><code>gunzip -c data/statements.json.gz | \\\nhead -n 100 | \\\njq -s . | \\\ncurl -sLk \\\n  --user foo:bar \\\n  -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -d @- \\\n  \"https://$(\\\n      kubectl -n development-ralph \\\n      get \\\n      ingress/ralph-app-current \\\n      -o jsonpath='{.spec.rules[0].host}')/xAPI/statements/\"\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_guide/#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_guide/#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_guide/#after_your_development","title":"After your development","text":""},{"location":"tutorials/development_guide/#testing","title":"Testing","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_guide/#linting","title":"Linting","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_guide/#documentation","title":"Documentation","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/helm/","title":"Ralph Helm chart","text":"<p>Ralph LRS is distributed as a Helm chart in the DockerHub OCI openfuncharts.</p>"},{"location":"tutorials/helm/#setting_environment_values","title":"Setting environment values","text":"<p>All default values are in the <code>values.yaml</code> file. With Helm, you can extend the values file: there is no need to copy/paste all the default values. You can create an environment values file, e.g. <code>custom-values.yaml</code> and only set needed customizations.</p> <p>All sensitive environment values, needed for Ralph to work, are expected to be in an external Secret Kubernetes object. An example manifest is provided in the <code>ralph-env-secret.yaml</code> file here that you can adapt to fit your needs.</p> <p>All other non-sensitive environment values, also needed for Ralph to work, are expected to be in an external ConfigMap Kubernetes object. An example manifest is provided in the <code>ralph-env-cm.yaml</code> file here that you can adapt to fit your needs.</p>"},{"location":"tutorials/helm/#creating_authentication_secret","title":"Creating authentication secret","text":"<p>Ralph stores users credentials in an external Secret Kubernetes object. An example authentication file <code>auth-demo.json</code> is provided here, that you can take inspiration from. Refer to the LRS guide for creating user credentials.</p>"},{"location":"tutorials/helm/#reviewing_manifest","title":"Reviewing manifest","text":"<p>To generate and review your Helm generated manifest, under <code>./src/helm</code> run the following command:</p> <pre><code>helm template oci://registry-1.docker.io/openfuncharts/ralph\n</code></pre>"},{"location":"tutorials/helm/#installing_the_chart","title":"Installing the chart","text":"<p>Ralph Helm chart is distributed on DockerHub, and you can install it with: <pre><code>helm install RELEASE_NAME oci://registry-1.docker.io/openfuncharts/ralph\n</code></pre></p> <p>Tips:</p> <ul> <li>use <code>--values</code> to pass an env values file to extend and/or replace the default values</li> <li><code>--set var=value</code> to replace one var/value</li> <li><code>--dry-run</code> to verify your manifest before deploying</li> </ul>"},{"location":"tutorials/helm/#tutorial_deploying_ralph_lrs_on_a_local_cluster","title":"Tutorial: deploying Ralph LRS on a local cluster","text":"<p>This tutorial aims at deploying Ralph LRS on a local Kubernetes cluster using Helm. In this tutorial, you will learn to:</p> <ul> <li>run and configure a small Kubernetes cluster on your machine,</li> <li>deploy a data lake that stores learning records: we choose Elasticsearch,</li> <li>deploy Ralph LRS (Learning Records Store) that receives and sends learning records in   xAPI,</li> </ul>"},{"location":"tutorials/helm/#requirements","title":"Requirements","text":"<ul> <li><code>curl</code>, the CLI to make HTTP requests.</li> <li><code>jq</code>, the JSON data Swiss-Knife.</li> <li><code>kubectl</code>, the Kubernetes CLI.</li> <li><code>helm</code>, the package manager for Kubernetes.</li> <li><code>minikube</code>, a lightweight kubernetes   distribution to work locally on the project.</li> </ul>"},{"location":"tutorials/helm/#bootstrapping_a_local_cluster","title":"Bootstrapping a local cluster","text":"<p>Let\u2019s begin by running a local cluster with Minikube, where we will deploy Ralph on.</p> <pre><code># Start a local kubernetes cluster\nminikube start\n</code></pre> <p>We will now create our own Kubernetes namespace to work on:</p> <pre><code># This is our namespace\nexport K8S_NAMESPACE=\"learning-analytics\"\n\n# Check your namespace value\necho ${K8S_NAMESPACE}\n\n# Create the namespace\nkubectl create namespace ${K8S_NAMESPACE}\n\n# Activate the namespace\nkubectl config set-context --current --namespace=${K8S_NAMESPACE}\n</code></pre>"},{"location":"tutorials/helm/#deploying_the_data_lake_elasticsearch","title":"Deploying the data lake: Elasticsearch","text":"<p>In its recent releases, Elastic recommends deploying its services using Custom Resource Definitions (CRDs) installed via its official Helm chart. We will first install the Elasticsearch (ECK) operator cluster-wide:</p> <pre><code># Add elastic official helm charts repository\nhelm repo add elastic https://helm.elastic.co\n\n# Update available charts list\nhelm repo update\n\n# Install the ECK operator\nhelm install elastic-operator elastic/eck-operator -n elastic-system --create-namespace\n</code></pre> <p>Now that CRDs are already deployed cluster-wide, we can deploy an Elasticsearch cluster. To help you in this task, we provide an example manifest <code>data-lake.yml</code>, that deploy a two-nodes elasticsearch \u201ccluster\u201d. Adapt it to match your needs, then apply it with:</p> <pre><code>kubectl apply -f data-lake.yml\n</code></pre> <p>Once applied, your elasticsearch pod should be running. You can check this using the following command:</p> <pre><code>kubectl get pods -w\n</code></pre> <p>We expect to see two pods called <code>data-lake-es-default-0</code> and <code>data-lake-es-default-1</code>.</p> <p>When our Elasticsearch cluster is up (this can take few minutes), you may create the Elasticsearch index that will be used to store learning traces (xAPI statements):</p> <pre><code># Store elastic user password\nexport ELASTIC_PASSWORD=\"$(kubectl get secret data-lake-es-elastic-user -o jsonpath=\"{.data.elastic}\" | base64 -d)\"\n\n# Execute an index creation request in the elasticsearch container\nkubectl exec data-lake-es-default-0 --container elasticsearch -- \\\n    curl -ks -X PUT \"https://elastic:${ELASTIC_PASSWORD}@localhost:9200/statements?pretty\"\n</code></pre> <p>Our Elasticsearch cluster is all set. In the next section, we will now deploy Ralph, our LRS.</p>"},{"location":"tutorials/helm/#deploy_the_lrs_ralph","title":"Deploy the LRS: Ralph","text":"<p>First and foremost, we should create a Secret object containing the user credentials file. We provide an example authentication file <code>auth-demo.json</code> that you can take inspiration from. We can create a secret object directly from the file with the command:</p> <pre><code>kubectl create secret generic ralph-auth-secret \\\n    --from-file=auth.json=auth-demo.json\n</code></pre> <p>Secondly, we should create two objects containing environment values necessary for Ralph:</p> <ul> <li>a Secret containing sensitive environment variables such as passwords, tokens etc;</li> <li>a ConfigMap containing all other non-sensitive environment variables.</li> </ul> <p>We provide two example manifests (<code>ralph-env-secret.yaml</code> and <code>ralph-env-cm.yml</code>) that you can adapt to fit your needs. </p> <p>For this tutorial, we only need to replace the <code>&lt;PASSWORD&gt;</code> tag in the Secret manifest by the actual password of the <code>elastic</code> user with the command: <pre><code>sed -i -e \"s|&lt;PASSWORD&gt;|$ELASTIC_PASSWORD|g\" ralph-env-secret.yaml\n</code></pre></p> <p>We can now apply both manifests, to create a ConfigMap and a Secret object in our local cluster: <pre><code># Create Secret object\nkubectl apply -f ralph-env-secret.yaml\n\n# Create ConfigMap object\nkubectl apply -f ralph-env-cm.yaml\n</code></pre></p> <p>We can now deploy Ralph: <pre><code>helm install lrs oci://registry-1.docker.io/openfuncharts/ralph \\\n  --values development.yaml\n</code></pre></p> <p>One can check if the server is running by opening a network tunnel to the service using the <code>port-forward</code> sub-command:</p> <pre><code>kubectl port-forward svc/lrs-ralph 8080:8080\n</code></pre> <p>And then send a request to the server using this tunnel:</p> <pre><code>curl --user admin:password localhost:8080/whoami\n</code></pre> <p>We expect a valid JSON response stating about the user you are using for this request.</p> <p>If everything went well, we can send 22k xAPI statements to the LRS using:</p> <pre><code>gunzip -c ../../data/statements.jsonl.gz | \\\n  sed \"s/@timestamp/timestamp/g\" | \\\n  jq -s . | \\\n  curl -Lk \\\n    --user admin:password \\\n    -X POST \\\n    -H \"Content-Type: application/json\" \\\n    http://localhost:8080/xAPI/statements/ -d @-\n</code></pre> <p>Congrats \ud83c\udf89</p>"},{"location":"tutorials/helm/#go_further","title":"Go further","text":"<p>Now that the LRS is running, we can go further and deploy the dashboard suite Warren. Refer to the tutorial of the Warren Helm chart.</p>"},{"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>"},{"location":"tutorials/lrs/","title":"How to use Ralph LRS?","text":"<p>This tutorial shows you how to run Ralph LRS, step by step.</p> <p>Warning</p> <p>Ralph LRS will be executed locally for demonstration purpose. If you want to deploy Ralph LRS on a production server, please refer to the  deployment guide.</p> <p>Ralph LRS is based on FastAPI. In this tutorial, we will run the server manually with Uvicorn, but other alternatives exists (Hypercorn, Daphne).</p> <p>Prerequisites</p> <p>Some tools are required to run the commands of this tutorial. Make sure they are installed first:</p> <ul> <li>Ralph package with CLI optional dependencies, e.g. <code>pip install ralph-malph[cli]</code> (check the CLI tutorial)</li> <li>Docker Compose</li> <li>curl or httpie</li> </ul>"},{"location":"tutorials/lrs/backends/","title":"Backends","text":"<p>Ralph LRS is built to be used with a database instead of writing learning records in a local file.</p> <p>Ralph LRS supports the following databases:</p> <ul> <li>Elasticsearch</li> <li>Mongo</li> <li>ClickHouse</li> </ul> <p>Let\u2019s add the service of your choice to the <code>docker-compose.yml</code> file:</p> ElasticsearchMongoClickHouse docker-compose.yml<pre><code>version: \"3.9\"\n\nservices:\n  db:\n    image: elasticsearch:8.1.0\n    environment:\n      discovery.type: single-node\n      xpack.security.enabled: \"false\"\n    ports:\n      - \"9200:9200\"\n    mem_limit: 2g\n    ulimits:\n      memlock:\n        soft: -1\n        hard: -1\n    healthcheck:\n      test: curl --fail http://localhost:9200/_cluster/health?wait_for_status=green || exit 1\n      interval: 1s\n      retries: 60\n\n  lrs:\n    image: fundocker/ralph:latest\n    environment:\n      RALPH_APP_DIR: /app/.ralph\n      RALPH_RUNSERVER_BACKEND: es\n      RALPH_BACKENDS__LRS__ES__HOSTS: http://db:9200\n    ports:\n      - \"8100:8100\"\n    command:\n      - \"uvicorn\"\n      - \"ralph.api:app\"\n      - \"--proxy-headers\"\n      - \"--host\"\n      - \"0.0.0.0\"\n      - \"--port\"\n      - \"8100\"\n    volumes:\n      - .ralph:/app/.ralph\n</code></pre> <p>We can now start the database service and wait for it to be up and healthy: <pre><code>docker compose up -d --wait db\n</code></pre></p> <p>Before using Elasticsearch, we need to create an index, which we call <code>statements</code> for this example:</p> curlHTTPie <pre><code>curl -X PUT http://localhost:9200/statements\n</code></pre> <pre><code>http PUT :9200/statements\n</code></pre> <p>docker-compose.yml<pre><code>version: \"3.9\"\n\nservices:\n  db:\n    image: mongo:5.0.9\n    ports:\n      - \"27017:27017\"\n    healthcheck:\n      test: mongosh --eval 'db.runCommand(\"ping\").ok' localhost:27017/test --quiet\n      interval: 1s\n      retries: 60\n\n  lrs:\n    image: fundocker/ralph:latest\n    environment:\n      RALPH_APP_DIR: /app/.ralph\n      RALPH_RUNSERVER_BACKEND: mongo\n      RALPH_BACKENDS__LRS__MONGO__CONNECTION_URI: mongodb://db:27017\n    ports:\n      - \"8100:8100\"\n    command:\n      - \"uvicorn\"\n      - \"ralph.api:app\"\n      - \"--proxy-headers\"\n      - \"--host\"\n      - \"0.0.0.0\"\n      - \"--port\"\n      - \"8100\"\n    volumes:\n      - .ralph:/app/.ralph\n</code></pre> We can now start the database service and wait for it to be up and healthy: <pre><code>docker compose up -d --wait db\n</code></pre></p> <p>docker-compose.yml<pre><code>version: \"3.9\"\n\nservices:\n  db:\n    image: clickhouse/clickhouse-server:23.1.1.3077-alpine\n    environment:\n      CLICKHOUSE_DB: xapi\n      CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1\n    ports:\n      - 8123:8123\n      - 9000:9000\n    # ClickHouse needs to maintain a lot of open files, so they\n    # suggest running the container with increased limits:\n    # https://hub.docker.com/r/clickhouse/clickhouse-server/#!\n    ulimits:\n      nofile:\n        soft: 262144\n        hard: 262144\n    healthcheck:\n      test:  wget --no-verbose --tries=1 --spider http://localhost:8123/ping || exit 1\n      interval: 1s\n      retries: 60\n\n  lrs:\n    image: fundocker/ralph:latest\n    environment:\n      RALPH_APP_DIR: /app/.ralph\n      RALPH_RUNSERVER_BACKEND: clickhouse\n      RALPH_BACKENDS__LRS__CLICKHOUSE__HOST: db\n      RALPH_BACKENDS__LRS__CLICKHOUSE__PORT: 8123\n    ports:\n      - \"8100:8100\"\n    command:\n      - \"uvicorn\"\n      - \"ralph.api:app\"\n      - \"--proxy-headers\"\n      - \"--host\"\n      - \"0.0.0.0\"\n      - \"--port\"\n      - \"8100\"\n    volumes:\n      - .ralph:/app/.ralph\n</code></pre> We can now start the database service and wait for it to be up and healthy: <pre><code>docker compose up -d --wait db\n</code></pre></p> <p>Before using ClickHouse, we need to create a table in the <code>xapi</code> database, which we call <code>xapi_events_all</code>:</p> curlHTTPie <pre><code>  echo \"CREATE TABLE xapi.xapi_events_all (\n    event_id UUID NOT NULL,\n    emission_time DateTime64(6) NOT NULL,\n    event String NOT NULL\n    )\n    ENGINE MergeTree ORDER BY (emission_time, event_id)\n    PRIMARY KEY (emission_time, event_id)\" | \\\n  curl --data-binary @- \"http://localhost:8123/\"\n</code></pre> <pre><code>  echo \"CREATE TABLE xapi.xapi_events_all (\n    event_id UUID NOT NULL,\n    emission_time DateTime64(6) NOT NULL,\n    event String NOT NULL\n    )\n    ENGINE MergeTree ORDER BY (emission_time, event_id)\n    PRIMARY KEY (emission_time, event_id)\" | \\\n  http :8123\n</code></pre> <p>Then we can start Ralph LRS: <pre><code>docker compose up -d lrs\n</code></pre></p> <p>We can finally send some xAPI statements to Ralph LRS:</p> curlHTTPie <pre><code>curl -sL https://github.com/openfun/ralph/raw/master/data/statements.json.gz | \\\ngunzip | \\\nhead -n 100 | \\\njq -s . | \\\ncurl \\\n  --user janedoe:supersecret \\\n  -H \"Content-Type: application/json\" \\\n  -X POST \\\n  -d @- \\\n  \"http://localhost:8100/xAPI/statements\"\n</code></pre> <pre><code>curl -sL https://github.com/openfun/ralph/raw/master/data/statements.json.gz | \\\ngunzip | \\\nhead -n 100 | \\\njq -s . | \\\nhttp -a janedoe:supersecret POST :8100/xAPI/statements\n</code></pre> <p>And fetch, them back: </p> curlHTTPie <pre><code>curl \\\n  --user janedoe:supersecret \\\n  -X GET \\\n  \"http://localhost:8100/xAPI/statements\"\n</code></pre> <pre><code>http -a janedoe:supersecret :8100/xAPI/statements\n</code></pre>"},{"location":"tutorials/lrs/first-steps/","title":"First steps","text":"<p>Ralph LRS is distributed as a Docker image on DockerHub, following the format: <code>fundocker/ralph:&lt;release version | latest&gt;</code>.</p> <p>Let\u2019s dive straight in and create a <code>docker-compose.yml</code> file:</p> docker-compose.yml<pre><code>version: \"3.9\"\n\nservices:\n\n  lrs:\n    image: fundocker/ralph:latest\n    environment:\n      RALPH_APP_DIR: /app/.ralph\n      RALPH_RUNSERVER_BACKEND: fs\n    ports:\n      - \"8100:8100\"\n    command:\n      - \"uvicorn\"\n      - \"ralph.api:app\"\n      - \"--proxy-headers\"\n      - \"--workers\"\n      - \"1\"\n      - \"--host\"\n      - \"0.0.0.0\"\n      - \"--port\"\n      - \"8100\"\n    volumes:\n      - .ralph:/app/.ralph\n</code></pre> <p>For now, we are using the <code>fs</code> (File System) backend, meaning that Ralph LRS will store learning records in local files.</p> <p>First, we need to manually create the <code>.ralph</code> directory alongside the <code>docker-compose.yml</code> file with the command:</p> <pre><code>mkdir .ralph\n</code></pre> <p>We can then run Ralph LRS from a terminal with the command:</p> <pre><code>docker compose up -d lrs\n</code></pre> <p>Ralph LRS server should be up and running!</p> <p>We can request the <code>whoami</code> endpoint to check if the user is authenticated. On success, the endpoint returns the username and permission scopes.</p> curlHTTPie <p><pre><code>curl http://localhost:8100/whoami\n</code></pre> <pre><code>{\"detail\":\"Invalid authentication credentials\"}% \n</code></pre></p> <p><pre><code>http :8100/whoami\n</code></pre> <pre><code>HTTP/1.1 401 Unauthorized\ncontent-length: 47\ncontent-type: application/json\ndate: Mon, 06 Nov 2023 15:37:32 GMT\nserver: uvicorn\nwww-authenticate: Basic\n\n{\n    \"detail\": \"Invalid authentication credentials\"\n}\n</code></pre></p> <p>If you\u2019ve made it this far, congrats! \ud83c\udf89</p> <p>You\u2019ve successfully deployed the Ralph LRS and got a response to your request!</p> <p>Let\u2019s shutdown the Ralph LRS server with the command <code>docker compose down</code> and set up authentication.</p>"},{"location":"tutorials/lrs/forwarding/","title":"Forwarding to another LRS","text":"<p>Ralph LRS server can be configured to forward xAPI statements it receives to other LRSs. Statement forwarding enables the Total Learning Architecture and allows systems containing multiple LRS to share data.</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>Warning</p> <p>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> .env<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":"tutorials/lrs/multitenancy/","title":"Multitenancy","text":"<p>By default, all authenticated users have full read and write access to the server. Ralph LRS implements the specified Authority mechanism to restrict behavior.</p>"},{"location":"tutorials/lrs/multitenancy/#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 request. You may restrict read access to users \u201cown\u201d statements (thus enabling multitenancy) by setting the following environment variable: </p> .env<pre><code>RALPH_LRS_RESTRICT_BY_AUTHORITY=True # Default: False\n</code></pre> <p>Warning</p> <p>Two accounts with different credentials may share the same <code>authority</code>, meaning they can access the same statements. It is the administrator\u2019s responsibility to ensure that <code>authority</code> is properly assigned.</p> <p>Info</p> <p>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":"tutorials/lrs/multitenancy/#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> .env<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":"tutorials/lrs/sentry/","title":"Sentry","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> .env<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 the 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:</p> .env<pre><code>RALPH_SENTRY_CLI_TRACES_SAMPLE_RATE=0.1\nRALPH_SENTRY_LRS_TRACES_SAMPLE_RATE=0.3\n</code></pre> <p>Sample rate</p> <p>A sample 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> .env<pre><code>RALPH_SENTRY_IGNORE_HEALTH_CHECKS=True\n</code></pre>"},{"location":"tutorials/lrs/authentication/","title":"Authentication","text":"<p>The API server supports the following authentication methods:</p> <ul> <li>HTTP basic authentication</li> <li>OpenID Connect authentication on top of OAuth2.0</li> </ul> <p>Either one or both can be enabled for Ralph LRS using the environment variable <code>RALPH_RUNSERVER_AUTH_BACKENDS</code>:</p> <pre><code>RALPH_RUNSERVER_AUTH_BACKENDS=basic,oidc\n</code></pre>"},{"location":"tutorials/lrs/authentication/basic/","title":"HTTP Basic Authentication","text":"<p>The default method for securing the Ralph API server is HTTP Basic Authentication. For this, we need to create a user in Ralph LRS.</p>"},{"location":"tutorials/lrs/authentication/basic/#creating_user_credentials","title":"Creating user credentials","text":"<p>To create a new user credentials, Ralph CLI provides a dedicated command:</p> Ralph CLIDocker Compose <pre><code>ralph auth \\\n    --write-to-disk \\\n    --username janedoe \\\n    --password supersecret \\\n    --scope statements/write \\\n    --scope statements/read \\\n    --agent-ifi-mbox mailto:janedoe@example.com\n</code></pre> <pre><code>docker compose run --rm lrs \\\n  ralph auth \\\n    --write-to-disk \\\n    --username janedoe \\\n    --password supersecret \\\n    --scope statements/write \\\n    --scope statements/read \\\n    --agent-ifi-mbox mailto:janedoe@example.com\n</code></pre> <p>Tip</p> <p>You can either display the helper with <code>ralph auth --help</code> or check the CLI tutorial here</p> <p>This command updates your credentials file with the new <code>janedoe</code> user. Here is the file that has been created by the <code>ralph auth</code> command:</p> auth.json<pre><code>[                                                                               \n  {                                                                             \n    \"agent\": {                                                                  \n      \"mbox\": \"mailto:janedoe@example.com\",                                     \n      \"objectType\": \"Agent\",                                                    \n      \"name\": null                                                              \n    },                                                                          \n    \"scopes\": [                                                                 \n      \"statements/write\",                                                           \n      \"statements/read\"\n    ],                                                                          \n    \"hash\": \"$2b$12$eQmMF/7ALdNuksL4lkI.NuTibNjKLd0fw2Xe.FZqD0mNkgnnjLLPa\",     \n    \"username\": \"janedoe\"                                                       \n  }                                                                             \n] \n</code></pre> <p>Alternatively, the credentials file can also be created manually. It is expected to be a valid JSON file. Its location is specified by the <code>RALPH_AUTH_FILE</code> configuration value. </p> <p>Tip</p> <p>By default, Ralph LRS looks 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:</p> <ul> <li>the username</li> <li>the user\u2019s hashed+salted password</li> <li>the scopes they can access</li> <li>an <code>agent</code> object used to represent the user in the LRS. </li> </ul> <p>Info</p> <p>The <code>agent</code> is constrained by LRS specifications, and must use one of four valid Inverse Functional Identifiers.</p>"},{"location":"tutorials/lrs/authentication/basic/#making_a_get_request","title":"Making a GET request","text":"<p>After changing the <code>docker-compose.yml</code> file as follow: docker-compose.yml<pre><code>version: \"3.9\"\n\nservices:\n\n  lrs:\n    image: fundocker/ralph:latest\n    environment:\n      RALPH_APP_DIR: /app/.ralph\n      RALPH_RUNSERVER_BACKEND: fs\n      RALPH_RUNSERVER_AUTH_BACKENDS: basic\n    ports:\n      - \"8100:8100\"\n    command:\n      - \"uvicorn\"\n      - \"ralph.api:app\"\n      - \"--proxy-headers\"\n      - \"--workers\"\n      - \"1\"\n      - \"--host\"\n      - \"0.0.0.0\"\n      - \"--port\"\n      - \"8100\"\n    volumes:\n      - .ralph:/app/.ralph\n</code></pre> and running the Ralph LRS with:</p> <pre><code>docker compose up -d lrs\n</code></pre> <p>we can request the <code>whoami</code> endpoint again, but this time sending our username and password through Basic Auth:</p> curlHTTPie <p><pre><code>curl --user janedoe:supersecret http://localhost:8100/whoami\n</code></pre> <pre><code>{\"agent\":{\"mbox\":\"mailto:janedoe@example.com\",\"objectType\":\"Agent\",\"name\":null},\"scopes\":[\"statements/read\",\"statements/write\"]}\n</code></pre></p> <p><pre><code>http -a janedoe:supersecret :8100/whoami \n</code></pre> <pre><code>HTTP/1.1 200 OK\ncontent-length: 107\ncontent-type: application/json\ndate: Tue, 07 Nov 2023 17:32:31 GMT\nserver: uvicorn\n\n{\n    \"agent\": {\n        \"mbox\": \"mailto:janedoe@example.com\",\n        \"name\": null,\n        \"objectType\": \"Agent\"\n    },\n    \"scopes\": [\n        \"statements/read\",\n        \"statements/write\"\n    ]\n}\n</code></pre></p> <p>Congrats! \ud83c\udf89 You have been successfully authenticated!</p> <p>HTTP Basic auth caching</p> <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.</p> <p>To speed up requests, credentials are stored in an LRU cache with a \u201cTime To Live\u201d.</p> <p>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 \u201cTime To Live\u201d of the cache entries in seconds. Defaults to 3600s.</p> <pre><code>RALPH_AUTH_CACHE_TTL=3600\n</code></pre>"},{"location":"tutorials/lrs/authentication/oidc/","title":"OpenID Connect authentication","text":"<p>Ralph LRS also supports OpenID Connect on top of OAuth 2.0 for authentication and authorization.</p> <p>To enable OpenID Connect authentication mode, we should change the <code>RALPH_RUNSERVER_AUTH_BACKENDS</code> environment variable to <code>oidc</code> and we should define the <code>RALPH_RUNSERVER_AUTH_OIDC_ISSUER_URI</code> environment variable with the identity provider\u2019s Issuer Identifier URI as follows:</p> <pre><code>RALPH_RUNSERVER_AUTH_BACKENDS=oidc\nRALPH_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 OpenID Connect Discovery to retrieve public keys and other information about the OpenID Connect environment.</p> <p>It is also strongly recommended to set the optional <code>RALPH_RUNSERVER_AUTH_OIDC_AUDIENCE</code> environment variable to the origin address of Ralph LRS itself (e.g. \u201chttp://localhost:8100\u201d) to enable verification that a given token was issued specifically for that Ralph LRS.</p>"},{"location":"tutorials/lrs/authentication/oidc/#identity_providers","title":"Identity Providers","text":"<p>OpenID Connect support is currently developed and tested against Keycloak but may work with other identity providers that implement the specification.</p>"},{"location":"tutorials/lrs/authentication/oidc/#an_example_with_keycloak","title":"An example with Keycloak","text":"<p>The Learning analytics playground repository contains a Docker Compose file and configuration for a demonstration instance of Keycloak with a <code>ralph</code> client.</p> <p>First, we should stop the Ralph LRS server (if it\u2019s still running): <pre><code>docker compose down\n</code></pre></p> <p>We can clone the <code>learning-analytics-playground</code> repository: <pre><code>git clone git@github.com:openfun/learning-analytics-playground\n</code></pre></p> <p>And then bootstrap the project: <pre><code>cd learning-analytics-playground/\nmake bootstrap\n</code></pre></p> <p>After a couple of minutes, the playground containers should be up and running.</p> <p>Create another docker compose file, let\u2019s call it <code>docker-compose.oidc.yml</code>, with the following content: docker-compose.oidc.yml<pre><code>version: \"3.9\"\n\nservices:\n\n  lrs:\n    image: fundocker/ralph:latest\n    environment:\n      RALPH_APP_DIR: /app/.ralph\n      RALPH_RUNSERVER_AUTH_BACKENDS: oidc\n      RALPH_RUNSERVER_AUTH_OIDC_ISSUER_URI: http://learning-analytics-playground-keycloak-1:8080/auth/realms/fun-mooc\n      RALPH_RUNSERVER_BACKEND: fs\n    ports:\n      - \"8100:8100\"\n    command:\n      - \"uvicorn\"\n      - \"ralph.api:app\"\n      - \"--proxy-headers\"\n      - \"--workers\"\n      - \"1\"\n      - \"--host\"\n      - \"0.0.0.0\"\n      - \"--port\"\n      - \"8100\"\n    volumes:\n      - .ralph:/app/.ralph\n    networks:\n      - ralph\n\nnetworks:\n  ralph:\n    external: true\n</code></pre></p> <p>Again, we need to create the <code>.ralph</code> directory: <pre><code>mkdir .ralph\n</code></pre></p> <p>Then we can start the <code>lrs</code> service: <pre><code>docker compose -f docker-compose.oidc.yml up -d lrs\n</code></pre></p> <p>Now that both Keycloak and Ralph LRS server are up and running, we should be able to get the access token from Keycloak with the command:</p> curlHTTPie <pre><code>curl -X POST \\\n  -d \"grant_type=password\" \\\n  -d \"client_id=ralph\" \\\n  -d \"client_secret=bcef3562-730d-4575-9e39-63e185f99bca\" \\\n  -d \"username=ralph_admin\" \\\n  -d \"password=funfunfun\" \\\n  http://localhost:8080/auth/realms/fun-mooc/protocol/openid-connect/token\n</code></pre> <pre><code>{\"access_token\":\"&lt;access token content&gt;\",\"expires_in\":300,\"refresh_expires_in\":1800,\"refresh_token\":\"&lt;refresh token content&gt;\",\"token_type\":\"Bearer\",\"not-before-policy\":0,\"session_state\":\"0889b3a5-d742-45fb-98b3-20e967960e74\",\"scope\":\"email profile\"} \n</code></pre> <pre><code>http -f POST \\\n  :8080/auth/realms/fun-mooc/protocol/openid-connect/token \\\n  grant_type=password \\\n  client_id=ralph \\\n  client_secret=bcef3562-730d-4575-9e39-63e185f99bca \\\n  username=ralph_admin \\\n  password=funfunfun\n</code></pre> <pre><code>HTTP/1.1 200 OK\n...\n{\n    \"access_token\": \"&lt;access token content&gt;\",\n    \"expires_in\": 300,\n    \"not-before-policy\": 0,\n    \"refresh_expires_in\": 1800,\n    \"refresh_token\": \"&lt;refresh token content&gt;\",\n    \"scope\": \"email profile\",\n    \"session_state\": \"1e826fa2-b4b3-42bf-837f-158fe9d5e1e5\",\n    \"token_type\": \"Bearer\"\n}\n</code></pre> <p>With this access token, we can now make a request to the Ralph LRS server:</p> curlHTTPie <pre><code>curl -H 'Authorization: Bearer &lt;access token content&gt;' \\\nhttp://localhost:8100/whoami\n</code></pre> <pre><code>{\"agent\":{\"openid\":\"http://localhost:8080/auth/realms/fun-mooc/b6e85bd0-ce6e-4b24-9f0e-6e18d8744e54\"},\"scopes\":[\"email\",\"profile\"]}\n</code></pre> <pre><code>http -A bearer -a &lt;access token content&gt; :8100/whoami\n</code></pre> <pre><code>HTTP/1.1 200 OK\n...\n{\n    \"agent\": {\n        \"openid\": \"http://localhost:8080/auth/realms/fun-mooc/b6e85bd0-ce6e-4b24-9f0e-6e18d8744e54\"\n    },\n    \"scopes\": [\n        \"email\",\n        \"profile\"\n    ]\n}\n</code></pre> <p>Congrats, you\u2019ve managed to authenticate using OpenID Connect! \ud83c\udf89</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, an 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":"#what_is_an_lrs","title":"What is an LRS?","text":"<p>A Learning Record Store, or LRS, is a key component in the context of learning analytics and the Experience API (xAPI).</p> <p>The Experience API (or Tin Can API) is a standard for tracking and reporting learning experiences.  In particular, it defines:</p> <ul> <li>the xAPI format of the learning events. xAPI statements include an <code>actor</code>, a <code>verb</code>, an <code>object</code> as well as contextual information. Here\u2019s an example statement:  <pre><code>{\n    \"id\": \"12345678-1234-5678-1234-567812345678\",\n    \"actor\":{\n        \"mbox\":\"mailto:xapi@adlnet.gov\"\n    },\n    \"verb\":{\n        \"id\":\"http://adlnet.gov/expapi/verbs/created\",\n        \"display\":{\n            \"en-US\":\"created\"\n        }\n    },\n    \"object\":{\n        \"id\":\"http://example.adlnet.gov/xapi/example/activity\"\n    }\n}\n</code></pre></li> <li>the Learning Record Store (LRS), is a RESTful API that collects, stores and retrieves these events. Think of it as a learning database that unifies data from various learning platforms and applications.  These events can come from an LMS (Moodle, edX), or any other learning component that supports sending xAPI statements to an LRS (e.g. an embedded video player), from various platforms.</li> </ul> <p>xAPI specification version</p> <p>In Ralph, we\u2019re following the xAPI specification 1.0.3 that you can find here.</p> <p>For your information, xAPI specification 2.0 is out! It\u2019s not currently supported in Ralph, but you can check it here.</p>"},{"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 want to generate xAPI statements from your application and only need to integrate learning statement models 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 want to play around with backends with Ralph as a library, you can install: </li> </ul> <pre><code>pip install ralph-malph[backends]\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[full]\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":"#lrs_specification_compliance","title":"LRS specification compliance","text":"<p>WIP.</p>"},{"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/#420_-_2024-04-08","title":"4.2.0 - 2024-04-08","text":""},{"location":"CHANGELOG/#added","title":"Added","text":"<ul> <li>Models: Add Edx teams-related events support</li> <li>Models: Add Edx notes events support</li> <li>Models: Add Edx certificate events support</li> <li>Models: Add Edx bookmark (renamed Course Resource) events support</li> <li>Models: Add Edx poll and survey events support</li> <li>Models: Add Edx Course Content Completion events support</li> <li>Models: Add Edx drag and drop events support</li> <li>Models: Add Edx cohort events support</li> <li>Models: Add Edx content library interaction events support</li> <li>Backends: Add <code>ralph.backends.data</code> and <code>ralph.backends.lrs</code> entry points   to discover backends from plugins.</li> </ul>"},{"location":"CHANGELOG/#changed","title":"Changed","text":"<ul> <li>Backends: the first argument of the <code>get_backends</code> method now requires a list   of <code>EntryPoints</code>, each pointing to a backend class, instead of a tuple of   packages containing backends.</li> <li>API: The <code>RUNSERVER_BACKEND</code> configuration value is no longer validated to   point to an existing backend.</li> </ul>"},{"location":"CHANGELOG/#fixed","title":"Fixed","text":"<ul> <li>LRS: Fix querying on <code>activity</code> when LRS contains statements with an object   lacking a <code>objectType</code> attribute</li> </ul>"},{"location":"CHANGELOG/#410_-_2024-02-12","title":"4.1.0 - 2024-02-12","text":""},{"location":"CHANGELOG/#added_1","title":"Added","text":"<ul> <li>Add LRS multitenancy support for user-specific target storage</li> </ul>"},{"location":"CHANGELOG/#changed_1","title":"Changed","text":"<ul> <li><code>query_statements</code> and <code>query_statements_by_ids</code> methods can now take an optional user-specific target</li> </ul>"},{"location":"CHANGELOG/#fixed_1","title":"Fixed","text":"<ul> <li>Backends: switch LRSStatementsQuery since/until field types to iso 8601 string</li> </ul>"},{"location":"CHANGELOG/#removed","title":"Removed","text":"<ul> <li>Removed <code>event_table_name</code> attribute of the ClickHouse data backend</li> </ul>"},{"location":"CHANGELOG/#400_-_2024-01-23","title":"4.0.0 - 2024-01-23","text":""},{"location":"CHANGELOG/#added_2","title":"Added","text":"<ul> <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>max_statements</code> option to data backends <code>read</code> method</li> <li>Backends: Add <code>prefetch</code> option to async data backends <code>read</code> method</li> <li>Backends: Add <code>concurrency</code> option to async data backends <code>write</code> method</li> <li>Backends: Add <code>get_backends</code> function to automatically discover backends   for CLI and LRS usage</li> <li>Backends: Add client options for WSDataBackend</li> <li>Backends: Add <code>READ_CHUNK_SIZE</code> and <code>WRITE_CHUNK_SIZE</code> data backend settings</li> <li>Models: Implement Pydantic model for LRS Statements resource query parameters</li> <li>Models: Implement xAPI LMS Profile statements validation</li> <li>Models: Add <code>EdX</code> to <code>xAPI</code> converters for enrollment events</li> <li>Project: Add aliases for <code>ralph-malph</code> extra dependencies: <code>backends</code> and   <code>full</code></li> </ul>"},{"location":"CHANGELOG/#changed_2","title":"Changed","text":"<ul> <li>Arnold: Add variable to override PVC name in arnold deployment</li> <li>API: <code>GET /statements</code> now has \u201cmine\u201d option which matches statements that   have an authority field matching that of the user</li> <li>API: Invalid parameters now return 400 status code</li> <li>API: Forwarding PUT now uses PUT (instead of POST)</li> <li>API: Incoming statements are enriched with <code>id</code>, <code>timestamp</code>, <code>stored</code>   and <code>authority</code></li> <li>API: Add <code>RALPH_LRS_RESTRICT_BY_AUTHORITY</code> option making <code>?mine=True</code>   implicit</li> <li>API: Add <code>RALPH_LRS_RESTRICT_BY_SCOPE</code> option enabling endpoint access   control by user scopes</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> <li>Backends: Refactor LRS Statements resource query parameters defined for   <code>ralph</code> API</li> <li>Backends: Refactor <code>database</code>, <code>storage</code>, <code>http</code> and <code>stream</code> backends under   the unified <code>data</code> backend interface [BC]</li> <li>Backends: 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>Backends: Update <code>statementId</code> and <code>voidedStatementId</code> to snake_case,   with camelCase alias, in <code>LRSStatementsQuery</code></li> <li>Backends: Replace reference to a JSON column in ClickHouse with   function calls on the String column [BC]</li> <li>CLI: User credentials must now include an \u201cagent\u201d field which can be created   using the cli</li> <li>CLI: Change <code>push</code> to <code>write</code> and <code>fetch</code> to <code>read</code> [BC]</li> <li>CLI: Change <code>-c --chunk-size</code> option to <code>-s --chunk-size</code> [BC]</li> <li>CLI: Change websocket backend name <code>-b ws</code> to <code>-b async_ws</code> along with it\u2019s   uri option <code>--ws-uri</code> to <code>--async-ws-uri</code> [BC]</li> <li>CLI: List cli usage strings in alphabetical order</li> <li>CLI: Change backend configuration environment variable prefixes from   <code>RALPH_BACKENDS__{{DATABASE|HTTP|STORAGE|STREAM}}__{{BACKEND}}__{{OPTION}}</code>   to <code>RALPH_BACKENDS__DATA__{{BACKEND}}__{{OPTION}}</code></li> <li>Models: The xAPI <code>context.contextActivities.category</code> field is now mandatory   in the video and virtual classroom profiles. [BC]</li> <li>Upgrade base python version to 3.12 for the development stack and Docker   image</li> <li>Upgrade <code>bcrypt</code> to <code>4.1.2</code></li> <li>Upgrade <code>cachetools</code> to <code>5.3.2</code></li> <li>Upgrade <code>fastapi</code> to <code>0.108.0</code></li> <li>Upgrade <code>sentry_sdk</code> to <code>1.39.1</code></li> <li>Upgrade <code>uvicorn</code> to <code>0.25.0</code></li> </ul>"},{"location":"CHANGELOG/#fixed_2","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_1","title":"Removed","text":"<ul> <li>Project: Drop support for Python 3.7</li> <li>Models: Remove <code>school</code>, <code>course</code>, <code>module</code> context extensions in Edx to xAPI   base converter</li> <li>Models: Remove <code>name</code> field in <code>VideoActivity</code> xAPI model mistakenly used in   <code>video</code> profile</li> <li>CLI: Remove <code>DEFAULT_BACKEND_CHUNK_SIZE</code> environment variable configuration</li> </ul>"},{"location":"CHANGELOG/#390_-_2023-07-21","title":"3.9.0 - 2023-07-21","text":""},{"location":"CHANGELOG/#changed_3","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_3","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_4","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_4","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_5","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_2","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_5","title":"Added","text":"<ul> <li>Allow to ignore health check routes for Sentry transactions</li> </ul>"},{"location":"CHANGELOG/#changed_6","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_3","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_7","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_4","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_6","title":"Added","text":"<ul> <li>Implement PUT verb on statements endpoint</li> <li>Add ClickHouse database backend support</li> </ul>"},{"location":"CHANGELOG/#changed_8","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_9","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_5","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_7","title":"Added","text":"<ul> <li>Restore python 3.7+ support for library usage (models)</li> </ul>"},{"location":"CHANGELOG/#changed_10","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_11","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_8","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_12","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_6","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_9","title":"Added","text":"<ul> <li>EdX to xAPI converters for video events</li> </ul>"},{"location":"CHANGELOG/#changed_13","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_3","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_10","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_14","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_4","title":"Removed","text":"<ul> <li>Remove YAML configuration file support and <code>pyyaml</code> dependency (BC)</li> </ul>"},{"location":"CHANGELOG/#fixed_7","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_11","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_15","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_16","title":"Changed","text":"<ul> <li>Upgrade <code>elasticsearch</code> to <code>7.13.3</code></li> </ul>"},{"location":"CHANGELOG/#fixed_8","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_12","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_17","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_9","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_13","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_10","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_5","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_14","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_18","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_6","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_15","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/#3x_to_4y","title":"3.x to 4.y","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_ralph_cli_usage","title":"Upgrade Ralph CLI usage","text":"<p>If you are using Ralph\u2019s CLI, the following changes may affect you:</p> <ul> <li>The <code>ralph fetch</code> command changed to <code>ralph read</code></li> <li>The <code>-b ws</code> backend option changed to <code>-b async_ws</code><ul> <li>The corresponding <code>--ws-uri</code> option changed to <code>--async-ws-uri</code></li> </ul> </li> <li>The <code>-c --chunk-size</code> option changed to <code>-s --chunk-size</code></li> <li> <p>The <code>DEFAULT_BACKEND_CHUNK_SIZE</code> environment variable configuration is removed in     favor of allowing each backend to define their own defaults:</p> Backend Environment variable for default (read) chunk size async_es/es RALPH_BACKENDS__DATA__ES__READ_CHUNK_SIZE=500 async_lrs/lrs RALPH_BACKENDS__DATA__LRS__READ_CHUNK_SIZE=500 async_mongo/mongo RALPH_BACKENDS__DATA__MONGO__READ_CHUNK_SIZE=500 clickhouse RALPH_BACKENDS__DATA__CLICKHOUSE__READ_CHUNK_SIZE=500 fs RALPH_BACKENDS__DATA__FS__READ_CHUNK_SIZE=4096 ldp RALPH_BACKENDS__DATA__LDP__READ_CHUNK_SIZE=4096 s3 RALPH_BACKENDS__DATA__S3__READ_CHUNK_SIZE=4096 swift RALPH_BACKENDS__DATA__SWIFT__READ_CHUNK_SIZE=4096 </li> <li> <p>The <code>ralph push</code> command changed to <code>ralph write</code></p> </li> <li>The <code>-c --chunk-size</code> option changed to <code>-s --chunk-size</code></li> <li> <p>The <code>DEFAULT_BACKEND_CHUNK_SIZE</code> environment variable configuration is removed in     favor of allowing each backend to define their own defaults:</p> Backend Environment variable for default (write) chunk size async_es/es RALPH_BACKENDS__DATA__ES__WRITE_CHUNK_SIZE=500 async_lrs/lrs RALPH_BACKENDS__DATA__LRS__WRITE_CHUNK_SIZE=500 async_mongo/mongo RALPH_BACKENDS__DATA__MONGO__WRITE_CHUNK_SIZE=500 clickhouse RALPH_BACKENDS__DATA__CLICKHOUSE__WRITE_CHUNK_SIZE=500 fs RALPH_BACKENDS__DATA__FS__WRITE_CHUNK_SIZE=4096 ldp RALPH_BACKENDS__DATA__LDP__WRITE_CHUNK_SIZE=4096 s3 RALPH_BACKENDS__DATA__S3__WRITE_CHUNK_SIZE=4096 swift RALPH_BACKENDS__DATA__SWIFT__WRITE_CHUNK_SIZE=4096 </li> <li> <p>Environment variables used to configure backend options for CLI usage   (read/write/list commands) changed their prefix:   <code>RALPH_BACKENDS__{{DATABASE or HTTP or STORAGE or STREAM}}__{{BACKEND}}__{{OPTION}}</code>   changed to   <code>RALPH_BACKENDS__DATA__{{BACKEND}}__{{OPTION}}</code></p> </li> <li>Environment variables used to configure backend options for LRS usage   (runserver command) changed their prefix:   <code>RALPH_BACKENDS__{{DATABASE}}__{{BACKEND}}__{{OPTION}}</code>   changed to   <code>RALPH_BACKENDS__LRS__{{BACKEND}}__{{OPTION}}</code></li> </ul>"},{"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_ralph_library_usage_backends","title":"Upgrade Ralph library usage (backends)","text":"<p>If you use Ralph\u2019s backends in your application, the following changes might affect you:</p> <p>Backends from <code>ralph.backends.database</code>, <code>ralph.backends.http</code>, <code>ralph.backends.stream</code>, and <code>ralph.backends.storage</code> packages have moved to a single <code>ralph.backends.data</code> package.</p> Ralph v3 (database/http/storage/stream) backends Ralph v4 data backends <code>ralph.backends.database.clickhouse.ClickHouseDatabase</code> <code>ralph.backends.data.clickhouse.ClickHouseDataBackend</code> <code>ralph.backends.database.es.ESDatabase</code> <code>ralph.backends.data.es.ESDataBackend</code> <code>ralph.backends.database.mongo.MongoDatabase</code> <code>ralph.backends.data.mongo.MongoDataBackend</code> <code>ralph.backends.http.async_lrs.AsyncLRSHTTP</code> <code>ralph.backends.data.async_lrs.AsyncLRSDataBackend</code> <code>ralph.backends.http.lrs.LRSHTTP</code> <code>ralph.backends.data.lrs.LRSDataBackend</code> <code>ralph.backends.storage.fs.FSStorage</code> <code>ralph.backends.data.fs.FSDataBackend</code> <code>ralph.backends.storage.ldp.LDPStorage</code> <code>ralph.backends.data.ldp.LDPDataBackend</code> <code>ralph.backends.storage.s3.S3Storage</code> <code>ralph.backends.data.s3.S3DataBackend</code> <code>ralph.backends.storage.swift.SwiftStorage</code> <code>ralph.backends.data.swift.SwiftDataBackend</code> <code>ralph.backends.stream.ws.WSStream</code> <code>ralph.backends.data.async_ws.AsyncWSDataBackend</code> <p>LRS-specific <code>query_statements</code> and <code>query_statements_by_ids</code> database backend methods have moved to a dedicated <code>ralph.backends.lrs.BaseLRSBackend</code> interface that extends the data backend interface with these two methods.</p> <p>The <code>query_statements_by_ids</code> method return type changed to <code>Iterator[dict]</code>.</p> Ralph v3 database backends for lrs usage Ralph v4 LRS data backends <code>ralph.backends.database.clickhouse.ClickHouseDatabase</code> <code>ralph.backends.lrs.clickhouse.ClickHouseLRSBackend</code> <code>ralph.backends.database.es.ESDatabase</code> <code>ralph.backends.lrs.es.ESLRSBackend</code> <code>ralph.backends.database.mongo.MongoDatabase</code> <code>ralph.backends.lrs.mongo.MongoLRSBackend</code> <p>Backend interface differences</p> <ul> <li>Data backends are read-only by default</li> <li>Data backends that support write operations inherit from the   <code>ralph.backends.data.base.Writable</code> interface</li> <li>Data backends that support list operations inherit from the   <code>ralph.backends.data.base.Listable</code> interface</li> <li>Data backends that support LRS operations   (<code>query_statements</code>/<code>query_statements_by_ids</code>) inherit from the   <code>ralph.backends.lrs.BaseLRSBackend</code> interface</li> <li><code>__init__(self, **kwargs)</code> changed to <code>__init__(self, settings: DataBackendSettings)</code>   where each DataBackend defines it\u2019s own Settings object   For example the <code>FSDataBackend</code> uses <code>FSDataBackendSettings</code></li> <li><code>stream</code> and <code>get</code> methods changed to <code>read</code></li> <li><code>put</code> methods changed to <code>write</code></li> </ul> <p>Backend usage migration example</p> <p>Ralph v3 using <code>ESDatabase</code>:</p> <pre><code>from ralph.conf import ESClientOptions\nfrom ralph.backends.database.es import ESDatabase, ESQuery\n\n# Instantiate the backend.\nbackend = ESDatabase(\n  hosts=\"localhost\",\n  index=\"statements\"\n  client_options=ESClientOptions(verify_certs=False)\n)\n# Read records from backend.\nquery = ESQuery(query={\"query\": {\"term\": {\"modulo\": 0}}})\nes_statements = list(backend.get(query))\n\n# Write records to backend.\nbackend.put([{\"id\": 1}])\n</code></pre> <p>Ralph v4 using <code>ESDataBackend</code>:</p> <pre><code>from ralph.backends.data.es import (\n  ESClientOptions,\n  ESDataBackend,\n  ESDataBackendSettings,\n  ESQuery,\n)\n\n# Instantiate the backend.\nsettings = ESDataBackendSettings(\n  HOSTS=\"localhost\",\n  INDEX=\"statements\",\n  CLIENT_OPTIONS=ESClientOptions(verify_certs=False)\n)\nbackend = ESDataBackend(settings)\n\n# Read records from backend.\nquery = ESQuery(query={\"term\": {\"modulo\": 0}})\nes_statements = list(backend.read(query))\n\n# Write records to backend.\nbackend.write([{\"id\": 1}])\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  -t, --target TEXT               The target location where statements are\n                                  stored for the user.\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>main</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":"features/api/","title":"LRS HTTP server","text":"<p>Ralph implements the Learning Record Store (LRS) specification defined by ADL.</p> <p>Ralph LRS, based on FastAPI, has the following key features:</p> <ul> <li>Supports of multiple databases through different backends</li> <li>Secured with multiple authentication methods</li> <li>Supports multitenancy</li> <li>Enables the Total Learning Architecture with statements forwarding</li> <li>Monitored thanks to the Sentry integration</li> </ul>"},{"location":"features/api/#api_documentation","title":"API documentation","text":""},{"location":"features/api/#fastapi_010","title":"FastAPI 0.1.0","text":""},{"location":"features/api/#endpoints","title":"Endpoints","text":""},{"location":"features/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":"features/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\": \"dcdd0906-53b3-463e-99df-192b963a8f28\",\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":"features/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":"features/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":"features/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\": \"2f1e28e8-5663-4e4d-a1a2-a45463b4564a\",\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":"features/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":"features/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":"features/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":"features/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":"features/api/#schemas","title":"Schemas","text":""},{"location":"features/api/#basexapiaccount","title":"BaseXapiAccount","text":"Name Type <code>homePage</code> string <code>name</code> string"},{"location":"features/api/#basexapiagentwithaccount","title":"BaseXapiAgentWithAccount","text":"Name Type <code>account</code> BaseXapiAccount <code>name</code> string <code>objectType</code> string"},{"location":"features/api/#basexapiagentwithmbox","title":"BaseXapiAgentWithMbox","text":"Name Type <code>mbox</code> string <code>name</code> string <code>objectType</code> string"},{"location":"features/api/#basexapiagentwithmboxsha1sum","title":"BaseXapiAgentWithMboxSha1Sum","text":"Name Type <code>mbox_sha1sum</code> string <code>name</code> string <code>objectType</code> string"},{"location":"features/api/#basexapiagentwithopenid","title":"BaseXapiAgentWithOpenId","text":"Name Type <code>name</code> string <code>objectType</code> string <code>openid</code> string(uri)"},{"location":"features/api/#basexapianonymousgroup","title":"BaseXapiAnonymousGroup","text":"Name Type <code>member</code> Array&lt;&gt; <code>name</code> string <code>objectType</code> string"},{"location":"features/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":"features/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":"features/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":"features/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":"features/api/#errordetail","title":"ErrorDetail","text":"Name Type <code>detail</code> string"},{"location":"features/api/#httpvalidationerror","title":"HTTPValidationError","text":"Name Type <code>detail</code> Array&lt;ValidationError&gt;"},{"location":"features/api/#laxobjectfield","title":"LaxObjectField","text":"Name Type <code>id</code> string(uri)"},{"location":"features/api/#laxstatement","title":"LaxStatement","text":"Name Type <code>actor</code> <code>id</code> string(uuid) <code>object</code> LaxObjectField <code>verb</code> LaxVerbField"},{"location":"features/api/#laxverbfield","title":"LaxVerbField","text":"Name Type <code>id</code> string(uri)"},{"location":"features/api/#validationerror","title":"ValidationError","text":"Name Type <code>loc</code> Array&lt;&gt; <code>msg</code> string <code>type</code> string"},{"location":"features/api/#security_schemes","title":"Security schemes","text":"Name Type Scheme Description HTTPBasic http basic"},{"location":"features/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":"features/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__DATA__{{ backend_name | uppercase }}__{{ parameter | uppercase }}</code> for environment variables.</li> </ul>"},{"location":"features/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_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>READ_CHUNK_SIZE</code> <code>int</code> <p>The default chunk size for reading batches of documents.</p> <code>REFRESH_AFTER_WRITE</code> <code>str or bool</code> <p>Whether the Elasticsearch index should be refreshed after the write operation.</p> <code>WRITE_CHUNK_SIZE</code> <code>int</code> <p>The default chunk size for writing batches of documents.</p>"},{"location":"features/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>LOCALE_ENCODING</code> <code>str</code> <p>The locale encoding to use when none is provided.</p> <code>READ_CHUNK_SIZE</code> <code>int</code> <p>The default chunk size for reading batches of documents.</p> <code>WRITE_CHUNK_SIZE</code> <code>int</code> <p>The default chunk size for writing batches of documents.</p>"},{"location":"features/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>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>LOCALE_ENCODING</code> <code>str</code> <p>The locale encoding to use when none is provided.</p> <code>READ_CHUNK_SIZE</code> <code>int</code> <p>The default chunk size for reading.</p> <code>WRITE_CHUNK_SIZE</code> <code>int</code> <p>The default chunk size for writing.</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":"features/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>READ_CHUNK_SIZE</code> <code>str</code> <p>The default chunk size for reading archives.</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":"features/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>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> <code>READ_CHUNK_SIZE</code> <code>str</code> <p>The default chunk size for reading objects.</p> <code>WRITE_CHUNK_SIZE</code> <code>str</code> <p>The default chunk size for writing objects.</p>"},{"location":"features/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>LOCALE_ENCODING</code> <code>str</code> <p>The encoding used for writing dictionaries to objects.</p> <code>READ_CHUNK_SIZE</code> <code>str</code> <p>The default chunk size for reading objects.</p> <code>WRITE_CHUNK_SIZE</code> <code>str</code> <p>The default chunk size for writing objects.</p>"},{"location":"features/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_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> <code>READ_CHUNK_SIZE</code> <code>int</code> <p>The default chunk size for reading files.</p> <code>WRITE_CHUNK_SIZE</code> <code>int</code> <p>The default chunk size for writing files.</p>"},{"location":"features/backends/#learning_record_store_lrs","title":"Learning Record Store (LRS)","text":"<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 data 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>LOCALE_ENCODING</code> <code>str</code> <p>The encoding used for reading statements.</p> <code>READ_CHUNK_SIZE</code> <code>int</code> <p>The default chunk size for reading statements.</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> <code>WRITE_CHUNK_SIZE</code> <code>int</code> <p>The default chunk size for writing statements.</p>"},{"location":"features/backends/#websocket","title":"WebSocket","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 data backend default configuration.</p> <p>Attributes:</p> Name Type Description <code>CLIENT_OPTIONS</code> <code>dict</code> <p>A dictionary of valid options for the websocket client connection. See <code>WSClientOptions</code>.</p> <code>URI</code> <code>str</code> <p>The URI to connect to.</p> <p>Client options for <code>websockets.connection</code>.</p> <p>For mode details, see the websockets.connection documentation</p> <p>Attributes:</p> Name Type Description <code>close_timeout</code> <code>float</code> <p>Timeout for opening the connection in seconds.</p> <code>compression</code> <code>str</code> <p>Per-message compression (deflate) is activated by default. Setting it to <code>None</code> disables compression.</p> <code>max_size</code> <code>int</code> <p>Maximum size of incoming messages in bytes. Setting it to <code>None</code> disables the limit.</p> <code>max_queue</code> <code>int</code> <p>Maximum number of incoming messages in receive buffer. Setting it to <code>None</code> disables the limit.</p> <code>open_timeout</code> <code>float</code> <p>Timeout for opening the connection in seconds. Setting it to <code>None</code> disables the timeout.</p> <code>origin</code> <code>str</code> <p>Value of the <code>Origin</code> header, for servers that require it.</p> <code>ping_interval</code> <code>float</code> <p>Delay between keepalive pings in seconds. Setting it to <code>None</code> disables keepalive pings.</p> <code>ping_timeout</code> <code>float</code> <p>Timeout for keepalive pings in seconds. Setting it to <code>None</code> disables timeouts.</p> <code>read_limit</code> <code>int</code> <p>High-water mark of read buffer in bytes.</p> <code>user_agent_header</code> <code>str</code> <p>Value of  the <code>User-Agent</code> request header. It defaults to \u201cPython/x.y.z websockets/X.Y\u201d. Setting it to <code>None</code> removes the header.</p> <code>write_limit</code> <code>int</code> <p>High-water mark of write buffer in bytes.</p>"},{"location":"features/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":"features/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":"features/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":"features/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_guide/","title":"Development guide","text":"<p>Welcome to our developer contribution guidelines!</p> <p>You should know that we would be glad to help you contribute to Ralph! Here\u2019s our Discord to contact us easily.</p>"},{"location":"tutorials/development_guide/#preparation","title":"Preparation","text":"<p>Prerequisites</p> <p>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> <p>Info</p> <p>In this tutorial, and even more generally in others tutorials, we tend to use Elasticsearch backend. Note that you can do the same with another LRS backend implemented in Ralph.</p> <p>To start playing with <code>ralph</code>, you should first <code>bootstrap</code> using:</p> <pre><code>make bootstrap\n</code></pre> <p>When bootstrapping the project for the first time, the <code>env.dist</code> template file is copied to the <code>.env</code> file. You may want to edit the 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> <p>Default configuration in <code>.env</code> file</p> <p>Defaults are provided for some environment variables that you can use by uncommenting them.</p>"},{"location":"tutorials/development_guide/#backends","title":"Backends","text":"<p>Virtual memory for Elasticsearch</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>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>Once configured, start the database container using the following command, substituting <code>[BACKEND]</code> by the backend name (e.g. <code>es</code> for Elasticsearch):</p> <pre><code>make run-[BACKEND]\n</code></pre> <p>You can also start other services with the following commands: <pre><code>make run-es\nmake run-swift\nmake run-mongo\nmake run-clickhouse\n# Start all backends\nmake run-all\n</code></pre></p> <p>Now that you have started the <code>elasticsearch</code> and <code>swift</code> backends, it\u2019s time to play with them with Ralph CLI:</p> <p>We can store a JSON file in the Swift backend: <pre><code>echo '{\"id\": 1, \"foo\": \"bar\"}' | \\\n    ./bin/ralph write -b swift -t foo.json\n</code></pre></p> <p>We can check that we have created a new JSON file in the Swift backend: <pre><code>bin/ralph list -b swift\n&gt;&gt;&gt; foo.json\n</code></pre></p> <p>Let\u2019s read the content of the JSON file and index it in Elasticsearch <pre><code>bin/ralph read -b swift -t foo.json | \\\n    bin/ralph write -b es\n</code></pre></p> <p>We can now check that we have properly indexed the JSON file in Elasticsearch <pre><code>bin/ralph read -b es\n&gt;&gt;&gt; {\"id\": 1, \"foo\": \"bar\"}\n</code></pre></p>"},{"location":"tutorials/development_guide/#wip_lrs","title":"[WIP] LRS","text":""},{"location":"tutorials/development_guide/#tray","title":"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> <p>Prerequisites</p> <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_guide/#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_guide/#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 LRS 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_guide/#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_guide/#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>Let\u2019s also send some test statements:</p> <pre><code>gunzip -c data/statements.json.gz | \\\nhead -n 100 | \\\njq -s . | \\\ncurl -sLk \\\n  --user foo:bar \\\n  -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -d @- \\\n  \"https://$(\\\n      kubectl -n development-ralph \\\n      get \\\n      ingress/ralph-app-current \\\n      -o jsonpath='{.spec.rules[0].host}')/xAPI/statements/\"\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_guide/#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_guide/#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_guide/#after_your_development","title":"After your development","text":""},{"location":"tutorials/development_guide/#testing","title":"Testing","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_guide/#linting","title":"Linting","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_guide/#documentation","title":"Documentation","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/helm/","title":"Ralph Helm chart","text":"<p>Ralph LRS is distributed as a Helm chart in the DockerHub OCI openfuncharts.</p>"},{"location":"tutorials/helm/#setting_environment_values","title":"Setting environment values","text":"<p>All default values are in the <code>values.yaml</code> file. With Helm, you can extend the values file: there is no need to copy/paste all the default values. You can create an environment values file, e.g. <code>custom-values.yaml</code> and only set needed customizations.</p> <p>All sensitive environment values, needed for Ralph to work, are expected to be in an external Secret Kubernetes object. An example manifest is provided in the <code>ralph-env-secret.yaml</code> file here that you can adapt to fit your needs.</p> <p>All other non-sensitive environment values, also needed for Ralph to work, are expected to be in an external ConfigMap Kubernetes object. An example manifest is provided in the <code>ralph-env-cm.yaml</code> file here that you can adapt to fit your needs.</p>"},{"location":"tutorials/helm/#creating_authentication_secret","title":"Creating authentication secret","text":"<p>Ralph stores users credentials in an external Secret Kubernetes object. An example authentication file <code>auth-demo.json</code> is provided here, that you can take inspiration from. Refer to the LRS guide for creating user credentials.</p>"},{"location":"tutorials/helm/#reviewing_manifest","title":"Reviewing manifest","text":"<p>To generate and review your Helm generated manifest, under <code>./src/helm</code> run the following command:</p> <pre><code>helm template oci://registry-1.docker.io/openfuncharts/ralph\n</code></pre>"},{"location":"tutorials/helm/#installing_the_chart","title":"Installing the chart","text":"<p>Ralph Helm chart is distributed on DockerHub, and you can install it with: <pre><code>helm install RELEASE_NAME oci://registry-1.docker.io/openfuncharts/ralph\n</code></pre></p> <p>Tips:</p> <ul> <li>use <code>--values</code> to pass an env values file to extend and/or replace the default values</li> <li><code>--set var=value</code> to replace one var/value</li> <li><code>--dry-run</code> to verify your manifest before deploying</li> </ul>"},{"location":"tutorials/helm/#tutorial_deploying_ralph_lrs_on_a_local_cluster","title":"Tutorial: deploying Ralph LRS on a local cluster","text":"<p>This tutorial aims at deploying Ralph LRS on a local Kubernetes cluster using Helm. In this tutorial, you will learn to:</p> <ul> <li>run and configure a small Kubernetes cluster on your machine,</li> <li>deploy a data lake that stores learning records: we choose Elasticsearch,</li> <li>deploy Ralph LRS (Learning Records Store) that receives and sends learning records in   xAPI,</li> </ul>"},{"location":"tutorials/helm/#requirements","title":"Requirements","text":"<ul> <li><code>curl</code>, the CLI to make HTTP requests.</li> <li><code>jq</code>, the JSON data Swiss-Knife.</li> <li><code>kubectl</code>, the Kubernetes CLI.</li> <li><code>helm</code>, the package manager for Kubernetes.</li> <li><code>minikube</code>, a lightweight kubernetes   distribution to work locally on the project.</li> </ul>"},{"location":"tutorials/helm/#bootstrapping_a_local_cluster","title":"Bootstrapping a local cluster","text":"<p>Let\u2019s begin by running a local cluster with Minikube, where we will deploy Ralph on.</p> <pre><code># Start a local kubernetes cluster\nminikube start\n</code></pre> <p>We will now create our own Kubernetes namespace to work on:</p> <pre><code># This is our namespace\nexport K8S_NAMESPACE=\"learning-analytics\"\n\n# Check your namespace value\necho ${K8S_NAMESPACE}\n\n# Create the namespace\nkubectl create namespace ${K8S_NAMESPACE}\n\n# Activate the namespace\nkubectl config set-context --current --namespace=${K8S_NAMESPACE}\n</code></pre>"},{"location":"tutorials/helm/#deploying_the_data_lake_elasticsearch","title":"Deploying the data lake: Elasticsearch","text":"<p>In its recent releases, Elastic recommends deploying its services using Custom Resource Definitions (CRDs) installed via its official Helm chart. We will first install the Elasticsearch (ECK) operator cluster-wide:</p> <pre><code># Add elastic official helm charts repository\nhelm repo add elastic https://helm.elastic.co\n\n# Update available charts list\nhelm repo update\n\n# Install the ECK operator\nhelm install elastic-operator elastic/eck-operator -n elastic-system --create-namespace\n</code></pre> <p>Now that CRDs are already deployed cluster-wide, we can deploy an Elasticsearch cluster. To help you in this task, we provide an example manifest <code>data-lake.yml</code>, that deploy a two-nodes elasticsearch \u201ccluster\u201d. Adapt it to match your needs, then apply it with:</p> <pre><code>kubectl apply -f data-lake.yml\n</code></pre> <p>Once applied, your elasticsearch pod should be running. You can check this using the following command:</p> <pre><code>kubectl get pods -w\n</code></pre> <p>We expect to see two pods called <code>data-lake-es-default-0</code> and <code>data-lake-es-default-1</code>.</p> <p>When our Elasticsearch cluster is up (this can take few minutes), you may create the Elasticsearch index that will be used to store learning traces (xAPI statements):</p> <pre><code># Store elastic user password\nexport ELASTIC_PASSWORD=\"$(kubectl get secret data-lake-es-elastic-user -o jsonpath=\"{.data.elastic}\" | base64 -d)\"\n\n# Execute an index creation request in the elasticsearch container\nkubectl exec data-lake-es-default-0 --container elasticsearch -- \\\n    curl -ks -X PUT \"https://elastic:${ELASTIC_PASSWORD}@localhost:9200/statements?pretty\"\n</code></pre> <p>Our Elasticsearch cluster is all set. In the next section, we will now deploy Ralph, our LRS.</p>"},{"location":"tutorials/helm/#deploy_the_lrs_ralph","title":"Deploy the LRS: Ralph","text":"<p>First and foremost, we should create a Secret object containing the user credentials file. We provide an example authentication file <code>auth-demo.json</code> that you can take inspiration from. We can create a secret object directly from the file with the command:</p> <pre><code>kubectl create secret generic ralph-auth-secret \\\n    --from-file=auth.json=auth-demo.json\n</code></pre> <p>Secondly, we should create two objects containing environment values necessary for Ralph:</p> <ul> <li>a Secret containing sensitive environment variables such as passwords, tokens etc;</li> <li>a ConfigMap containing all other non-sensitive environment variables.</li> </ul> <p>We provide two example manifests (<code>ralph-env-secret.yaml</code> and <code>ralph-env-cm.yml</code>) that you can adapt to fit your needs. </p> <p>For this tutorial, we only need to replace the <code>&lt;PASSWORD&gt;</code> tag in the Secret manifest by the actual password of the <code>elastic</code> user with the command: <pre><code>sed -i -e \"s|&lt;PASSWORD&gt;|$ELASTIC_PASSWORD|g\" ralph-env-secret.yaml\n</code></pre></p> <p>We can now apply both manifests, to create a ConfigMap and a Secret object in our local cluster: <pre><code># Create Secret object\nkubectl apply -f ralph-env-secret.yaml\n\n# Create ConfigMap object\nkubectl apply -f ralph-env-cm.yaml\n</code></pre></p> <p>We can now deploy Ralph: <pre><code>helm install lrs oci://registry-1.docker.io/openfuncharts/ralph \\\n  --values development.yaml\n</code></pre></p> <p>One can check if the server is running by opening a network tunnel to the service using the <code>port-forward</code> sub-command:</p> <pre><code>kubectl port-forward svc/lrs-ralph 8080:8080\n</code></pre> <p>And then send a request to the server using this tunnel:</p> <pre><code>curl --user admin:password localhost:8080/whoami\n</code></pre> <p>We expect a valid JSON response stating about the user you are using for this request.</p> <p>If everything went well, we can send 22k xAPI statements to the LRS using:</p> <pre><code>gunzip -c ../../data/statements.jsonl.gz | \\\n  sed \"s/@timestamp/timestamp/g\" | \\\n  jq -s . | \\\n  curl -Lk \\\n    --user admin:password \\\n    -X POST \\\n    -H \"Content-Type: application/json\" \\\n    http://localhost:8080/xAPI/statements/ -d @-\n</code></pre> <p>Congrats \ud83c\udf89</p>"},{"location":"tutorials/helm/#go_further","title":"Go further","text":"<p>Now that the LRS is running, we can go further and deploy the dashboard suite Warren. Refer to the tutorial of the Warren Helm chart.</p>"},{"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>"},{"location":"tutorials/lrs/","title":"How to use Ralph LRS?","text":"<p>This tutorial shows you how to run Ralph LRS, step by step.</p> <p>Warning</p> <p>Ralph LRS will be executed locally for demonstration purpose. If you want to deploy Ralph LRS on a production server, please refer to the  deployment guide.</p> <p>Ralph LRS is based on FastAPI. In this tutorial, we will run the server manually with Uvicorn, but other alternatives exists (Hypercorn, Daphne).</p> <p>Prerequisites</p> <p>Some tools are required to run the commands of this tutorial. Make sure they are installed first:</p> <ul> <li>Ralph package with CLI optional dependencies, e.g. <code>pip install ralph-malph[cli]</code> (check the CLI tutorial)</li> <li>Docker Compose</li> <li>curl or httpie</li> </ul>"},{"location":"tutorials/lrs/backends/","title":"Backends","text":"<p>Ralph LRS is built to be used with a database instead of writing learning records in a local file.</p> <p>Ralph LRS supports the following databases:</p> <ul> <li>Elasticsearch</li> <li>Mongo</li> <li>ClickHouse</li> </ul> <p>Let\u2019s add the service of your choice to the <code>docker-compose.yml</code> file:</p> ElasticsearchMongoClickHouse docker-compose.yml<pre><code>version: \"3.9\"\n\nservices:\n  db:\n    image: elasticsearch:8.1.0\n    environment:\n      discovery.type: single-node\n      xpack.security.enabled: \"false\"\n    ports:\n      - \"9200:9200\"\n    mem_limit: 2g\n    ulimits:\n      memlock:\n        soft: -1\n        hard: -1\n    healthcheck:\n      test: curl --fail http://localhost:9200/_cluster/health?wait_for_status=green || exit 1\n      interval: 1s\n      retries: 60\n\n  lrs:\n    image: fundocker/ralph:latest\n    environment:\n      RALPH_APP_DIR: /app/.ralph\n      RALPH_RUNSERVER_BACKEND: es\n      RALPH_BACKENDS__LRS__ES__HOSTS: http://db:9200\n    ports:\n      - \"8100:8100\"\n    command:\n      - \"uvicorn\"\n      - \"ralph.api:app\"\n      - \"--proxy-headers\"\n      - \"--host\"\n      - \"0.0.0.0\"\n      - \"--port\"\n      - \"8100\"\n    volumes:\n      - .ralph:/app/.ralph\n</code></pre> <p>We can now start the database service and wait for it to be up and healthy: <pre><code>docker compose up -d --wait db\n</code></pre></p> <p>Before using Elasticsearch, we need to create an index, which we call <code>statements</code> for this example:</p> curlHTTPie <pre><code>curl -X PUT http://localhost:9200/statements\n</code></pre> <pre><code>http PUT :9200/statements\n</code></pre> <p>docker-compose.yml<pre><code>version: \"3.9\"\n\nservices:\n  db:\n    image: mongo:5.0.9\n    ports:\n      - \"27017:27017\"\n    healthcheck:\n      test: mongosh --eval 'db.runCommand(\"ping\").ok' localhost:27017/test --quiet\n      interval: 1s\n      retries: 60\n\n  lrs:\n    image: fundocker/ralph:latest\n    environment:\n      RALPH_APP_DIR: /app/.ralph\n      RALPH_RUNSERVER_BACKEND: mongo\n      RALPH_BACKENDS__LRS__MONGO__CONNECTION_URI: mongodb://db:27017\n    ports:\n      - \"8100:8100\"\n    command:\n      - \"uvicorn\"\n      - \"ralph.api:app\"\n      - \"--proxy-headers\"\n      - \"--host\"\n      - \"0.0.0.0\"\n      - \"--port\"\n      - \"8100\"\n    volumes:\n      - .ralph:/app/.ralph\n</code></pre> We can now start the database service and wait for it to be up and healthy: <pre><code>docker compose up -d --wait db\n</code></pre></p> <p>docker-compose.yml<pre><code>version: \"3.9\"\n\nservices:\n  db:\n    image: clickhouse/clickhouse-server:23.1.1.3077-alpine\n    environment:\n      CLICKHOUSE_DB: xapi\n      CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1\n    ports:\n      - 8123:8123\n      - 9000:9000\n    # ClickHouse needs to maintain a lot of open files, so they\n    # suggest running the container with increased limits:\n    # https://hub.docker.com/r/clickhouse/clickhouse-server/#!\n    ulimits:\n      nofile:\n        soft: 262144\n        hard: 262144\n    healthcheck:\n      test:  wget --no-verbose --tries=1 --spider http://localhost:8123/ping || exit 1\n      interval: 1s\n      retries: 60\n\n  lrs:\n    image: fundocker/ralph:latest\n    environment:\n      RALPH_APP_DIR: /app/.ralph\n      RALPH_RUNSERVER_BACKEND: clickhouse\n      RALPH_BACKENDS__LRS__CLICKHOUSE__HOST: db\n      RALPH_BACKENDS__LRS__CLICKHOUSE__PORT: 8123\n    ports:\n      - \"8100:8100\"\n    command:\n      - \"uvicorn\"\n      - \"ralph.api:app\"\n      - \"--proxy-headers\"\n      - \"--host\"\n      - \"0.0.0.0\"\n      - \"--port\"\n      - \"8100\"\n    volumes:\n      - .ralph:/app/.ralph\n</code></pre> We can now start the database service and wait for it to be up and healthy: <pre><code>docker compose up -d --wait db\n</code></pre></p> <p>Before using ClickHouse, we need to create a table in the <code>xapi</code> database, which we call <code>xapi_events_all</code>:</p> curlHTTPie <pre><code>  echo \"CREATE TABLE xapi.xapi_events_all (\n    event_id UUID NOT NULL,\n    emission_time DateTime64(6) NOT NULL,\n    event String NOT NULL\n    )\n    ENGINE MergeTree ORDER BY (emission_time, event_id)\n    PRIMARY KEY (emission_time, event_id)\" | \\\n  curl --data-binary @- \"http://localhost:8123/\"\n</code></pre> <pre><code>  echo \"CREATE TABLE xapi.xapi_events_all (\n    event_id UUID NOT NULL,\n    emission_time DateTime64(6) NOT NULL,\n    event String NOT NULL\n    )\n    ENGINE MergeTree ORDER BY (emission_time, event_id)\n    PRIMARY KEY (emission_time, event_id)\" | \\\n  http :8123\n</code></pre> <p>Then we can start Ralph LRS: <pre><code>docker compose up -d lrs\n</code></pre></p> <p>We can finally send some xAPI statements to Ralph LRS:</p> curlHTTPie <pre><code>curl -sL https://github.com/openfun/ralph/raw/master/data/statements.json.gz | \\\ngunzip | \\\nhead -n 100 | \\\njq -s . | \\\ncurl \\\n  --user janedoe:supersecret \\\n  -H \"Content-Type: application/json\" \\\n  -X POST \\\n  -d @- \\\n  \"http://localhost:8100/xAPI/statements\"\n</code></pre> <pre><code>curl -sL https://github.com/openfun/ralph/raw/master/data/statements.json.gz | \\\ngunzip | \\\nhead -n 100 | \\\njq -s . | \\\nhttp -a janedoe:supersecret POST :8100/xAPI/statements\n</code></pre> <p>And fetch, them back: </p> curlHTTPie <pre><code>curl \\\n  --user janedoe:supersecret \\\n  -X GET \\\n  \"http://localhost:8100/xAPI/statements\"\n</code></pre> <pre><code>http -a janedoe:supersecret :8100/xAPI/statements\n</code></pre>"},{"location":"tutorials/lrs/first-steps/","title":"First steps","text":"<p>Ralph LRS is distributed as a Docker image on DockerHub, following the format: <code>fundocker/ralph:&lt;release version | latest&gt;</code>.</p> <p>Let\u2019s dive straight in and create a <code>docker-compose.yml</code> file:</p> docker-compose.yml<pre><code>version: \"3.9\"\n\nservices:\n\n  lrs:\n    image: fundocker/ralph:latest\n    environment:\n      RALPH_APP_DIR: /app/.ralph\n      RALPH_RUNSERVER_BACKEND: fs\n    ports:\n      - \"8100:8100\"\n    command:\n      - \"uvicorn\"\n      - \"ralph.api:app\"\n      - \"--proxy-headers\"\n      - \"--workers\"\n      - \"1\"\n      - \"--host\"\n      - \"0.0.0.0\"\n      - \"--port\"\n      - \"8100\"\n    volumes:\n      - .ralph:/app/.ralph\n</code></pre> <p>For now, we are using the <code>fs</code> (File System) backend, meaning that Ralph LRS will store learning records in local files.</p> <p>First, we need to manually create the <code>.ralph</code> directory alongside the <code>docker-compose.yml</code> file with the command:</p> <pre><code>mkdir .ralph\n</code></pre> <p>We can then run Ralph LRS from a terminal with the command:</p> <pre><code>docker compose up -d lrs\n</code></pre> <p>Ralph LRS server should be up and running!</p> <p>We can request the <code>whoami</code> endpoint to check if the user is authenticated. On success, the endpoint returns the username and permission scopes.</p> curlHTTPie <p><pre><code>curl http://localhost:8100/whoami\n</code></pre> <pre><code>{\"detail\":\"Invalid authentication credentials\"}% \n</code></pre></p> <p><pre><code>http :8100/whoami\n</code></pre> <pre><code>HTTP/1.1 401 Unauthorized\ncontent-length: 47\ncontent-type: application/json\ndate: Mon, 06 Nov 2023 15:37:32 GMT\nserver: uvicorn\nwww-authenticate: Basic\n\n{\n    \"detail\": \"Invalid authentication credentials\"\n}\n</code></pre></p> <p>If you\u2019ve made it this far, congrats! \ud83c\udf89</p> <p>You\u2019ve successfully deployed the Ralph LRS and got a response to your request!</p> <p>Let\u2019s shutdown the Ralph LRS server with the command <code>docker compose down</code> and set up authentication.</p>"},{"location":"tutorials/lrs/forwarding/","title":"Forwarding to another LRS","text":"<p>Ralph LRS server can be configured to forward xAPI statements it receives to other LRSs. Statement forwarding enables the Total Learning Architecture and allows systems containing multiple LRS to share data.</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>Warning</p> <p>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> .env<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":"tutorials/lrs/multitenancy/","title":"Multitenancy","text":"<p>By default, all authenticated users have full read and write access to the server. Ralph LRS implements the specified Authority mechanism to restrict behavior.</p>"},{"location":"tutorials/lrs/multitenancy/#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 request. You may restrict read access to users \u201cown\u201d statements (thus enabling multitenancy) by setting the following environment variable: </p> .env<pre><code>RALPH_LRS_RESTRICT_BY_AUTHORITY=True # Default: False\n</code></pre> <p>Warning</p> <p>Two accounts with different credentials may share the same <code>authority</code>, meaning they can access the same statements. It is the administrator\u2019s responsibility to ensure that <code>authority</code> is properly assigned.</p> <p>Info</p> <p>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":"tutorials/lrs/multitenancy/#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> .env<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":"tutorials/lrs/sentry/","title":"Sentry","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> .env<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 the 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:</p> .env<pre><code>RALPH_SENTRY_CLI_TRACES_SAMPLE_RATE=0.1\nRALPH_SENTRY_LRS_TRACES_SAMPLE_RATE=0.3\n</code></pre> <p>Sample rate</p> <p>A sample 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> .env<pre><code>RALPH_SENTRY_IGNORE_HEALTH_CHECKS=True\n</code></pre>"},{"location":"tutorials/lrs/authentication/","title":"Authentication","text":"<p>The API server supports the following authentication methods:</p> <ul> <li>HTTP basic authentication</li> <li>OpenID Connect authentication on top of OAuth2.0</li> </ul> <p>Either one or both can be enabled for Ralph LRS using the environment variable <code>RALPH_RUNSERVER_AUTH_BACKENDS</code>:</p> <pre><code>RALPH_RUNSERVER_AUTH_BACKENDS=basic,oidc\n</code></pre>"},{"location":"tutorials/lrs/authentication/basic/","title":"HTTP Basic Authentication","text":"<p>The default method for securing the Ralph API server is HTTP Basic Authentication. For this, we need to create a user in Ralph LRS.</p>"},{"location":"tutorials/lrs/authentication/basic/#creating_user_credentials","title":"Creating user credentials","text":"<p>To create a new user credentials, Ralph CLI provides a dedicated command:</p> Ralph CLIDocker Compose <pre><code>ralph auth \\\n    --write-to-disk \\\n    --username janedoe \\\n    --password supersecret \\\n    --scope statements/write \\\n    --scope statements/read \\\n    --agent-ifi-mbox mailto:janedoe@example.com\n</code></pre> <pre><code>docker compose run --rm lrs \\\n  ralph auth \\\n    --write-to-disk \\\n    --username janedoe \\\n    --password supersecret \\\n    --scope statements/write \\\n    --scope statements/read \\\n    --agent-ifi-mbox mailto:janedoe@example.com\n</code></pre> <p>Tip</p> <p>You can either display the helper with <code>ralph auth --help</code> or check the CLI tutorial here</p> <p>This command updates your credentials file with the new <code>janedoe</code> user. Here is the file that has been created by the <code>ralph auth</code> command:</p> auth.json<pre><code>[                                                                               \n  {                                                                             \n    \"agent\": {                                                                  \n      \"mbox\": \"mailto:janedoe@example.com\",                                     \n      \"objectType\": \"Agent\",                                                    \n      \"name\": null                                                              \n    },                                                                          \n    \"scopes\": [                                                                 \n      \"statements/write\",                                                           \n      \"statements/read\"\n    ],                                                                          \n    \"hash\": \"$2b$12$eQmMF/7ALdNuksL4lkI.NuTibNjKLd0fw2Xe.FZqD0mNkgnnjLLPa\",     \n    \"username\": \"janedoe\"                                                       \n  }                                                                             \n] \n</code></pre> <p>Alternatively, the credentials file can also be created manually. It is expected to be a valid JSON file. Its location is specified by the <code>RALPH_AUTH_FILE</code> configuration value. </p> <p>Tip</p> <p>By default, Ralph LRS looks 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:</p> <ul> <li>the username</li> <li>the user\u2019s hashed+salted password</li> <li>the scopes they can access</li> <li>an <code>agent</code> object used to represent the user in the LRS. </li> </ul> <p>Info</p> <p>The <code>agent</code> is constrained by LRS specifications, and must use one of four valid Inverse Functional Identifiers.</p>"},{"location":"tutorials/lrs/authentication/basic/#making_a_get_request","title":"Making a GET request","text":"<p>After changing the <code>docker-compose.yml</code> file as follow: docker-compose.yml<pre><code>version: \"3.9\"\n\nservices:\n\n  lrs:\n    image: fundocker/ralph:latest\n    environment:\n      RALPH_APP_DIR: /app/.ralph\n      RALPH_RUNSERVER_BACKEND: fs\n      RALPH_RUNSERVER_AUTH_BACKENDS: basic\n    ports:\n      - \"8100:8100\"\n    command:\n      - \"uvicorn\"\n      - \"ralph.api:app\"\n      - \"--proxy-headers\"\n      - \"--workers\"\n      - \"1\"\n      - \"--host\"\n      - \"0.0.0.0\"\n      - \"--port\"\n      - \"8100\"\n    volumes:\n      - .ralph:/app/.ralph\n</code></pre> and running the Ralph LRS with:</p> <pre><code>docker compose up -d lrs\n</code></pre> <p>we can request the <code>whoami</code> endpoint again, but this time sending our username and password through Basic Auth:</p> curlHTTPie <p><pre><code>curl --user janedoe:supersecret http://localhost:8100/whoami\n</code></pre> <pre><code>{\"agent\":{\"mbox\":\"mailto:janedoe@example.com\",\"objectType\":\"Agent\",\"name\":null},\"scopes\":[\"statements/read\",\"statements/write\"]}\n</code></pre></p> <p><pre><code>http -a janedoe:supersecret :8100/whoami \n</code></pre> <pre><code>HTTP/1.1 200 OK\ncontent-length: 107\ncontent-type: application/json\ndate: Tue, 07 Nov 2023 17:32:31 GMT\nserver: uvicorn\n\n{\n    \"agent\": {\n        \"mbox\": \"mailto:janedoe@example.com\",\n        \"name\": null,\n        \"objectType\": \"Agent\"\n    },\n    \"scopes\": [\n        \"statements/read\",\n        \"statements/write\"\n    ]\n}\n</code></pre></p> <p>Congrats! \ud83c\udf89 You have been successfully authenticated!</p> <p>HTTP Basic auth caching</p> <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.</p> <p>To speed up requests, credentials are stored in an LRU cache with a \u201cTime To Live\u201d.</p> <p>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 \u201cTime To Live\u201d of the cache entries in seconds. Defaults to 3600s.</p> <pre><code>RALPH_AUTH_CACHE_TTL=3600\n</code></pre>"},{"location":"tutorials/lrs/authentication/oidc/","title":"OpenID Connect authentication","text":"<p>Ralph LRS also supports OpenID Connect on top of OAuth 2.0 for authentication and authorization.</p> <p>To enable OpenID Connect authentication mode, we should change the <code>RALPH_RUNSERVER_AUTH_BACKENDS</code> environment variable to <code>oidc</code> and we should define the <code>RALPH_RUNSERVER_AUTH_OIDC_ISSUER_URI</code> environment variable with the identity provider\u2019s Issuer Identifier URI as follows:</p> <pre><code>RALPH_RUNSERVER_AUTH_BACKENDS=oidc\nRALPH_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 OpenID Connect Discovery to retrieve public keys and other information about the OpenID Connect environment.</p> <p>It is also strongly recommended to set the optional <code>RALPH_RUNSERVER_AUTH_OIDC_AUDIENCE</code> environment variable to the origin address of Ralph LRS itself (e.g. \u201chttp://localhost:8100\u201d) to enable verification that a given token was issued specifically for that Ralph LRS.</p>"},{"location":"tutorials/lrs/authentication/oidc/#identity_providers","title":"Identity Providers","text":"<p>OpenID Connect support is currently developed and tested against Keycloak but may work with other identity providers that implement the specification.</p>"},{"location":"tutorials/lrs/authentication/oidc/#an_example_with_keycloak","title":"An example with Keycloak","text":"<p>The Learning analytics playground repository contains a Docker Compose file and configuration for a demonstration instance of Keycloak with a <code>ralph</code> client.</p> <p>First, we should stop the Ralph LRS server (if it\u2019s still running): <pre><code>docker compose down\n</code></pre></p> <p>We can clone the <code>learning-analytics-playground</code> repository: <pre><code>git clone git@github.com:openfun/learning-analytics-playground\n</code></pre></p> <p>And then bootstrap the project: <pre><code>cd learning-analytics-playground/\nmake bootstrap\n</code></pre></p> <p>After a couple of minutes, the playground containers should be up and running.</p> <p>Create another docker compose file, let\u2019s call it <code>docker-compose.oidc.yml</code>, with the following content: docker-compose.oidc.yml<pre><code>version: \"3.9\"\n\nservices:\n\n  lrs:\n    image: fundocker/ralph:latest\n    environment:\n      RALPH_APP_DIR: /app/.ralph\n      RALPH_RUNSERVER_AUTH_BACKENDS: oidc\n      RALPH_RUNSERVER_AUTH_OIDC_ISSUER_URI: http://learning-analytics-playground-keycloak-1:8080/auth/realms/fun-mooc\n      RALPH_RUNSERVER_BACKEND: fs\n    ports:\n      - \"8100:8100\"\n    command:\n      - \"uvicorn\"\n      - \"ralph.api:app\"\n      - \"--proxy-headers\"\n      - \"--workers\"\n      - \"1\"\n      - \"--host\"\n      - \"0.0.0.0\"\n      - \"--port\"\n      - \"8100\"\n    volumes:\n      - .ralph:/app/.ralph\n    networks:\n      - ralph\n\nnetworks:\n  ralph:\n    external: true\n</code></pre></p> <p>Again, we need to create the <code>.ralph</code> directory: <pre><code>mkdir .ralph\n</code></pre></p> <p>Then we can start the <code>lrs</code> service: <pre><code>docker compose -f docker-compose.oidc.yml up -d lrs\n</code></pre></p> <p>Now that both Keycloak and Ralph LRS server are up and running, we should be able to get the access token from Keycloak with the command:</p> curlHTTPie <pre><code>curl -X POST \\\n  -d \"grant_type=password\" \\\n  -d \"client_id=ralph\" \\\n  -d \"client_secret=bcef3562-730d-4575-9e39-63e185f99bca\" \\\n  -d \"username=ralph_admin\" \\\n  -d \"password=funfunfun\" \\\n  http://localhost:8080/auth/realms/fun-mooc/protocol/openid-connect/token\n</code></pre> <pre><code>{\"access_token\":\"&lt;access token content&gt;\",\"expires_in\":300,\"refresh_expires_in\":1800,\"refresh_token\":\"&lt;refresh token content&gt;\",\"token_type\":\"Bearer\",\"not-before-policy\":0,\"session_state\":\"0889b3a5-d742-45fb-98b3-20e967960e74\",\"scope\":\"email profile\"} \n</code></pre> <pre><code>http -f POST \\\n  :8080/auth/realms/fun-mooc/protocol/openid-connect/token \\\n  grant_type=password \\\n  client_id=ralph \\\n  client_secret=bcef3562-730d-4575-9e39-63e185f99bca \\\n  username=ralph_admin \\\n  password=funfunfun\n</code></pre> <pre><code>HTTP/1.1 200 OK\n...\n{\n    \"access_token\": \"&lt;access token content&gt;\",\n    \"expires_in\": 300,\n    \"not-before-policy\": 0,\n    \"refresh_expires_in\": 1800,\n    \"refresh_token\": \"&lt;refresh token content&gt;\",\n    \"scope\": \"email profile\",\n    \"session_state\": \"1e826fa2-b4b3-42bf-837f-158fe9d5e1e5\",\n    \"token_type\": \"Bearer\"\n}\n</code></pre> <p>With this access token, we can now make a request to the Ralph LRS server:</p> curlHTTPie <pre><code>curl -H 'Authorization: Bearer &lt;access token content&gt;' \\\nhttp://localhost:8100/whoami\n</code></pre> <pre><code>{\"agent\":{\"openid\":\"http://localhost:8080/auth/realms/fun-mooc/b6e85bd0-ce6e-4b24-9f0e-6e18d8744e54\"},\"scopes\":[\"email\",\"profile\"]}\n</code></pre> <pre><code>http -A bearer -a &lt;access token content&gt; :8100/whoami\n</code></pre> <pre><code>HTTP/1.1 200 OK\n...\n{\n    \"agent\": {\n        \"openid\": \"http://localhost:8080/auth/realms/fun-mooc/b6e85bd0-ce6e-4b24-9f0e-6e18d8744e54\"\n    },\n    \"scopes\": [\n        \"email\",\n        \"profile\"\n    ]\n}\n</code></pre> <p>Congrats, you\u2019ve managed to authenticate using OpenID Connect! \ud83c\udf89</p>"}]}
\ No newline at end of file
diff --git a/dev/sitemap.xml.gz b/dev/sitemap.xml.gz
index 8e31d21a3575ce3490062a64fae4c97f6c890e08..4811aee8d35fae4e2b6e42b6033c8c1cfb373909 100644
GIT binary patch
delta 16
XcmeBS?qOz^@8;kz<rdk<-pU979%ut{

delta 16
XcmeBS?qOz^@8;mRF-LeKdn+RVCO!nE