Metadata-Version: 2.5
Name: ol-openedx-chat
Version: 0.7.1
Summary: An Open edX plugin to add Open Learning AI chat aside to xBlocks
Author: MIT Office of Digital Learning
License-Expression: BSD-3-Clause
License-File: LICENSE.txt
Keywords: Python,edx
Requires-Python: >=3.11
Requires-Dist: django>=5.2
Requires-Dist: djangorestframework>=3.16.0
Requires-Dist: edx-django-utils>=8.0.0
Requires-Dist: xblock
Description-Content-Type: text/x-rst

OL OpenedX Chat
###############

An xBlock aside to add MIT Open Learning chat into xBlocks.


Purpose
*******

MIT's AI chatbot for Open edX

Version Compatibility
======================

For this plugin's compatibility with Open edX, see the
`Open edX Release Compatibility table <../../docs#open-edx-release-compatibility>`_.

Setup
=====

For detailed installation instructions, please refer to the `plugin installation guide <../../docs#installation-guide>`_.

Installation required in:

* LMS
* Studio (CMS)

Configuration
=============

1. edx-platform configuration
-----------------------------

- Add the following configuration values to the config file in Open edX. For any release after Juniper, that config file is ``/edx/etc/lms.yml``. If you're using ``private.py``, add these values to ``lms/envs/private.py``. These should be added to the top level. **Ask a fellow developer for these values.**

  .. code-block::

    MIT_LEARN_AI_API_URL: <MIT_LEARN_AI_API_URL>
    MIT_LEARN_API_BASE_URL: <MIT_LEARN_API_BASE_URL>
    MIT_LEARN_SUMMARY_FLASHCARD_URL: <MIT_LEARN_SUMMARY_FLASHCARD_URL>

- For Tutor installations, these values can also be managed through a `custom Tutor plugin <https://docs.tutor.edly.io/tutorials/plugin.html#plugin-development-tutorial>`_.

2. Add database record
----------------------

- Create a record for the ``XBlockAsidesConfig`` model (LMS admin URL: ``/admin/lms_xblock/xblockasidesconfig/``).

- Create a record in the ``StudioConfig`` model (CMS admin URL: ``/admin/xblock_config/studioconfig/``).

3. In frontend-app-learning, Run the below in the shell inside the learning MFE folder:
---------------------------------------------------------------------------------------
This will download the smoot-design package and copy the pre-bundled JS file to a location loadable by OpenEdx.

.. code-block:: sh

   npm pack @mitodl/smoot-design@^6.17.0
   tar -xvzf mitodl-smoot-design*.tgz
   mkdir -p public/static/smoot-design
   cp package/dist/bundles/* public/static/smoot-design

4. Create env.config.jsx in the frontend-app-learning and add the below code:

The Unit is rendered inside an Iframe and we use postMessage to communicate between the Iframe and the parent window. The below code is used to initialize the remoteAiChatDrawer.

.. code-block:: js

   import { getConfig } from '@edx/frontend-platform';
   import { getAuthenticatedHttpClient } from '@edx/frontend-platform/auth';

   import(
      /* webpackIgnore: true */
   "/static/smoot-design/aiDrawerManager.es.js").then(module => {
      module.init({
         messageOrigin: getConfig().LMS_BASE_URL,
         transformBody: messages => ({ message: messages[messages.length - 1].content }),
         getTrackingClient: getAuthenticatedHttpClient,
      })
   })

   const config = {
   ...process.env,
   };

   export default config;

(Alternatively, you can import the drawer code from a CDN like kg.com/@mitodl/smoot-design@6.4.0/dist/bundles/remoteTutorDrawer.umd.js to skip Step 3. However, the steps outlined here are most similar to what we do in production.)

5. Start learning MFE by ``npm run dev``
----------------------------------------
6. In LMS, enable the ``ol_openedx_chat.ol_openedx_chat_enabled`` waffle flag at ``<LMS>/admin/waffle/flag/``
---------------------------------------------------------------------------------------------------------------
This will enable the ol_openedx_chat plugin for all courses. You can disable it and add a ``Waffle Flag Course Override`` at ``/admin/waffle_utils/waffleflagcourseoverridemodel/`` to enable it for a single course.

7. Set `FEATURES["ENABLE_OTHER_COURSE_SETTINGS"] = True` in your `cms/envs/private.py` and `lms/envs/private.py` files
----------------------------------------------------------------------------------------------------------------------
This enables "Other Course Settings" below.

8. Go to any course in CMS > Settings > Advanced Settings and add the below in "Other Course Settings"
-------------------------------------------------------------------------------------------------------
.. code-block::

   {"OL_OPENEDX_CHAT_VIDEO_BLOCK_ENABLED": true, "OL_OPENEDX_CHAT_PROBLEM_BLOCK_ENABLED": true}

