Тести й критерії через API

Ця сторінка — для платформ шкіл, які готують курс запитами до API, без програми автора. Якщо ви працюєте в програмі автора, вам потрібна сторінка Тести.

Як створити тест

Файлом. У програмі автора завантажте YAML-файл (.yaml чи .yml) у потрібний розділ курсу, як будь-який матеріал, і оберіть тип завдання «Тест». Система не обробляє такий файл, як лекцію: вона одразу перевіряє його й створює тест із чернеткою; сам файл не зберігається. Якщо у файлі помилка формату, тест не створюється, а відмова називає її місце (див. Коли тест відмовлено). Незавершений тест створюється — його можна дописати пізніше (див. Незавершена чернетка).

У програмі автора тест починають кнопкою «Новий тест» і правлять у редакторі тесту. Запити до API нижче — довідка для платформ, які працюють із тестами без програми автора: ключ доступу вашої школи з правом підготовки курсу (сфера PREP) — у заголовку X-API-Key, $NODE_ID — розділ курсу, $TEST_ID — тест.

Те саме завантаження запитом — вид джерела (source_type) обов'язковий, але для тесту не важить:

curl -X POST https://api.pythoncourse.me/api/v1/nodes/$NODE_ID/documents \
     -H "X-API-Key: $PREP_KEY" \
     -F source_type=text -F task_type=test -F file=@lecture-3-test.yaml

Запитом. Тіло — YAML (Content-Type: application/yaml) або та сама структура в JSON (application/json); назва (title) тут обов'язкова:

curl -X POST https://api.pythoncourse.me/api/v1/nodes/$NODE_ID/tests \
     -H "X-API-Key: $PREP_KEY" -H "Content-Type: application/yaml" \
     --data-binary @lecture-3-test.yaml

Відповідь 201 — тест: id (це й є $TEST_ID), title, draft — питання з номерами, варіанти з літерами й позначками — і published: null, а поруч — поля, описані в Що показує читання чернетки. Завантаження файлом теж повертає id тесту.

Чернетка й публікація

Прочитати чернетку — з літерами варіантів і позначками — і чинну версію:

curl https://api.pythoncourse.me/api/v1/tests/$TEST_ID/draft -H "X-API-Key: $PREP_KEY"

published — чинна версія: number (номер за порядком), version (позначка того, що бачить студент) і published_at; до першої публікації — null. Решту полів — що лишилось завершити, що знайшла перевірка, чи є неопубліковані зміни — описано в Що показує читання чернетки.

Замінити чернетку — цілком, YAML чи JSON, як при створенні:

curl -X PUT https://api.pythoncourse.me/api/v1/tests/$TEST_ID/draft \
     -H "X-API-Key: $PREP_KEY" -H "Content-Type: application/yaml" \
     --data-binary @lecture-3-test.yaml

Чернетка з помилкою формату не зберігається — лишається попередня; незавершена зберігається така, як є (див. Незавершена чернетка). title у новій чернетці перейменовує тест одразу, без публікації; без title назва лишається та сама. Решту правок студенти не бачать, поки ви не опублікуєте чернетку. Перед публікацією її можна перевірити (див. Перевірити чернетку).

curl -X POST https://api.pythoncourse.me/api/v1/tests/$TEST_ID/publish -H "X-API-Key: $PREP_KEY"

Відповідь 201 — опубліковано нову версію; 200 — чернетка така сама, як чинна версія, і нічого не змінилося. Нова версія одразу стає тією, яку бачать і складають студенти. Пояснення мовою курсу до нових питань, варіантів чи позначок система пише під час перевірки чернетки, а якщо чернетку не перевіряли, — після публікації; публікація перевіреної чернетки бере їх готовими й нічого не доплачує (див. Пояснення).

422 TEST_DRAFT_INCOMPLETE — чернетку не завершено; нічого не опубліковано.

409 GENERATION_IN_PROGRESS — система саме пише пояснення до цього тесту; з публікації нічого не збережено. Зачекайте, доки вона закінчить, і опублікуйте ще раз.

Незавершена чернетка

