460 lines
14 KiB
Markdown
460 lines
14 KiB
Markdown
# Didactopus
|
|
|
|
|
|
|
|
Didactopus is a local-first educational workbench for turning source material into structured learning domains, grounding tutoring and evaluation in those domains, and exporting knowledge products that other AI systems can use as a skill.
|
|
|
|
The short version is:
|
|
|
|
- ingest a course, topic outline, or notes
|
|
- build a concept graph and learning path
|
|
- review and improve that structure
|
|
- use it to support guided human learning
|
|
- export grounded knowledge products for AI use
|
|
|
|
## Project Description
|
|
|
|
Didactopus sits between raw educational material and both human and AI learning activity.
|
|
|
|
It is not meant to be a "do the assignment for me" system. Its intended role is closer to a structured mentor, pedagogy workbench, and knowledge-grounding layer. The aim is to reduce confusion, improve sequencing, and make learning more visible without encouraging answer offloading.
|
|
|
|
At a high level, the repository does six 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 packs through a workspace-backed review flow.
|
|
4. Build learning graphs, learner sessions, evidence summaries, and capability exports.
|
|
5. Support grounded LLM-backed mentor, practice, and evaluator behavior.
|
|
6. Export reusable knowledge products and skills from grounded learning artifacts.
|
|
|
|
## Design And Teaching Philosophy
|
|
|
|
Didactopus is built around a few core ideas:
|
|
|
|
- learning should stay effortful for the learner
|
|
- guidance should be structured, grounded, and inspectable
|
|
- source material should matter more than model prior knowledge
|
|
- explanations, critique, and next-step advice should preserve learner trust
|
|
- local and low-cost deployment matter for access
|
|
|
|
In practice, that means Didactopus tries to help with:
|
|
|
|
- topic structure
|
|
- prerequisite visibility
|
|
- study sequencing
|
|
- grounded explanation
|
|
- practice design
|
|
- evaluator feedback
|
|
- capability and progress artifacts
|
|
|
|
It explicitly tries not to become a silent answer surrogate.
|
|
|
|
The project is also being advanced with a future-compatibility constraint: avoid choices that assume abundant compute, fluent English, expert supervision, or only mature learners. That keeps the current roadmap moving while preserving eventual usefulness for more constrained and equity-sensitive educational settings.
|
|
|
|
## Who It Is For
|
|
|
|
Didactopus has several real audiences:
|
|
|
|
- autodidacts who want a structured mentor scaffold for a topic
|
|
- students who want help understanding coursework without outsourcing the work
|
|
- instructors, tutors, and curriculum designers who want reviewable concept structures
|
|
- technically oriented users who want local, grounded LLM support
|
|
- libraries, labs, and other shared-resource settings that may want a more advanced local inference stack
|
|
|
|
The repo currently serves the technically comfortable user best, but the design direction is broader: grounded, accessible educational support that can work for a single learner or in a shared institutional setting.
|
|
|
|
## Brief Roadmap
|
|
|
|
Current priorities are:
|
|
|
|
1. graph-grounded learner sessions
|
|
2. local-model adequacy benchmarking
|
|
3. multilingual grounded learner support
|
|
4. accessibility-first learner outputs
|
|
5. arena-based comparison of model, prompt, and language choices
|
|
|
|
The live detailed roadmap is in:
|
|
|
|
- `docs/roadmap.md`
|
|
- `docs/multilingual-qa.md`
|
|
|
|
Didactopus can also generate a starter multilingual QA draft from a pack:
|
|
|
|
```bash
|
|
python -m didactopus.multilingual_qa_seed domain-packs/mit-ocw-information-entropy
|
|
```
|
|
|
|
## Start Here If You Just Want To Learn
|
|
|
|
If your main question is "how quickly can this help me learn something?", start here:
|
|
|
|
```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`
|
|
- `skills/ocw-information-entropy-agent/`
|
|
|
|
That path gives you:
|
|
|
|
- a generated domain pack
|
|
- a graph-grounded learner session
|
|
- accessible HTML and text outputs
|
|
- a visible mastery path
|
|
- a capability export
|
|
- a reusable grounded skill
|
|
|
|
The point is not to replace your effort. The point is to give your effort structure, feedback, and momentum.
|
|
|
|
## Basic Learner Use Case
|
|
|
|
The simplest Didactopus pattern for a human learner is:
|
|
|
|
1. Start from a topic or course source.
|
|
2. Generate a draft pack and path quickly.
|
|
3. Use the learner session to get explanation, practice, and feedback.
|
|
4. Review only the obvious extraction noise.
|
|
5. Keep learning with the grounded structure instead of starting every time from a blank prompt.
|
|
|
|
For the fastest included example, use the MIT OCW Information and Entropy demo. It is the current end-to-end reference flow for:
|
|
|
|
- course ingestion
|
|
- graph construction
|
|
- learner session generation
|
|
- progress visualization
|
|
- skill export
|
|
|
|
## Didactopus As Pedagogy Support
|
|
|
|
Didactopus is broader than a learner chat loop.
|
|
|
|
It is also meant to support the pedagogy around learning:
|
|
|
|
- building and reviewing concept structures
|
|
- checking prerequisite logic
|
|
- generating and comparing practice tasks
|
|
- evaluating explanations with trust-preserving critique
|
|
- exporting evidence and capability artifacts
|
|
- supporting multilingual and accessible outputs
|
|
|
|
This is why the repository contains review workspaces, validation flows, knowledge graphs, and capability export machinery rather than only a chat interface.
|
|
|
|
## Grounded AI Learner And Skill Production
|
|
|
|
Didactopus can also produce grounded knowledge products that other AI systems can use.
|
|
|
|
The current repo demonstrates:
|
|
|
|
- generating a grounded domain pack from MIT OCW-derived material
|
|
- running deterministic and LLM-backed learner-style flows over that pack
|
|
- exporting capability and artifact summaries
|
|
- packaging those artifacts into a reusable skill bundle
|
|
|
|
The key idea is that the AI skill should come from the reviewed knowledge product, not from an ungrounded prompt alone.
|
|
|
|
The main demo commands are:
|
|
|
|
```bash
|
|
python -m didactopus.ocw_information_entropy_demo
|
|
python -m didactopus.learner_session_demo --language es
|
|
python -m didactopus.ocw_skill_agent_demo
|
|
python -m didactopus.model_bench
|
|
python -m didactopus.arena --arena-spec configs/arena.example.yaml
|
|
```
|
|
|
|
## 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
|
|
|
|
Low-friction starting configs:
|
|
|
|
- `configs/config.ollama.example.yaml`
|
|
- `configs/config.openai-compatible.example.yaml`
|
|
|
|
Setup docs:
|
|
|
|
- `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.
|