diff --git a/README.md b/README.md index 51a1490..83372ed 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,19 @@ level, runs the tutoring session directly, remembers what you've mastered across sessions, and reviews your progress from the transcript. +![Generating a Rust mentor prompt](docs/images/terminal-prompt-rust.png) + +
+More screenshots and diagrams + +![How a field becomes a mentor session](docs/images/diagram-flow.svg) +![Curated field profiles](docs/images/terminal-fields.png) +![Supported providers](docs/images/terminal-providers.png) +![mentor doctor](docs/images/terminal-doctor.png) + +More in [docs/diagrams.md](docs/diagrams.md). +
+ [![CI](https://github.com/voidstackloop/expert-mentor/actions/workflows/ci.yml/badge.svg)](https://github.com/voidstackloop/expert-mentor/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/expert-mentor.svg)](https://pypi.org/project/expert-mentor/) [![Python versions](https://img.shields.io/pypi/pyversions/expert-mentor.svg)](https://pypi.org/project/expert-mentor/) diff --git a/docs/diagrams.md b/docs/diagrams.md new file mode 100644 index 0000000..6cc9291 --- /dev/null +++ b/docs/diagrams.md @@ -0,0 +1,98 @@ +# expert-mentor diagrams + +Rendered copies live in [`docs/images/`](images/). Related docs: +[commands](commands.md), [providers](providers.md), [learning](learning.md), +[configuration](configuration.md). + +## From field to mentor + +What happens between `mentor --field "Rust"` and a live session, and where the +learner's progress is kept afterwards. + +![expert-mentor flow](images/diagram-flow.svg) + +```mermaid +flowchart LR + subgraph IN["Learner input"] + F["--field · --level
--goal · --context
--style · --language"] + SAVED["saved mentor
mentor run rustbuddy"] + end + + subgraph BUILD["Prompt builder · expert_mentor.py"] + PROF["field profile
references/fields.json
concepts · misconceptions · anchors"] + TPL["templates/
mentor_system_prompt.md
compact_prompt.md"] + SHAPE["shape_prompt
markdown or XML · compact
for small local models"] + HIST["learner history
injected when --learner"] + end + + subgraph EMIT["Emit (no network)"] + TXT["text / markdown
paste into any chat"] + JSON["JSON request body"] + MF["Ollama Modelfile"] + end + + subgraph RT["Provider adapters · mentor_runtime.py (stdlib urllib, SSE streaming)"] + A["Claude
Messages API · thinking"] + O["OpenAI
reasoning effort"] + G["Gemini"] + OL["Ollama
localhost:11434"] + LC["llama.cpp / LM Studio
OpenAI-compatible"] + end + + SESS["mentor run
interactive session
intake → roadmap → teach/practice → consolidate"] + + subgraph MEM["~/.config/expert-mentor"] + TR["sessions/<ts>-<name>.md
transcript + metadata"] + LP["learners/<name>.json
mastered · shaky · misconceptions"] + CARDS["learners/<name>.cards.json
SM-2-lite schedule"] + end + + REV["mentor review
strict JSON assessment"] + QZ["mentor cards --generate
mentor quiz"] + + F --> PROF + SAVED --> PROF + PROF --> TPL --> SHAPE + HIST --> SHAPE + SHAPE --> TXT & JSON & MF + SHAPE --> SESS + SESS <--> A & O & G & OL & LC + SESS --> TR + TR --> REV --> LP + TR --> QZ --> CARDS + LP -. "--remember" .-> HIST +``` + +## A `mentor run --remember` session + +```mermaid +sequenceDiagram + autonumber + actor L as Learner + participant M as mentor CLI + participant P as Provider adapter + participant LLM as Model (cloud or local) + participant S as ~/.config/expert-mentor + + L->>M: mentor run --field Rust --provider claude --remember + M->>S: load learners/rust.json + M->>M: build system prompt + inject learner history + M->>P: stream(system, messages) + P->>LLM: HTTPS / localhost request + LLM-->>P: SSE chunks (text · thinking · usage) + P-->>L: streamed reply (Phase 1: intake) + loop teach / practice + L->>M: answer or exercise attempt + M->>P: history (last N turns) + new message + P->>LLM: request + LLM-->>L: feedback, next step + end + L->>M: /quit + M->>S: save transcript + metadata + Note over L,S: later, as separate commands + L->>M: mentor review rust --apply + M->>P: review prompt (strict JSON) + P->>LLM: assess latest transcript + LLM-->>M: mastered · shaky · misconceptions · next lesson + M->>S: merge into learners/rust.json +``` diff --git a/docs/images/diagram-flow.png b/docs/images/diagram-flow.png new file mode 100644 index 0000000..85703fe Binary files /dev/null and b/docs/images/diagram-flow.png differ diff --git a/docs/images/diagram-flow.svg b/docs/images/diagram-flow.svg new file mode 100644 index 0000000..acb6a09 --- /dev/null +++ b/docs/images/diagram-flow.svg @@ -0,0 +1,99 @@ +

~/.config/expert-mentor

Provider adapters · mentor_runtime.py (stdlib urllib, SSE streaming)

Emit (no network)

Prompt builder · expert_mentor.py

Learner input

--remember

--field · --level
--goal · --context
--style · --language

saved mentor
mentor run rustbuddy

field profile
references/fields.json
concepts · misconceptions · anchors

templates/
mentor_system_prompt.md
compact_prompt.md

shape_prompt
markdown or XML · compact
for small local models

learner history
injected when --learner

text / markdown
paste into any chat

JSON request body

Ollama Modelfile

Claude
Messages API · thinking

OpenAI
reasoning effort

Gemini

Ollama
localhost:11434

llama.cpp / LM Studio
OpenAI-compatible

mentor run
interactive session
intake → roadmap → teach/practice → consolidate

sessions/<ts>-<name>.md
transcript + metadata

learners/<name>.json
mastered · shaky · misconceptions

learners/<name>.cards.json
SM-2-lite schedule

mentor review
strict JSON assessment

mentor cards --generate
mentor quiz

 \ No newline at end of file diff --git a/docs/images/diagram-session-sequence.png b/docs/images/diagram-session-sequence.png new file mode 100644 index 0000000..330676c Binary files /dev/null and b/docs/images/diagram-session-sequence.png differ diff --git a/docs/images/diagram-session-sequence.svg b/docs/images/diagram-session-sequence.svg new file mode 100644 index 0000000..11d84e1 --- /dev/null +++ b/docs/images/diagram-session-sequence.svg @@ -0,0 +1,99 @@ +~/.config/expert-mentorModel (cloud or local)Provider adaptermentor CLI~/.config/expert-mentorModel (cloud or local)Provider adaptermentor CLIloop[teach / practice]later, as separate commandsLearnermentor run --field Rust --provider claude --remember1load learners/rust.json2build system prompt + inject learner history3stream(system, messages)4HTTPS / localhost request5SSE chunks (text · thinking · usage)6streamed reply (Phase 1: intake)7answer or exercise attempt8history (last N turns) + new message9request10feedback, next step11/quit12save transcript + metadata13mentor review rust --apply14review prompt (strict JSON)15assess latest transcript16mastered · shaky · misconceptions · next lesson17merge into learners/rust.json18Learner \ No newline at end of file diff --git a/docs/images/terminal-doctor.png b/docs/images/terminal-doctor.png new file mode 100644 index 0000000..e54a70b Binary files /dev/null and b/docs/images/terminal-doctor.png differ diff --git a/docs/images/terminal-fields.png b/docs/images/terminal-fields.png new file mode 100644 index 0000000..8cfc372 Binary files /dev/null and b/docs/images/terminal-fields.png differ diff --git a/docs/images/terminal-prompt-rust.png b/docs/images/terminal-prompt-rust.png new file mode 100644 index 0000000..8d51050 Binary files /dev/null and b/docs/images/terminal-prompt-rust.png differ diff --git a/docs/images/terminal-providers.png b/docs/images/terminal-providers.png new file mode 100644 index 0000000..2196068 Binary files /dev/null and b/docs/images/terminal-providers.png differ