ai-report v0.1.2
subsystem education.ctf
capsule://capsule-examples/ai-report@0.1.2
Subscribes to lab lifecycle events, collects per-student behavior
traces (commands tried, files touched, errors hit), and generates a
natural-language progress report for the instructor at the end of a
lab session.
Owns
- per-lab behavior trace storage
- LLM-backed report generation pipeline
- instructor-facing report HTTP API
Does not own
- container lifecycle (see lab-runtime-docker)
- authentication (see auth-core)
- grading or scoring (the scoreboard capsule consumes reports, doesn't live here)
AI orientation
You are looking at ai-report. It is downstream of lab-runtime-docker and
auth-core. It consumes lab.* events, never reaches into lab containers
directly. Reports are drafted by an LLM — treat that LLM as untrusted:
sanitize trace inputs before prompting, and never echo back arbitrary
student input as instructions.
Avoid
- Calling Docker or the lab runtime directly; subscribe to events.
- Persisting raw LLM prompts in instructor-readable storage (might leak other students' data).
Extension points
trace-redactoratsrc/aireport/redact.py:redact- Pure function (trace_event) -> trace_event with secrets removed.
Called before any LLM prompting.
Provides
http_api:ai-report-read
Requires
event:lab.createdfromlab-runtime-docker(>=0.2 <1.0)event:lab.destroyedfromlab-runtime-docker(>=0.2 <1.0)http_api:auth-introspectfromauth-core(>=0.2 <1.0)env:AI_REPORT_LLM_API_KEY— API key for the LLM used to draft reports.
Dependencies
Capsules
lab-runtime-docker>=0.2.0 <1.0.0auth-core>=0.2.0 <1.0.0
Runtime
python>=3.11
Invariants (must always hold)
- One student's trace must never appear in another student's report.
- Reports must not include raw LLM API keys, even if a trace did.
- Report generation must be idempotent for a given (student_id, lab_id).
Glossary
trace- an append-only log of student actions within one lab session
report- an instructor-facing natural-language summary derived from a trace