Тест можна писати частинами: чернетка зберігається й без питань, з питанням без варіантів чи з одним, без позначки correct: true, з порожнім текстом питання чи варіанта. Перевірити й опублікувати можна лише завершену чернетку — незавершеній обидві дії відмовляють кодом TEST_DRAFT_INCOMPLETE, і нічого не змінюється.

Що лишилось завершити, читання чернетки показує в полі incomplete — у тому порядку, у якому ви читаєте тест: текст питання, тексти варіантів, скільки варіантів, чи позначено правильний. Кожне місце — код, номер питання (question) і номер варіанта (option), рахуючи з 1; чого місце не стосується, те null. Порожній перелік — чернетку завершено.

"incomplete": [
  {"code": "TEST_TEXT_EMPTY", "question": 1, "option": 2},
  {"code": "TEST_NO_CORRECT_OPTION", "question": 3, "option": null}
]

код	місце	що не так	що зробити
TEST_NO_QUESTIONS	тест	питань немає	додайте питання
TEST_TEXT_EMPTY	питання, а коли задано option, — варіант	порожній текст	напишіть текст
TEST_OPTIONS_COUNT	питання	менше двох варіантів	додайте варіанти
TEST_NO_CORRECT_OPTION	питання з варіантами	жоден варіант не позначено correct: true	позначте правильні варіанти

Перевірити чернетку

Перевірка показує ще до публікації, що система напише до тесту: пояснення до кожного питання мовою курсу й сумніви у ваших позначках (див. Сумнів). Перевірка нічого не публікує: студенти нічого з неї не бачать.

curl -X POST https://api.pythoncourse.me/api/v1/tests/$TEST_ID/check -H "X-API-Key: $PREP_KEY"

Відповідь 200 — стан перевірки: state, explanations і doubts, як у полі check читання чернетки (див. Що показує читання чернетки). in_progress — система пише пояснення; коли допише, читання чернетки покаже ready. ready — пояснення до цих самих питань, варіантів і позначок уже написано, і вони вже у відповіді.

Скільки це коштує:

• Чернетка, до якої пояснень ще немає — нова чи змінена в питаннях, варіантах чи позначках, — одне написання пояснень: стільки ж коштувала б її публікація без перевірки.
• Незмінена чернетка, уже перевірена чи опублікована, — нічого: система віддає те, що вже написала. Повторний запит, поки перевірка йде, теж нічого не коштує.
• Публікація перевіреної чернетки нічого не доплачує, навіть поки перевірка ще йде: нова версія бере пояснення, які написала чи пише перевірка.
• Поріг заліку й ваші власні пояснення перевірки не скидають: змінивши лише їх, перевіряти знову не треба, і публікація теж нічого не доплатить.

Якщо перевірка не вдалася (failed у читанні чернетки), перевірте ще раз — система спробує заново. Публікувати без перевірки теж можна: тоді пояснення система напише після публікації.

422 TEST_DRAFT_INCOMPLETE — чернетку не завершено; нічого не перевірено. 409 GENERATION_IN_PROGRESS — система саме пише інші пояснення до цього тесту; нічого не збережено — перевірте ще раз, коли вона закінчить.

Що показує читання чернетки

Читання чернетки — як і відповідь створення й заміни — несе, крім самої чернетки (draft) і чинної версії (published):

• incomplete — що лишилось завершити (див. Незавершена чернетка); порожній перелік — чернетку завершено.
• check — що знайшла перевірка чернетки такої, як вона є: state — стан перевірки (таблиця нижче), explanations — пояснення системи за номерами питань, doubts — питання, у позначках яких система сумнівається, наприклад {"2": true} (див. Сумнів). Доки стан не ready, explanations і doubts порожні. Ваші власні пояснення — у самій чернетці, окремо від пояснень системи.
• unpublished_changes — чи дасть публікація нову версію: true, коли чернетка відрізняється від чинної версії питаннями, варіантами, позначками, порогом, вашими поясненнями чи мовою курсу, і до першої публікації. Нова назва змін не додає: її видно одразу.
• course_root_id — курс, у якому стоїть тест.

check.state	що означає
not_checked	чернетку не перевіряли, змінили в питаннях, варіантах чи позначках після перевірки або ще не завершили
in_progress	система пише пояснення
ready	пояснення й сумніви написано
failed	пояснення написати не вдалося — перевірте ще раз

