welsberr
/
Didactopus
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Didactopus/README.md

6.1 KiB
Raw Blame History

Didactopus

Didactopus mascot

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.

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.

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

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. 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

pip install -e .

Run tests

pytest

Generate the MIT OCW demo pack, learner outputs, and skill bundle

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/

Render learner progress visualizations

Path-focused view:

python -m didactopus.ocw_progress_viz

Full concept map including noisy non-path concepts:

python -m didactopus.ocw_progress_viz --full-map

Run the review bridge server

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

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.