epam-ai-conductor

EPAM AI Conductor — a Socratic AI mentor CLI for the React Fundamentals course, powered by CodeMie + Claude.

The mentor knows the full course content and hidden test expectations, but guides students with questions instead of answers — so they learn by doing, never by copy-pasting.

Student setup

# 1. Clone the template
git clone <template-repo-url> my-react-app
cd my-react-app

# 2. Install EPAM AI Conductor
npm install -g epam-ai-conductor

# 3. Start a module session
ai-conductor start -m 1

On first run it walks you through CodeMie setup (EPAM SSO login).

Commands

ai-conductor help                       # show usage
ai-conductor start                      # pick a module interactively
ai-conductor start -m <1-5>             # start a specific module
ai-conductor start -m <1-5> -d <path>   # start in a specific directory

Slash commands during a session

| Command | What it does | |----------|-------------| | /hint | One targeted hint — a question, not code | | /check | Reviews your src/ against the task criteria | | /step | Suggests the single most logical next step |

Requirements

• Node.js >= 20
• A CodeMie account (EPAM SSO) — set up automatically on first run
• codemie-claude installed (codemie install claude)

Course coordinator — updating content

When coursebook or test files change, re-sync and rebuild:

# Repos must be siblings of this directory:
#   ../react-fundamentals-coursebook
#   ../react-fundamentals-app-tests

npm run sync-content   # copies from sibling repos into src/content/
npm run build          # compiles TS + copies content into dist/

Publishing a new version

# 1. Bump the version
npm version patch   # 0.1.2 → 0.1.3
# or
npm version minor   # 0.1.2 → 0.2.0

# 2. Push the tag — GitLab CI will publish to npm automatically
git push origin --tags

Requires NPM_TOKEN set in GitLab: Settings → CI/CD → Variables

How the mentor evaluates (and stays grounded)

The MCP server exposes these tools to the mentor:

| Tool | Purpose | |------|---------| | get_criteria | Graded checklist with stable ids + point weights (parsed from the ## Criteria section of each module's task). The source of truth for "is it done". | | get_test_expectations | The objective contract a component's hidden tests assert (expected export/path, props, required output text, queried roles/testids, interactions) — never the raw test code. | | get_module_overview | The module map linking each component to its criteria and test contract. | | get_theory | Course theory, filterable by topic. | | scan_project | A fresh structural snapshot of the student's current code. /check and /hint call this first so assessments are never stale. |

The persona enforces an intake triage (conceptual / debugging / answer-request / progress-check) and a pre-send self-check that strips any task-solving code or quoted test source.

Curated criteria overrides

Auto-extraction follows the coursebook. To hand-tune a module's checklist, add src/content/module-N/criteria.override.json — an array of { id, component, points, requirement, details, optional } — and it fully replaces the parsed list for that module.

Note: a few coursebook modules state a "max points" total that doesn't equal the sum of their listed items (e.g. Module 2 lists 56 pts under a "35 max" heading). get_criteria reports the actual itemized total; fix the source or add an override to reconcile.

Session logs

Each MCP tool call is appended (locally, anonymous) to ~/.ai-conductor/logs/tools-YYYY-MM-DD.jsonl — useful for spotting where the mentor mis-assessed or leaked. Delete the dir to clear.