Metadata-Version: 2.1
Name: ai-aside
Version: 3.7.0
Summary: A plugin containing xblocks and apps supporting GPT and other LLM use on edX.
Home-page: https://github.com/openedx/ai-aside
Author: edX
Author-email: ashultz@edx.org
License: AGPL 3.0
Keywords: Python edx
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django
Classifier: Framework :: Django :: 3.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Requires-Python: >=3.8
License-File: LICENSE.txt
Requires-Dist: Django
Requires-Dist: djangorestframework
Requires-Dist: edx-drf-extensions
Requires-Dist: edx-opaque-keys
Requires-Dist: edx_django_utils
Requires-Dist: xblock

ai-aside
#############################

|pypi-badge| |ci-badge| |codecov-badge| |doc-badge| |pyversions-badge|
|license-badge| |status-badge|

Purpose
*******

This plugin holds LLM related blocks and tools, initially the summary XBlock aside but eventually more options.

Getting Started
***************

Developing
==========

One Time Setup
--------------
.. code-block::

  # Clone the repository
  git clone git@github.com:openedx/ai-aside.git
  cd ai-aside

  # Set up a virtualenv using virtualenvwrapper with the same name as the repo and activate it
  mkvirtualenv -p python3.8 ai-aside

Local testing
~~~~~~~~~~~~~
To test your changes locally, you will need to install the package from your local branch into edx-platform. For example, if using devstack, copy or clone your branch into <devstack-parent>/src/ai-aside. Bring up the LMS and CMS containers in devstack, and run this make target in the ai-aside directory::

  make install-local

You should see it uninstall any existing ai-aside in and install your local source, for both the CMS and LMS.

The plug-in configuration will automatically be picked up once installed. Changes will be hot reloaded after the next LMS or CMS restart.

If you would like to manually install ai-aside, go to your lms or cms shell and run::

  pip install -e /edx/src/ai-aside


Run Migrations
..............
You will also need to run migrations for local testing. Using the same lms or cms shell as before, run::

  ./manage.py lms migrate ai_aside


Testing in Docker with AI-spot
..............................

If you are running both devstack and a local instance of the supporting ai-spot in docker, you need two pieces of special setup to let ai-spot call the aside handler and retrieve content.

The first is to connect ai-spot to the devstack network with a docker command::

  docker network connect devstack_default ai-spot-server-1

The second is to change the handler URLs generated by ai-aside to a URL that is accessible by ai-spot in the same docker. This is already set up for you in ``summaryhook_aside/settings/devstack.py``. If your AI service is running locally outside of docker, you will need to change that setting.


Enabling the Aside
~~~~~~~~~~~~~~~~~~

For the summary aside to work, you will have to make two changes in the LMS admin:

1. You must create an ``XBlockAsidesConfig`` (admin URL: `/admin/lms_xblock/xblockasidesconfig/`). This model has a list of blocks you do not want asides to apply to that can be left alone, and an enabled setting that unsurprisingly should be True.

2. You must enable a course waffle flag for each course you want to summarize. ``summaryhook.summaryhook_enabled`` is the main one, ``summaryhook_enabled.summaryhook_staff_only`` can be used if you only want staff to see it.

3. You must enable a course waffle flag if you want to use the feature for enabling/disabling the summary by its settings. ``summaryhook.summaryhook_summaries_configuration``. If this flag is enabled, you can enable/disable the courses and the blocks by its settings.

Aside Settings API
~~~~~~~~~~~~~~~~~~

There are some endpoints that can be used to pinpoint units to be either enabled or disabled based on their configs. The new settings work as follows:
- If a course is enabled, the summary for all the blocks for that course are enabled by default.
- If a course is disabled or the setting does not exists, then the summary for all the blocks from that course are disabled by default.
- If a block has its own settings, it will override any other setting with the one that is saved.
- If a block does not have any settings saved, then the enabled state will fall back to the course's enabled state mentioned above.

The new endpoints for updating these settings are:

Fetch settings
..............

