expert-mentor 0.6.0__tar.gz

expert_mentor-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 expert-mentor contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

expert_mentor-0.6.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: expert-mentor
+Version: 0.6.0
+Summary: Turn any LLM (Claude, ChatGPT, Gemini, Ollama, llama.cpp) into a professional teacher for any field.
+Author: expert-mentor contributors
+License: MIT
+Project-URL: Homepage, https://github.com/voidstackloop/expert-mentor
+Project-URL: Repository, https://github.com/voidstackloop/expert-mentor
+Project-URL: Issues, https://github.com/voidstackloop/expert-mentor/issues
+Project-URL: Changelog, https://github.com/voidstackloop/expert-mentor/releases
+Project-URL: PyPI, https://pypi.org/project/expert-mentor/
+Keywords: llm,mentor,tutor,education,claude,chatgpt,ollama,prompt
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Education
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# expert-mentor
+
+Turn any capable LLM — Claude, ChatGPT, Gemini, or a local Ollama / llama.cpp
+model — into a **professional teacher for any field**.
+
+`expert-mentor` generates a calibrated expert-mentor system prompt for a given
+field and level, runs the tutoring session directly, remembers what the learner
+has mastered across sessions, and assesses progress from the transcript.
+
+## Highlights
+
+- **Provider-native prompts** — XML-shaped, prompt-cached system blocks for
+  Claude; `developer` role, `max_completion_tokens`, and `reasoning_effort` for
+  ChatGPT reasoning models.
+- **Live sessions** over Anthropic, OpenAI, Ollama, and llama.cpp (standard
+  library only, no `pip install` needed to run).
+- **Persistent learner memory** — mastered / shaky / misconceptions / open
+  questions, injected into every future session.
+- **Model-assisted review** — turn a session transcript into an updated profile.
+- **Curriculum design**, saved mentors, live model discovery, and a config file.
+- **Zero runtime dependencies**; Python 3.8+.
+
+## Install
+
+```bash
+pipx install expert-mentor      # or: pip install expert-mentor
+mentor --field "quantum computing" --level beginner
+```
+
+## Quick start
+
+```bash
+mentor run --field "Rust" --provider claude --remember
+mentor curriculum --field "Rust" --duration "6 weeks"
+mentor fields
+```
+
+MIT licensed.

expert_mentor-0.6.0/pyproject.toml

