Didactopus/docs/roadmap.md

Roadmap

This document summarizes the current prioritized improvement roadmap for Didactopus as a learner-facing system.

The ordering is intentional. The project should first strengthen the graph-grounded mentor loop that defines the real learner task, then use that stable backbone for local-model evaluation, accessibility work, and broader UX improvements.

Priorities

1. Graph-grounded conversational mentor loop

Status: in progress

Why first:

• It defines the actual learner-facing interaction Didactopus is trying to support.
• It makes later benchmarking and accessibility work target a real session model rather than an abstract idea.
• It uses the graph and source-corpus artifacts already present in the repository.

Near-term scope:

• continue strengthening the learner session backend
• make mentor, practice, and evaluator turns consistently source-grounded
• improve trust-preserving feedback behavior
• extend the session flow beyond one short interaction
• make scientific virtues operational in the session loop by separating observation from interpretation, preserving uncertainty, and rewarding justified revision
• replace stubbed provider output in learner-facing pilot flows with configured real model backends where available
• make learner-facing guidance explicitly distinction-aware:
  • A vs B
  • A does not imply B
  • B can occur without A

Current code anchors:

• didactopus.learner_session
• didactopus.learner_session_demo
• didactopus.graph_retrieval
• didactopus.ocw_rolemesh_transcript_demo

2. Local-model adequacy benchmark for constrained hardware

Status: planned

Why next:

• The learner loop should be benchmarked as soon as its task shape is stable.
• Adequate local models on low-cost hardware would materially improve access in underserved regions.
• Didactopus does not need a single perfect model; it needs role-adequate behavior.

Primary questions:

• Which models are adequate for mentor, practice, and evaluator roles?
• What latency, memory, and throughput are acceptable on Raspberry Pi-class hardware?
• Which roles can degrade gracefully to smaller models?

Expected outputs:

• benchmark tasks grounded in the MIT OCW pack
• per-role adequacy scores
• recommended deployment profiles for low-end, laptop, and stronger local systems

3. Accessibility-first learner interaction

Status: planned

Why high priority:

• Didactopus has clear potential for learners who do not have access to enough teachers or tutors.
• Blind learners and other accessibility-focused use cases benefit directly from structured, guided interaction.
• Voice and text accessibility can build on the same learner-session backend.

Target features:

• screen-reader-friendly learner output
• accessible HTML alternatives to purely visual artifacts
• text-first navigation of concept neighborhoods and progress
• explicit structural cues in explanations and feedback

4. Voice interaction with local STT and TTS

Status: planned

Why after accessibility baseline:

• The project should first ensure that the session structure is accessible in text.
• Voice interaction is more useful once the mentor loop and pending-response behavior are stable.

Target features:

• speech-to-text input for learner answers
• text-to-speech output for mentor, practice, and evaluator turns
• spoken waiting notices during slow local-model responses
• repeat, interrupt, and slow-down controls

5. Learner workbench UI

Status: pilot in progress

Why important:

• The repository has review-focused interfaces and generated artifacts, but the learner path is still fragmented.
• A dedicated learner workbench would make Didactopus more usable as a personal mentor rather than only a pipeline/demo system.

Target features:

• current concept and why-it-matters view
• prerequisite chain and supporting lessons
• grounded source excerpts
• definitions, constraints, and qualifications view
• quote candidates and source-trail view for argumentation workflows
• active practice task
• evaluator feedback
• recommended next step
• first external pilot should use the evidence-trail evo-edu pack as a learner-workbench test case

Current progress:

• the first external pilot pack now exists at domain-packs/evidence-trail/
• pack_to_frontend output is generated and copied into webui/public/packs/evidence-trail-pack.json
• the web UI now has a learner-workbench launcher and Evidence Trail pilot mode in addition to the review workbench
• the learner pilot exposes question, observation, interpretation, uncertainty, and revision-trigger fields directly in the UI
• scientific virtues are now reflected in the UI framing and in backend learner-session prompt construction
• the backend now exposes POST /api/learner-workbench/session
• end-to-end verification succeeded locally: the API starts, the endpoint returns structured concept/session output, and the frontend/backend contract is working

Immediate next steps:

• replace current stubbed mentor/practice/evaluator text with a configured real provider path
• enrich the Evidence Trail pack with grounded source fragments so returned guidance is based on more than pack metadata
• persist learner-session state instead of treating each call as a stateless step
• connect learner progress, evidence, and revision history to the standard backend session model
• define deployment notes for running the learner workbench against the local API outside development mode

Current pilot state:

• a backend learner-workbench path exists in didactopus.learner_workbench
• the API exposes POST /api/learner-workbench/session
• the web UI now has a launcher that separates review workbench from learner workbench
• the first pilot pack exists at domain-packs/evidence-trail/
• the frontend can load a static learner-pack payload from webui/public/packs/evidence-trail-pack.json
• the current pilot explicitly emphasizes question framing, observation versus interpretation, uncertainty, and revision

Next steps:

