Final revision before thesis release

.github/workflows/build.yml

@@ -59,6 +59,29 @@ jobs:
           removeArtifacts: true
           artifacts: src/main.pdf
 
+  publish-revision-release:
+    needs: build-latex
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/heads/revision-')
+    steps:
+      - name: Download PDF artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: thesis-pdf
+          path: src
+
+      - name: Publish PDF to revision release
+        uses: ncipollo/release-action@v1
+        with:
+          tag: revision-latest
+          name: Latest Revision Thesis PDF
+          body: Automatically updated thesis PDF from `${{ github.ref_name }}`.
+          allowUpdates: true
+          removeArtifacts: true
+          artifacts: src/main.pdf
+          prerelease: true
+          makeLatest: false
+
   publish-pages:
     needs: build-latex
     runs-on: ubuntu-latest

.run/Build Thesis.run.xml

@@ -1,5 +1,5 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="Build Thesis" type="LATEX_RUN_CONFIGURATION" factoryName="LaTeX configuration factory">
+  <configuration default="false" name="Build Thesis" type="LATEX_RUN_CONFIGURATION" factoryName="LaTeX configuration factory" activateToolWindowBeforeRun="false">
     <texify>
       <compiler>XELATEX</compiler>
       <compiler-path />
@@ -13,11 +13,12 @@
       <main-file>$PROJECT_DIR$/src/main.tex</main-file>
       <output-path>$PROJECT_DIR$/target</output-path>
       <auxil-path>{projectDir}/auxil</auxil-path>
+      <working-directory>{mainFileParent}</working-directory>
       <compile-twice>false</compile-twice>
       <output-format>PDF</output-format>
       <latex-distribution>PROJECT_SDK</latex-distribution>
       <has-been-run>true</has-been-run>
-      <bib-run-config>[BibTeX.Build biblio]</bib-run-config>
+      <bib-run-config>[]</bib-run-config>
       <makeindex-run-config>[]</makeindex-run-config>
     </texify>
     <method v="2" />

.run/Build biblio.run.xml

@@ -1,5 +1,5 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="Build biblio" type="BIBTEX_RUN_CONFIGURATION" factoryName="LaTeX configuration factory">
+  <configuration default="false" name="Build biblio" type="BIBTEX_RUN_CONFIGURATION" factoryName="LaTeX configuration factory" activateToolWindowBeforeRun="false">
     <texify-bibtex>
       <compiler>BIBER</compiler>
       <compiler-path />
@@ -9,7 +9,7 @@
         <env name="BSTINPUTS" value="$PROJECT_DIR$/src;" />
       </envs>
       <main-file>$PROJECT_DIR$/src/main.tex</main-file>
-      <aux-dir />
+      <aux-dir>$PROJECT_DIR$/target</aux-dir>
       <latex-distribution>PROJECT_SDK</latex-distribution>
     </texify-bibtex>
     <method v="2" />

src/additionallst.sty

@@ -3,46 +3,13 @@
 
 \definecolor{darkgreen}{rgb}{0,0.6,0}
 \definecolor{mauve}{rgb}{0.58,0,0.82}
+\definecolor{codegray}{gray}{0.95}
 