Наприклад, так виглядають ці поля перевіреної, але ще не опублікованої чернетки:

{
  "incomplete": [],
  "check": {"state": "ready", "explanations": {"1": "…", "2": "…"}, "doubts": {"2": true}},
  "unpublished_changes": true,
  "course_root_id": "…"
}

Читання нічого не замовляє й нічого не коштує.

Пояснення

Пояснення до кожного питання система пише мовою курсу — один раз для тих самих питань, варіантів і позначок: коли ви перевіряєте чернетку (див. Перевірити чернетку), а якщо не перевіряли, — після публікації, що змінила питання, варіанти чи позначки. Стан пояснень чинної версії:

curl https://api.pythoncourse.me/api/v1/documents/$TEST_ID/reference -H "X-API-Key: $PREP_KEY"

Відповідь несе status: awaiting_key — тест ще не опубліковано, generating — пояснення пишуться, ready — усе готово, failed — пояснення написати не вдалося (причину названо в failure_reason; щоб спробувати знову, опублікуйте тест ще раз). Поруч — answers (літери правильних варіантів чинної версії), pass_threshold, explanations (ваші власні й ті, що написала система) і doubts (див. Сумнів). Що знайшла перевірка ще не опублікованої чернетки, цей запит не показує — це показує читання чернетки (check, див. Що показує читання чернетки).

Вивантажити тест у YAML

curl https://api.pythoncourse.me/api/v1/tests/$TEST_ID/yaml -H "X-API-Key: $PREP_KEY" -o lecture-3-test.yaml

Відповідь — чернетка разом із назвою у форматі YAML, з полями в тому самому порядку, що й у прикладі на сторінці Тести. Цей файл можна виправити й завантажити назад заміною чернетки. Вивантаження несе правильні відповіді, тож його віддають лише ключем вашої школи з правом підготовки курсу; студент і платформа школи його не отримують.

Приховати тест

Приховайте тест кнопкою «Приховати тест» — у редакторі тесту чи в рядку тесту в дереві курсу — або запитом DELETE /api/v1/documents/$TEST_ID. Тест зникає з курсу для студентів. Уже зроблені спроби й рецензії на них система зберігає, але через курс студент до них більше не дістанеться.

Роль тесту змінити не можна: тест — завжди навчальний матеріал. Методичного матеріалу студенти не бачать, тож тест тихо зник би з курсу; такий запит відмовляє кодом TEST_OBJECT_ROLE_FIXED.

Коли тест відмовлено

Відмова несе в полі detail код причини й пояснення, а відмова формату — ще й місце: {"code": "…", "details": "…", "place": {…}}. place називає рядок і стовпчик у YAML (line, column) і номер питання й варіанта (question, option), рахуючи з 1; чого немає — null. Відмова незавершеної чернетки замість місця несе перелік incomplete (див. TEST_DRAFT_INCOMPLETE). Нічого з відмовленого запиту не зберігається: ні тесту, ні зміни чернетки, ні нової версії.

TEST_YAML_UNREADABLE

422. YAML (чи JSON) не читається — синтаксична помилка, наприклад неоднакові відступи чи двокрапка в тексті без лапок. place називає рядок і стовпчик. Виправте запис у цьому місці.

TEST_YAML_DUPLICATE_KEY

422. Те саме поле двічі в одному місці — наприклад, два text в одному варіанті. place називає друге. Лишіть одне.

TEST_YAML_ALIAS

422. У файлі є якір чи посилання YAML — & чи * перед назвою. Запишіть текст повністю в кожному місці, де він потрібен.

TEST_FIELD_INVALID

422. Поле невідоме чи відсутнє, назва порожня, поле не того виду (наприклад, correct: так замість true або поріг 80.5) чи задовге. details каже, що саме не так, place — де. Виправте поле за таблицею формату. Створення тесту запитом без title теж дає цю відмову.

TEST_OPTIONS_COUNT

422. У питанні понад 26 варіантів. place називає питання. Розділіть питання на кілька.

Той самий код у переліку incomplete означає інше: у питанні менше двох варіантів. Така чернетка зберігається, але перевірити й опублікувати її можна, лише додавши варіанти (див. Незавершена чернетка).

