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 +50 -0
- stucktrace/__main__.py +3 -0
- stucktrace/_version.py +1 -0
- stucktrace/adapters.py +501 -0
- stucktrace/cli.py +64 -0
- stucktrace/compressor.py +405 -0
- stucktrace/demo.py +130 -0
- stucktrace/events.py +38 -0
- stucktrace/reporter.py +104 -0
- stucktrace/tracker.py +440 -0
- stucktrace-0.1.0.dist-info/METADATA +305 -0
- stucktrace-0.1.0.dist-info/RECORD +16 -0
- stucktrace-0.1.0.dist-info/WHEEL +5 -0
- stucktrace-0.1.0.dist-info/entry_points.txt +2 -0
- stucktrace-0.1.0.dist-info/licenses/LICENSE +21 -0
- stucktrace-0.1.0.dist-info/top_level.txt +1 -0
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
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())
|