• connect the learner-workbench pilot more directly to the standard learner-session backend
• persist learner-workbench state instead of treating each step as a stateless interaction
• ground the pilot more deeply in source fragments instead of mostly pack-level structure
• decide which scientific-virtues framing belongs in the stable learner path versus remaining pilot-specific
• document a simple local run path for using the learner workbench outside ad hoc development

6. Adaptive diagnostics and practice refinement

Status: planned

Why this matters:

• Learners need clearer answers to “what am I weak at?” and “what should I do next?”
• The repository already has evidence and evaluator machinery that can be surfaced in learner terms.

Target features:

• weak-dimension summaries by concept
• misconception tracking
• remedial branch suggestions
• hint ladders and difficulty control
• oral, short-answer, and compare-and-contrast practice modes

7. Source-grounded citation transparency

Status: planned

Why it matters:

• Trust depends on showing what is grounded in source material and what is model inference.
• This is especially important for learners using local models with variable quality.

Target features:

• lesson and source-fragment references in explanations
• explicit distinction between cited source support and model inference
• easier inspection of concept-to-source provenance
• explicit quote marking and attribution in any public-facing output
• no unmarked source wording in public Notebook exposition

8. Notebook-centered knowledge layer

Status: planned

Why it matters:

• The Foundation Notebook pilot suggests that Didactopus needs one durable concept-network representation between raw source grounding and learner-facing products.
• Topic labels alone are too weak; broad explanatory hubs and first-ring concept neighborhoods work better.
• The Notebook is the right place to preserve definitions, constraints, qualifications, and contrasts.
• The pilot also suggests that the Notebook is the durable center between raw source-grounding work and learner-facing products, not just a supplemental static page format.

Target features:

• hub-first concept organization
• first-ring and second-ring concept neighborhoods
• first-class distinction modeling:
  • A vs B
  • A does not imply B
  • B can occur without A
• support for source-role weighting:
  • overview
  • mechanism
  • nuance
  • controversy
  • argumentation
• support for learner-significance cues so explanation and practice can answer “why does this distinction matter?”
• Notebook-adjacent secondary products:
  • definitions
  • qualifications
  • constraints
  • quote candidates
• separate rendering rules for Notebook, workbench, and public exposition

Immediate next steps:

• promote the Foundation Notebook pilot conclusions into the stable design model for Didactopus
• prefer broad explanatory hubs over narrow topic labels when organizing new Notebook regions
• make source-role-aware retrieval available to learner workbench flows
• treat secondary products as first-class review/export outputs rather than incidental metadata
• connect Notebook concept neighborhoods more directly to learner-session grounding and practice generation

9. Pack quality, review, and concept-graph curation improvements

Status: planned

Why later:

• These are important, but they mainly improve the quality of the learning substrate rather than the immediate learner interaction.
• The graph-first path should first prove out the learner experience it supports.

Target features:

• concept merge and split workflows
• alias handling across packs
• impact analysis for concept edits
• stronger review support for noisy or broad concepts
• improved source coverage QA

10. Incremental re-ingestion and course updates

Status: planned

Why useful:

• External course repositories are now part of the intended workflow.
• Didactopus should avoid full rebuilds when only part of a source tree changes.

Target features:

• changed-file detection
• stable concept and fragment IDs where possible
• graph and pack diffs
• preservation of learner evidence across source updates

11. Richer multimodal and notation support

Status: longer-term

Why longer-term:

• This work is valuable but more specialized and technically demanding than the earlier roadmap items.

Examples:

• spoken math rendering improvements
• diagram descriptions
• accessible handling of image-heavy source materials
• EPUB and other learner-friendly export targets

Guiding Principles

• Use the graph and source corpus before relying on model prior knowledge.
• Optimize for guided learning, not answer offloading.
• Prefer role-adequate local models over chasing a single best model.
• Keep accessibility and low-cost deployment in scope from the start, not as cleanup work.
• Preserve provenance and license compliance as first-class constraints.
• Advance the current roadmap without assuming abundant compute, fluent English, expert supervision, or mature learners.
• Treat scientific virtues as operational principles: encourage curiosity, honesty about evidence, skepticism toward weak claims, attentiveness to caveats, and revision when the evidence changes.
• Separate observation from interpretation in learner-facing guidance so the system does not blur grounded support with model inference.
• Frame revision as progress rather than as failure, especially in mentor and evaluator feedback.
• Preserve distinctions, caveats, and scope conditions as learning assets rather than treating them as noise.
• Treat the Notebook as the durable knowledge layer, but not as the only learner-facing representation.

Suggested Implementation Sequence

1. Strengthen didactopus.learner_session into the standard session backend.
2. Fold the learner-workbench pilot into that backend without losing its stronger study-state framing.
3. Add a Notebook-centered operating layer with hub concepts, distinctions, and secondary products.
4. Replace stubbed learner-workbench provider output with a configured real model backend.
5. Ground the evidence-trail pilot and future Notebook pilots in richer source fragments, definitions, constraints, and persisted learner state.
6. Build a small model-benchmark harness around the unified learner backend.
7. Add accessible learner HTML and text-first outputs.
8. Add local TTS and STT support to the same session flow.
9. Expand adaptive practice and diagnostics.
10. Improve review, impact analysis, and incremental update support.