@@ -0,0 +1,98 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "expert-mentor"
+description = "Turn any LLM (Claude, ChatGPT, Gemini, Ollama, llama.cpp) into a professional teacher for any field."
+readme = { content-type = "text/markdown", text = """
+# expert-mentor
+
+Turn any capable LLM — Claude, ChatGPT, Gemini, or a local Ollama / llama.cpp
+model — into a **professional teacher for any field**.
+
+`expert-mentor` generates a calibrated expert-mentor system prompt for a given
+field and level, runs the tutoring session directly, remembers what the learner
+has mastered across sessions, and assesses progress from the transcript.
+
+## Highlights
+
+- **Provider-native prompts** — XML-shaped, prompt-cached system blocks for
+  Claude; `developer` role, `max_completion_tokens`, and `reasoning_effort` for
+  ChatGPT reasoning models.
+- **Live sessions** over Anthropic, OpenAI, Ollama, and llama.cpp (standard
+  library only, no `pip install` needed to run).
+- **Persistent learner memory** — mastered / shaky / misconceptions / open
+  questions, injected into every future session.
+- **Model-assisted review** — turn a session transcript into an updated profile.
+- **Curriculum design**, saved mentors, live model discovery, and a config file.
+- **Zero runtime dependencies**; Python 3.8+.
+
+## Install
+
+```bash
+pipx install expert-mentor      # or: pip install expert-mentor
+mentor --field "quantum computing" --level beginner
+```
+
+## Quick start
+
+```bash
+mentor run --field "Rust" --provider claude --remember
+mentor curriculum --field "Rust" --duration "6 weeks"
+mentor fields
+```
+
+MIT licensed.
+""" }
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "expert-mentor contributors" }]
+keywords = ["llm", "mentor", "tutor", "education", "claude", "chatgpt", "ollama", "prompt"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Education",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Education",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dynamic = ["version"]
+
+[project.urls]
+Homepage = "https://github.com/voidstackloop/expert-mentor"
+Repository = "https://github.com/voidstackloop/expert-mentor"
+Issues = "https://github.com/voidstackloop/expert-mentor/issues"
+Changelog = "https://github.com/voidstackloop/expert-mentor/releases"
+"PyPI" = "https://pypi.org/project/expert-mentor/"
+
+[project.scripts]
+mentor = "expert_mentor:cli"
+expert-mentor = "expert_mentor:cli"
+
+[tool.setuptools]
+package-dir = { "" = "scripts" }
+py-modules = ["expert_mentor", "mentor_runtime", "mentor_memory", "mentor_cards"]
+
+[tool.setuptools.dynamic]
+version = { attr = "expert_mentor.__version__" }
+
+[tool.setuptools.data-files]
+"share/expert-mentor/templates" = ["templates/*.md"]
+"share/expert-mentor/references" = ["references/*.md", "references/*.json"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py38"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B"]
+ignore = ["E501"]

expert_mentor-0.6.0/references/fields.md

@@ -0,0 +1,64 @@
+# Field profiles
+
+A **field profile** tells the mentor what professional competence looks like in
+a specific field: the concepts, the misconceptions, the authoritative sources,
+and the capstone that proves mastery. The generator ships with curated profiles
+for a few common fields and falls back to a solid generic profile for everything
+else.
+
+## Curated profiles (built in)
+
+- **quantum computing** — `quantum-computing`
+- **Rust** — `rust`
+- **organic chemistry** — `organic-chemistry`
+- **machine learning** — `machine-learning` (also matches "AI")
+- **macroeconomics** — `macroeconomics`
+- **contract law** — `contract-law`
+
+List them anytime:
+
+```bash
+mentor fields
+```
+
+## Adding your own
+
+Create `references/fields.json`. The generator merges it over the built-ins at
+startup. Keys are arbitrary; each value uses this schema:
+
+```json
+{
+  "my-field": {
+    "key": "the Human-readable field name",
+    "aliases": ["my field", "alternate spelling", "abbreviation"],
+    "mentor_name": "Dr. Example Name",
+    "notes": "A paragraph on what professionalism in this field means: the core reasoning, the standards, the traps, and the canonical anchors.",
+    "concepts": ["concept 1", "concept 2"],
+    "misconceptions": ["wrong model A", "wrong model B"],
+    "resources": ["Author, Title", "standard/body/venue"],
+    "capstone": "One realistic project that proves competence."
+  }
+}
+```
+
+### Writing good notes
+
+The `notes` paragraph is the highest-leverage part. A strong profile:
+
+1. Names the field's **foundational reasoning** and demands it first.
+2. States the **standards** a professional is held to.
+3. Names the **classic traps** learners fall into.
+4. Points at **real authorities** (textbooks, standards bodies, journals).
+
+### Matching rules
+
+The resolver checks, in order: exact key / alias match, then substring match,
+then falls back to the generic profile. Aliases let one profile cover many
+phrasings ("ml", "deep learning", "statistical learning").
+
+## The generic fallback
+
+For fields without a profile, the generator builds notes that force the mentor
+to establish vocabulary and models first, then tools and workflows, then applied
+judgement — while distinguishing consensus from debate and attacking
+misconceptions. This is deliberately field-agnostic but pedagogically strong.

expert_mentor-0.6.0/references/pedagogy.md

@@ -0,0 +1,90 @@
+# Pedagogy — how the Expert Mentor teaches
+
+The mentor is not a content database. It is a teacher, and its behaviour is
+grounded in established learning science. This file explains the methods baked
+into `templates/mentor_system_prompt.md` so you can tune or extend them.
+
+## Core principles
+
+### 1. Zone of proximal development (Vygotsky)
+Teach just beyond what the learner can already do alone, but within reach with
+guidance. Too easy → boredom; too hard → shutdown. The mentor continuously
+probes to find this band and adjusts step size.
+
+### 2. Cognitive load theory (Sweller)
+Working memory is small. Introduce one new element at a time, use worked
+examples early, and only remove the scaffolds once the learner is fluent. This
+is why the mentor does "one concept at a time" and fades support.
+
+### 3. Retrieval practice and testing effect (Roediger & Karpicke)
+Pulling knowledge out of memory strengthens it far more than re-reading. Every
+explanation is followed by a question the learner must answer from memory.
+
+### 4. Spacing and interleaving
+Spread practice over sessions and mix related problem types rather than
+blocking. The mentor's roadmap revisits earlier milestones and mixes review into
+new practice.
+
+### 5. Scaffolding and fading (Wood, Bruner & Ross)
+Support is temporary. The mentor models → guides → watches → steps back.
+
+### 6. Formative feedback (Hattie & Timperley)
+Effective feedback answers three questions: Where am I going? How am I going?
+Where to next? The mentor names the exact gap and the next action; it never
+offers vague praise.
+
+### 7. Metacognition (Flavell)
+Strong learners monitor their own understanding. The mentor asks the learner to
+predict, self-explain, and summarise — building the habit of self-assessment.
+
+### 8. Threshold concepts and misconceptions
+Some ideas are gateways (e.g. pointers, eigenvalues, opportunity cost) that
+unlock everything above. Others are actively wrong mental models that block
+progress. The mentor targets both deliberately.
+
+## The teach/practice cycle
+
+```
+activate prior knowledge
+        ↓
+explain + worked example
+        ↓
+retrieval check (learner answers)
+        ↓
+    correct? ── no ──→ re-teach differently (new analogy, smaller step) → check again
+        │ yes
+        ↓
+guided practice → independent exercise → precise feedback
+        ↓
+advance milestone or consolidate
+```
+
+## Question types the mentor uses
+
+| Type | Example | Purpose |
+|------|---------|---------|
+| Retrieval | "Without looking, what does X do?" | Strengthen memory |
+| Prediction | "What will happen if we change Y?" | Activate reasoning |
+| Self-explanation | "Why does that step work?" | Deepen understanding |
+| Application | "Solve this new case." | Transfer |
+| Contrast | "How is X different from Z?" | Sharpen discrimination |
+| Metacognitive | "How confident are you, and why?" | Calibrate self-assessment |
+
+## Adapting to level
+
+- **Beginner** — concrete first, heavy analogy, small steps, lots of worked
+  examples, frequent checks, no jargon without definition.
+- **Intermediate** — connect ideas into systems, pressure-test with edge cases,
+  introduce trade-offs and "why not the obvious approach".
+- **Advanced** — focus on judgement, literature, and frontier debates; the
+  learner should be arguing and the mentor should be challenging.
+- **Expert** — peer-level discussion; the mentor probes limits, counterexamples,
+  and open problems rather than explaining basics.
+
+## What the mentor must never do
+
+- Dump a full solution when a hint would teach more.
+- Say "does that make sense?" instead of testing understanding.
+- Praise vaguely ("great!") without naming what was good.
+- Fabricate a source, formula, or API to look authoritative.
+- Let a misconception stand because the learner seemed satisfied.

expert_mentor-0.6.0/references/providers.md

@@ -0,0 +1,132 @@
+# Providers — deployment recipes
+
+The same mentor prompt is adapted per provider because cloud models and local
+models have very different capability envelopes. The generator injects the right
+**capability notes** and emits a format each provider can consume.
+
+Run `mentor providers` to see defaults, or `mentor models` for the model catalog.
+
+## Capability envelopes
+
+| Provider | Aliases | Temperature | Default model | Capability notes |
+|----------|---------|-------------|---------------|------------------|
+| `generic` | — | 0.6 | any capable model | cloud notes |
+| `anthropic` | `claude` | 0.7 | `claude-sonnet-5` | Claude notes + XML shaping |
+| `openai` | `chatgpt`, `gpt`, `oai` | 0.7 | `gpt-5.6` | ChatGPT notes + markdown |
+| `google` | `gemini` | 0.8 | `gemini-2.5-pro` | cloud notes |
+| `ollama` | `local` | 0.4 | `llama3.1:8b` | local notes |
+| `llamacpp` | — | 0.4 | local-gguf | local notes |
+
+- **Cloud notes** tell the model to exploit its large context: maintain a
+  detailed learner model, use rich analogies, cite real sources when confident.
+- **Claude notes** additionally ask for structured prose / XML tags and a clean
+  separation between private deliberation and what the learner sees.
+- **ChatGPT notes** additionally ask for clear markdown structure and explicit
+  next steps.
+- **Local notes** tell the model to compensate for limited context and reasoning:
+  follow the flow strictly, keep replies short, one question per reply, never
+  invent citations, restate the goal each turn.
+
+Discover the current model line-up any time:
+
+```bash
+mentor models                      # built-in catalog for Claude + ChatGPT
+mentor models --provider claude --refresh   # live lookup with your API key
+```
+
+## Anthropic (Claude)
+
+```bash
+mentor --field "quantum computing" --provider claude --emit json
+mentor run --field "Rust" --provider claude --model claude-sonnet-5
+```
+
+The generator and runtime both produce a correct **Messages API** request:
+
+- the mentor prompt is a top-level `system` **list of blocks** marked with
+  `cache_control: {"type": "ephemeral"}` — Anthropic **prompt caching**, a large
+  cost/latency win for a long, static system prompt (`--no-cache` disables it);
+- the prompt is re-shaped into **XML section tags** (`<identity>`,
+  `<the_teaching_contract>`, …) because Claude follows XML structure well
+  (`--prompt-format markdown` opts out);
+- optional **extended thinking**: `--thinking` (`--thinking-budget` default
+  4096). When thinking is on, `temperature` is omitted (the API requires the
+  default).
+- streaming understands `text_delta` and `thinking_delta`, and reports input,
+  **cache-read**, and output tokens per turn.
+
+Recommended: `max_tokens>=2048`. Current models: `claude-sonnet-5`,
+`claude-opus-5`, `claude-fable-5-1`, `claude-haiku-4-5`.
+
+## OpenAI (ChatGPT)
+
+```bash
+mentor --field "organic chemistry" --provider chatgpt --emit json
+mentor run --field "Rust" --provider chatgpt --model gpt-5.6 --reasoning-effort high
+```
+
+The request shape is adapted automatically from the model name:
+
+| Model family | System role | Token limit field | Temperature | Reasoning |
+|--------------|-------------|-------------------|-------------|-----------|
+| `gpt-5*`, `gpt-6*`, `o1…o9*` | `developer` | `max_completion_tokens` | omitted | `reasoning_effort` supported |
+| `gpt-4o`, `gpt-4.1`, etc. | `system` | `max_tokens` | sent | not supported |
+
+- `--reasoning-effort` accepts `none|minimal|low|medium|high|xhigh|max` (values
+  the model actually supports are a subset).
+- Streaming sets `stream_options.include_usage` and reports token usage.
+- Works unchanged with any OpenAI-compatible endpoint via `$OPENAI_BASE_URL`
+  (vLLM, Together, Groq, LM Studio server, …).
+
+## Google (Gemini)
+
+```bash
+mentor --field "macroeconomics" --provider google --emit json
+```
+
+Produces a `systemInstruction` + `contents` payload for the Generative Language
+API.
+
+## Ollama (local)
+
+```bash
+mentor --field "Rust" --level intermediate \
+    --provider ollama --emit modelfile --model qwen2.5:7b --compact > Modelfile
+ollama create expert-rust -f Modelfile
+ollama run expert-rust
+```
+
+The Modelfile pins `SYSTEM`, `temperature`, `num_ctx`, and `top_p`. Use
+`--compact` for 7B-and-under models and raise `--num-ctx` to match the model.
+
+## llama.cpp / LM Studio (local)
+
+```bash
+mentor --field "music theory" --provider llamacpp --emit json --compact
+```
+
+Emits a JSON object with `system_prompt`, `temperature`, `n_ctx`, and
+`max_tokens`. In LM Studio, paste `system_prompt` into the system-prompt field
+and match the parameters. In llama.cpp server, pass it via the chat template's
+system slot or your wrapper.
+
+## Choosing `--compact`
+
+Use `--compact` when:
+
+- the model has under ~8k context,
+- the model is 7B parameters or smaller,
+- the model tends to ignore long system prompts.
+
+The compact template strips the long teaching contract down to numbered rules
+and a short flow, which small models follow far more reliably.
+
+## Tuning tips
+
+- **Mentor too passive?** Raise temperature slightly or switch `--style direct`.
+- **Mentor gives answers away?** Switch `--style socratic` and say "don't give
+  me the answer yet" in your first message.
+- **Mentor invents sources?** Append "If you are not certain a source exists,
+  say so and tell me how to find it." Local notes already include this.
+- **Long-winded local model?** Add your own `num_predict` cap and keep
+  `--compact` on.

expert_mentor-0.6.0/scripts/expert_mentor.egg-info/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: expert-mentor
+Version: 0.6.0
+Summary: Turn any LLM (Claude, ChatGPT, Gemini, Ollama, llama.cpp) into a professional teacher for any field.
+Author: expert-mentor contributors
+License: MIT
+Project-URL: Homepage, https://github.com/voidstackloop/expert-mentor
+Project-URL: Repository, https://github.com/voidstackloop/expert-mentor
+Project-URL: Issues, https://github.com/voidstackloop/expert-mentor/issues
+Project-URL: Changelog, https://github.com/voidstackloop/expert-mentor/releases
+Project-URL: PyPI, https://pypi.org/project/expert-mentor/
+Keywords: llm,mentor,tutor,education,claude,chatgpt,ollama,prompt
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Education
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# expert-mentor
+
+Turn any capable LLM — Claude, ChatGPT, Gemini, or a local Ollama / llama.cpp
+model — into a **professional teacher for any field**.
+
+`expert-mentor` generates a calibrated expert-mentor system prompt for a given
+field and level, runs the tutoring session directly, remembers what the learner
+has mastered across sessions, and assesses progress from the transcript.
+
+## Highlights
+
+- **Provider-native prompts** — XML-shaped, prompt-cached system blocks for
+  Claude; `developer` role, `max_completion_tokens`, and `reasoning_effort` for
+  ChatGPT reasoning models.
+- **Live sessions** over Anthropic, OpenAI, Ollama, and llama.cpp (standard
+  library only, no `pip install` needed to run).
+- **Persistent learner memory** — mastered / shaky / misconceptions / open
+  questions, injected into every future session.
+- **Model-assisted review** — turn a session transcript into an updated profile.
+- **Curriculum design**, saved mentors, live model discovery, and a config file.
+- **Zero runtime dependencies**; Python 3.8+.
+
+## Install
+
+```bash
+pipx install expert-mentor      # or: pip install expert-mentor
+mentor --field "quantum computing" --level beginner
+```
+
+## Quick start
+
+```bash
+mentor run --field "Rust" --provider claude --remember
+mentor curriculum --field "Rust" --duration "6 weeks"
+mentor fields
+```
+
+MIT licensed.

expert_mentor-0.6.0/scripts/expert_mentor.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE
+pyproject.toml
+references/fields.md
+references/pedagogy.md
+references/providers.md
+scripts/expert_mentor.py
+scripts/mentor_cards.py
+scripts/mentor_memory.py
+scripts/mentor_runtime.py
+scripts/expert_mentor.egg-info/PKG-INFO
+scripts/expert_mentor.egg-info/SOURCES.txt
+scripts/expert_mentor.egg-info/dependency_links.txt
+scripts/expert_mentor.egg-info/entry_points.txt
+scripts/expert_mentor.egg-info/top_level.txt
+templates/cards_prompt.md
+templates/compact_prompt.md
+templates/curriculum_prompt.md
+templates/mentor_system_prompt.md
+templates/review_prompt.md

expert_mentor-0.6.0/scripts/expert_mentor.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

expert_mentor-0.6.0/scripts/expert_mentor.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+expert-mentor = expert_mentor:cli
+mentor = expert_mentor:cli

expert_mentor-0.6.0/scripts/expert_mentor.egg-info/top_level.txt

@@ -0,0 +1,4 @@
+expert_mentor
+mentor_cards
+mentor_memory
+mentor_runtime