TEST_TOO_LARGE

413. Файл чи тіло запиту більші за 256 КБ. Розділіть тест на кілька.

SECURITY_REJECTED

400. Текст тесту містить невидимі символи (так буває з текстом, скопійованим із Word чи вебсторінки) або фрази, схожі на вказівки системі, що пише пояснення, чи файл не вдалося прочитати як текст. Поле category називає, що саме знайдено: suspicious_unicode, prompt_injection чи charset_violation. Наберіть підозрілий текст заново — або збережіть файл у кодуванні UTF-8 — і надішліть тест ще раз.

NOT_A_TEST_OBJECT

422. Ідентифікатор веде до іншого матеріалу вашої школи, а не до тесту, створеного в системі: наприклад, до лекції чи до тесту, колись завантаженого текстом. Перевірте ідентифікатор. Тест, завантажений текстом, відповідей більше не приймає — створіть його заново з YAML.

404 Document not found — тесту немає, його видалено або він належить іншій школі; 404 Node not found — те саме для розділу, у якому ви створюєте тест. 415 — тіло запиту не YAML і не JSON.

TEST_DRAFT_INCOMPLETE

422. Перевірка чи публікація незавершеної чернетки. Замість place відмова несе перелік incomplete — той самий, що й читання чернетки: кожне місце, яке лишилось завершити, з кодом і номерами питання й варіанта (див. Незавершена чернетка):

{"detail": {"code": "TEST_DRAFT_INCOMPLETE", "details": "…",
            "incomplete": [{"code": "TEST_NO_CORRECT_OPTION", "question": 2, "option": null}]}}

Нічого не перевірено й не опубліковано. Завершіть кожне місце з переліку, збережіть чернетку й повторіть перевірку чи публікацію.

GENERATION_IN_PROGRESS

409. Система саме пише пояснення до цього тесту — до іншого стану чернетки, до чинної версії чи мовою когось зі студентів. З перевірки чи публікації нічого не збережено. Зачекайте, доки вона закінчить, і повторіть запит.

Відмови завантаження й зміни матеріалу

Ці коди дають маршрути матеріалів — завантаження, зміна, повторна обробка, — коли справа стосується тесту. Тіло — {"code": "…", "details": "…"}; нічого не збережено.

TEST_FILE_NOT_YAML

422. Матеріал із типом завдання «Тест» — не YAML-файл (.yaml, .yml), а інший файл чи посилання. Тест із тексту чи документа Word система більше не приймає. Запишіть тест у YAML і завантажте файлом.

TEST_OBJECT_SOURCE_RESERVED

422. Запит сам вказав вид джерела test_object — цей вид ставить лише система. Завантажте YAML-файл із типом завдання «Тест» або створіть тест запитом (див. Як створити тест).

TEST_OBJECT_TYPE_FIXED

422. Спроба змінити тип завдання тесту, створеного в системі. Тест лишається тестом; якщо потрібне інше завдання — створіть новий матеріал.

TEST_OBJECT_ROLE_FIXED

422. Спроба зробити тест, створений у системі, методичним матеріалом — поставити йому роль (material_role), відмінну від educational. Тест завжди навчальний: методичного матеріалу студенти не бачать. Роль лишається навчальною; щоб прибрати тест від студентів, приховайте його (див. Приховати тест).

TEST_IS_AN_OBJECT

422. Спроба зробити тестом наявний матеріал, змінивши його тип завдання. Тест створюється з YAML — завантажте файл або створіть тест запитом.

TEST_OBJECT_NOT_PROCESSED

422. Повторна обробка чи ролі файлів для тесту, створеного в системі: такий тест не обробляється, як лекція. Щоб змінити тест, змініть чернетку й опублікуйте.

KEY_LIVES_IN_TEST

422. Запит замінити чи прибрати ключ відповідей (PUT чи DELETE …/reference/override) для тесту, створеного в системі. Правильні відповіді — позначки correct у самому тесті: змініть чернетку й опублікуйте.

Критерії текстового завдання

