feat(tool-picker): implement scoring-based tool recommendation

- Implement scoring-based recommendation logic comparing user and tool answers
- Select best matching tool per submission
- Add user submission mutation to capture user answers
- Add test cases for submission and recommendation flow
- Add type hints for related managers to fix static typing issues

Author: sudip-khanal

apps/resources/migrations/0001_initial.py

@@ -1,4 +1,4 @@
-# Generated by Django 5.2.9 on 2026-01-08 06:17
+# Generated by Django 5.2.9 on 2026-02-02 08:15
 
 import django.db.models.deletion
 from django.conf import settings

apps/tool_picker/admin.py

@@ -330,20 +330,31 @@ def recommendation_count(self, obj: UserSubmission):
         return obj.results.count()
 
 
+@admin.register(CheckboxOption)
+class CheckboxOptionAdmin(admin.ModelAdmin):
+    search_fields = ["id"]
+
+
 @admin.register(UserAnswer)
 class UserAnswerAdmin(admin.ModelAdmin):  # type: ignore[reportMissingTypeArgument]
     list_display = ["submission_id", "question", "question_type", "get_answer"]
     list_filter = ["submission__catalog", "question__question_type"]
-    search_fields = ["submission__id", "question__title"]
+    search_fields = ["submission__id", "question__title", "selected_options__id"]
+    autocomplete_fields = ("selected_options",)
+    readonly_fields = ("selected_options",)
+
+    @typing.override
+    def get_queryset(self, request):  # type: ignore[reportMissingTypeArgument]
+        return super().get_queryset(request).prefetch_related("selected_options")
 
     def get_fields(self, request, obj=None):  # type: ignore[reportMissingTypeArgument]
         """Show only relevant fields based on question type."""
         base_fields = ["submission", "question"]
 
-        if obj and obj.question.question_type == "ordinal":
+        if obj and obj.question.question_type == QuestionTypeEnum.ORDINAL.value:
             return [*base_fields, "ordinal_value"]
 
-        if obj and obj.question.question_type == "checkbox":
+        if obj and obj.question.question_type == QuestionTypeEnum.CHECKBOX.value:
             return [*base_fields, "selected_options"]
 
         return [*base_fields, "ordinal_value", "selected_options"]
@@ -366,7 +377,7 @@ def question_type(self, obj: UserAnswer):
 
     @admin.display(description="Answer")
     def get_answer(self, obj: UserAnswer):
-        if obj.question.question_type == "ordinal":
+        if obj.question.question_type == QuestionTypeEnum.ORDINAL:
             return obj.ordinal_value or "-"
         options = obj.selected_options.all()
         return ", ".join([opt.text for opt in options]) if options else "(none)"

apps/tool_picker/factories.py

@@ -1,22 +1,82 @@
-from factory.declarations import SubFactory
+from factory.declarations import Sequence, SubFactory
 from factory.django import DjangoModelFactory
 
-from apps.tool_picker.models import Catalog, Tool
+from apps.tool_picker.models import (
+    Catalog,
+    CheckboxOption,
+    Question,
+    Tool,
+    ToolAnswer,
+)
 from apps.user.factories import UserFactory
 
 
 class CatalogFactory(DjangoModelFactory[Catalog]):
-    class Meta:  # type: ignore[misc]
+    class Meta:  # type: ignore[reportMissingTypeArgument]
         model = Catalog
 
+    name = Sequence(lambda n: f"Catalog {n}")
+    description = "Catalog description"
+    show_in_help_me_choose = False
+
+    created_by = SubFactory(UserFactory)
+    modified_by = SubFactory(UserFactory)
+
+
+class QuestionFactory(DjangoModelFactory[Question]):
+    class Meta:  # type: ignore[reportMissingTypeArgument]
+        model = Question
+
+    catalog = SubFactory(CatalogFactory)
+
+    title = Sequence(lambda n: f"Question {n}")
+    short_name = Sequence(lambda n: f"question_{n}")
+    description = "Question description"
+    order = Sequence(lambda n: n + 1)
+
+    # Ordinal labels
+    label_na = "N/A"
+    label_1 = "1"
+    label_2 = "2"
+    label_3 = "3"
+    label_4 = "4"
+
+    created_by = SubFactory(UserFactory)
+    modified_by = SubFactory(UserFactory)
+
+
+class CheckboxOptionFactory(DjangoModelFactory[CheckboxOption]):
+    class Meta:  # type: ignore[reportMissingTypeArgument]
+        model = CheckboxOption
+
+    text = Sequence(lambda n: f"Option {n}")
+    order = Sequence(lambda n: n + 1)
+
     created_by = SubFactory(UserFactory)
     modified_by = SubFactory(UserFactory)
 
 
 class ToolFactory(DjangoModelFactory[Tool]):