+--------+-------------------------------------+-------------------------------------------------------------------+
| Method | Path                                | Responses                                                         |
+========+=====================================+===================================================================+
| GET    | ``ai_aside/v1/:course_id``          | - Code 200: ``{ "success": true }``                               |
+--------+-------------------------------------+ - Code 400: ``{ "success": false, "message": "(description)" }``  |
| GET    | ``ai_aside/v1/:course_id/:unit_id`` | - Code 404: ``{ "success": false }``                              |
+--------+-------------------------------------+-------------------------------------------------------------------+

Update settings
...............

+--------+-------------------------------------+-------------------------------+------------------------------------------------------------------+
| Method | Path                                | Payload                       | Responses                                                        |
+========+=====================================+===============================+==================================================================+
| POST   | ``ai_aside/v1/:course_id``          | ``{ "enabled": true|false }`` | - Code 200: ``{ "success": true }``                              |
+--------+-------------------------------------+-------------------------------+ - Code 400: ``{ "success": false, "message": "(description)" }`` |
| POST   | ``ai_aside/v1/:course_id/:unit_id`` | ``{ "enabled": true|false }`` |                                                                  |
+--------+-------------------------------------+-------------------------------+------------------------------------------------------------------+

Delete settings
...............

+--------+-------------------------------------+-------------------------------------------------------------------+
| Method | Path                                | Responses                                                         |
+========+=====================================+===================================================================+
| DELETE | ``ai_aside/v1/:course_id``          | - Code 200: ``{ "success": true }``                               |
+--------+-------------------------------------+ - Code 400: ``{ "success": false, "message": "(description)" }``  |
| DELETE | ``ai_aside/v1/:course_id/:unit_id`` | - Code 404: ``{ "success": false }``                              |
+--------+-------------------------------------+-------------------------------------------------------------------+

Every time you develop something in this repo
---------------------------------------------
.. code-block::

  # Activate the virtualenv
  workon ai-aside

  # Grab the latest code
  git checkout main
  git pull

  # Install/update the dev requirements
  make requirements

  # Run the tests and quality checks (to verify the status before you make any changes)
  make validate

  # Make a new branch for your changes
  git checkout -b <your_github_username>/<short_description>

  # Using your favorite editor, edit the code to make your change.
  vim ...

  # Run your new tests
  pytest ./path/to/new/tests

  # Run all the tests and quality checks
  make validate

  # Commit all your changes
  git commit ...
  git push

  # Open a PR and ask for review.

Deploying
=========

This plugin is deployed on edx.org via EDXAPP_EXTRA_REQUIREMENTS.

License
*******

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

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

Contributing
************

Contributions are very welcome.
Please read `How To Contribute <https://openedx.org/r/how-to-contribute>`_ for details.

This project is currently accepting all types of contributions, bug fixes,
security fixes, maintenance work, or new features.  However, please make sure
to have a discussion about your new feature idea with the maintainers prior to
beginning development to maximize the chances of your change being accepted.
You can start a conversation by creating a new issue on this repo summarizing
your idea.

The Open edX Code of Conduct
****************************

All community members are expected to follow the `Open edX Code of Conduct`_.

.. _Open edX Code of Conduct: https://openedx.org/code-of-conduct/

People
******

The assigned maintainers for this component and other project details may be
found in `Backstage`_. Backstage pulls this data from the ``catalog-info.yaml``
file in this repo.

.. _Backstage: https://open-edx-backstage.herokuapp.com/catalog/default/component/ai-aside

Reporting Security Issues
*************************

Please do not report security issues in public. Please email security@tcril.org.

.. |pypi-badge| image:: https://img.shields.io/pypi/v/ai-aside.svg
    :target: https://pypi.python.org/pypi/ai-aside/
    :alt: PyPI

.. |ci-badge| image:: https://github.com/openedx/ai-aside/workflows/Python%20CI/badge.svg?branch=main
    :target: https://github.com/openedx/ai-aside/actions
    :alt: CI

.. |codecov-badge| image:: https://codecov.io/github/openedx/ai-aside/coverage.svg?branch=main
    :target: https://codecov.io/github/openedx/ai-aside?branch=main
    :alt: Codecov