Роботи студентів над текстовим завданням — коротким завданням, завданням чи проєктом — система перевіряє за переліком критеріїв. Перелік складає сама система з тексту, назви й опису завдання, опису розділу й основних понять розділу й курсу. Складає його один раз — після першої подачі роботи студентом на перевірку, — і далі кожна робота з цього завдання перевіряється за тим самим переліком. Ви можете його поправити.

Опис розділу в програмі автора — вікно «Опис вузла» — дає переліку опис розділу завдання, а основні поняття (поле «Основні концепти») — розділу завдання й курсу. Якщо перелік склали, коли опису не мав ні розділ, ні курс, система складе його ще раз — після першої подачі, що прийде, коли опис з'явиться, — і лише один раз.

Кожен критерій несе:

поле	що це
id	позначка критерію — c1, c2, …; її ставить система
text	що перевірити
evidence	за якою ознакою видно, що виконано
weight	вага: must — обов'язково, should — бажано, may — можна
check_method	як перевірити: model_verdict — система оцінює роботу за текстом і ознакою критерію; mandatory_points — критерій виконано, коли в роботі є кожен обов'язковий пункт; code_test — перевірка запуском коду, лише в проєкті
soft_descent	true — перевірку запуском коду поки виконує оцінка системи: запускати код система ще не вміє
concepts	основні поняття, яких стосується критерій
mandatory_points	обов'язкові пункти — для mandatory_points; кожен має свою позначку: c1.p1, c1.p2, …

Прочитати перелік

curl https://api.pythoncourse.me/api/v1/documents/$TASK_ID/criteria -H "X-API-Key: $PREP_KEY"

Відповідь несе status — чи є перелік, а якщо немає, то чому:

• ready — перелік є;
• awaiting_first_submission — переліку ще немає, і жодна робота студента на нього не чекає;
• composing — система складає перелік саме зараз, це триває кілька хвилин;
• not_composed — переліку немає, хоча роботи студентів чекають на нього, або остання спроба скласти його не вдалася.

Поки переліку немає, message каже, що сталося й що робити, reason_code у стані not_composed — чому переліку немає, а waiting_submissions — скільки робіт студентів чекають на перелік, щоб їх перевірили за ним (див. Коли переліку немає). Поруч:

• model — перелік, який склала система;
• author — ваша правка, якщо ви її зробили;
• in_force — перелік, за яким перевіряються роботи: layer каже, чий він (author — ваша правка, model — перелік системи), criteria — самі критерії;
• contradictions — де завдання суперечить опису розділу. Це лише для вас: ні в критерії, ні в бал воно не йде;
• concepts — поняття, які можна назвати в критеріях.

Коли переліку немає

Поки жодна робота на перелік не чекає (awaiting_first_submission), message таке:

Перелік критеріїв буде складено після першої подачі роботи студентом на перевірку, після цього його можна поправити.

Поки система його складає (composing):

Перелік критеріїв складається зараз. Роботи студентів, що чекають на нього, буде перевірено, щойно він буде готовий; після цього перелік можна поправити.

Якщо переліку немає з іншої причини (not_composed), reason_code її називає, а message каже, що робити:

reason_code	message
task_not_processed	Перелік критеріїв ще не складено: обробку тексту завдання не завершено. Якщо обробка ще триває — дочекайтеся її завершення; якщо вона завершилася з помилкою — запустіть її знову. Після цього перелік складеться автоматично, щойно хтось зі студентів подасть роботу на це завдання, і тоді ж буде перевірено роботи, що чекають. Якщо нових робіт найближчим часом не буде — зверніться до адміністратора системи, і він запустить повторну спробу.
models_unavailable	Перелік критеріїв не вдалося скласти: сервіс, що його складає, був тимчасово недоступний. Від вас нічого не потрібно: повторна спроба відбудеться автоматично, щойно хтось зі студентів подасть роботу на це завдання, і тоді ж буде перевірено роботи, що чекають. Якщо нових робіт найближчим часом не буде або стан не зміниться — зверніться до адміністратора системи.
limit_reached	Перелік критеріїв не вдалося скласти: завдання завелике для обмежень, що зараз діють у системі. Зверніться до адміністратора системи: після зміни обмежень він запустить повторну спробу, і тоді ж буде перевірено роботи, що чекають. Не правте заради цього текст завдання: правка створить нову версію завдання й не допоможе роботам, що вже чекають.
composition_error	Перелік критеріїв не вдалося скласти через внутрішню помилку системи. Зверніться до адміністратора системи: після виправлення він запустить повторну спробу, і тоді ж буде перевірено роботи, що чекають.
not_attempted	Перелік критеріїв для поточної версії завдання ще не складався, а роботи студентів уже чекають на нього. Він складеться автоматично, щойно хтось зі студентів подасть роботу на це завдання, і тоді ж буде перевірено роботи, що чекають. Якщо нових робіт найближчим часом не буде — зверніться до адміністратора системи, і він запустить повторну спробу.

