open-lesson

name	open-lesson
description	Interact with openLesson tutoring API for Socratic learning: generate learning plans as directed graphs, start audio-based tutoring sessions, analyze reasoning gaps, and manage tutoring workflows. Use when users want personalized tutoring, learning plan generation, or Socratic dialogue-based education.
description_zh	苏格拉底式 AI 辅导：生成学习计划、音频对话式教学、诊断推理差距
description_en	Socratic AI tutoring: generate learning plans, audio sessions, reasoning gap analysis
version	1.0.2
homepage	https://clawhub.ai/dncolomer/open-lesson
allowed-tools	Read,Write,Bash

OPENLESSON AGENT API SKILL

You are an AI agent that can interact with the openLesson tutoring platform via API.

OVERVIEW

openLesson is a tutoring system that uses audio-based dialogue to help users learn by asking questions rather than giving answers. The platform generates personalized learning plans as directed graphs, where each node is a session. Agents can programmatically generate learning plans, start sessions, and analyze audio chunks for reasoning gaps.

IMPORTANT: NO BROWSER TOOL REQUIRED

You do not need a browser tool. You only need shell tools (e.g., curl) to make API calls to openLesson.

IMPORTANT: AUDIO-ONLY SYSTEM

CRITICAL: The openLesson platform is audio-only. The analyze endpoint accepts ONLY audio input, NOT text.

• Always convert speech to base64-encoded audio before calling the analyze endpoint
• Supported formats: webm, mp4, ogg
• Do not send text to the analyze endpoint — it will be rejected

AUTHENTICATION

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Important: Always use https://www.openlesson.academy for API calls. The domain openlesson.academy has a redirect that loses the Authorization header.

CREDENTIALS

This skill requires an API key for the openLesson API:

• Environment variable: OPENLESSON_API_KEY
• How to obtain: Generate from the user's dashboard at /dashboard

ENDPOINTS

1. GENERATE LEARNING PLAN

Creates a directed graph of learning sessions for a given topic.

Endpoint: POST /api/agent/plan

{
  "topic": "Machine Learning Fundamentals",
  "days": 30
}

Days to Sessions mapping:

• 7 days: 3-5 sessions
• 14 days: 4-7 sessions
• 30 days (default): 5-10 sessions
• 60 days: 8-14 sessions
• 90 days: 10-18 sessions
• 180 days: 15-25 sessions

2. START SESSION

Starts a new Socratic session.

Endpoint: POST /api/agent/session/start

{
  "problem": "Explain how gradient descent works in neural networks",
  "plan_node_id": "uuid-from-plan"
}

3. ANALYZE AUDIO CHUNK

Submits an audio chunk for Socratic analysis. Returns reasoning gap score and follow-up questions.

Endpoint: POST /api/agent/session/analyze

{
  "session_id": "uuid-from-start",
  "audio_base64": "base64-encoded-audio-data",
  "audio_format": "webm"
}

Response includes: gapScore, signals, transcript, followUpQuestion, requiresFollowUp

4. END SESSION

Ends an agent session and generates a summary report.

Endpoint: POST /api/agent/session/end

5. GET SESSION SUMMARY

Retrieves the summary report of a completed session.

Endpoint: GET /api/agent/session/summary?session_id=xxx

COMPLETE AGENT WORKFLOW

1. Generate a learning plan → get plan with nodes
2. Start a session for the first node → get session ID
3. Record and analyze audio → get gap scores and follow-up questions
4. Continue until concept mastery
5. End session → get summary report
6. Move to next node in the plan

TIPS FOR AGENTS

1. Always use audio: The analyze endpoint ONLY accepts audio
2. Record in webm format (Opus codec preferred)
3. Chunk audio: Send 30-60 second chunks for analysis
4. Follow up: If requiresFollowUp is true, ask the follow-up question
5. Track gap scores: Use gap score to determine mastery
6. Schedule all sessions: Create reminders for each planned session

ERROR HANDLING

• 401: Invalid or inactive API key
• 403: Session doesn't belong to this key
• 404: Session not found
• 500: Internal server error