* ``OL_OPENEDX_CHAT_VIDEO_BLOCK_ENABLED`` is used to enable/disable the VideoGPT for all videos.
* ``OL_OPENEDX_CHAT_PROBLEM_BLOCK_ENABLED`` is used to enable/disable the AI Chat for all problems.
* Once these settings are enabled, you will see a checkbox ``Enable AI Chat Assistant`` below problem and video blocks in the CMS course unit.

CMS View

.. image:: ol_openedx_chat/static/images/ai_chat_aside_cms_view.png

* You will also see a Chat Button titled "AskTIM about this video/problem" in the LMS. Now AI Chat/VideoGPT is enabled for all videos and problems.

LMS View with AskTIM button

.. image:: ol_openedx_chat/static/images/ai_chat_aside_lms_view.png

LMS Chat Drawer View

.. image:: ol_openedx_chat/static/images/ai_chat_aside_lms_drawer_view.png

9. Disable it for a single block
----------------------------------
If you want to disable it for a few videos/problems then you disable the ``Enable AI Chat Assistant`` checkbox against the block in CMS.

Contact us launcher flag
========================

The Contact us launcher rendered by the MFE footer is gated on the
``ol_openedx_chat.contact_us_enabled`` course waffle flag, read over
``/ol-openedx-chat/api/contact-us-enabled/`` (optionally with a course key
appended). The endpoint is unauthenticated and returns ``{"enabled": <bool>}``.

* Site-wide: the flag's ``everyone`` value. The endpoint declares no
  authentication classes, so DRF resolves the caller to ``AnonymousUser`` and
  writes that back onto the Django request that crum hands to
  ``CourseWaffleFlag``. ``superusers``, ``staff`` and ``authenticated`` therefore
  never match, even for a signed-in superuser. The caller-independent fields
  waffle falls through to — ``testing``, ``languages`` and ``percent`` — are still
  evaluated, so a stray ``percent`` or ``languages`` value turns the launcher on
  for everyone. ``waffle_flag --create`` leaves every field unset, which reads as
  off; set ``everyone`` explicitly rather than relying on that.
* Per course: add a ``WaffleFlagCourseOverrideModel`` row in Django admin. Course
  overrides beat org overrides, which beat the site-wide value.
* To remove an override, add a new row with ``enabled`` unchecked. These are
  ``ConfigurationModel`` records, so Django admin offers no delete action.

On deployments managed by ol-infrastructure, ``everyone`` is owned by Pulumi:
``set_waffle_flags.py`` runs as a pre-deploy job on **every** edxapp rollout and
re-applies ``edxapp:waffle_flags``, resetting ``everyone`` and the other flag
fields it parses. Flipping the flag in Django admin takes effect immediately but
is reverted by the next deploy, including an unrelated one. For an immediate
kill, flip it in admin and then open a Pulumi PR to make it stick. Course
override rows are not touched by that job, so they are the durable per-course
lever.

Clients treat anything other than an explicit ``true`` as off, so an unreachable
LMS hides the launcher rather than showing it.

Translations
============

Only **Ask TIM** is not translated (brand). All other user-facing strings are
translatable.

Translations live in the translations repo (e.g. https://github.com/mitodl/mitxonline-translations) at
``translations/open-edx-plugins/ol_openedx_chat/conf/locale/``. For any
language, run ``sync_and_translate_language`` to create or update the .po
files there; then run ``make pull_translations`` in edx-platform to pull and
compile them into ``conf/plugins-locale/plugins/ol_openedx_chat/``. Until
``make pull_translations`` is run, the UI shows English (msgid fallback).

Why no ``conf/locale/config.yaml`` or Makefile (unlike edx-bulk-grades)?
------------------------------------------------------------------------

Plugins like `edx-bulk-grades
<https://github.com/openedx/edx-bulk-grades/tree/master/bulk_grades/conf/locale>`_
use ``conf/locale/config.yaml`` and a Makefile (extract_translations,
compile_translations, pull_translations) because *that plugin repo* is the
source for Transifex/Atlas. For ol_openedx_chat we use a different flow: the
*translations repo* holds the .po files; ``sync_and_translate_language`` syncs
and translates there, and edx-platform's ``make pull_translations`` pulls into
``conf/plugins-locale/plugins/ol_openedx_chat/``. This plugin repo never runs
Atlas or Transifex, so ``config.yaml`` and a Makefile here would be unused.

Documentation
=============

License
*******

The code in this repository is licensed under the AGPL 3.0 unless
otherwise noted.

Please see `LICENSE.txt <LICENSE.txt>`_ for details.
