feat: provide openedx_learning djangoapp and CompetencyTaxonomy model

.importlinter

@@ -5,6 +5,7 @@
 
 [importlinter]
 root_packages =
+    openedx_learning
     openedx_content
     openedx_tagging
     openedx_django_lib
@@ -17,8 +18,12 @@ root_packages =
 name = "top-level source folders are layered correctly"
 type = layers
 layers =
-    # Content is currently the highest-level thing in this repo.
-    # Over time, we may add apps "above" or "below" this.
+    # Learning-domain features (currently CBE; Learning Pathways to follow).
+    # May build on content and tagging. Nothing below may import it: in
+    # particular, openedx_tagging must never know that CBE exists.
+    openedx_learning
+
+    # Content: authoring-side models and APIs.
     openedx_content
 
     # Tagging is very simple & fundamental. Should probably not depend on any other Django apps.

docs/openedx_learning/decisions/0004-competency-mastery-concurrency.rst

@@ -155,11 +155,11 @@ Rejected Alternatives
    with another writer already in flight.
 
     - Pros:
-      - Recovers from the race within the same request, without a separate marker or job.
+        - Recovers from the race within the same request, without a separate marker or job.
     - Cons:
-      - Decision 1 shares a transaction only between the grade and its leaf, and Decision 3 commits each rollup level
-        separately before reading the next. That leaves no single transaction boundary for a read-after-write check to
-        run inside: by the time a re-read would happen, the level below has already committed and could change again
-        before the write completes.
-      - It also only checks for a race at the moment each parent is read. If the worker crashes mid-cascade before reaching the next read,
-        nothing notices the rollup was left unfinished. Decision 5's manual recovery mechanism exists to catch that case.
+        - Decision 1 shares a transaction only between the grade and its leaf, and Decision 3 commits each rollup level
+          separately before reading the next. That leaves no single transaction boundary for a read-after-write check to
+          run inside: by the time a re-read would happen, the level below has already committed and could change again
+          before the write completes.
+        - It also only checks for a race at the moment each parent is read. If the worker crashes mid-cascade before reaching the next read,
+          nothing notices the rollup was left unfinished. Decision 5's manual recovery mechanism exists to catch that case.

docs/openedx_tagging/decisions/0013-competency-taxonomy-detection.rst

@@ -30,7 +30,7 @@ Decision
 
 Report a taxonomy's type entirely within **openedx-platform**, using the existing relation
 between ``Taxonomy`` and ``CompetencyTaxonomy`` established in ADR 0002, without adding any
-field, method, or enum value to ``openedx_tagging`` or the CBE app:
+field, method, or enum value to ``openedx_tagging``:
 
 .. image:: images/CompetencyTypeDetection.png
    :alt: Studio calls openedx-platform's serializer, which delegates to oel_tagging's pure
@@ -41,22 +41,29 @@ field, method, or enum value to ``openedx_tagging`` or the CBE app:
 - openedx-platform's REST layer adds a read-only ``taxonomy_type`` value to its taxonomy
   serializer, computed by checking whether a related ``CompetencyTaxonomy`` row exists for
   that ``Taxonomy``: ``"competency"`` if so, ``"tags"`` otherwise.
+- It performs that check through the CBE app's public API,
+  ``openedx_learning.api.is_competency_taxonomy()``, rather than naming the relation itself.
+  The relation name is a Django-generated default derived from the model's class name, so
+  spelling it in openedx-platform would let a rename upstream break Studio with nothing
+  failing in either repository's tests.
 - That same layer's queryset fetches the related ``CompetencyTaxonomy`` row alongside the
-  ``Taxonomy`` list, so the check costs no extra query per row.
-- ``openedx_tagging``'s ``Taxonomy`` model, its base ``TaxonomySerializer``, and the CBE app
-  stay fully unaware of each other for this purpose: no new field, no new enum value, no
-  import.
+  ``Taxonomy`` list, using the companion ``select_competency_taxonomies()``, so the check
+  costs no extra query per row.
+- ``openedx_tagging``'s ``Taxonomy`` model and its base ``TaxonomySerializer`` gain nothing
+  for this purpose: no new field, no new enum value, no import. That constraint is on
+  ``openedx_tagging`` alone. The CBE app owns this relation, so exposing it through the CBE
+  app's own public API is expected rather than avoided.
 - No creation-time wiring is needed to keep this accurate: ADR 0002 Decision 1 already
   creates the ``CompetencyTaxonomy`` row in the same transaction as its parent ``Taxonomy``
   row, so the existence check can never drift out of sync the way a separately-stored
   field could.
 
 **Known trade-off.** A future third taxonomy type needs another hardcoded branch in
 openedx-platform's shared serializer, the same cost a field-based approach would have
