497 lines
16 KiB
Markdown
497 lines
16 KiB
Markdown
# Didactopus
|
|
|
|
|
|
|
|
Didactopus is a local-first Python codebase for turning educational source material into structured learning domains, evaluating learner progress against those domains, and exporting review, mastery, and skill artifacts.
|
|
|
|
Its intended use is closer to a structured mentor or self-study workbench than a "do my assignment for me" engine. The project should help learners get guidance, sequencing, feedback, and explanation without encouraging the offloading effect that comes from unstructured GenAI use.
|
|
|
|
At a high level, the repository does five things:
|
|
|
|
1. Ingest source material such as Markdown, text, HTML, PDF-ish text, DOCX-ish text, and PPTX-ish text into normalized course/topic structures.
|
|
2. Distill those structures into draft domain packs with concepts, prerequisites, roadmaps, projects, attribution, and review flags.
|
|
3. Validate, review, and promote those draft packs through a workspace-backed review flow.
|
|
4. Build merged learning graphs, rank next concepts, accumulate learner evidence, and export capability profiles.
|
|
5. Demonstrate end-to-end flows, including an MIT OCW Information and Entropy demo that produces a pack, learner outputs, a reusable skill bundle, and progress visualizations.
|
|
|
|
## Start Here If You Just Want To Learn
|
|
|
|
If you only want the shortest path to "show me Didactopus helping someone learn," run:
|
|
|
|
```bash
|
|
pip install -e .
|
|
python -m didactopus.ocw_information_entropy_demo
|
|
python -m didactopus.learner_session_demo
|
|
python -m didactopus.ocw_progress_viz
|
|
python -m didactopus.ocw_skill_agent_demo
|
|
```
|
|
|
|
Then open:
|
|
|
|
- `examples/ocw-information-entropy-run/learner_progress.html`
|
|
- `examples/ocw-information-entropy-session.json`
|
|
- `examples/ocw-information-entropy-session.html`
|
|
- `examples/ocw-information-entropy-session.txt`
|
|
- `examples/ocw-information-entropy-skill-demo/skill_demo.md`
|
|
- `examples/ocw-information-entropy-rolemesh-transcript/rolemesh_transcript.md`
|
|
- `skills/ocw-information-entropy-agent/`
|
|
|
|
That gives you:
|
|
|
|
- a generated topic pack
|
|
- a graph-grounded mentor/practice/evaluator learner session
|
|
- accessible HTML and text-first learner-session outputs
|
|
- a visible learning path
|
|
- progress artifacts
|
|
- a reusable skill grounded in the exported knowledge
|
|
- a transcript showing how a local-LLM-backed learner/mentor interaction can look
|
|
|
|
The point is not to replace your effort. The point is to give your effort structure, feedback, and momentum.
|
|
|
|
If that is your use case, read the next section, `Fast Start For Impatient Autodidacts`, and skip the deeper architecture sections until you need them.
|
|
|
|
## Fast Start For Impatient Autodidacts
|
|
|
|
If your real question is "How quickly can I get this to help me learn something?", use one of these paths.
|
|
|
|
### Fastest path: use the included MIT OCW demo
|
|
|
|
This is the shortest route to seeing the whole system work as a personal mentor scaffold.
|
|
|
|
1. Install the repo:
|
|
|
|
```bash
|
|
pip install -e .
|
|
```
|
|
|
|
2. Generate the demo pack, learner outputs, and reusable skill:
|
|
|
|
```bash
|
|
python -m didactopus.ocw_information_entropy_demo
|
|
```
|
|
|
|
3. Render the learner progress views:
|
|
|
|
```bash
|
|
python -m didactopus.learner_session_demo
|
|
python -m didactopus.ocw_progress_viz
|
|
python -m didactopus.ocw_progress_viz --full-map
|
|
```
|
|
|
|
4. Run the "agent uses the learned skill" demo:
|
|
|
|
```bash
|
|
python -m didactopus.ocw_skill_agent_demo
|
|
```
|
|
|
|
After that, inspect:
|
|
|
|
- `examples/ocw-information-entropy-run/`
|
|
- `examples/ocw-information-entropy-skill-demo/`
|
|
- `skills/ocw-information-entropy-agent/`
|
|
|
|
What you get:
|
|
|
|
- a domain pack for the topic
|
|
- a guided curriculum path
|
|
- a deterministic learner run over that path
|
|
- a graph-grounded learner session with mentor, practice, evaluation, and next-step turns
|
|
- a capability export
|
|
- a reusable skill bundle
|
|
- visual progress artifacts
|
|
- an optional local-LLM learner/mentor transcript path via RoleMesh
|
|
|
|
This is the best "show me why this is fun" path in the current repo.
|
|
|
|
### Fast custom path: turn one markdown file into a draft learning domain
|
|
|
|
If you already have notes, a syllabus, or a course outline, the lightest custom workflow is:
|
|
|
|
1. Put the material in a Markdown or text file.
|
|
2. Adapt and ingest it through the course/topic pipeline.
|
|
3. Emit a draft pack.
|
|
4. Review only what matters.
|
|
|
|
The easiest reference for this flow is the OCW demo source tree:
|
|
|
|
- `examples/ocw-information-entropy/course/`
|
|
|
|
Use it as a template for your own topic, then follow the same pattern implemented in:
|
|
|
|
- `didactopus.ocw_information_entropy_demo`
|
|
|
|
### If you want a mentor more than a curation tool
|
|
|
|
Treat Didactopus as a loop:
|
|
|
|
1. Start from one topic you genuinely care about.
|
|
2. Generate a draft pack quickly, even if it is imperfect.
|
|
3. Keep only the concepts and progression that feel useful.
|
|
4. Use the resulting pack and skill outputs to drive explanations, study plans, and self-checks.
|
|
|
|
The important idea is not "perfect ingestion first." It is "usable learning structure fast enough that you keep going."
|
|
|
|
### If you are using it alongside coursework
|
|
|
|
The intended pattern is:
|
|
|
|
1. Use Didactopus to clarify the topic map and prerequisites.
|
|
2. Ask it for hints, sequencing, comparisons, and self-check prompts.
|
|
3. Use its outputs to diagnose where you are weak.
|
|
4. Still do the actual writing, solving, and explaining yourself.
|
|
|
|
That is the difference between assisted learning and offloading. Didactopus should help you think better, not quietly substitute for your thinking.
|
|
|
|
### Current friction honestly stated
|
|
|
|
The lowest-friction path is the included demo. The custom path still asks you to be comfortable with:
|
|
|
|
- running Python commands locally
|
|
- editing or preparing a source file
|
|
- accepting heuristic extraction noise
|
|
- reviewing draft outputs before trusting them
|
|
|
|
Didactopus is already good at reducing the activation energy from "pile of source material" to "coherent learning structure," but it is not yet a one-click end-user tutor product.
|
|
|
|
### Why use it anyway?
|
|
|
|
Because it can make learning feel more like building a visible map of mastery than passively consuming material.
|
|
|
|
Instead of only reading notes, you can get:
|
|
|
|
- a concept graph
|
|
- a staged path
|
|
- explicit prerequisites
|
|
- evidence-aware progress artifacts
|
|
- reusable skill outputs for future tutoring or evaluation
|
|
|
|
In the best case, that makes learning feel more like active skill-building and less like either passive consumption or answer outsourcing.
|
|
|
|
### Current learner-session backbone
|
|
|
|
The main mentor-style backend now has a dedicated demo entry point:
|
|
|
|
```bash
|
|
python -m didactopus.learner_session_demo
|
|
python -m didactopus.learner_session_demo --language es
|
|
```
|
|
|
|
That demo builds a graph-grounded session from the MIT OCW skill bundle and emits:
|
|
|
|
- a learner goal
|
|
- a grounded mentor response
|
|
- a practice prompt
|
|
- evaluator feedback
|
|
- a recommended next step
|
|
|
|
The learner-facing CLI now treats language as a first-class parameter, so the same session flow can target another output language while preserving the English source-grounding context.
|
|
|
|
The point of this module is architectural as much as demonstrational: it is the session core that future accessibility, model-benchmark, and voice-interaction work should build on.
|
|
|
|
The learner-session demo also writes accessible companion outputs:
|
|
|
|
- `examples/ocw-information-entropy-session.html`
|
|
- `examples/ocw-information-entropy-session.txt`
|
|
|
|
The first benchmark harness for that session core is now:
|
|
|
|
```bash
|
|
python -m didactopus.model_bench
|
|
```
|
|
|
|
It evaluates local-model adequacy for the `mentor`, `practice`, and `evaluator` roles using the MIT OCW skill bundle as grounded context.
|
|
|
|
There is also now a Didactopus-specific arena for comparing provider/model/prompt combinations:
|
|
|
|
```bash
|
|
python -m didactopus.arena --arena-spec configs/arena.example.yaml
|
|
```
|
|
|
|
That produces rankings, a human review queue, and an optional LLM-written comparative summary for reviewer triage.
|
|
|
|
### Easiest LLM setup paths
|
|
|
|
If you want live LLM-backed Didactopus behavior without the complexity of RoleMesh, start with one of these:
|
|
|
|
1. `ollama` for simple local use
|
|
2. `openai_compatible` for simple hosted use
|
|
3. `rolemesh` only if you need routing and multi-model orchestration
|
|
|
|
The two low-friction starting configs are:
|
|
|
|
- `configs/config.ollama.example.yaml`
|
|
- `configs/config.openai-compatible.example.yaml`
|
|
|
|
For setup details, see:
|
|
|
|
- `docs/model-provider-setup.md`
|
|
|
|
## What Is In This Repository
|
|
|
|
- `src/didactopus/`
|
|
The application and library code.
|
|
- `tests/`
|
|
The automated test suite.
|
|
- `domain-packs/`
|
|
Example and generated domain packs.
|
|
- `examples/`
|
|
Sample source inputs and generated outputs.
|
|
- `skills/`
|
|
Repo-local skill bundles generated from knowledge products.
|
|
- `webui/`
|
|
A local review/workbench frontend scaffold.
|
|
- `docs/`
|
|
Focused design and workflow notes.
|
|
|
|
## Core Workflows
|
|
|
|
### 1. Course and topic ingestion
|
|
|
|
The ingestion path converts source documents into `NormalizedDocument`, `NormalizedCourse`, and `TopicBundle` objects, then emits a draft pack.
|
|
|
|
Main modules:
|
|
|
|
- `didactopus.document_adapters`
|
|
- `didactopus.course_ingest`
|
|
- `didactopus.topic_ingest`
|
|
- `didactopus.rule_policy`
|
|
- `didactopus.pack_emitter`
|
|
|
|
Primary outputs:
|
|
|
|
- `pack.yaml`
|
|
- `concepts.yaml`
|
|
- `roadmap.yaml`
|
|
- `projects.yaml`
|
|
- `rubrics.yaml`
|
|
- `review_report.md`
|
|
- `conflict_report.md`
|
|
- `license_attribution.json`
|
|
- `pack_compliance_manifest.json` when a source inventory is provided
|
|
|
|
### 2. Review and workspace management
|
|
|
|
Draft packs can be brought into review workspaces, edited, and promoted to reviewed packs.
|
|
|
|
Main modules:
|
|
|
|
- `didactopus.review_schema`
|
|
- `didactopus.review_loader`
|
|
- `didactopus.review_actions`
|
|
- `didactopus.review_export`
|
|
- `didactopus.workspace_manager`
|
|
- `didactopus.review_bridge`
|
|
- `didactopus.review_bridge_server`
|
|
|
|
Key capabilities:
|
|
|
|
- create and list workspaces
|
|
- preview draft-pack imports
|
|
- import draft packs with overwrite checks
|
|
- save review actions
|
|
- export promoted packs
|
|
- export `review_data.json` for the frontend
|
|
|
|
### 3. Learning graph and planning
|
|
|
|
Validated packs can be merged into a namespaced DAG, including explicit overrides and stage/project catalogs.
|
|
|
|
Main modules:
|
|
|
|
- `didactopus.artifact_registry`
|
|
- `didactopus.learning_graph`
|
|
- `didactopus.graph_builder`
|
|
- `didactopus.concept_graph`
|
|
- `didactopus.planner`
|
|
- `didactopus.adaptive_engine`
|
|
|
|
Key capabilities:
|
|
|
|
- dependency validation for packs
|
|
- merged prerequisite DAG construction
|
|
- roadmap generation from merged stages
|
|
- graph-aware next-concept ranking
|
|
- adaptive plan generation from current mastery
|
|
|
|
### 4. Evidence, mastery, and capability export
|
|
|
|
Learner progress is represented as evidence summaries plus exported capability artifacts.
|
|
|
|
Main modules:
|
|
|
|
- `didactopus.evidence_engine`
|
|
- `didactopus.evaluator_pipeline`
|
|
- `didactopus.progression_engine`
|
|
- `didactopus.mastery_ledger`
|
|
- `didactopus.knowledge_export`
|
|
|
|
Key capabilities:
|
|
|
|
- weighted evidence ingestion
|
|
- confidence estimation
|
|
- multidimensional mastery checks
|
|
- resurfacing weak concepts
|
|
- capability profile JSON export
|
|
- markdown capability reports
|
|
- artifact manifests
|
|
|
|
### 5. Local model integration
|
|
|
|
Didactopus can now target a RoleMesh Gateway-backed local LLM setup through its `ModelProvider` abstraction.
|
|
|
|
Main modules:
|
|
|
|
- `didactopus.model_provider`
|
|
- `didactopus.role_prompts`
|
|
- `didactopus.rolemesh_demo`
|
|
|
|
What this enables:
|
|
|
|
- role-based local model routing
|
|
- separate mentor/practice/project-advisor/evaluator prompts
|
|
- local heterogeneous compute usage through an OpenAI-compatible gateway
|
|
- a clean path to keep tutoring assistance structured instead of offloading learner work
|
|
|
|
### 6. Agentic learner demos and visualization
|
|
|
|
The repository includes deterministic agentic demos rather than a live external model integration.
|
|
|
|
Main modules:
|
|
|
|
- `didactopus.agentic_loop`
|
|
- `didactopus.ocw_information_entropy_demo`
|
|
- `didactopus.ocw_progress_viz`
|
|
|
|
Generated demo artifacts:
|
|
|
|
- `domain-packs/mit-ocw-information-entropy/`
|
|
- `examples/ocw-information-entropy-run/`
|
|
- `skills/ocw-information-entropy-agent/`
|
|
|
|
## Quick Start
|
|
|
|
### Install
|
|
|
|
```bash
|
|
pip install -e .
|
|
```
|
|
|
|
### Run tests
|
|
|
|
```bash
|
|
pytest
|
|
```
|
|
|
|
### Generate the MIT OCW demo pack, learner outputs, and skill bundle
|
|
|
|
```bash
|
|
python -m didactopus.ocw_information_entropy_demo
|
|
```
|
|
|
|
This writes:
|
|
|
|
- `domain-packs/mit-ocw-information-entropy/`
|
|
- `examples/ocw-information-entropy-run/`
|
|
- `skills/ocw-information-entropy-agent/`
|
|
|
|
The generated MIT OCW pack also includes:
|
|
|
|
- `license_attribution.json`
|
|
- `pack_compliance_manifest.json`
|
|
- `source_inventory.yaml`
|
|
|
|
### Try the local RoleMesh integration path
|
|
|
|
Stubbed local-provider demo:
|
|
|
|
```bash
|
|
python -m didactopus.rolemesh_demo --config configs/config.example.yaml
|
|
```
|
|
|
|
RoleMesh-backed example config:
|
|
|
|
```bash
|
|
python -m didactopus.rolemesh_demo --config configs/config.rolemesh.example.yaml
|
|
```
|
|
|
|
MIT OCW learner transcript through the local-LLM path:
|
|
|
|
```bash
|
|
python -m didactopus.ocw_rolemesh_transcript_demo --config configs/config.rolemesh.example.yaml
|
|
```
|
|
|
|
If your local models are slow, Didactopus now prints pending-status lines while each mentor, practice, learner, or evaluator turn is being generated. For a long manual run, capture both the transcript payload and those live status messages:
|
|
|
|
```bash
|
|
python -u -m didactopus.ocw_rolemesh_transcript_demo \
|
|
--config configs/config.rolemesh.example.yaml \
|
|
--out-dir examples/ocw-information-entropy-rolemesh-transcript \
|
|
2>&1 | tee examples/ocw-information-entropy-rolemesh-transcript/manual-run.log
|
|
```
|
|
|
|
That command leaves the final transcript in `rolemesh_transcript.md` and `rolemesh_transcript.json`, while `manual-run.log` preserves the conversational “working on it” notices during the wait.
|
|
|
|
### Render learner progress visualizations
|
|
|
|
Path-focused view:
|
|
|
|
```bash
|
|
python -m didactopus.ocw_progress_viz
|
|
```
|
|
|
|
Full concept map including noisy non-path concepts:
|
|
|
|
```bash
|
|
python -m didactopus.ocw_progress_viz --full-map
|
|
```
|
|
|
|
### Run the review bridge server
|
|
|
|
```bash
|
|
python -m didactopus.review_bridge_server
|
|
```
|
|
|
|
The default config file is `configs/config.example.yaml`.
|
|
|
|
## Current State
|
|
|
|
This repository is functional, but parts of it remain intentionally heuristic.
|
|
|
|
What is solid:
|
|
|
|
- pack validation and dependency checks
|
|
- review-state export and workspace import flow
|
|
- merged learning graph construction
|
|
- weighted evidence and capability exports
|
|
- deterministic agentic demo runs
|
|
- generated skill bundles and progress visualizations
|
|
|
|
What remains heuristic or lightweight:
|
|
|
|
- document adapters for binary formats are simplified text adapters
|
|
- concept extraction can produce noisy candidate terms
|
|
- evaluator outputs are heuristic rather than formal assessments
|
|
- the agentic learner loop uses synthetic attempts
|
|
- the frontend and bridge flow are local-first scaffolds, not a hosted product
|
|
|
|
## Recommended Reading
|
|
|
|
- [docs/roadmap.md](docs/roadmap.md)
|
|
- [docs/arena.md](docs/arena.md)
|
|
- [docs/learner-accessibility.md](docs/learner-accessibility.md)
|
|
- [docs/local-model-benchmark.md](docs/local-model-benchmark.md)
|
|
- [docs/model-provider-setup.md](docs/model-provider-setup.md)
|
|
- [docs/course-to-pack.md](docs/course-to-pack.md)
|
|
- [docs/learning-graph.md](docs/learning-graph.md)
|
|
- [docs/agentic-learner-loop.md](docs/agentic-learner-loop.md)
|
|
- [docs/mastery-ledger.md](docs/mastery-ledger.md)
|
|
- [docs/workspace-manager.md](docs/workspace-manager.md)
|
|
- [docs/interactive-review-ui.md](docs/interactive-review-ui.md)
|
|
- [docs/mit-ocw-course-guide.md](docs/mit-ocw-course-guide.md)
|
|
- [docs/rolemesh-integration.md](docs/rolemesh-integration.md)
|
|
- [docs/faq.md](docs/faq.md)
|
|
|
|
## MIT OCW Demo Notes
|
|
|
|
The MIT OCW Information and Entropy demo is grounded in the MIT OpenCourseWare course page and selected unit/readings metadata, then converted into a local course source file for reproducible ingestion. The resulting generated pack and learner outputs are intentionally reviewable rather than presented as authoritative course mirrors.
|