stucktrace 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
stucktrace/__init__.py ADDED
@@ -0,0 +1,50 @@
1
+ """stucktrace — learning-trajectory telemetry & reflection for Moodle + OPT_Mentor + Hermes.
2
+
3
+ Public API::
4
+
5
+ import stucktrace as st
6
+ st.start_session(student_id="s123", task="loops") # auto-hooks Jupyter cells
7
+ st.mark_confusion("I don't get the loop")
8
+ st.log_viz(step=3, line=5)
9
+ st.generate_report("student") # or "instructor"
10
+
11
+ In Jupyter you can also use ``%load_ext stucktrace``.
12
+ """
13
+ from ._version import __version__
14
+ from .adapters import HermesClient, LocalReportGenerator, MoodleAdapter, OPTMentorAdapter
15
+ from .compressor import CompressedTrajectory, CompressorConfig, compress, error_signature
16
+ from .reporter import Report, generate_report, spoiler_guard
17
+ from .tracker import (
18
+ Session,
19
+ end_session,
20
+ get_session,
21
+ log_viz,
22
+ mark_confusion,
23
+ set_task,
24
+ start_session,
25
+ track,
26
+ )
27
+
28
+ init_session = start_session # alias used in docs / notebooks
29
+
30
+ __all__ = [
31
+ "__version__",
32
+ "start_session", "init_session", "end_session", "get_session", "set_task",
33
+ "mark_confusion", "log_viz", "track", "generate_report",
34
+ "Session", "Report", "compress", "CompressorConfig", "CompressedTrajectory", "error_signature",
35
+ "spoiler_guard", "MoodleAdapter", "OPTMentorAdapter", "HermesClient", "LocalReportGenerator",
36
+ "load_ipython_extension", "unload_ipython_extension",
37
+ ]
38
+
39
+
40
+ def load_ipython_extension(ipython): # %load_ext stucktrace
41
+ from .tracker import _current, install_jupyter_hooks
42
+ if _current is None:
43
+ start_session(jupyter=False)
44
+ install_jupyter_hooks(ipython)
45
+ print("stucktrace: tracking cells. Use %stucktrace task <name>, %confused <text>, %stucktrace report")
46
+
47
+
48
+ def unload_ipython_extension(ipython):
49
+ from .tracker import uninstall_jupyter_hooks
50
+ uninstall_jupyter_hooks(ipython)
stucktrace/__main__.py ADDED
@@ -0,0 +1,3 @@
1
+ from .cli import main
2
+
3
+ raise SystemExit(main())
stucktrace/_version.py ADDED
@@ -0,0 +1 @@
1
+ __version__ = "0.1.0"
stucktrace/adapters.py ADDED
@@ -0,0 +1,501 @@
1
+ """Integration adapters: Moodle, OPT_Mentor, Hermes (+ offline fallback).
2
+
3
+ All adapters use the standard library only. Field names for Moodle and
4
+ OPT_Mentor are deliberately simple and configurable: when the real API
5
+ contracts are known, only this module changes.
6
+ """
7
+ from __future__ import annotations
8
+
9
+ import csv
10
+ import io
11
+ import json
12
+ import os
13
+ import urllib.error
14
+ import urllib.request
15
+ from typing import Any, Dict, List, Optional
16
+
17
+ from ._version import __version__
18
+ from .compressor import CompressedTrajectory, TaskSummary, _fmt_clock, _fmt_dur, _pct
19
+
20
+
21
+ # =================================================================== Moodle
22
+ class MoodleAdapter:
23
+ """Maps a compressed trajectory onto Moodle quiz-attempt metadata.
24
+
25
+ ``question_map`` maps stucktrace task names to Moodle question slots,
26
+ e.g. ``{"sum_evens": 1, "fizzbuzz": 2}``.
27
+ """
28
+
29
+ CSV_FIELDS = ["userid", "courseid", "quizid", "attempt", "slot", "task", "attempts", "failures",
30
+ "solved", "first_success_attempt", "time_spent_sec", "panic_level", "panic_score",
31
+ "top_error", "confusions"]
32
+
33
+ def __init__(self, course_id: Any = None, quiz_id: Any = None, user_id: Any = None,
34
+ attempt: Any = None, question_map: Optional[Dict[str, int]] = None) -> None:
35
+ self.course_id, self.quiz_id, self.user_id, self.attempt = course_id, quiz_id, user_id, attempt
36
+ self.question_map = question_map or {}
37
+
38
+ @classmethod
39
+ def from_attempt(cls, meta: Dict[str, Any], question_map: Optional[Dict[str, int]] = None) -> "MoodleAdapter":
40
+ """Build from Moodle-style attempt metadata (e.g. mod_quiz attempt / LTI launch params)."""
41
+ g = lambda *keys: next((meta[k] for k in keys if k in meta), None) # noqa: E731
42
+ return cls(course_id=g("courseid", "course_id", "context_id"),
43
+ quiz_id=g("quizid", "quiz_id", "cmid", "resource_link_id"),
44
+ user_id=g("userid", "user_id"),
45
+ attempt=g("attempt", "attemptid", "attempt_id"),
46
+ question_map=question_map)
47
+
48
+ def apply_to(self, session: Any) -> None:
49
+ session.metadata["moodle"] = self._ids()
50
+ if self.user_id is not None:
51
+ session.metadata.setdefault("student_id", str(self.user_id))
52
+
53
+ def _ids(self) -> Dict[str, Any]:
54
+ return {k: v for k, v in dict(courseid=self.course_id, quizid=self.quiz_id,
55
+ userid=self.user_id, attempt=self.attempt).items() if v is not None}
56
+
57
+ def _rows(self, ctx: CompressedTrajectory) -> List[Dict[str, Any]]:
58
+ rows = []
59
+ for i, t in enumerate(ctx.tasks, start=1):
60
+ rows.append({
61
+ "userid": self.user_id, "courseid": self.course_id, "quizid": self.quiz_id,
62
+ "attempt": self.attempt, "slot": self.question_map.get(t.task, i), "task": t.task,
63
+ "attempts": t.attempts, "failures": t.failures, "solved": int(t.solved),
64
+ "first_success_attempt": t.first_success_attempt, "time_spent_sec": t.time_on_task,
65
+ "panic_level": t.panic_level, "panic_score": t.panic_score, "top_error": t.top_error or "",
66
+ "confusions": " | ".join(t.confusions),
67
+ })
68
+ return rows
69
+
70
+ def export_attempt_json(self, ctx: CompressedTrajectory) -> Dict[str, Any]:
71
+ return {"source": "stucktrace", "version": __version__, "session_id": ctx.session_id,
72
+ "moodle": self._ids(), "totals": {k: v for k, v in ctx.totals.items() if k != "top_errors"},
73
+ "questions": self._rows(ctx)}
74
+
75
+ def export_csv(self, ctx: CompressedTrajectory, path: Optional[str] = None) -> str:
76
+ buf = io.StringIO()
77
+ w = csv.DictWriter(buf, fieldnames=self.CSV_FIELDS)
78
+ w.writeheader()
79
+ for r in self._rows(ctx):
80
+ w.writerow(r)
81
+ text = buf.getvalue()
82
+ if path:
83
+ with open(path, "w", encoding="utf-8", newline="") as fh:
84
+ fh.write(text)
85
+ return text
86
+
87
+
88
+ # =============================================================== OPT_Mentor
89
+ class OPTMentorAdapter:
90
+ """Imports visualization / tracing steps.
91
+
92
+ Accepts Online-Python-Tutor-style traces::
93
+
94
+ {"code": "...", "trace": [{"event": "step_line", "line": 3, "func_name": "f",
95
+ "stack_to_render": [...], "exception_msg": "..."}]}
96
+
97
+ One trace becomes ONE summarised ``viz`` event (steps, lines visited,
98
+ max stack depth, exception) – raw steps are not stored, which keeps the
99
+ log small. Use ``session.log_viz`` for per-step logging.
100
+ """
101
+
102
+ def import_trace(self, trace: Any, session: Any = None, task: Optional[str] = None) -> Optional[Dict[str, Any]]:
103
+ from .tracker import get_session
104
+ try:
105
+ if isinstance(trace, (str, bytes)):
106
+ trace = json.loads(trace)
107
+ steps = trace.get("trace", trace if isinstance(trace, list) else [])
108
+ lines = [s.get("line") for s in steps if isinstance(s, dict) and s.get("line") is not None]
109
+ depth = max((len(s.get("stack_to_render") or []) for s in steps if isinstance(s, dict)), default=0)
110
+ exc = next((s.get("exception_msg") for s in steps if isinstance(s, dict) and s.get("exception_msg")), None)
111
+ summary = {"source": "opt_mentor", "steps": len(steps), "unique_lines": len(set(lines)),
112
+ "max_stack_depth": depth}
113
+ if exc:
114
+ summary["exception"] = str(exc)[:200]
115
+ (session or get_session()).log_viz(event="trace_imported", task=task,
116
+ note=f"OPT_Mentor trace, {len(steps)} steps", **summary)
117
+ return summary
118
+ except Exception:
119
+ return None
120
+
121
+ @staticmethod
122
+ def export_steps(session: Any) -> List[Dict[str, Any]]:
123
+ return [e.to_dict() for e in session.events if e.kind == "viz"]
124
+
125
+
126
+ # =================================================================== Hermes
127
+ class HermesError(RuntimeError):
128
+ pass
129
+
130
+
131
+ _SYSTEM = {
132
+ "student": (
133
+ "You are a supportive programming tutor writing a SELF-REFLECTION report for a student, "
134
+ "based on a compressed telemetry log of how they worked. Rules: never give the solution or "
135
+ "corrected code; point to concepts, habits and questions to ask themselves; be specific about "
136
+ "where they got stuck and which error patterns repeated; acknowledge what worked; end with 3 "
137
+ "concrete things to try next time. Use Markdown with short sections. Max 250 words."
138
+ ),
139
+ "instructor": (
140
+ "You are a teaching assistant writing a DIAGNOSTIC report for an instructor, based on a compressed "
141
+ "telemetry log of one student's session. Be factual and concise: rank tasks by difficulty, explain "
142
+ "stuck/panic points with timestamps, name the misconceptions the error clusters suggest, note whether "
143
+ "visualization helped, and propose 2-3 targeted interventions. Use Markdown with a summary table. "
144
+ "Max 350 words."
145
+ ),
146
+ }
147
+
148
+
149
+ class HermesClient:
150
+ """Minimal client for a Hermes LLM endpoint.
151
+
152
+ Assumes an OpenAI-compatible ``/chat/completions`` contract (the common
153
+ way Hermes models are served). Configure via arguments or env vars
154
+ ``HERMES_API_URL``, ``HERMES_API_KEY``, ``HERMES_MODEL``.
155
+ """
156
+
157
+ def __init__(self, api_url: Optional[str] = None, api_key: Optional[str] = None,
158
+ model: Optional[str] = None, timeout: float = 12.0) -> None:
159
+ self.api_url = api_url or os.environ.get("HERMES_API_URL")
160
+ self.api_key = api_key or os.environ.get("HERMES_API_KEY")
161
+ self.model = model or os.environ.get("HERMES_MODEL", "hermes")
162
+ self.timeout = timeout
163
+
164
+ @property
165
+ def available(self) -> bool:
166
+ return bool(self.api_url)
167
+
168
+ def build_messages(self, ctx: CompressedTrajectory, mode: str = "student", lang: str = "en") -> List[Dict[str, str]]:
169
+ language = "Russian" if lang == "ru" else "English"
170
+ system = _SYSTEM["instructor" if mode == "instructor" else "student"] + f" Write in {language}."
171
+ return [{"role": "system", "content": system},
172
+ {"role": "user", "content": "Compressed trajectory:\n" + ctx.to_prompt()}]
173
+
174
+ def complete(self, messages: List[Dict[str, str]]) -> str:
175
+ if not self.api_url:
176
+ raise HermesError("HERMES_API_URL is not configured")
177
+ body = json.dumps({"model": self.model, "messages": messages, "temperature": 0.3}).encode()
178
+ headers = {"Content-Type": "application/json", "User-Agent": f"stucktrace/{__version__}"}
179
+ if self.api_key:
180
+ headers["Authorization"] = f"Bearer {self.api_key}"
181
+ req = urllib.request.Request(self.api_url, data=body, headers=headers, method="POST")
182
+ try:
183
+ with urllib.request.urlopen(req, timeout=self.timeout) as resp:
184
+ payload = json.loads(resp.read().decode("utf-8"))
185
+ except (urllib.error.URLError, OSError, ValueError) as exc:
186
+ raise HermesError(f"Hermes request failed: {exc}") from exc
187
+ text = _extract_text(payload)
188
+ if not text:
189
+ raise HermesError("Hermes returned an empty / unknown response shape")
190
+ return text
191
+
192
+ def report(self, ctx: CompressedTrajectory, mode: str = "student", lang: str = "en") -> str:
193
+ return self.complete(self.build_messages(ctx, mode, lang))
194
+
195
+
196
+ def _extract_text(payload: Any) -> Optional[str]:
197
+ if not isinstance(payload, dict):
198
+ return None
199
+ try:
200
+ return payload["choices"][0]["message"]["content"]
201
+ except (KeyError, IndexError, TypeError):
202
+ pass
203
+ for key in ("output", "text", "response", "content", "report"):
204
+ v = payload.get(key)
205
+ if isinstance(v, str) and v.strip():
206
+ return v
207
+ return None
208
+
209
+
210
+ # ===================================================== Offline report engine
211
+ _HINTS = {
212
+ "en": {
213
+ "NameError": "a name is used before it exists — check spelling and where the variable is first assigned",
214
+ "TypeError": "two values of incompatible types meet — print the type() of each operand before the failing line",
215
+ "IndexError": "an index goes past the end — trace the loop bounds for the first and last iteration",
216
+ "KeyError": "a dict key is missing — print the keys you actually have",
217
+ "SyntaxError": "Python cannot parse the line — look at brackets, colons and quotes just before the arrow",
218
+ "IndentationError": "the block structure is off — check which lines belong inside the loop/if",
219
+ "ValueError": "the type is right but the value is not — check what input reaches the conversion",
220
+ "ZeroDivisionError": "a divisor can be zero — which case did you not handle?",
221
+ "AttributeError": "the object is not the type you think — print type(obj) and dir(obj)",
222
+ "RecursionError": "the recursion never reaches its base case — write down the base case first",
223
+ "UnboundLocalError": "a variable is assigned inside the function, so Python treats it as local",
224
+ "AssertionError": "a test expectation failed — compare expected vs actual on the smallest input",
225
+ "ModuleNotFoundError": "the import name or environment is wrong",
226
+ "ImportError": "the import name or environment is wrong",
227
+ },
228
+ "ru": {
229
+ "NameError": "имя используется до того, как оно создано — проверь написание и место первого присваивания",
230
+ "TypeError": "встретились значения несовместимых типов — выведи type() каждого операнда перед строкой с ошибкой",
231
+ "IndexError": "индекс выходит за границу — проследи границы цикла на первой и последней итерации",
232
+ "KeyError": "в словаре нет ключа — выведи ключи, которые реально есть",
233
+ "SyntaxError": "Python не может разобрать строку — смотри скобки, двоеточия и кавычки перед стрелкой",
234
+ "IndentationError": "сломана структура блоков — проверь, какие строки должны быть внутри цикла/if",
235
+ "ValueError": "тип верный, но значение нет — проверь, что приходит в преобразование",
236
+ "ZeroDivisionError": "делитель может быть нулём — какой случай не обработан?",
237
+ "AttributeError": "объект не того типа, что ты думаешь — выведи type(obj) и dir(obj)",
238
+ "RecursionError": "рекурсия не доходит до базового случая — сначала запиши базовый случай",
239
+ "UnboundLocalError": "переменная присваивается внутри функции, поэтому Python считает её локальной",
240
+ "AssertionError": "тест не прошёл — сравни ожидаемое и фактическое на самом маленьком входе",
241
+ "ModuleNotFoundError": "неверное имя модуля или окружение",
242
+ "ImportError": "неверное имя модуля или окружение",
243
+ },
244
+ }
245
+
246
+ _T = {
247
+ "en": {
248
+ "s_title": "## 🪞 Self-Reflection Report",
249
+ "i_title": "## 🧭 Instructor Diagnostic Report",
250
+ "overview": "**Session:** {tasks} task(s) · {runs} runs · {fails} failed · {dur}",
251
+ "stuck_h": "### Where you got stuck",
252
+ "no_stuck": "- No real stuck points — steady work. 👏",
253
+ "patterns_h": "### Patterns you repeated",
254
+ "no_patterns": "- No repeated error patterns.",
255
+ "worked_h": "### What worked",
256
+ "next_h": "### Try next time",
257
+ "pressure": {"low": "low pressure", "medium": "some pressure", "high": "high pressure"},
258
+ "unsolved": "not solved yet",
259
+ "you_flagged": "you flagged: {t}",
260
+ "fix": "On **{task}** you fixed `{err}` after {n} failed attempt(s) with a {size} edit.",
261
+ "small": "small", "large": "large",
262
+ "viz": "On **{task}** the visualizer helped: success came within a few runs after tracing.",
263
+ "solved_first": "**{task}** worked on the first try.",
264
+ "no_worked": "- You kept going — that is the part that counts. Next time, look for one small win per task.",
265
+ "tip_burst": "When a run fails, stop for 30 seconds and read the *whole* traceback before re-running.",
266
+ "tip_repeat": "If the same error comes back, write down (or say out loud) what you *expect* that line to do.",
267
+ "tip_rewrite": "Change one thing at a time — big rewrites after an error hide what actually fixed it.",
268
+ "tip_pause": "If you are silent for minutes, ask for help or open the visualizer earlier.",
269
+ "tip_confusion": "Turn \"{t}\" into a concrete question and try the smallest possible example.",
270
+ "tip_viz": "Keep using step-by-step visualization — it worked for you.",
271
+ "tip_default": "Test your code on the smallest input you can think of before the full one.",
272
+ "who": "**Student:** {sid} · **Course:** {course} · **Session:** `{sess}` · {dur}",
273
+ "table": "| Task | Runs | Solved | 1st success | Time | Panic | Top error |\n|---|---|---|---|---|---|---|",
274
+ "hot_h": "### Difficulty hotspots (ranked by panic score)",
275
+ "clusters_h": "### Error clusters",
276
+ "trans_h": "### Key transitions (error → fix)",
277
+ "conf_h": "### Student-flagged confusion",
278
+ "none": "- none",
279
+ "interv_h": "### Suggested interventions",
280
+ "iv_burst": "**{task}**: trial-and-error bursts — model a debugging routine (read traceback → hypothesis → one change).",
281
+ "iv_repeat": "**{task}**: persistent `{etype}` — likely misconception; a 2-minute targeted explanation is worth it.",
282
+ "iv_unsolved": "**{task}**: not solved — consider a scaffolded hint or a worked example of a *similar* task.",
283
+ "iv_conf": "**{task}**: the student explicitly asked for help (\"{t}\") — follow up personally.",
284
+ "iv_viz": "Visualization shortened time-to-fix on **{task}** — recommend it for similar exercises.",
285
+ "iv_default": "No intervention needed — the session looks healthy.",
286
+ "signals": {"rapid_fail_burst": "rapid-fail burst", "repeated_error": "repeated error",
287
+ "long_pause": "long pause", "rewrite": "rewrite after error", "confusion": "confusion marker"},
288
+ "viz_note": "visualizer used {n}× (helped: {h})",
289
+ "detail": {"rapid_fail_burst": "{n} failed runs in {span}s", "repeated_error": "same {etype} {n}× in a row",
290
+ "long_pause": "{secs}s of silence after {etype}", "rewrite": "{pct} of the code rewritten after {etype}",
291
+ "confusion": "\"{text}\""},
292
+ "cluster": "×{count} `{sig}` — {task}, attempts {a}–{b}, max streak {s}, {res}",
293
+ "resolved": "resolved", "unresolved": "UNRESOLVED",
294
+ "trans": "**{task}**: `{err}` fixed after {n} failed attempt(s), {secs}s, edit {pct}{viz}",
295
+ "after_viz": " · after visualization",
296
+ "yes": "yes", "no": "no",
297
+ },
298
+ "ru": {
299
+ "s_title": "## 🪞 Отчёт для самоанализа",
300
+ "i_title": "## 🧭 Диагностический отчёт для преподавателя",
301
+ "overview": "**Сессия:** задач: {tasks} · запусков: {runs} · неудачных: {fails} · {dur}",
302
+ "stuck_h": "### Где ты застрял",
303
+ "no_stuck": "- Явных застреваний нет — ровная работа. 👏",
304
+ "patterns_h": "### Повторяющиеся паттерны ошибок",
305
+ "no_patterns": "- Повторяющихся ошибок нет.",
306
+ "worked_h": "### Что сработало",
307
+ "next_h": "### Что попробовать в следующий раз",
308
+ "pressure": {"low": "спокойно", "medium": "заметное напряжение", "high": "сильное напряжение"},
309
+ "unsolved": "пока не решено",
310
+ "you_flagged": "ты отметил: {t}",
311
+ "fix": "В **{task}** ты исправил `{err}` после неудачных попыток: {n} — {size} правкой.",
312
+ "small": "небольшой", "large": "крупной",
313
+ "viz": "В **{task}** помог визуализатор: успех пришёл через пару запусков после трассировки.",
314
+ "solved_first": "**{task}** получилось с первой попытки.",
315
+ "no_worked": "- Ты не бросил — это главное. В следующий раз ищи одну маленькую победу на задачу.",
316
+ "tip_burst": "После ошибки остановись на 30 секунд и прочитай traceback *целиком*, прежде чем перезапускать.",
317
+ "tip_repeat": "Если ошибка повторяется, запиши (или проговори), что *должна* делать эта строка.",
318
+ "tip_rewrite": "Меняй по одной вещи за раз — большие переписывания скрывают, что именно помогло.",
319
+ "tip_pause": "Если долго молчишь — раньше проси помощи или открывай визуализатор.",
320
+ "tip_confusion": "Преврати «{t}» в конкретный вопрос и попробуй самый маленький пример.",
321
+ "tip_viz": "Продолжай пользоваться пошаговой визуализацией — она тебе помогла.",
322
+ "tip_default": "Проверяй код на самом маленьком входе перед полным.",
323
+ "who": "**Студент:** {sid} · **Курс:** {course} · **Сессия:** `{sess}` · {dur}",
324
+ "table": "| Задача | Запуски | Решена | 1-й успех | Время | Паника | Главная ошибка |\n|---|---|---|---|---|---|---|",
325
+ "hot_h": "### Точки затруднения (по индексу паники)",
326
+ "clusters_h": "### Кластеры ошибок",
327
+ "trans_h": "### Ключевые переходы (ошибка → исправление)",
328
+ "conf_h": "### Явные маркеры непонимания",
329
+ "none": "- нет",
330
+ "interv_h": "### Рекомендуемые действия",
331
+ "iv_burst": "**{task}**: серии проб и ошибок — покажите алгоритм отладки (traceback → гипотеза → одно изменение).",
332
+ "iv_repeat": "**{task}**: устойчивая `{etype}` — вероятное заблуждение; стоит 2-минутное точечное объяснение.",
333
+ "iv_unsolved": "**{task}**: не решена — дайте поэтапную подсказку или разбор *похожей* задачи.",
334
+ "iv_conf": "**{task}**: студент явно просил помощи («{t}») — свяжитесь лично.",
335
+ "iv_viz": "Визуализация ускорила исправление в **{task}** — рекомендуйте её для похожих упражнений.",
336
+ "iv_default": "Вмешательство не требуется — сессия выглядит здоровой.",
337
+ "signals": {"rapid_fail_burst": "серия быстрых неудач", "repeated_error": "повтор ошибки",
338
+ "long_pause": "долгая пауза", "rewrite": "переписывание после ошибки", "confusion": "маркер непонимания"},
339
+ "viz_note": "визуализатор: {n}× (помог: {h})",
340
+ "detail": {"rapid_fail_burst": "неудачных запусков подряд: {n} за {span} с", "repeated_error": "одна и та же {etype} {n}× подряд",
341
+ "long_pause": "{secs} с тишины после {etype}", "rewrite": "переписано {pct} кода после {etype}",
342
+ "confusion": "«{text}»"},
343
+ "cluster": "×{count} `{sig}` — {task}, попытки {a}–{b}, макс. серия {s}, {res}",
344
+ "resolved": "исправлена", "unresolved": "НЕ ИСПРАВЛЕНА",
345
+ "trans": "**{task}**: `{err}` исправлена после неудачных попыток: {n}, {secs} с, правка {pct}{viz}",
346
+ "after_viz": " · после визуализации",
347
+ "yes": "да", "no": "нет",
348
+ },
349
+ }
350
+
351
+
352
+ class LocalReportGenerator:
353
+ """Deterministic, rule-based report writer. Works fully offline — the demo always runs."""
354
+
355
+ def generate(self, ctx: CompressedTrajectory, mode: str = "student", lang: str = "en") -> str:
356
+ lang = lang if lang in _T else "en"
357
+ return self._instructor(ctx, lang) if mode == "instructor" else self._student(ctx, lang)
358
+
359
+ # ---------------------------------------------------------- student
360
+ def _student(self, ctx: CompressedTrajectory, lang: str) -> str:
361
+ T, H = _T[lang], _HINTS[lang]
362
+ tt = ctx.totals
363
+ out = [T["s_title"], T["overview"].format(tasks=tt["tasks"], runs=tt["runs"], fails=tt["failures"],
364
+ dur=_fmt_dur(ctx.duration)), "", T["stuck_h"]]
365
+ stuck_tasks = sorted([t for t in ctx.tasks if t.stuck_points or not t.solved],
366
+ key=lambda t: -t.panic_score)
367
+ if not stuck_tasks:
368
+ out.append(T["no_stuck"])
369
+ for t in stuck_tasks:
370
+ bits = [self._signal_text(s, T) for s in self._key_signals(t)]
371
+ if not t.solved:
372
+ bits.append(T["unsolved"])
373
+ out.append(f"- **{t.task}** — {T['pressure'][t.panic_level]}: " + "; ".join(bits))
374
+
375
+ out += ["", T["patterns_h"]]
376
+ clusters = [(t, c) for t in ctx.tasks for c in t.error_clusters if c.count >= 2]
377
+ clusters.sort(key=lambda tc: -tc[1].count)
378
+ if not clusters:
379
+ out.append(T["no_patterns"])
380
+ seen = set()
381
+ for t, c in clusters[:4]:
382
+ hint = H.get(c.error_type, "")
383
+ out.append(f"- `{c.error_type}` ×{c.count} ({t.task})" + (f" — {hint}" if hint and c.error_type not in seen else ""))
384
+ seen.add(c.error_type)
385
+
386
+ out += ["", T["worked_h"]]
387
+ worked = []
388
+ for t in ctx.tasks:
389
+ if t.first_success_attempt == 1:
390
+ worked.append(T["solved_first"].format(task=t.task))
391
+ for tr in t.transitions[:1]:
392
+ size = T["small"] if (tr.edit_ratio or 0) < 0.3 else T["large"]
393
+ worked.append(T["fix"].format(task=t.task, err=tr.fixed_error.split(":")[0], n=tr.after_attempts, size=size))
394
+ if t.viz_helped:
395
+ worked.append(T["viz"].format(task=t.task))
396
+ out += [f"- {w}" for w in worked[:4]] or [T["no_worked"]]
397
+
398
+ out += ["", T["next_h"]]
399
+ out += [f"{i}. {tip}" for i, tip in enumerate(self._tips(ctx, T), start=1)]
400
+ return "\n".join(out)
401
+
402
+ def _key_signals(self, t: TaskSummary):
403
+ picked, kinds = [], set()
404
+ for s in t.stuck_points:
405
+ if s.kind not in kinds:
406
+ picked.append(s)
407
+ kinds.add(s.kind)
408
+ return picked[:4]
409
+
410
+ @staticmethod
411
+ def _detail(s, T) -> str:
412
+ try:
413
+ return T["detail"][s.kind].format(**s.data)
414
+ except (KeyError, IndexError):
415
+ return s.detail
416
+
417
+ def _signal_text(self, s, T) -> str:
418
+ if s.kind == "confusion":
419
+ return T["you_flagged"].format(t=self._detail(s, T))
420
+ return self._detail(s, T)
421
+
422
+ def _tips(self, ctx: CompressedTrajectory, T) -> List[str]:
423
+ kinds = {s.kind for t in ctx.tasks for s in t.stuck_points}
424
+ tips = []
425
+ if "rapid_fail_burst" in kinds:
426
+ tips.append(T["tip_burst"])
427
+ if "repeated_error" in kinds:
428
+ tips.append(T["tip_repeat"])
429
+ if "rewrite" in kinds:
430
+ tips.append(T["tip_rewrite"])
431
+ if "long_pause" in kinds:
432
+ tips.append(T["tip_pause"])
433
+ conf = next((c for t in ctx.tasks for c in t.confusions if c), None)
434
+ if conf:
435
+ tips.append(T["tip_confusion"].format(t=conf))
436
+ if any(t.viz_helped for t in ctx.tasks):
437
+ tips.append(T["tip_viz"])
438
+ if len(tips) < 3:
439
+ tips.append(T["tip_default"])
440
+ return tips[:3] if len(tips) > 3 else tips
441
+
442
+ # ------------------------------------------------------- instructor
443
+ def _instructor(self, ctx: CompressedTrajectory, lang: str) -> str:
444
+ T = _T[lang]
445
+ md = ctx.metadata
446
+ out = [T["i_title"],
447
+ T["who"].format(sid=md.get("student_id", "—"), course=md.get("course", "—"),
448
+ sess=ctx.session_id, dur=_fmt_dur(ctx.duration)),
449
+ "", T["table"]]
450
+ for t in ctx.tasks:
451
+ out.append(f"| {t.task} | {t.attempts} | {'✅' if t.solved else '❌'} | {t.first_success_attempt or '—'} | "
452
+ f"{_fmt_dur(t.time_on_task)} | {t.panic_level} ({t.panic_score:.2f}) | "
453
+ f"{(t.top_error or '—').replace('|', '/')[:60]} |")
454
+
455
+ out += ["", T["hot_h"]]
456
+ for t in sorted(ctx.tasks, key=lambda t: -t.panic_score):
457
+ if not t.stuck_points:
458
+ continue
459
+ out.append(f"- **{t.task}** — {t.panic_level} ({t.panic_score:.2f}); "
460
+ + T["viz_note"].format(n=t.viz_steps, h=T["yes"] if t.viz_helped else T["no"]))
461
+ for s in t.stuck_points:
462
+ out.append(f" - `+{_fmt_clock(s.t)}` {T['signals'][s.kind]}: {self._detail(s, T)}")
463
+ out.append(f" - digest: `{t.digest}`")
464
+ if not any(t.stuck_points for t in ctx.tasks):
465
+ out.append(T["none"])
466
+
467
+ out += ["", T["clusters_h"]]
468
+ rows = [(t, c) for t in ctx.tasks for c in t.error_clusters]
469
+ rows.sort(key=lambda tc: -tc[1].count)
470
+ out += ["- " + T["cluster"].format(count=c.count, sig=c.signature, task=t.task, a=c.first_attempt,
471
+ b=c.last_attempt, s=c.max_streak,
472
+ res=T["resolved"] if c.resolved else T["unresolved"])
473
+ for t, c in rows[:8]] or [T["none"]]
474
+
475
+ out += ["", T["trans_h"]]
476
+ out += ["- " + T["trans"].format(task=t.task, err=tr.fixed_error, n=tr.after_attempts,
477
+ secs=f"{tr.seconds:.0f}", pct=_pct(tr.edit_ratio),
478
+ viz=T["after_viz"] if tr.viz_before else "")
479
+ for t in ctx.tasks for tr in t.transitions] or [T["none"]]
480
+
481
+ out += ["", T["conf_h"]]
482
+ out += [f"- **{t.task}**: “{c}”" for t in ctx.tasks for c in t.confusions if c] or [T["none"]]
483
+
484
+ out += ["", T["interv_h"]]
485
+ iv = []
486
+ for t in sorted(ctx.tasks, key=lambda t: -t.panic_score):
487
+ kinds = {s.kind for s in t.stuck_points}
488
+ if "repeated_error" in kinds and t.error_clusters:
489
+ iv.append(T["iv_repeat"].format(task=t.task, etype=t.error_clusters[0].error_type))
490
+ elif "rapid_fail_burst" in kinds:
491
+ iv.append(T["iv_burst"].format(task=t.task))
492
+ if not t.solved:
493
+ iv.append(T["iv_unsolved"].format(task=t.task))
494
+ conf = next((c for c in t.confusions if c), None)
495
+ if conf:
496
+ iv.append(T["iv_conf"].format(task=t.task, t=conf))
497
+ if t.viz_helped:
498
+ iv.append(T["iv_viz"].format(task=t.task))
499
+ out += [f"{i}. {x}" for i, x in enumerate(iv[:5], start=1)] or [f"1. {T['iv_default']}"]
500
+ return "\n".join(out)
501
+
stucktrace/cli.py ADDED
@@ -0,0 +1,64 @@
1
+ """Command line: ``stucktrace report trace.jsonl --mode instructor``."""
2
+ from __future__ import annotations
3
+
4
+ import argparse
5
+ import sys
6
+ from typing import List, Optional
7
+
8
+ from . import __version__
9
+ from .adapters import MoodleAdapter
10
+ from .reporter import generate_report
11
+ from .tracker import Session
12
+
13
+
14
+ def main(argv: Optional[List[str]] = None) -> int:
15
+ p = argparse.ArgumentParser(prog="stucktrace", description="Learning-trajectory reports from a saved log.")
16
+ p.add_argument("--version", action="version", version=f"stucktrace {__version__}")
17
+ sub = p.add_subparsers(dest="cmd", required=True)
18
+
19
+ r = sub.add_parser("report", help="generate a report from a .jsonl trajectory")
20
+ r.add_argument("path")
21
+ r.add_argument("--mode", choices=["student", "instructor"], default="student")
22
+ r.add_argument("--lang", choices=["en", "ru"], default="en")
23
+ r.add_argument("--offline", action="store_true", help="never call Hermes")
24
+ r.add_argument("-o", "--out", help="write Markdown to this file")
25
+
26
+ c = sub.add_parser("compress", help="print the compressed context")
27
+ c.add_argument("path")
28
+ c.add_argument("--format", choices=["json", "md", "prompt"], default="md")
29
+
30
+ m = sub.add_parser("moodle", help="export Moodle CSV/JSON")
31
+ m.add_argument("path")
32
+ m.add_argument("--format", choices=["csv", "json"], default="csv")
33
+
34
+ d = sub.add_parser("demo", help="run the 45-second end-to-end demo")
35
+ d.add_argument("--lang", choices=["en", "ru"], default="en")
36
+ d.add_argument("--hermes", action="store_true", help="try the Hermes API (falls back offline)")
37
+ d.add_argument("--pause", type=float, default=0.0, help="seconds to pause between demo steps")
38
+
39
+ a = p.parse_args(argv)
40
+ if a.cmd == "demo":
41
+ from .demo import run_demo
42
+ run_demo(lang=a.lang, backend="hermes" if a.hermes else "offline", pause=a.pause)
43
+ return 0
44
+ session = Session.load(a.path)
45
+ if a.cmd == "report":
46
+ rep = generate_report(a.mode, session=session, backend="offline" if a.offline else "auto", lang=a.lang)
47
+ if a.out:
48
+ rep.save(a.out)
49
+ print(rep._repr_markdown_())
50
+ if rep.warning:
51
+ print(f"\n[warning] {rep.warning}", file=sys.stderr)
52
+ elif a.cmd == "compress":
53
+ ctx = session.compress()
54
+ print({"json": ctx.to_json, "md": ctx.to_markdown, "prompt": ctx.to_prompt}[a.format]())
55
+ elif a.cmd == "moodle":
56
+ import json
57
+ ad = MoodleAdapter(user_id=session.metadata.get("student_id"))
58
+ ctx = session.compress()
59
+ print(ad.export_csv(ctx) if a.format == "csv" else json.dumps(ad.export_attempt_json(ctx), indent=2, ensure_ascii=False))
60
+ return 0
61
+
62
+
63
+ if __name__ == "__main__": # pragma: no cover
64
+ raise SystemExit(main())