-    class Meta:  # type: ignore[misc]
+    class Meta:  # type: ignore[reportMissingTypeArgument]
         model = Tool
 
     catalog = SubFactory(CatalogFactory)
+
+    name = Sequence(lambda n: f"Tool {n}")
+    tagline = Sequence(lambda n: f"Tagline {n}")
+    description = "Tool description"
+
+    video_link = None
+    tool_link = None
+    logo = None
+
+    created_by = SubFactory(UserFactory)
+    modified_by = SubFactory(UserFactory)
+
+
+class ToolAnswerFactory(DjangoModelFactory[ToolAnswer]):
+    class Meta:  # type: ignore[reportMissingTypeArgument]
+        model = ToolAnswer
+
     created_by = SubFactory(UserFactory)
     modified_by = SubFactory(UserFactory)

apps/tool_picker/graphql/filters.py

@@ -1,7 +1,7 @@
 import strawberry
 import strawberry_django
 
-from apps.tool_picker.models import Catalog, Tool
+from apps.tool_picker.models import Catalog, RecommendationResult, Tool, UserSubmission
 
 
 @strawberry_django.filters.filter(Catalog, lookups=True)
@@ -14,3 +14,14 @@ class CatalogFilter:
 class ToolFilter:
     id: strawberry.ID | None
     catalog_id: strawberry.auto
+
+
+@strawberry_django.filters.filter(UserSubmission, lookups=True)
+class UserSubmissionFilter:
+    id: strawberry.ID | None = strawberry.UNSET
+
+
+@strawberry_django.filters.filter(RecommendationResult, lookups=True)
+class RecommendationResultFilter:
+    id: strawberry.ID | None = strawberry.UNSET
+    submission: UserSubmissionFilter | None = strawberry.UNSET

apps/tool_picker/graphql/inputs.py

@@ -0,0 +1,14 @@
+import strawberry
+
+
+@strawberry.input
+class UserAnswerInput:
+    question: strawberry.ID
+    ordinal_value: int | None = strawberry.UNSET
+    selected_options: list[strawberry.ID] | None = strawberry.UNSET
+
+
+@strawberry.input
+class UserSubmissionInput:
+    catalog: strawberry.ID
+    answers: list[UserAnswerInput]

apps/tool_picker/graphql/mutations.py

@@ -0,0 +1,24 @@
+import strawberry
+import strawberry_django
+
+from apps.tool_picker.graphql.inputs import UserSubmissionInput
+from apps.tool_picker.graphql.types import UserSubmissionType
+from apps.tool_picker.serializers import UserSubmissionSerializer
+from main.graphql.context import Info
+from utils.graphql.mutations import ModelMutation
+from utils.graphql.types import MutationResponseType
+
+
+@strawberry.type
+class Mutation:
+    @strawberry_django.mutation
+    async def create_user_submission(
+        self,
+        info: Info,
+        data: UserSubmissionInput,
+    ) -> MutationResponseType[UserSubmissionType]:
+        return await ModelMutation(UserSubmissionSerializer).handle_create_mutation(
+            data,
+            info,
+            None,
+        )

apps/tool_picker/graphql/orders.py

@@ -1,7 +1,7 @@
 import strawberry
 import strawberry_django
 
-from apps.tool_picker.models import Catalog, Tool
+from apps.tool_picker.models import Catalog, RecommendationResult, Tool
 
 
 @strawberry_django.order_type(Catalog)
@@ -12,3 +12,9 @@ class CatalogOrder:
 @strawberry_django.order_type(Tool)
 class ToolOrder:
     id: strawberry.auto
+
+
+@strawberry_django.order_type(RecommendationResult)
+class RecommendationResultOrder:
+    id: strawberry.auto
+    rank: strawberry.auto

apps/tool_picker/graphql/queries.py

@@ -2,9 +2,9 @@
 import strawberry_django
 from strawberry_django.pagination import OffsetPaginated
 
