I built a Socratic tutoring agent that guides students through quantitative problems without handing them the answer. It diagnoses misconceptions in real time and adapts each hint based on the student's reasoning. This is the kind of tool ed-tech teams are actually shipping to reduce instructor workload and keep learners engaged.
What you'll need
- Python 3.10 or newer
- The OpenAI SDK:
pip install openai - An Oxlo.ai API key from https://portal.oxlo.ai
- A sample problem to practice. I will use a basic kinematics question.
Because Oxlo.ai uses request-based pricing, a long multi-turn tutoring session with full problem context costs the same per message no matter how many tokens are in the history. That makes it easy to budget for classroom scale. You can see details at https://oxlo.ai/pricing.
Step 1: Connect to Oxlo.ai
First, I instantiate the client. Oxlo.ai is fully OpenAI SDK compatible, so the only difference is the base URL and the API key. I test the connection with a quick ping.
from openai import OpenAI
client = OpenAI(base_url="https://api.oxlo.ai/v1", api_key="YOUR_OXLO_API_KEY")
response = client.chat.completions.create(
model="llama-3.3-70b",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Say 'Oxlo.ai connection OK'"},
],
)
print(response.choices[0].message.content)Step 2: Define the tutor's system prompt
The personality of the agent lives in the system prompt. I force it to stay in Socratic mode, never giving the final answer, and to end the session with a SOLVED tag only when the student demonstrates correct reasoning.
SYSTEM_PROMPT = """You are a patient Socratic tutor for high school physics and math.
Rules:
- Never give the student the final numerical answer.
- Guide the student with one targeted question or hint per turn.
- If the student is stuck, break the problem into smaller conceptual steps.
- When the student shows correct reasoning and arrives at the answer, reply with "SOLVED" and briefly summarize their reasoning.
- Keep responses under three sentences."""Step 3: Add misconception detection
Before the tutor replies, I run the student's last answer through a reasoning model to classify the error. This keeps the main loop clean and lets me swap specialist models for different subjects. I use DeepSeek V3.2 on Oxlo.ai because it handles complex reasoning and coding tasks efficiently, and its cost is predictable per request.
import json
from openai import OpenAI
client = OpenAI(base_url="https://api.oxlo.ai/v1", api_key="YOUR_OXLO_API_KEY")
def diagnose_misconception(problem_text, student_answer):
prompt = f"""Problem: {problem_text}
Student's latest answer: {student_answer}
Identify the specific misconception. Return valid JSON with keys:
- error_type (e.g., "formula_selection", "algebraic", "conceptual")
- explanation (one sentence)
- hint (one sentence to guide the student back on track)
Do not include markdown fences."""
response = client.chat.completions.create(
model="deepseek-v3.2",
messages=[
{"role": "system", "content": "You are an expert physics educator."},
{"role": "user", "content": prompt},
],
)
raw = response.choices[0].message.content
return json.loads(raw)Step 4: Build the interactive tutoring loop
Now I wire everything together. The loop maintains conversation history, calls the diagnostic function after each student input, and appends the structured feedback so the tutor model can adapt its next hint. I use Llama 3.3 70B for the tutor because it is responsive and general purpose, which matters for an interactive CLI.
from openai import OpenAI
client = OpenAI(base_url="https://api.oxlo.ai/v1", api_key="YOUR_OXLO_API_KEY")
# Paste SYSTEM_PROMPT and diagnose_misconception from the previous steps here.
def tutor_session(problem, max_turns=6):
history = [
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": f"Help me solve this problem: {problem}"}
]
for turn in range(max_turns):
response = client.chat.completions.create(
model="llama-3.3-70b",
messages=history,
)
tutor_msg = response.choices[0].message.content
print(f"\nTutor: {tutor_msg}")
if "SOLVED" in tutor_msg:
print("\nSession complete.")
return
student_input = input("Your answer: ").strip()
if student_input.lower() in ["quit", "exit"]:
print("Session ended.")
return
diag = diagnose_misconception(problem, student_input)
feedback = (
f"Student answered: {student_input}\n"
f"Diagnosis: {diag['error_type']}. {diag['explanation']}\n"
f"Hint direction: {diag['hint']}"
)
history.append({"role": "assistant", "content": tutor_msg})
history.append({"role": "user", "content": feedback})
print("\nMax turns reached.")Run it
Save the full script below as tutor.py, export your key, and run it. The example output shows a complete student session for the kinematics problem.
import json
from openai import OpenAI
client = OpenAI(base_url="https://api.oxlo.ai/v1", api_key="YOUR_OXLO_API_KEY")
SYSTEM_PROMPT = """You are a patient Socratic tutor for high school physics and math.
Rules:
- Never give the student the final numerical answer.
- Guide the student with one targeted question or hint per turn.
- If the student is stuck, break the problem into smaller conceptual steps.
- When the student shows correct reasoning and arrives at the answer, reply with "SOLVED" and briefly summarize their reasoning.
- Keep responses under three sentences."""
def diagnose_misconception(problem_text, student_answer):
prompt = f"""Problem: {problem_text}
Student's latest answer: {student_answer}
Identify the specific misconception. Return valid JSON with keys:
- error_type (e.g., "formula_selection", "algebraic", "conceptual")
- explanation (one sentence)
- hint (one sentence to guide the student back on track)
Do not include markdown fences."""
response = client.chat.completions.create(
model="deepseek-v3.2",
messages=[
{"role": "system", "content": "You are an expert physics educator."},
{"role": "user", "content": prompt},
],
)
raw = response.choices[0].message.content
return json.loads(raw)
def tutor_session(problem, max_turns=6):
history = [
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": f"Help me solve this problem: {problem}"}
]
for turn in range(max_turns):
response = client.chat.completions.create(
model="llama-3.3-70b",
messages=history,
)
tutor_msg = response.choices[0].message.content
print(f"\nTutor: {tutor_msg}")
if "SOLVED" in tutor_msg:
print("\nSession complete.")
return
student_input = input("Your answer: ").strip()
if student_input.lower() in ["quit", "exit"]:
print("Session ended.")
return
diag = diagnose_misconception(problem, student_input)
feedback = (
f"Student answered: {student_input}\n"
f"Diagnosis: {diag['error_type']}. {diag['explanation']}\n"
f"Hint direction: {diag['hint']}"
)
history.append({"role": "assistant", "content": tutor_msg})
history.append({"role": "user", "content": feedback})
print("\nMax turns reached.")
if __name__ == "__main__":
PROBLEM = "A car starts from rest and accelerates at 2 m/sĀ² for 10 seconds. How far does it travel?"
tutor_session(PROBLEM)Example interaction:
Tutor: Let's work through this together. What information does the problem give you, and what are you trying to find? Your answer: I see acceleration and time, but I need distance. Tutor: Good. You are given acceleration and time. The car starts from rest. What does that tell you about its initial velocity? Your answer: Initial velocity is zero. Tutor: Exactly. Which kinematic equation relates distance, initial velocity, acceleration, and time? Your answer: d = vi*t + 0.5*a*t^2 Tutor: Perfect. Now plug in the values you know and tell me the result. Your answer: d = 0 + 0.5*2*100 = 100 meters Tutor: SOLVED. You correctly applied the kinematic equation for constant acceleration and arrived at 100 meters. Well done. Session complete.
Next steps
This CLI proves the concept, but the real value comes from integration. I recommend wrapping the tutor_session function in a FastAPI endpoint so a frontend can stream responses to students. You could also switch the main tutor to kimi-k2.6 so learners can upload photos of handwritten work and receive feedback on their actual notation. Because Oxlo.ai charges per request rather than per token, you can let students paste full textbook chapters as context without worrying that a growing conversation history will inflate your bill.
Top comments (0)