-avoided with a one-line enum addition. Accepted because keeping ``openedx_tagging`` and the
-CBE app free of any competency-specific reference, even an inert stored value, was judged
-more valuable than that extensibility, particularly given the project's move away from
-system-defined taxonomies, which makes a third taxonomy flavor unlikely soon.
+avoided with a one-line enum addition. Accepted because keeping ``openedx_tagging`` free of
+any competency-specific reference, even an inert stored value, was judged more valuable
+than that extensibility, particularly given the project's move away from system-defined
+taxonomies, which makes a third taxonomy flavor unlikely soon.
 
 Rejected Alternatives
 ----------------------
@@ -69,9 +76,8 @@ A ``TaxonomyType(models.TextChoices)`` field (``TAGS``/``COMPETENCY``) added dir
 transaction as ADR 0002 Decision 1's existing lifecycle rule. Although this requires no
 per-request check and was more extensible for a hypothetical third taxonomy flavor, it
 still named a CBE-specific concept, a ``COMPETENCY`` enum value, directly in
-``openedx_tagging``'s own schema and public API. Keeping ``openedx_tagging`` and the CBE
-app fully free of any competency-specific reference, even an inert one, is worth the lost
-extensibility.
+``openedx_tagging``'s own schema and public API. Keeping ``openedx_tagging`` fully free of
+any competency-specific reference, even an inert one, is worth the lost extensibility.
 
 Check for a related ``CompetencyTaxonomy`` row directly inside ``openedx_tagging``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

projects/dev.py

@@ -39,6 +39,7 @@
 
     # Our Apps
     "openedx_catalog",
+    "openedx_learning",
     "openedx_tagging",
     "openedx_content",
     *openedx_content_backcompat_apps_to_install(),

src/openedx_core/__init__.py