.. |doc-badge| image:: https://readthedocs.org/projects/ai-aside/badge/?version=latest
    :target: https://docs.openedx.org/projects/ai-aside
    :alt: Documentation

.. |pyversions-badge| image:: https://img.shields.io/pypi/pyversions/ai-aside.svg
    :target: https://pypi.python.org/pypi/ai-aside/
    :alt: Supported Python versions

.. |license-badge| image:: https://img.shields.io/github/license/openedx/ai-aside.svg
    :target: https://github.com/openedx/ai-aside/blob/main/LICENSE.txt
    :alt: License

.. TODO: Choose one of the statuses below and remove the other status-badge lines.
.. |status-badge| image:: https://img.shields.io/badge/Status-Experimental-yellow
.. .. |status-badge| image:: https://img.shields.io/badge/Status-Maintained-brightgreen
.. .. |status-badge| image:: https://img.shields.io/badge/Status-Deprecated-orange
.. .. |status-badge| image:: https://img.shields.io/badge/Status-Unsupported-red


Change Log
##########

..
   All enhancements and patches to ai_aside will be documented
   in this file.  It adheres to the structure of https://keepachangelog.com/ ,
   but in reStructuredText instead of Markdown (for ease of incorporation into
   Sphinx documentation and the PyPI description).

   This project adheres to Semantic Versioning (https://semver.org/).

.. There should always be an "Unreleased" section for changes pending release.

Unreleased
**********

3.6.2 — 2023-10-12
**********************************************

* Handle rare blocks missing dates when calculating last updated
* Remove log of expected "not here" exception during config

3.6.1 — 2023-10-10
**********************************************

* Resolve scenario where a user has no associated enrollment value

3.6.0 – 2023-10-05
**********************************************

* Include user role in summary hook HTML.
* Add make install-local target for easy devstack installation.

3.5.0 – 2023-09-04
**********************************************

* Add edx-drf-extensions lib.
* Add JwtAuthentication checks before each request.
* Add SessionAuthentication checks before each request.
* Add HasStudioWriteAccess permissions checks before each request.


3.4.0 – 2023-08-30
**********************************************

* Include last updated timestamp in summary hook HTML, derived from the blocks.
* Also somewhat reformats timestamps in the handler return to conform to ISO standard.


3.3.1 – 2023-08-21
**********************************************

* Remove no longer needed first waffle flag summaryhook_enabled

3.3.0 – 2023-08-16
**********************************************

Features
=========
* Add xpert summaries configuration by default for units

3.2.0 – 2023-07-26
**********************************************

Features
=========
* Added the checks for the module settings behind the waffle flag `summaryhook.summaryhook_summaries_configuration`.
* Added is this course configurable endpoint
* Error suppression logs now include block ID
* Missing video transcript is caught earlier in content fetch

3.1.0 – 2023-07-20
**********************************************

Features
=========

* Added API endpoints for updating settings for courses and modules (enable/disable for now) (Has migrations)

3.0.1 – 2023-07-20
**********************************************

* Add positive log when summary fragement decides to inject

3.0.0 – 2023-07-16
**********************************************

Features
=========
* Summary content handler now requires a staff user identity, otherwise returns 403. This is a breaking change.
* Added models to summaryhook_aside (Has migrations)
* Catch exceptions in a couple of locations so the aside cannot crash content.

2.0.2 – 2023-07-05
**********************************************

Fix
=====

* Updated HTML parser to remove tags with their content for specific cases like `<script>` or `<style>`.


2.0.1 – 2023-06-29
**********************************************

Fix
=====

* Fix transcript format request and conversion


2.0.0 – 2023-06-28
**********************************************

Added
=====

* Adds a handler endpoint to provide summarizable content
* Improves content length checking using that summarizable content


1.2.1 – 2023-05-19
**********************************************

Fixes
=====

* Fix summary-aside settings package

1.2.0 – 2023-05-11
**********************************************

Added
=====

* Porting over summary-aside from edx-arch-experiments version 1.2.0