-from .filters import CatalogFilter, ToolFilter
-from .orders import CatalogOrder, ToolOrder
-from .types import CatalogType, ToolType
+from .filters import CatalogFilter, RecommendationResultFilter, ToolFilter
+from .orders import CatalogOrder, RecommendationResultOrder, ToolOrder
+from .types import CatalogType, RecommendationResultType, ToolType
 
 
 @strawberry.type
@@ -22,3 +22,9 @@ class Query:
     )
 
     tool: ToolType = strawberry_django.field()
+
+    recommendation_results: OffsetPaginated[RecommendationResultType] = strawberry_django.offset_paginated(
+        filters=RecommendationResultFilter,
+        order=RecommendationResultOrder,
+    )
+    recommendation_result: RecommendationResultType = strawberry_django.field()

apps/tool_picker/graphql/types.py

@@ -5,6 +5,7 @@
     Catalog,
     CheckboxOption,
     Question,
+    RecommendationResult,
     Tool,
     ToolAnswer,
 )
@@ -65,3 +66,18 @@ class ToolType:
     tool_link: strawberry.auto
     logo: DjangoFileType | None
     answers: list[ToolAnswerType]
+
+
+@strawberry.type
+class UserSubmissionType:
+    id: strawberry.ID
+    catalog_id: strawberry.ID
+
+
+@strawberry_django.type(RecommendationResult)
+class RecommendationResultType:
+    id: strawberry.auto
+    submission: strawberry.auto
+    rank: strawberry.auto
+    score: strawberry.auto
+    tool: ToolType

apps/tool_picker/migrations/0001_initial.py

@@ -1,4 +1,4 @@
-# Generated by Django 5.2.9 on 2026-01-08 06:17
+# Generated by Django 5.2.9 on 2026-02-02 08:15
 
 import apps.tool_picker.models
 import django.core.validators
@@ -26,6 +26,7 @@ class Migration(migrations.Migration):
                 ('modified_at', models.DateTimeField(auto_now=True)),
                 ('name', models.CharField(max_length=200)),
                 ('description', models.TextField()),
+                ('show_in_help_me_choose', models.BooleanField(default=False)),
                 ('created_by', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='%(class)s_created', to=settings.AUTH_USER_MODEL)),
                 ('modified_by', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='%(class)s_modified', to=settings.AUTH_USER_MODEL)),
             ],
@@ -135,7 +136,7 @@ class Migration(migrations.Migration):
                 ('created_at', models.DateTimeField(auto_now_add=True)),
                 ('modified_at', models.DateTimeField(auto_now=True)),
                 ('description', models.TextField()),
-                ('ordinal_value', django_choices_field.fields.IntegerChoicesField(blank=True, choices=[(10, 'n/a'), (11, '1'), (12, '2'), (13, '3'), (14, '4')], choices_enum=apps.tool_picker.models.OrdinalTypeEnum, null=True)),
+                ('ordinal_value', django_choices_field.fields.IntegerChoicesField(blank=True, choices=[(100, 'n/a'), (1, 'One'), (2, 'Two'), (3, 'Three'), (4, 'Four')], choices_enum=apps.tool_picker.models.OrdinalTypeEnum, null=True)),
                 ('created_by', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='%(class)s_created', to=settings.AUTH_USER_MODEL)),
                 ('modified_by', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='%(class)s_modified', to=settings.AUTH_USER_MODEL)),
                 ('question', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='tool_answers', to='tool_picker.question')),
@@ -154,7 +155,7 @@ class Migration(migrations.Migration):
             name='UserAnswer',
             fields=[
                 ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
-                ('ordinal_value', django_choices_field.fields.IntegerChoicesField(blank=True, choices=[(10, 'n/a'), (11, '1'), (12, '2'), (13, '3'), (14, '4')], choices_enum=apps.tool_picker.models.OrdinalTypeEnum, null=True)),
+                ('ordinal_value', django_choices_field.fields.IntegerChoicesField(blank=True, choices=[(100, 'n/a'), (1, 'One'), (2, 'Two'), (3, 'Three'), (4, 'Four')], choices_enum=apps.tool_picker.models.OrdinalTypeEnum, null=True)),
                 ('question', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='user_answers', to='tool_picker.question')),
                 ('selected_options', models.ManyToManyField(blank=True, related_name='user_answers', to='tool_picker.checkboxoption')),
                 ('submission', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='answers', to='tool_picker.usersubmission')),