[math4] Quiz/Question API Proposal

[Enimihil]

Hello all,

This is my first post so I guess I should introduce myself a bit.  I'm
Greg S., one of the RIT students in the class working on the Math4
goals, and something that I've mentioned might be a good idea a few
times now is a shared library/API for quiz questions/drilling so that
activity developers can leverage content and easily use questions
written in a variety of formats, from a variety of sources.

Inline below is a simple outline of a proposal for an API along those
lines, with a few notes on implementation at the end.  Just trying to
propose something to save and/or centralize some common work that
needs to be done for a variety of activities.

=================================
Sugar Quiz API Preliminary Design
=================================

Motivation
==========

In the RIT class working on the Math4 projects, many proposed activities
require a question database of some kind.  A common API or library for
accessing databases in different formats, stored either locally or remotely,
along with a simple mechanism to determine more complex formatting or
presentation than simple text (e.g. to include simple graphics or
mathematical notation) would cover a majority of the cases where the
activity needs some configurable "curriculum data".

Eventually this library could be extended to provide hints, explanations, or
walkthroughs for questions, in addition to the basic metadata about level,
grouping, difficulty, and subject matter that would be part of the base
system.

Envisioned Usage
================

Consider a simple flash-card-like activity.  It presents a question from a
list of questions, allows the student to select an answer from the provided
answers for the question or to enter their own answer.  Then the correct
answer is revealed and the student it told whether their answer is correct.
If the question has an explanation of the correct answer, the flash-card
activity will show the explanation of the correct answer.  (Note that this
is just a simple usage example, the interaction design of a drilling
activity could be markedly different.)

The flash-card activity would use this proposed Quiz API for the following:

   - Loading the questions from the storage location into memory. This
     includes any filtering or network lookup to download the questions
     from a remote resource and select appropriate questions for the
     student.

   - Determining whether the student has entered a correct answer.

   - Rendering the question to a simple widget/canvas. (i.e. pass the
     library a GtkCanvas or similar and tell it to display the question)

To start with, the library would simply be a time-saving tool for developers
needing similar functionality, but as the XS (School Server) becomes more
fully developed the library should integrate the functions provided by the
XS to enable automated update of course material for the current topic of
study so the students can drill material using any tool they prefer, while
still reporting progress to the instructor using the XS services.

Proposed API
============

The Quiz API would be a python library, to act mostly as glue between
various file formats (and local or remote resources) for question data and
the Gtk graphical environment, providing a simple way to consistently
present and layout questions.

   :quizdata.open(uri, [cache=False]):
       Opens a URI, returning a list of quizdata.Question instances.  A
       standard method of filtering question data based on parameters
       should be specified.  Examples of URIs that might be used::

           http://xs-server/math4class/current_topic?level=4&difficulty=hard&format=moodle

           file:///var/lib/mathquestions/quiz1?level=4&difficulty=hard&format=xml

           xmpp://teacheraccount@xs.server/classname?difficulty=hard&level=4

       The cache parameter would locally save the retrieved questions to a
       persistent storage so requests from the same URI (with cache=True)
       would read from the cache.

   :class quizdata.Question:
       This class contains individual data for a question:
           - The question text
           - The style of answer (incl. multiple-choice, numeric, free
             response, etc.)
           - The correct answer (or if the question is subjective, that
             there *is* no correct answer).
           - Question difficulty
           - Grade level
           - Tags (for free-form grouping by topic, course, instructor,
             etc.)

       The question text and answers should support at least minimal
       markup, like that supported by pango, in addition to markup
       rendering with MathML/LaTeX syntax.

       .. note::
           The attributes listed above will should grow standardized names
           and be documented as part of the interface to the Question
           class, to allow for fine-grained for activity controlled
           rendering of the Question, if the simple show() call is not
           appropriate.

       :Question.show(surface, x, y, [width=-1, [height=-1]]):
           Draw the question to the drawing surface at coordinates (x,y)
           limited to the optionally specified width/height.

           This also should set up the appropriate input widgets for the
           type of question (multiple-choice/free-response) and handle the
           vents for those widgets.

       :Question.answered():
           Returns True if the student has provided an answer for the
           Question.

       :Question.submitted():
           Returns True if the student has submitted an answer for the
           Question.

       :Question.correct():
           Returns True if the currently selected answer is correct for the
           Question.

       :Question.answer():
           Returns the answer the student has currently selected, or None
           if no answer has been entered.

       :Question.clear():
           Removes the widgets and drawings that show() set up, preparing
           the surface to receive the next question or other widgets.


Implementation Issues
======================

The implementation of this (deceptively simple) library will take some
effort, in that it will be closely tied to the windowing/graphical toolkit,
PyGtk/Cairo/Pango rather directly, due to the high level of abstraction.
Additionally the URI lookup and question filtering based on parameters will
be necessary, as will interpreter the various format parsers necessary to
build the Question objects.

For MathML support, the GtkMathView widget will need to be available, so a
certain amount of effort may be involved in packaging the library in a
simple way for activity developers.

Next Steps
==========

Firstly, this API is being proposed and posted to the Math4 mailing list for
feedback and changes before any commitments to this interface is decided.
For any activity developers who are currently working on an activity that
could take advantage of such a system, or who have written similar
functionality in an activity, your input on usage and the naturalness of the
API.

Secondly, anyone who is interested in doing work on this library or using
the library in their activity should chime in, along with the expected usage
or how you can contribute.

Greg S.
--
Email is packaged by intellectual weight, not volume. Some settling of
contents may have occurred during transmission.