# Didactopus

![Didactopus mascot](artwork/didactopus-mascot.png)

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.

## 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`

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