-\lstdefinelanguage{CSS}{
-    sensitive=true,
-    keywords={color:, background-color:, margin:, padding:, font:, weight:, display:, position:, top:, left:, right:, bottom:, list:, style:, border:},
-    morecomment=[l]{//},
-    morecomment=[s]{/*}{*/},
-    morestring=[b]',
-    morestring=[b]",
-    alsoletter={:},
-    alsodigit={-}
-}
-
-\lstdefinelanguage{HTML} {
-    sensitive=true,
-    keywords={html,head,title,meta,script,style,link,body,h1,h2,h3,h4,h5,h6,p,div,span,a,img,ul,ol,li,table,th,tr,td,thead,tbody,tfoot,form,input,button,select,option,label,textarea},
-    morecomment=[s]{<!--}{-->}
-}
-
-\lstdefinelanguage{JavaScript} {
-    sensitive=true,
-    keywords={typeof, new, true, false, catch, function, return, null, catch, switch, var, if, in, while, do, else, case, break, import, from},
-    morecomment=[s]{/*}{*/},
-    morecomment=[l]//,
-    morestring=[b]",
-    morestring=[b]'
-}
-
-\lstdefinelanguage{TypeScript} {
-    sensitive=true,
-    keywords={typeof, new, catch, function, return, null, catch, switch, var, if, in, while, do, else, case, break, export, class, public, const, constructor, private, console},
-    morecomment=[s]{/*}{*/},
-    morecomment=[l]//,
-    morestring=[b]",
-    morestring=[b]',
+\lstdefinelanguage{Markdown}{
+    sensitive=false,
+    morecomment=[l]{>},
     morestring=[b]`,
-}
-
-\lstdefinelanguage{JSON} {
-    morestring=[b]",
-    morestring=[b]'
+    moredelim=[l][\color{blue}\bfseries]{\#},
 }
 
 \lstset{

src/chapters/1-Introduction.tex

@@ -0,0 +1,20 @@
+\chapter{Úvod}
+\label{ch:introduction}
+
+Výuka programování na vysokých školách je dnes běžně podporována informačními systémy umožňujícími odevzdávání úloh, automatické testování a správu hodnocení.
+Přesto zůstává samotné posuzování zdrojového kódu jednou z nejnáročnějších částí výuky.
+Na rozdíl od úloh s jednoznačně správným výsledkem nelze kvalitu programového řešení redukovat pouze na ověření funkčnosti.
+Vyučující musí současně hodnotit efektivitu algoritmu, strukturu programu, čitelnost, práci s pamětí, ošetření chybových stavů i dodržování konvencí daného programovacího jazyka.
+S rostoucím počtem studentů a komplexitou zadání se tento proces stává časově velmi náročným, což může vést ke zjednodušování zpětné vazby a snížení její pedagogické hodnoty.
+
+V posledních letech se jako potenciální podpůrný nástroj ukazují \textbf{velké jazykové modely} (\textit{large language models}, LLM), které dokáží řešit zadání, analyzovat zdrojový kód, identifikovat problematická místa a generovat strukturované komentáře v přirozeném jazyce.
+Přestože tyto modely neposkytují formální záruku správnosti a nemohou nahradit odborný úsudek vyučujícího, mohou významně usnadnit orientaci v řešení a sloužit jako první analytická vrstva nad odevzdaným kódem.
+Vyučující tak může svůj čas věnovat především ověřování, zpřesňování automaticky navržených připomínek namísto jejich prvotního vyhledávání.
+
+Tato diplomová práce se zaměřuje na návrh, implementaci a ověření modulu pro automatickou analýzu studentských zdrojových kódů pomocí LLM, integrovaného do systému Kelvin -- webového informačního systému využívaného při výuce programování.
+Navržené řešení umožňuje asynchronní zpracování odevzdaných řešení, generování řádkových komentářů, celkového shrnutí a jejich následnou úpravu vyučujícím.
+Součástí práce je rovněž porovnání přístupů k nasazení jazykových modelů, návrh vhodné promptovací strategie a experimentální ověření kvality výstupů na historických studentských datech včetně zhodnocení přínosů, omezení a rizik navrženého řešení.
+
+Důležité je zdůraznit, že cílem tohoto rozšíření není nahradit učitele při hodnocení, ale poskytnout podpůrný nástroj, který pedagogům pomůže rychleji se zorientovat v řešení a upozorní na problematické části kódu.
+
+\endinput

src/chapters/2-Kelvin.tex

@@ -0,0 +1,58 @@
+\chapter{Systém Kelvin}
+\label{ch:kelvin}
+
+Tato kapitola se věnuje školnímu systému Kelvin (\href{https://kelvin.cs.vsb.cz/}{https://kelvin.cs.vsb.cz/}), který slouží jako základní platforma pro odevzdávání a hodnocení programátorských úloh.
+Cílem kapitoly je přiblížit účel systému, jeho architekturu, způsob nasazení a především vývojová omezení, která významně ovlivnila návrh a implementaci řešení popsaného v této diplomové práci.
+
+% =============================================================
+\section{Účel systému}
+\label{sec:kelvin-purpose}
+
+Hlavním účelem systému Kelvin je podpora výuky, především programovacích předmětů v jazycích C, C++, Python nebo Rust.
+Systém ale slouží také rovněž jako obecná platforma pro odevzdávání úloh v dalších předmětech, jako jsou základy počítačové grafiky (ZPG), modelování v grafických aplikacích (MGA), jazyk Java a další.
+Kelvin poskytuje jednotné webové rozhraní, prostřednictvím kterého mohou studenti odevzdávat svá řešení úloh na jednotné místo.
+Vyučujícím následně umožňuje tato řešení kontrolovat, poskytovat k nim zpětnou vazbu a udělovat bodové hodnocení.
+Součástí systému jsou také moduly pro automatické přeložení odevzdaného kódu, jeho spuštění, ověření výstupů a další podpůrné funkce.
+
+\input{chapters/2-kelvin/2-1-kelvin-purpose/2-1-1-kelvin-purpose-workflow}
+\input{chapters/2-kelvin/2-1-kelvin-purpose/2-1-2-kelvin-purpose-features}
+
+% =============================================================
+\section{Architektura systému}
+\label{sec:kelvin-architecture}
+
+Systém Kelvin je realizován jako webová aplikace se standardním třívrstvým uspořádáním: databázová vrstva, backendová aplikační logika a frontendová prezentační vrstva.
+Komunikace mezi frontendem a backendem probíhá přes REST API (Representational State Transfer, Application Programming Interface)\@.
+
+\input{chapters/2-kelvin/2-2-kelvin-architecture/2-2-1-kelvin-architecture-backend}
+\input{chapters/2-kelvin/2-2-kelvin-architecture/2-2-2-kelvin-architecture-api}
+\input{chapters/2-kelvin/2-2-kelvin-architecture/2-2-3-kelvin-architecture-frontend}
+
+% =============================================================
+\section{Nasazení a provoz systému}
+\label{sec:kelvin-deployment}
+
+Pro produkční nasazení je systém Kelvin distribuován pomocí kontejnerizační technologie Docker, přičemž jednotlivé části aplikace jsou spravovány nástrojem Docker Compose.
+Tento přístup umožňuje zajistit jednotné běhové prostředí pro vývoj i produkci a zároveň usnadňuje správu závislostí aplikace.
+
+Proces nasazení systému je automatizován pomocí nástroje GitHub Actions, který po každém úspěšném sloučení změn do hlavní větve repozitáře provede sestavení Docker image a jejich nasazení na produkční server.
+Automatizovaný deployment snižuje riziko chyb při manuálním nasazování a zajišťuje, že produkční prostředí odpovídá aktuálnímu stavu zdrojového kódu.
+
+Využití Docker a Docker Compose zároveň zjednodušuje vývoj a testování systému, protože umožňuje snadno spouštět kompletní instanci Kelvin na lokálním počítači bez nutnosti složité konfigurace prostředí.
+
+% =============================================================
+\section{Vývojová omezení a proces}
+\label{sec:kelvin-development}
+
+Systém Kelvin vznikl původně jako školní projekt studenta Daniela Trnky\footnote[1]{\href{https://github.com/trnila}{https://github.com/trnila}}, ale v průběhu let byl postupně rozšiřován dalšími studenty a vyučujícími.
+Tento způsob vývoje bez jednotné dlouhodobé architektonické vize vedl ke vzniku technického dluhu, který se v systému projevuje například ve formě dlouhých a obtížně čitelných souborů, nedostatečného nebo chybějícího typování a míchání různých programátorských přístupů.
+Před přidáním nové aplikační logiky je proto často nutné provést částečný refaktoring existujícího kódu, aby byla zachována alespoň základní úroveň čitelnosti a udržovatelnosti systému.
+
+Vývoj systému Kelvin je dále ovlivněn několika zásadními omezeními, která vyplývají jak z jeho historického vývoje, tak z organizačních podmínek jeho správy a údržby.
+Tato omezení mají přímý dopad na návrh i samotnou implementaci řešení popsaného v této diplomové práci.
+
+\input{chapters/2-kelvin/2-4-kelvin-development/2-4-1-kelvin-development-atomicity}
+\input{chapters/2-kelvin/2-4-kelvin-development/2-4-2-kelvin-development-migration}
+\input{chapters/2-kelvin/2-4-kelvin-development/2-4-3-kelvin-development-organization}
+
+\endinput

src/chapters/2-kelvin/2-1-kelvin-purpose/2-1-1-kelvin-purpose-workflow.tex

@@ -0,0 +1,24 @@
+\subsection{Typický scénář použití}
+\label{subsec:kelvin-workflow}
+
+Cyklus jedné úlohy v systému Kelvin zahrnuje několik na sebe navazujících kroků, od vytvoření zadání vyučujícím až po závěrečné manuální hodnocení odevzdaného řešení:
+
+Vyučující nejprve vytvoří úlohu, kde zadá její textový popis, nastaví termín odevzdání a případě definuje testovací vstupy a očekávané výstupy.
+Úloha je pak zpřístupněna přihlášeným studentům okamžitě nebo v předem stanoveném čase.
+
+Student si zadání přečte, během přiděleného času vypracuje řešení ve svém vývojovém prostředí a výsledný zdrojový kód odevzdá prostřednictvím webového rozhraní systému.
+Bezprostředně po odevzdání systém spustí automatizované testy.
+Systém zkompiluje zdrojový kód a spustí jej proti připraveným testovacím vstupům, následné výsledky jsou porovnány s očekávanými výstupy.
+Student okamžitě vidí výsledky testů které prošly i ty, které selhaly a následně může na základě zpětné vazby řešení opravit a odevzdat znovu.
+
+Po uzavření termínu odevzdání přistoupí vyučující k manuálnímu hodnocení.
+Prohlíží zdrojový kód odevzdaného řešení přímo v prostředí systému, přidává podle svého hodnocení komentáře ke konkrétním řádkům a na základě celkového posouzení udělí bodové hodnocení.
+Student hodnocení a komentáře obdrží a může na ně reagovat, čímž může vznikat diskuse nad zdrojovým kódem a jeho kvalitou.
+
+\subsubsection*{Další formy hodnocení}
+\label{subsubsec:kelvin-other-assessments}
+
+Systém Kelvin je rovněž využíván pro testy, kvízy a jiné formy hodnocení, které nemusí nutně zahrnovat zdrojový kód.
+Například pro testování teoretických znalostí nebo algoritmického myšlení prostřednictvím krátkých formulářových nebo textových odpovědí.
+
+\endinput

src/chapters/2-kelvin/2-1-kelvin-purpose/2-1-2-kelvin-purpose-features.tex

@@ -0,0 +1,21 @@
+\subsection{Klíčové funkce systému}
+\label{subsec:kelvin-features}
+
+Systém Kelvin nabízí několik funkcí, které jsou podstatné jak pro běžný provoz, tak pro plánovanou integraci s LLM\@.
+
+\begin{itemize}
+    \item \textbf{Automatické evaluace} -- po každém odevzdání systém automaticky zkompiluje studentův kód, spustí jej proti sadě předpřipravených testovacích vstupů a porovná výstupy s očekávanými hodnotami.
+    Zdrojový kód je tak testován na jednotném prostředí, což zajišťuje spravedlivé hodnocení funkční správnosti.
+    Výsledky jednotlivých testů jsou studentovi zobrazeny okamžitě, což umožňuje rychlou iteraci nad řešením bez nutnosti čekat na zpětnou vazbu od vyučujícího.
+
+    \item \textbf{Automatické udělování bodů} -- na základě výsledků automatických testů může systém přidělit body automaticky podle poměru úspěšných testů.
+    Vyučující tak nemusí manuálně hodnotit funkční správnost a může se soustředit na kvalitativní aspekty řešení, jako je čitelnost kódu, vhodnost zvolené datové struktury nebo efektivita algoritmu.
+
+    \item \textbf{Řádkové a celkové komentáře} -- vyučující může označit libovolný řádek zdrojového kódu a připsat k němu připomínku.
+    Kromě řádkových komentářů systém umožňuje i vložení celkového komentáře k odevzdání, který není vázán na konkrétní řádek a slouží jako celkové shrnutí zpětné vazby.
+    Komentáře jsou studentovi zobrazeny přímo v kontextu kódu, takže okamžitě vidí, ke které konkrétní části řešení se zpětná vazba vztahuje.
+    Tato vlastnost je z pohledu integrace LLM zcela zásadní, protože LLM generuje komentáře přirozeně ve formátu \uv{k řádku X patří připomínka Y}.
+    Výstup modelu tak lze přímo mapovat na existující datový model systému bez nutnosti zavádět nové typy do databáze.
+\end{itemize}
+
+\endinput

src/chapters/2-kelvin/2-2-kelvin-architecture/2-2-1-kelvin-architecture-backend.tex

@@ -0,0 +1,29 @@
+\subsection{Backend}
+\label{subsec:kelvin-backend}
+
+Backend systému je implementován v programovacím jazyce Python s využitím webového frameworku Django.
+Django zajišťuje správu databázových modelů prostřednictvím ORM (Object-Relational Mapping), autentizaci a autorizaci uživatelů, správu souborů (odevzdaných zdrojových kódů a testovacích dat) a základní routování požadavků.
+
+Použitým databázovým systémem je PostgreSQL, přičemž veškerý přístup k němu probíhá výhradně přes Django ORM\@.
+Soubory zdrojových kódů jsou ukládány na souborový uložišti serveru, přičemž v databázi jsou uloženy pouze metadata (cesty, časové razítka, vazby na studenty a úlohy).
+
+\subsubsection*{Evaluační pipeline}
+\label{subsubsec:kelvin-evaluation-pipeline}
+
+Stávající evaluační pipeline systému zajišťuje kompilaci odevzdaného zdrojového kódu a spuštění automatických testů v izolovaném prostředí.
+Izolace je realizována prostřednictvím kontejnerů (Docker) a omezení přístupu k systémovým zdrojům, což chrání infrastrukturu před škodlivým nebo nekorektním kódem a současně garantuje jednotné podmínky evaluace pro všechny studenty.
+
+Vyhodnocení je implementováno jako asynchronní úloha z pohledu aplikační architektury, nicméně z hlediska uživatelského chování se jedná o proces synchronní, protože student čeká na jeho dokončení před zobrazením výsledků testů.
+
+Zařazení dalších výpočetně náročných operací přímo do této pipeline, například generování analýzy pomocí LLM, by vedlo k prodloužení doby čekání na výsledek.
+I pokud by byly tyto operace realizovány technicky asynchronně, jejich začlenění do stejného evaluačního procesu by mělo přímý dopad na vnímanou latenci systému uživatelem.
+
+\subsubsection*{Kontrola plagiátorství}
+\label{subsubsec:kelvin-plagiarism-check}
+
+Vedle evaluační pipeline systém Kelvin provádí rovněž kontrolu plagiátorství.
+Ta je ze své podstaty vázána na celou skupinu odevzdání, nikoli na jedno konkrétní, a je proto spouštěna buď manuálně učitelem, nebo automaticky po vypršení termínu odevzdání dané úlohy.
+Po spuštění systém porovná každé odevzdání s každým ostatním ve skupině za využití nástrojů DOLOS~\cite{dolos} a MOSS~\cite{moss}.
+Díky tomuto uspořádání kontrola plagiátorství nijak neovlivňuje dobu čekání studentů na výsledky automatických testů.
+
+\endinput

src/chapters/2-kelvin/2-2-kelvin-architecture/2-2-2-kelvin-architecture-api.tex

@@ -0,0 +1,12 @@
+\subsection{API vrstva}
+\label{subsec:kelvin-api}
+
+Komunikace mezi frontendem a backendem probíhá prostřednictvím REST API implementovaného za pomocí knihovny \textbf{Django Ninja}.
+Jedná se o moderní framework pro budování API nad Django, inspirovaný knihovnou \textit{FastAPI}, který využívá \textit{type hints} jazyku Python pro automatickou validaci vstupních dat, serializaci odpovědí a generování OpenAPI dokumentace přístupné například skrze rozhraní \textit{Swagger UI}\@.
+Tento přístup výrazně snižuje množství opakujícího se kódu, neboť datové modely požadavků a odpovědí jsou popsány jedinou definicí třídy, ze které jsou odvozeny jak validační pravidla, tak dokumentace endpointů.
+
+Jednotlivé endpointy jsou organizovány do logických celků (tzv. \textit{routers}) podle domény, které zpřístupňují -- například odevzdání, uživatelé, úlohy nebo hodnocení.
+Autentizace uživatelů probíhá pomocí session cookies sdílených se standardní autentizační vrstvou Django, což umožňuje přímé propojení s existujícím systémem uživatelských účtů a oprávnění.
+Autorizace vůči jednotlivým entitám (například přístup k odevzdání nebo úloze) je řešena na úrovni jednotlivých endpointů s využitím rolí definovaných v rámci předmětu.
+
+\endinput