get-smart-guidance.js•17.7 kB
#!/usr/bin/env node
/**
* Smart Guidance Tool v5.2.0 - FULLY OPERATIONAL
* Just-In-Time approach: Provides essential guidance without overwhelming API details
* @version 5.2.0 (January 12, 2025)
* @status FULLY OPERATIONAL - Token-efficient JIT workflow
* @reference JIT workflow step 1 of 7
* @milestone v5.2.0 - Lightweight guidance with widget prediction
*/
export class SmartGuidanceTool {
constructor() {
this.processingStartTime = null;
this.analysisLog = [];
this.gradeConfigurations = this.initializeGradeConfigurations();
this.subjectProfiles = this.initializeSubjectProfiles();
}
/**
* Main guidance entry point for JIT workflow
* @param {Object} input - Contains prompt, subject, gradeLevel
* @returns {Object} Lightweight guidance with widget predictions
*/
async processGuidanceRequest(input) {
this.processingStartTime = new Date();
this.analysisLog = [];
try {
const { prompt, subject, gradeLevel } = input;
// Validate inputs
if (!prompt || typeof prompt !== 'string') {
throw new Error('Prompt is required and must be a string');
}
// Analyze prompt and context
const promptAnalysis = this.analyzePrompt(prompt);
const gradeConfig = this.getGradeConfiguration(gradeLevel);
const subjectProfile = this.getSubjectProfile(subject);
// Generate widget predictions
const suggestedWidgets = this.predictOptimalWidgets(promptAnalysis, subjectProfile);
// Create JIT guidance response
const guidance = {
success: true,
data: {
workflowInstructions: {
currentStep: "Step 1: FULL Content Creation",
nextRequiredAction: "CREATE COMPLETE EDUCATIONAL CONTENT FIRST (not just structure), THEN use analyze_content_for_widgets tool",
criticalNote: "⚠️ IMPORTANT: You MUST create FULL educational content (explanations, examples, vocabulary, assessments) BEFORE using any tools",
contentRequirement: "Content should be COMPREHENSIVE with detailed explanations, examples, and educational substance - NOT just titles and structure",
toolSequence: [
"get_smart_guidance (current step)",
"CREATE FULL CONTENT (required next)",
"analyze_content_for_widgets (only after content is complete)",
"get_widget_requirements",
"validate_lesson_data",
"format_for_composer",
"save_composition_api",
"open_composition_editor"
]
},
basicGuidelines: {
duration: gradeConfig.recommendedDuration,
minimumTextLength: 20,
widgetRange: "3-8 widgets recommended",
cognitiveLoadBalance: "Mix of low, medium, and high complexity widgets",
assessmentRequirement: "Include at least one assessment widget (quiz or flashcards)",
gradeSpecific: {
attentionSpan: gradeConfig.attentionSpan,
complexity: gradeConfig.complexity,
examples: gradeConfig.exampleType
},
subjectSpecific: {
focus: subjectProfile.primaryFocus,
visuals: subjectProfile.visualImportance,
interaction: subjectProfile.interactionLevel
},
qualityStandards: {
content: "Original, engaging content with real-world connections",
language: "Age-appropriate vocabulary and concepts",
structure: "Logical progression from introduction to assessment",
engagement: "Interactive elements to maintain attention"
}
},
suggestedWidgets: suggestedWidgets,
contentCreationGuidance: {
approach: "⭐ CREATE FULL EDUCATIONAL CONTENT in natural language (like writing a textbook chapter) - NOT just structure or outlines",
criticalRequirement: "🚨 CONTENT MUST BE COMPLETE AND DETAILED before proceeding to analyze_content_for_widgets",
contentStructure: {
introduction: "Write FULL engaging introduction with context and objectives (not just a title)",
mainContent: "Write COMPLETE explanations with details, examples, and educational substance",
practice: "Create ACTUAL exercises and activities (not just placeholders)",
assessment: "Write COMPLETE quiz questions with options and answers"
},
contentTypes: {
explanatory: "FULL detailed explanations (multiple paragraphs per concept)",
questions: "COMPLETE assessment questions with all options and correct answers",
vocabulary: "COMPLETE terms with full definitions (not just term lists)",
procedures: "DETAILED step-by-step instructions with explanations",
visuals: "FULL descriptions of needed images and their educational purpose"
},
subjectFocus: subjectProfile.contentFocus,
contentExpectations: {
minimumLength: "Each section should have substantial content (100+ words)",
depth: "Explanations should be thorough and educational",
examples: "Include concrete, detailed examples",
completeness: "Every topic mentioned must be fully explained"
},
reminders: [
"🎯 CREATE FULL CONTENT FIRST - this is the most important step",
"📝 Write as if creating a complete textbook chapter",
"🚫 Do NOT create just titles, outlines, or structure",
"✅ Include ALL educational substance before using tools",
"💡 Think: Would a student learn from this content alone?",
"⏰ Take time to create quality content - don't rush to tools"
]
},
jitWorkflow: {
description: "Content-First JIT workflow - CREATE FULL CONTENT before using tools",
criticalFirstStep: "📚 YOU MUST CREATE COMPLETE EDUCATIONAL CONTENT FIRST",
steps: [
"1. 📝 CREATE FULL EDUCATIONAL CONTENT (detailed explanations, examples, activities - NOT just structure)",
"2. 🔍 ONLY THEN: Analyze your complete content to map optimal widgets",
"3. 📋 Get specific API requirements for selected widgets only",
"4. ✅ Validate content with targeted requirements",
"5. 🔧 Format content for Composer API",
"6. 💾 Save composition via API",
"7. 🎯 Open composition in Composer"
],
contentCreationExamples: {
good: "Write full paragraphs explaining photosynthesis process, include detailed examples of plants, create complete quiz questions with all options",
bad: "Just listing topics like 'Introduction to photosynthesis', 'Types of plants', 'Quiz section'"
},
benefits: [
"Natural content creation without format constraints",
"Token-efficient guidance (only relevant requirements)",
"Intelligent widget selection based on actual content",
"Precise API requirements delivered just-in-time",
"Better focus on educational quality"
],
nextStep: "⚠️ CRITICAL: CREATE YOUR COMPLETE EDUCATIONAL CONTENT FIRST (like writing a full lesson), THEN AND ONLY THEN use analyze_content_for_widgets tool",
workflowReminder: "🛑 STOP: Have you created FULL educational content yet? If not, DO THAT FIRST. Only use analyze_content_for_widgets AFTER you have complete content with explanations, examples, and assessments."
},
educationalPrinciples: {
attentionSpan: gradeConfig.attentionSpan,
cognitiveLoad: `Balance ${gradeConfig.complexity} complexity with interactive elements`,
learningStyles: ["visual", "auditory", "kinesthetic"],
engagement: subjectProfile.engagementStrategy,
assessment: "Formative assessment throughout lesson"
}
},
debug: {
timestamp: new Date().toISOString(),
promptAnalysis: promptAnalysis,
predictedComplexity: {
promptLevel: promptAnalysis.complexity,
gradeLevel: gradeLevel,
subjectComplexity: subjectProfile.complexity
},
processingTime: Date.now() - this.processingStartTime.getTime()
}
};
return guidance;
} catch (error) {
console.error('[SMART_GUIDANCE] Error:', error.message);
return {
success: false,
error: {
code: 'GUIDANCE_ERROR',
message: error.message,
timestamp: new Date().toISOString()
}
};
}
}
/**
* Analyze prompt to extract educational intent and complexity
*/
analyzePrompt(prompt) {
const length = prompt.length;
const complexity = this.determineComplexity(prompt);
const topics = this.extractTopics(prompt);
const intent = this.determineIntent(prompt);
return {
length,
complexity,
topics,
intent
};
}
/**
* Determine complexity based on prompt analysis
*/
determineComplexity(prompt) {
const complexIndicators = [
'análise', 'avaliação', 'síntese', 'comparação', 'aplicação',
'analysis', 'evaluation', 'synthesis', 'comparison', 'application'
];
const simpleIndicators = [
'introdução', 'básico', 'conceitos', 'definir', 'explicar',
'introduction', 'basic', 'concepts', 'define', 'explain'
];
const lowerPrompt = prompt.toLowerCase();
if (complexIndicators.some(indicator => lowerPrompt.includes(indicator))) {
return 'high';
} else if (simpleIndicators.some(indicator => lowerPrompt.includes(indicator))) {
return 'low';
}
return 'medium';
}
/**
* Extract educational topics from prompt
*/
extractTopics(prompt) {
// Simple topic extraction - in real implementation could be more sophisticated
const commonTopics = [
'física', 'química', 'biologia', 'matemática', 'história', 'geografia',
'physics', 'chemistry', 'biology', 'mathematics', 'history', 'geography'
];
const lowerPrompt = prompt.toLowerCase();
return commonTopics.filter(topic => lowerPrompt.includes(topic));
}
/**
* Determine educational intent
*/
determineIntent(prompt) {
const lowerPrompt = prompt.toLowerCase();
if (lowerPrompt.includes('crie') || lowerPrompt.includes('criar') ||
lowerPrompt.includes('create')) {
return 'creation';
} else if (lowerPrompt.includes('explique') || lowerPrompt.includes('explain')) {
return 'explanation';
} else if (lowerPrompt.includes('avalie') || lowerPrompt.includes('evaluate')) {
return 'assessment';
}
return 'creation'; // Default to creation
}
/**
* Predict optimal widgets based on content analysis
*/
predictOptimalWidgets(promptAnalysis, subjectProfile) {
const widgets = [];
// Always include header
widgets.push({
type: "head-1",
confidence: 1.0,
rationale: "Professional lesson header always required"
});
// Text content for explanations
widgets.push({
type: "text-1",
confidence: 0.95,
rationale: "Explanatory content detected"
});
// Subject-specific widgets
if (subjectProfile.visualImportance === 'high') {
widgets.push({
type: "image-1",
confidence: 0.8,
rationale: "Visual content recommended for subject"
});
}
// Assessment widgets based on complexity
if (promptAnalysis.complexity === 'high' || promptAnalysis.intent === 'assessment') {
widgets.push({
type: "quiz-1",
confidence: 0.85,
rationale: "Assessment content or high complexity detected"
});
} else {
widgets.push({
type: "flashcards-1",
confidence: 0.75,
rationale: "Terminology/vocabulary learning detected"
});
}
return widgets;
}
/**
* Get grade-specific configuration
*/
getGradeConfiguration(gradeLevel) {
return this.gradeConfigurations[gradeLevel] || this.gradeConfigurations['default'];
}
/**
* Get subject-specific profile
*/
getSubjectProfile(subject) {
const normalizedSubject = (subject || '').toLowerCase();
return this.subjectProfiles[normalizedSubject] || this.subjectProfiles['default'];
}
/**
* Initialize grade configurations
*/
initializeGradeConfigurations() {
return {
'6º ano': {
attentionSpan: 15,
complexity: 'low',
exampleType: 'concrete',
recommendedDuration: 30
},
'7º ano': {
attentionSpan: 17,
complexity: 'low-medium',
exampleType: 'concrete',
recommendedDuration: 35
},
'8º ano': {
attentionSpan: 20,
complexity: 'medium',
exampleType: 'mixed',
recommendedDuration: 40
},
'9º ano': {
attentionSpan: 22,
complexity: 'medium',
exampleType: 'mixed',
recommendedDuration: 45
},
'1º médio': {
attentionSpan: 25,
complexity: 'medium-high',
exampleType: 'abstract',
recommendedDuration: 50
},
'2º médio': {
attentionSpan: 27,
complexity: 'high',
exampleType: 'abstract',
recommendedDuration: 50
},
'3º médio': {
attentionSpan: 30,
complexity: 'high',
exampleType: 'abstract',
recommendedDuration: 50
},
'superior': {
attentionSpan: 35,
complexity: 'high',
exampleType: 'abstract',
recommendedDuration: 60
},
'default': {
attentionSpan: 25,
complexity: 'medium',
exampleType: 'mixed',
recommendedDuration: 45
}
};
}
/**
* Initialize subject profiles
*/
initializeSubjectProfiles() {
return {
'ciências': {
primaryFocus: 'process understanding',
visualImportance: 'high',
interactionLevel: 'high',
contentFocus: 'Scientific processes, cause-effect relationships, real-world applications',
engagementStrategy: 'Mix of visual, analytical, peer interaction',
complexity: 'medium'
},
'física': {
primaryFocus: 'mathematical modeling',
visualImportance: 'high',
interactionLevel: 'medium',
contentFocus: 'Mathematical relationships, practical applications, experimental concepts',
engagementStrategy: 'Visual demonstrations, problem-solving, real-world examples',
complexity: 'high'
},
'química': {
primaryFocus: 'molecular understanding',
visualImportance: 'high',
interactionLevel: 'high',
contentFocus: 'Molecular interactions, chemical processes, laboratory applications',
engagementStrategy: 'Visual models, interactive simulations, practical examples',
complexity: 'high'
},
'biologia': {
primaryFocus: 'systems thinking',
visualImportance: 'high',
interactionLevel: 'medium',
contentFocus: 'Biological systems, life processes, environmental connections',
engagementStrategy: 'Visual diagrams, case studies, ecological examples',
complexity: 'medium'
},
'matemática': {
primaryFocus: 'problem solving',
visualImportance: 'medium',
interactionLevel: 'high',
contentFocus: 'Mathematical concepts, step-by-step procedures, practical applications',
engagementStrategy: 'Interactive problem-solving, visual representations, progressive difficulty',
complexity: 'high'
},
'história': {
primaryFocus: 'chronological understanding',
visualImportance: 'medium',
interactionLevel: 'medium',
contentFocus: 'Historical events, cause-effect relationships, cultural contexts',
engagementStrategy: 'Narrative storytelling, timeline activities, critical analysis',
complexity: 'medium'
},
'default': {
primaryFocus: 'concept understanding',
visualImportance: 'medium',
interactionLevel: 'medium',
contentFocus: 'Core concepts, practical applications, skill development',
engagementStrategy: 'Balanced approach with multiple learning modalities',
complexity: 'medium'
}
};
}
}
/**
* Create and export the tool instance for JIT server integration
*/
export function createSmartGuidanceTool() {
const tool = new SmartGuidanceTool();
return {
name: 'get_smart_guidance',
description: 'STEP 1: Get lightweight educational guidance with widget prediction. Token-efficient alternative to comprehensive guidance.',
inputSchema: {
type: 'object',
properties: {
prompt: {
type: 'string',
description: 'Educational content prompt or lesson request'
},
subject: {
type: 'string',
description: 'Subject area (e.g., "Ciências", "Física", "Matemática")'
},
gradeLevel: {
type: 'string',
description: 'Grade level (e.g., "8º ano", "1º médio", "Superior")'
}
},
required: ['prompt']
},
handler: async (input) => {
return await tool.processGuidanceRequest(input);
}
};
}