Сьогодні робота студента, для якої переліку немає, однаково отримує рецензію — без переліку, — а наступна подача спробує скласти його знову, тож waiting_submissions — 0. Коли перевірка текстових завдань спиратиметься лише на перелік, робота без нього чекатиме, доки він з'явиться, і тоді ж отримає рецензію; waiting_submissions покаже, скільки таких робіт.

Поправити перелік

Правку надсилають цілим переліком:

curl -X PUT https://api.pythoncourse.me/api/v1/documents/$TASK_ID/criteria/override \
     -H "X-API-Key: $PREP_KEY" -H 'Content-Type: application/json' \
     -d '{"criteria": [{"id": "c1", "text": "Обробляє n = 0", "evidence": "factorial(0) повертає 1", "weight": "must", "check_method": "model_verdict", "concepts": ["Рекурсія"]}, {"text": "Є базовий випадок", "evidence": "рекурсія зупиняється", "weight": "should", "check_method": "mandatory_points", "mandatory_points": [{"text": "умова зупинки"}]}]}'

• Критерій чи пункт, який ви лишаєте, надсилайте з його id — позначка збережеться. Новий — без id: система дасть йому позначку після найбільшої в чинному переліку й у переліку системи, а новому пункту — після найбільшої серед пунктів його критерію. Критерій, якого немає в правці, з переліку прибрано.
• soft_descent не надсилають — його ставить система.
• Поняття — лише з concepts читання.
• Межі: до 60 критеріїв; текст і ознака — до 600 знаків; до 10 обов'язкових пунктів на критерій, пункт — до 300 знаків; до 10 понять на критерій. Порушення межі — відмова 422, що називає поле.
• Суперечностей правка не змінює.

Правка діє для завдання в тому вигляді, у якому ви її зробили. Якщо зміниться текст завдання чи його вид, система складе новий перелік після наступної подачі, а попередня правка перестане діяти й зникне з читання — поправте новий перелік.

Скинути правку

curl -X DELETE https://api.pythoncourse.me/api/v1/documents/$TASK_ID/criteria/override -H "X-API-Key: $PREP_KEY"

Роботи знову перевіряються за переліком системи. Скинута правка, як і кожна замінена, лишається в системі знімком, але не діє й у читанні не показується.

Усі три запити відповідають тим самим тілом, що й читання, — тож видно, що саме тепер діє.

Коли запит відмовлено

Відмова несе в полі detail код причини й пояснення: {"code": "…", "details": "…"}. Нічого з відмовленого запиту не зберігається.

код	стан	причина	що робити
NOT_A_TEXT_TASK	422	матеріал — тест або не завдання	тест перевіряють ваші позначки правильних відповідей (див. Редактор тесту); у матеріалу, що не є завданням, критеріїв немає
TASK_NOT_READY	422	завдання ще обробляється або його прибрано з курсу	дочекайтеся кінця обробки й повторіть запит
AWAITING_FIRST_SUBMISSION	422	правка, поки переліку немає	прочитайте перелік: status і message кажуть, чому його немає й що робити (див. Коли переліку немає); правте, коли status — ready
UNKNOWN_CRITERION_ID	422	у правці є id критерію чи пункту, якого немає в чинному переліку	прочитайте перелік знову й надішліть правку з його id; новий критерій надсилайте без id
CHECK_METHOD_NOT_ADMITTED	422	спосіб перевірки не для цього типу завдання: code_test — лише в проєкті	виберіть model_verdict чи mandatory_points
UNKNOWN_CONCEPT	422	поняття, якого немає в concepts читання	виберіть поняття з concepts або приберіть його