NeuraLearn – Conceptor
Detailed User Guide
This document explains how to use the NeuraLearn – Conceptor editor and what each field in the interface means. You can paste it as-is into a README.md file or help page.
1. Interface Overview
The interface is divided into two main areas:
- Left panel (≈ 70%):
Structured construction of the exam scenario (all fields that will generate the JSON file).
- Right panel (≈ 30%):
AI Chat with the OpenAI API to help you write content (objectives, context, instructions, etc.).
At the top, a navigation bar contains:
API Key button: to enter and save your OpenAI key.
Download JSON button: to generate and download the scenario.json file from the entered fields.
2. Left Panel – Scenario Construction
The left panel consists of several cards (Bootstrap cards). Each corresponds to a logical block of the future JSON file.
2.1. Metadata & Core Setup
This card fills the main section of the scenario:
{
"metadata": { ... },
"mode": "...",
"topic": "...",
"question_count": 25,
"duration_hint": "...",
"global_duration_minutes": 30,
"allow_qcm": true
}
Fields:
- Field:
Title
- Usage: Readable name of the scenario (e.g., "American Cinema of the 80s").
- Impact: Serves to identify the scenario and is also used as the base for the downloaded JSON filename.
- Version (
metadata.version)
- Field:
Version
- Usage: Scenario version (e.g.,
1.0.0, 1.1).
- Impact: Allows tracking scenario evolution over time.
- Language (
metadata.language)
- Field:
Language
- Typical values:
fr-FR, en-US.
- Impact: Tells the AI the expected working language for the exam.
- Field:
Topic
- Usage: Global exam theme (e.g., "MLOps and AI Industrialization", "Customer Conflict Management").
- Field:
Mode
- Typical values:
subject: knowledge/comprehension exam on a subject.
roleplay: scenario, role-play (customer conflict, interview, etc.).
- Impact: Conditions the scenario logic on the exam engine side (and the relevance of the Initial Situation section).
- Question Count (
question_count)
- Field:
Question count
- Usage: Target number of questions the AI should ask the candidate during the exam.
- Impact: Structural indication for the engine and for time calibration.
- Duration Hint (text) (
duration_hint)
- Field:
Duration hint (text)
- Examples:
≈10 minutes, between 20 and 30 minutes.
- Impact: Narrative information for the AI and/or interface, visible in initial instructions.
- Global Duration (minutes) (
global_duration_minutes)
- Field:
Global duration (minutes)
- Usage: Target exam duration in minutes.
- Impact: Used to calibrate timers and estimate question pacing.
- Field:
Allow MCQ (allow_qcm)
- Type: Checkbox.
- Impact: Indicates whether the AI is allowed to propose multiple-choice questions or should stick to open questions.
2.2. Learning Objectives
This card fills the array:
"objectives": [
"…",
"…"
]
- Objectives List (
objectives[])
- Action: "Add objective" button → adds a line.
- Usage: Each line describes a clear learning objective (e.g., "Assess ability to connect a film to its historical context.").
- Impact: Helps the AI understand what should actually be measured during the exam.
2.3. Context & Key Points
This card fills the section:
"context": {
"summary": "...",
"key_points": [ "…", "…" ]
}
Fields:
- Summary (
context.summary)
- Field:
Summary (context.summary)
- Usage: Summary text describing the general exam context (situation, stakes, scope).
- Example: "This exam focuses on the American cinema revolution in the 80s, between blockbusters and high-concept."
- Key Points (
context.key_points[])
- Section:
Key points (context.key_points)
- Action: "Add key point" button.
- Usage: Each line represents an important piece of information the AI should keep in mind (e.g., "rise of home video", "high-concept logic").
- Impact: Serves as a basis for generating varied questions centered on what is truly important.
2.4. Question Strategy
This card fills:
"question_strategy": {
"type": "...",
"instructions": [ "…" ],
"technology_pool": [ "…" ],
"randomization": {
"method": "...",
"avoid_repetition": true,
"seed_source": "...",
"weights": { ... }
}
}
Main fields:
- Type (
question_strategy.type)
- Field:
Type
- Examples:
dynamic_open, mixed, etc.
- Impact: Tells the engine the nature of questioning (dynamic open questions, mixed, etc.).
- Randomization Method (
question_strategy.randomization.method)
- Field:
Randomization (method)
- Examples:
shuffle, weighted, seeded_shuffle.
- Impact: Controls how questions are chosen or ordered.
- Avoid Repetition (
question_strategy.randomization.avoid_repetition)
- Field:
avoid_repetition
- Type: Checkbox.
- Impact: Prevents the AI from asking the same question or axis multiple times.
- Seed Source (
question_strategy.randomization.seed_source)
- Field:
seed_source
- Examples:
session, user_id, fixed.
- Impact: Allows making question order reproducible or not.
- Instructions (
question_strategy.instructions[])
- Section:
Instructions (question_strategy.instructions)
- Type: Textarea, dynamic list.
- Usage: Detailed rules for the AI on how to ask questions (structure, tone, number of easy/difficult questions, etc.).
- Example: "Start with 2 simple calibration questions, then progressively increase difficulty."
- Tech Pool (
question_strategy.technology_pool[])
- Section:
Tech pool (optional)
- Usage: List of technologies/concepts to draw from (e.g.,
Transformers, LLM, diffusion models).
- Impact: Useful for technical scenarios where the AI should choose sub-themes coherently.
2.5. Randomization Weights (optional)
This card completes:
"question_strategy": {
"randomization": {
"weights": {
"history": 0.4,
"art": 0.3,
"social": 0.3
}
}
}
- Weights (
randomization.weights)
- Each line in the card corresponds to a key/value pair:
- Key: question type or category (e.g.,
history, art, social).
- Value: numerical weight (e.g.,
0.25, 0.5).
- Impact: Allows controlling the proportion of questions by category. For example, 40% history, 30% art, etc.
2.6. Timing & Evaluation
This large card covers several sub-sections.
2.6.1. Timers per Question (timer_defaults)
"timer_defaults": {
"q_duration_min": 45,
"q_duration_avg": 80,
"q_duration_max": 120
}
- Field:
q_duration_min (s)
- Usage: Minimum duration indicated to answer a question.
- Field:
q_duration_avg (s)
- Usage: Target average duration.
- Field:
q_duration_max (s)
- Usage: Maximum acceptable duration before alerting or moving on.
2.6.2. Timer Policy (timer_policy)
"timer_policy": {
"respect_backoffice_windows": true,
"instructions": [ "…" ]
}
- Respect Back-office Windows (
timer_policy.respect_backoffice_windows)
- Field:
Respect back-office time windows
- Type: Checkbox.
- Usage: If enabled, the engine strictly follows time slots defined on the back-office side.
- Instructions (
timer_policy.instructions[])
- Section:
Timer instructions
- Typical text: "Announce the response time before each question via the [QUESTION TIME: XXs] tag."
- Impact: Specifies how the AI should announce and manage durations throughout the exam.
2.6.3. Clarification Policy (clarification_policy)
"clarification_policy": {
"threshold": "...",
"style": "..."
}
- Threshold (
clarification_policy.threshold)
- Field:
Clarification – threshold
- Usage: Conditions that trigger a clarification request (e.g., "if the response is too short or off-topic").
- Style (
clarification_policy.style)
- Field:
Clarification – style
- Usage: Style of clarification requests (e.g., "ask a short and kind question to invite the candidate to clarify").
2.6.4. Follow-up Policy (follow_up_policy)
"follow_up_policy": {
"frequency": "...",
"examples": [ "…" ]
}
- Frequency (
follow_up_policy.frequency)
- Field:
Frequency
- Usage: Text or numerical indication (e.g., "≈20% of questions trigger a follow-up").
- Follow-up Examples (
follow_up_policy.examples[])
- Section:
Follow-ups (follow_up_policy.examples)
- Usage: Concrete examples of follow-ups to use (e.g., "Can you elaborate on this point?").
2.6.5. Evaluation (evaluation)
"evaluation": {
"criteria": [ "…" ],
"scoring_guidance": "..."
}
- Criteria (
evaluation.criteria[])
- Field:
Evaluation criteria (1 per line)
- Usage: Each line describes a criterion (e.g.,
Technical accuracy, Clarity, Response structure).
- Scoring Guidance (
evaluation.scoring_guidance)
- Field:
Scoring guidance
- Usage: Description of how to score based on criteria (e.g., weights, thresholds, examples).
2.7. Adaptive Difficulty (optional)
"adaptive_difficulty": {
"principle": "...",
"indicators": {
"strong": "...",
"medium": "...",
"low": "..."
}
}
- Principle (
adaptive_difficulty.principle)
- Field:
Principle
- Usage: How difficulty should evolve during the exam (e.g., "If responses are very strong, increase the complexity of following questions.").
- Indicators (
adaptive_difficulty.indicators)
"Strong" indicator → indicators.strong
"Medium" indicator → indicators.medium
"Low" indicator → indicators.low
- Usage: Describes how to recognize a strong, medium, or weak candidate (signals in their responses).
2.8. Initial Situation (roleplay, optional)
"initial_situation": {
"context": "...",
"actors": [ "…" ],
"constraints": [ "…" ],
"randomization": { ... },
"modulators": { ... },
"cases": [ "…" ]
}
To be used mainly if mode = roleplay.
- Context (
initial_situation.context)
- Field:
Context
- Usage: Describes the opening scene (e.g., "Very upset customer about a surprise bill.").
- Actors (
initial_situation.actors[])
- Section:
Actors
- Usage: List of present roles (e.g.,
candidate, customer, manager).
- Constraints (
initial_situation.constraints[])
- Section:
Constraints
- Usage: Rules to respect during the scene (e.g., "Stay polite", "Never immediately offer a full refund").
- Randomization (
initial_situation.randomization)
Randomization (method) → randomization.method
Seed → randomization.seed
avoid_recent → randomization.avoid_recent
max_escalation → randomization.max_escalation
- Usage: Controls the variety of cases/intensity of staging from one launch to another.
- Modulators (
initial_situation.modulators)
persona_pool → customer types (very upset, passive-aggressive…)
channel_pool → channels (chat, phone, etc.)
stakes_pool → stake level (low, medium, high)
time_pressure_pool → time pressure (none, moderate, high)
- Impact: Allows randomizing variants of the initial situation.
- Cases (
initial_situation.cases[])
- Section:
Possible cases (cases)
- Usage: Short description of several possible scenarios (e.g., "Double-charged bill", "Undelivered order").
2.9. Exam Ending & Output Summary
"ending": {
"instructions": [ "…" ]
},
"output_summary": {
"include": [ "…" ]
}
- Ending Instructions (
ending.instructions[])
- Section:
Ending instructions (ending.instructions)
- Usage: What the AI should do at the end of the exam (rephrase the result, thank, announce the grade, etc.).
- Output Summary (
output_summary.include[])
- Section:
Output summary (output_summary.include)
- Usage: List of elements to include in the final report (e.g.,
Decision, Success rate, Strengths, Improvement areas).
3. Right Panel – AI Assistant
The right panel is a chat with the OpenAI API:
- Exchange history in the
AI Assistant area.
- Text input area at the bottom:
Enter → sends the message.
Shift+Enter → line break.
- The model is guided by a system prompt to help produce:
- Objectives from a description.
- A context summary.
- Questioning instructions.
- You can copy-paste its responses directly into the left panel fields or ask it to fill the complete scenario.
- Type
/help anytime to display the comprehensive list of what the assistant can do.
💡 By clearly formulating a request like "Create/generate a scenario (or subject) about…" or typing #scenario, the AI assistant automatically generates a complete scenario and pre-fills it in the form. You can then review and adjust each section before downloading the JSON. During this phase, an assistant chat bubble displays text + a spinner to indicate generation/synchronization is in progress.
💡 To correct a specific field, mention it in the chat (e.g., "fill the key and weight fields", "fix the objectives section", "adjust the initial situation"). The AI responds, updates only the concerned fields, and displays a dedicated progress status.
4. OpenAI API Key
To use the chat:
1. Click API Key in the top bar. 2. Enter your key (sk-...) in the field. 3. Click Save. 4. The API: configured badge turns green.
The key is stored in the browser's localStorage (nl_api_key), client-side only.
5. JSON Scenario Export
When fields are filled:
1. Click Download JSON. 2. The application:
6. Automatic Generation via AI Chat
- When you explicitly request scenario/subject creation in the chat, the application detects the request (e.g., "Can you create a complete scenario about…",
#scenario, etc.) and launches generation of all expected sections: metadata, objectives, context, question strategy, timers, follow-up policies, initial situation, exam ending, and output summary.
- A progress alert appears in the discussion thread; when generation is complete, a message confirms the form has been pre-filled. In case of API error, a coherent template is still injected to help you out.
- The AI follows up with a short question to see if you want to add details ("Want to adjust any fields?…"). If you respond mentioning a field, it directly updates the data corresponding to your request (without rewriting the entire scenario).
- You can edit each card as usual before downloading the JSON.
- This function doesn't replace anything: you can still chat with the AI to get specific texts, import/export existing scenarios, and manually modify fields.
7. Imported Scenario Review & Targeted Corrections
- When you import an existing JSON, the AI automatically reviews the content entered in the fields, displays a spinner, then delivers a summary (strengths, improvement areas, and suggestions for sections to refine).
- Following this diagnosis, you can ask: "update the objectives", "strengthen the follow-ups", "fix the weights", etc. The assistant will update only the concerned fields while keeping the rest of the scenario.
- The same commands work even without import: as long as a scenario is present in the editor, you can request field-by-field modifications to iterate quickly.