@@ -6,4 +6,4 @@
 """
 
 # The version for the entire repository
-__version__ = "1.2.0"
+__version__ = "1.3.0"

src/openedx_learning/README.rst

@@ -0,0 +1,11 @@
+Learning App
+============
+
+The ``openedx_learning`` app holds models and APIs for what learners are meant to achieve
+and how they get there. Its sibling ``openedx_content`` holds the material itself.
+
+Like ``openedx_content``, it is one Django app split into applets. Its first applet is
+``cbe``, for Competency-Based Education; Learning Pathways are expected to follow.
+
+In the layering that ``.importlinter`` enforces, this app sits above ``openedx_content``
+and ``openedx_tagging``. It may build on either of them; neither may import it.

src/openedx_learning/__init__.py

@@ -0,0 +1,3 @@
+"""
+Learning-domain features for Open edX Core.
+"""

src/openedx_learning/admin.py

@@ -0,0 +1,6 @@
+"""
+This module aggregates all applet Django Admin modules.
+"""
+# pylint: disable=wildcard-import
+
+from .applets.cbe.admin import *

src/openedx_learning/api.py

@@ -0,0 +1,6 @@
+"""
+This is the public API for learning-domain features in Open edX Core.
+"""
+# This wildcard import is okay because the applet api module declares __all__.
+# pylint: disable=wildcard-import
+from .applets.cbe.api import *

src/openedx_learning/applets/__init__.py

@@ -0,0 +1,3 @@
+"""
+The applets that make up the openedx_learning Django app.
+"""

src/openedx_learning/applets/cbe/README.rst

@@ -0,0 +1,21 @@
+Competency-Based Education Applet
+=================================
+
+The ``cbe`` applet models learner mastery of competencies. A competency is a tag; a
+competency taxonomy is a taxonomy whose tags are competencies rather than ordinary labels.
+
+``CompetencyTaxonomy`` marks a taxonomy as one of those. It is a Django multi-table
+inheritance subclass of ``openedx_tagging``'s ``Taxonomy``, so the two share a primary key:
+a competency taxonomy is the same taxonomy, not a copy of one. Creating one writes both
+rows in a single transaction, and deleting either row removes both.
+
+Ask whether a taxonomy is competency-enabled through ``openedx_learning.api``, not by
+reaching for ``taxonomy.competencytaxonomy``. ``is_competency_taxonomy()`` answers for one
+taxonomy; put a queryset through ``select_competency_taxonomies()`` first when checking a
+list, so the whole list costs one query instead of one per row. Keeping the check here is
+what lets ``openedx_tagging`` stay a generic tagging library that never learns CBE exists.
+
+The criteria, rule profile, and learner status tables this applet still needs are designed
+in ``docs/openedx_learning/decisions/``. ``openedx_tagging`` ADR 0013 covers how
+``openedx-platform`` calls ``is_competency_taxonomy()`` to report a taxonomy's type to
+Studio.

src/openedx_learning/applets/cbe/__init__.py

@@ -0,0 +1,3 @@
+"""
+The CBE (Competency-Based Education) applet.
+"""

src/openedx_learning/applets/cbe/admin.py

@@ -0,0 +1,21 @@
+"""
+Django Admin pages for CBE models.
+"""
+from django.contrib import admin
+
+from .models import CompetencyTaxonomy
+
+__all__ = [
+    "CompetencyTaxonomyAdmin",
+]
+
+
+class CompetencyTaxonomyAdmin(admin.ModelAdmin):
+    """
+    The CompetencyTaxonomy model admin.
+    """
+    list_display = ["name", "export_id", "enabled"]
+    list_filter = ["enabled"]
+
+
+admin.site.register(CompetencyTaxonomy, CompetencyTaxonomyAdmin)

src/openedx_learning/applets/cbe/api.py

@@ -0,0 +1,35 @@
+"""
+Public API for Competency-Based Education (CBE).
+"""
+from __future__ import annotations
+
+from django.db.models import QuerySet
+
+from openedx_tagging.models import Taxonomy
+
+__all__ = [
+    "is_competency_taxonomy",
+    "select_competency_taxonomies",
+]
+
+
+def is_competency_taxonomy(taxonomy: Taxonomy) -> bool:
+    """
+    Return True if ``taxonomy`` is competency-enabled, i.e. has a CompetencyTaxonomy row.
+
+    Costs one query per call unless ``taxonomy`` came from a queryset passed through
+    :func:`select_competency_taxonomies`. Returns False for an unsaved ``taxonomy``.
+    """
+    # "competencytaxonomy" is the accessor Django generates for the multi-table-inheritance
+    # link from Taxonomy to CompetencyTaxonomy.
+    return hasattr(taxonomy, "competencytaxonomy")
+
+
+def select_competency_taxonomies(taxonomies: QuerySet[Taxonomy]) -> QuerySet[Taxonomy]:
+    """
+    Return ``taxonomies`` with each CompetencyTaxonomy row joined in.
+
+    Pair this with :func:`is_competency_taxonomy` when checking more than one taxonomy,
+    so the check costs no additional query per row.
+    """
+    return taxonomies.select_related("competencytaxonomy")

src/openedx_learning/applets/cbe/models.py

@@ -0,0 +1,40 @@
+"""
+Models for Competency-Based Education (CBE).
+"""
+from openedx_tagging.models import Taxonomy
+
+__all__ = [
+    "CompetencyTaxonomy",
+]
+
+
+class CompetencyTaxonomy(Taxonomy):
+    """
+    Marks a Taxonomy as competency-enabled, so CBE features apply to its tags.
+
+    A taxonomy listed in this table:
+
+    - can be displayed in the competency criteria association view.
+    - can be displayed in the competency progress tracking views.
+    - can also be displayed in the existing generic taxonomy views.
+    - constrains its associated content objects to those supported for progress
+      tracking, and to ones that could logically be used to demonstrate mastery of
+      the competency (for example, associating both a course and one assignment
+      within that same course would be ambiguous).
+
+    A taxonomy *not* listed here:
+
+    - is only displayed in the existing generic taxonomy views.
+    - is not displayed in competency criteria association views.
+    - is not displayed in competency progress tracking views.
+    - has no competency-specific constraints on its associated content objects.
+
+    Creating a competency taxonomy creates both the parent ``Taxonomy`` row and this
+    row in one transaction; deleting either row removes both.
+
+    .. no_pii:
+    """
+
+    class Meta:
+        verbose_name = "Competency Taxonomy"
+        verbose_name_plural = "Competency Taxonomies"

src/openedx_learning/apps.py

@@ -0,0 +1,15 @@
+"""
+App Config for our umbrella openedx_learning app.
+"""
+from django.apps import AppConfig
+
+
+class LearningConfig(AppConfig):
+    """
+    Initialization for all applets must happen in here.
+    """
+
+    name = "openedx_learning"
+    verbose_name = "Open edX Core > Learning"
+    default_auto_field = "django.db.models.BigAutoField"
+    label = "openedx_learning"

src/openedx_learning/migrations/0001_initial.py

@@ -0,0 +1,27 @@
+# Generated by Django 5.2.16 on 2026-08-06 19:25
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        ('oel_tagging', '0020_tag_depth_and_lineage'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='CompetencyTaxonomy',
+            fields=[
+                ('taxonomy_ptr', models.OneToOneField(auto_created=True, on_delete=django.db.models.deletion.CASCADE, parent_link=True, primary_key=True, serialize=False, to='oel_tagging.taxonomy')),
+            ],
+            options={
+                'verbose_name': 'Competency Taxonomy',
+                'verbose_name_plural': 'Competency Taxonomies',
+            },
+            bases=('oel_tagging.taxonomy',),
+        ),
+    ]

src/openedx_learning/models.py

@@ -0,0 +1,7 @@
+"""
+This module aggregates all applet model modules.
+"""
+
+# pylint: disable=wildcard-import
+
+from .applets.cbe.models import *

src/openedx_learning/models_api.py

@@ -0,0 +1,9 @@
+"""
+Models that we want callers to extend or make foreign keys to.
+
+This is also the stable import point for the model class itself, for callers that
+need to create competency taxonomies directly.
+"""
+
+# pylint: disable=unused-import
+from .models import CompetencyTaxonomy

test_settings.py

@@ -58,6 +58,7 @@ def root(*args):
     "openedx_tagging",
     "openedx_content",
     "openedx_catalog",
+    "openedx_learning",
     *openedx_content_backcompat_apps_to_install(),
     # Apps with models that are only used for testing
     "tests.test_django_app",