Initial commit of the AI instructor assistant agent.

README.md

@@ -1,2 +1,52 @@
 # instructor_assistant
+
 AI Agent helps instructors create lesson plans, course outline, exercise program... any resource needed for faster course preparation and execution.
+
+## Setup with UV
+
+This project uses [UV](https://github.com/astral-sh/uv) for package management.
+
+### Prerequisites
+
+Install UV if you haven't already:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Or on macOS with Homebrew:
+```bash
+brew install uv
+```
+
+### Setup Instructions
+
+1. **Install dependencies:**
+   ```bash
+   uv sync
+   ```
+
+2. **Activate the virtual environment:**
+   ```bash
+   source .venv/bin/activate  # On macOS/Linux
+   # or
+   .venv\Scripts\activate  # On Windows
+   ```
+
+3. **Run the application:**
+   ```bash
+   uv run python course_manager.py
+   ```
+
+Alternatively, you can run directly with UV without activating the venv:
+```bash
+uv run course_manager.py
+```
+
+### Environment Variables
+
+Create a `.env` file in the project root with your OpenAI API key:
+
+```
+OPENAI_API_KEY=your_api_key_here
+```

coordinator_agent.py

@@ -0,0 +1,79 @@
+from typing import Literal
+
+from curriculum_designer_agent import Curriculum, CurriculumDesignerAgent
+from instruction_designer_agent import Instruction, InstructionDesignerAgent
+from practice_designer_agent import Practice, PracticeDesignerAgent
+from pydantic import BaseModel
+from qa_agent import QAAgent, QualityAssurance
+
+from agents import Agent
+
+INSTRUCTIONS = (
+    """You are an coordinator agent, you are responsible for coordinating the course instruction flow.
+    1. First the curriculum designer agent will design the curriculum.
+    2. Then the instruction designer must design the course instruction.
+    3. Then the practice designer must design the practice exercises.
+    4. Then the QA agent must assure that this course has the right quality. 
+If it doesn't have the right quality, you should start the flow again from the step the qa agent wasn't satisfied with.
+    """
+)
+
+class CoordinatorInstructions():
+    def name(self):
+        return "coordinator"
+    
+    def instructions(self):
+        return (
+            "You are an coordinator agent, you are responsible for coordinating the course instruction flow."
+            "1. First the curriculum designer agent will design the curriculum."
+            "2. Then the instruction designer must design the course instruction."
+            "3. Then the practice designer must design the practice exercises."
+            "4. Then the QA agent must assure that this course has the right quality." 
+                "If it doesn't have the right quality, you should start the flow again from the step the qa agent wasn't satisfied with."
+            "5. In the end based on all of the information provided to you in above steps, write a clear and concise course plan."
+        )
+        
+    def handoff_description(self):
+        return self.instructions()
+    
+    def model(self) -> Literal["gpt-4o-mini", "gpt-4o"]:
+        return "gpt-4o-mini"
+    
+
+class Course(BaseModel):
+    curriculum: Curriculum
+    instruction: Instruction
+    practice: Practice
+    qa: QualityAssurance
+
+
+class CoordinatorAgent():
+    def __init__(self):
+        self.curriculum_designer_agent = CurriculumDesignerAgent()
+        self.instruction_designer_agent = InstructionDesignerAgent()
+        self.practice_designer_agent = PracticeDesignerAgent()
+        self.qa_agent = QAAgent()
+        self.agent = self.init_agent()
+
+    def get_agent(self):
+        return self.agent
+
+    def init_agent(self):
+        tools = [
+            self.curriculum_designer_agent.as_tool(),
+            self.instruction_designer_agent.as_tool(),
+            self.practice_designer_agent.as_tool(),
+            self.qa_agent.as_tool(),
+        ]
+        instructions = CoordinatorInstructions()
+        agent = Agent(
+            name=instructions.name(),
+            instructions=instructions.instructions(),
+            model=instructions.model(),
+            tools=tools,
+        )
+        return agent
+
+    def as_tool(self):
+        instructions = CoordinatorInstructions()
+        return self.agent.as_tool(tool_name=instructions.name(), tool_description=instructions.handoff_description())

course_manager.py

@@ -0,0 +1,39 @@
+import gradio as gr
+from coordinator_agent import CoordinatorAgent
+from dotenv import load_dotenv
+from openai.types.responses import ResponseTextDeltaEvent
+
+from agents import Runner
+
+load_dotenv(override=True)
+
+async def run(query: str):
+    coordinator_agent = CoordinatorAgent().get_agent()
+    result = Runner.run_streamed(coordinator_agent, input=query)
+    response = ""
+    status = ""
+    async for event in result.stream_events():
+        if event.type == "raw_response_event" and isinstance(event.data, ResponseTextDeltaEvent) and event.data.delta:
+            response += event.data.delta
+            yield response, status
+        elif event.type == "run_item_stream_event":
+            item = event.item
+            item_type = getattr(item, "type", "")
+
+            if item_type == "tool_call_item":
+                tool_name = getattr(item.raw_item, 'name', '')
+                log_msg = f"Tool call: {tool_name}\n"
+                status += log_msg
+                yield response, status
+
+with gr.Blocks(theme=gr.themes.Soft(primary_hue="blue")) as ui:
+    gr.Markdown("# Course Instructor Assistant")
+    query_textbox = gr.Textbox(label="What topic would you like to create a course about?", placeholder="e.g. 'How to create your AI double'")
+    run_button = gr.Button("Run", variant="primary")
+    logs = gr.Textbox(label="Logs", placeholder="Logs will appear here")
+    report = gr.Markdown(label="Report")
+    
+    run_button.click(fn=run, inputs=query_textbox, outputs=[report, logs])
+    query_textbox.submit(fn=run, inputs=query_textbox, outputs=[report, logs])
+
+ui.launch(inbrowser=True)

curriculum_designer_agent.py

@@ -0,0 +1,90 @@
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from agents import Agent
+
+
+class CurriculumDesignerInstructions():
+    def name(self):
+        return "curriculum_designer"
+    
+    def instructions(self):
+        return (
+            "You are a curriculum designer. Given a course outline, you design a curriculum for the course. \n"
+            "* Break it into logical modules and lessons. \n"
+            "* Define learning objectives for each module.\n"
+            "* Recommend prerequisites and progression flow. \n"
+            "* The curriculum should be a list of modules, each with a title, description, and a list of lessons. \n"
+            "* Each lesson should have a title, description, and a list of activities. \n"
+            "Each activity should have a title, description, and a list of resources. "
+        )
+    
+    def handoff_description(self):
+        return self.instructions()
+    
+    def model(self) -> Literal["gpt-4o-mini", "gpt-4o"]:
+        return "gpt-4o-mini"
+
+class Activity(BaseModel):
+    """
+    Represents a learning activity within a lesson.
+    
+    Attributes:
+        title (str): The name or heading of the activity
+        description (str): Detailed explanation of what the activity entails
+    """
+    title: str = Field(description="The title of the activity")
+    description: str = Field(description="The description of the activity")
+    
+class Lesson(BaseModel):
+    """
+    Represents a lesson within a module of the curriculum.
+    
+    Attributes:
+        title (str): The name or heading of the lesson
+        description (str): Detailed explanation of the lesson content and objectives
+        activities (list[Activity]): Collection of learning activities that make up the lesson
+    """
+    title: str = Field(description="The title of the lesson")
+    description: str = Field(description="The description of the lesson")
+    activities: list[Activity] = Field(description="The list of activities in the lesson")
+    
+class Module(BaseModel):
+    """
+    Represents a module, which is a major section of the curriculum containing multiple lessons.
+    
+    Attributes:
+        title (str): The name or heading of the module
+        description (str): Detailed explanation of the module's content and learning objectives
+        lessons (list[Lesson]): Collection of lessons that make up the module
+    """
+    title: str = Field(description="The title of the module")
+    description: str = Field(description="The description of the module")
+    lessons: list[Lesson] = Field(description="The list of lessons in the module")
+    
+class Curriculum(BaseModel):
+    """
+    Represents the complete curriculum structure for a course.
+    
+    Attributes:
+        modules (list[Module]): Collection of all modules that make up the complete curriculum
+    """
+    modules: list[Module] = Field(description="The list of the modules of the course")
+
+
+class CurriculumDesignerAgent():
+    def __init__(self):
+        instructions = CurriculumDesignerInstructions()
+        self.agent = Agent(
+            name=instructions.name(),
+            instructions=instructions.instructions(),
+            model=instructions.model(),
+            handoff_description=instructions.handoff_description(),
+            output_type=Curriculum,
+        )
+    
+    def as_tool(self):
+        instructions = CurriculumDesignerInstructions()
+        return self.agent.as_tool(tool_name=instructions.name(), tool_description=instructions.handoff_description())
+    

instruction_designer_agent.py

@@ -0,0 +1,47 @@
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from agents import Agent
+
+
+class InstructionDesignerInstructions():
+    def name(self):
+        return "instruction_designer"
+    
+    def instructions(self):
+        return (
+            "You are an instructional designer agent. Your job is to turn curriculum outlines into engaging, "
+            "clear, and pedagogically sound lesson content. \n"
+            "For each lesson:"
+            "* Follow the learning objectives. \n"
+            "* Write explanations, examples, and step-by-step breakdowns. \n"
+            "* Incorporate analogies or visuals when appropriate (text description only). \n"
+            "* Keep tone aligned with the course level (beginner, intermediate, expert). \n"
+            "Do not generate quizzes or assessments. Pass structured lessons to the next agent."
+        )
+    
+    def handoff_description(self):
+        return self.instructions()
+    
+    def model(self) -> Literal["gpt-4o-mini", "gpt-4o"]:
+        return "gpt-4o-mini"
+    
+class Instruction(BaseModel):
+    title: str = Field(description="The title of the instruction")
+    description: str = Field(description="The description of the instruction")
+
+class InstructionDesignerAgent():
+    def __init__(self):
+        instructions = InstructionDesignerInstructions()
+        self.agent = Agent(
+            name=instructions.name(),
+            instructions=instructions.instructions(),
+            model=instructions.model(),
+            handoff_description=instructions.handoff_description(),
+            output_type=Instruction,
+        )
+    
+    def as_tool(self):
+        instructions = InstructionDesignerInstructions()
+        return self.agent.as_tool(tool_name=instructions.name(), tool_description=instructions.handoff_description())

instructor_assistant.egg-info/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: instructor-assistant
+Version: 0.1.0
+Summary: AI Agent helps instructors create lesson plans, course outline, exercise program... any resource needed for faster course preparation and execution.
+Requires-Python: >=3.11
+Requires-Dist: gradio>=5.49.1
+Requires-Dist: python-dotenv>=1.2.1
+Requires-Dist: openai[agents]>=1.54.0
+Requires-Dist: pydantic>=2.11.10
+Requires-Dist: openai-agents>=0.4.2

instructor_assistant.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+coordinator_agent.py
+course_manager.py
+curriculum_designer_agent.py
+instruction_designer_agent.py
+practice_designer_agent.py
+pyproject.toml
+qa_agent.py
+instructor_assistant.egg-info/PKG-INFO
+instructor_assistant.egg-info/SOURCES.txt
+instructor_assistant.egg-info/dependency_links.txt
+instructor_assistant.egg-info/requires.txt
+instructor_assistant.egg-info/top_level.txt

instructor_assistant.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

instructor_assistant.egg-info/requires.txt

@@ -0,0 +1,5 @@
+gradio>=5.49.1
+python-dotenv>=1.2.1
+openai[agents]>=1.54.0
+pydantic>=2.11.10
+openai-agents>=0.4.2

instructor_assistant.egg-info/top_level.txt

@@ -0,0 +1,6 @@
+coordinator_agent
+course_manager
+curriculum_designer_agent
+instruction_designer_agent
+practice_designer_agent
+qa_agent

practice_designer_agent.py

@@ -0,0 +1,51 @@
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from agents import Agent
+
+
+class PracticeDesignerInstructions():
+    def name(self):
+        return "practice_designer"
+    
+    def instructions(self):
+        return (
+            "You are a test designer agent. Based on lesson content and learning objectives, you generate:\n"
+            "* Multiple choice questions (MCQs). \n"
+            "* Short-answer questions. \n"
+            "* Case-based or scenario-driven exercises (if applicable). \n"
+            "* Include answers and explanations for each item. \n"
+            "* Ensure difficulty aligns with the lesson level and purpose (formative or summative assessment). \n"
+            "* Ensure coverage of all critical concepts. \n"
+        )
+
+    def handoff_description(self):
+        return self.instructions()
+    
+    def model(self) -> Literal["gpt-4o-mini", "gpt-4o"]:
+        return "gpt-4o-mini"
+
+class Question(BaseModel):
+    question: str = Field(description="The question to be asked from the student")
+    answer: str = Field(description="The answer to the question")
+    explanation: str = Field(description="The explanation of the answer")
+
+class Practice(BaseModel):
+    questions: list[Question]
+
+class PracticeDesignerAgent():
+    def __init__(self):
+        instructions = PracticeDesignerInstructions()
+        self.agent = Agent(
+            name=instructions.name(),
+            instructions=instructions.instructions(),
+            model=instructions.model(),
+            handoff_description=instructions.handoff_description(),
+            output_type=Practice,
+        )
+        
+    def as_tool(self):
+        instructions = PracticeDesignerInstructions()
+        return self.agent.as_tool(tool_name=instructions.name(), tool_description=instructions.handoff_description())
+    

pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "instructor-assistant"
+version = "0.1.0"
+description = "AI Agent helps instructors create lesson plans, course outline, exercise program... any resource needed for faster course preparation and execution."
+requires-python = ">=3.11"
+dependencies = [
+    "gradio>=5.49.1",
+    "python-dotenv>=1.2.1",
+    "openai[agents]>=1.54.0",
+    "pydantic>=2.11.10",
+    "openai-agents>=0.4.2",
+]
+
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+py-modules = ["coordinator_agent", "course_manager", "curriculum_designer_agent", "instruction_designer_agent", "practice_designer_agent", "qa_agent"]
+

qa_agent.py

@@ -0,0 +1,49 @@
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from agents import Agent
+
+
+class QAAgentInstructions():
+    def name(self):
+        return "qa_agent"
+    
+    def instructions(self):
+        return (
+            "You are a QA agent. Your job is to review the lesson content and practice activities to ensure \n"
+            "they are aligned with the learning objectives and are appropriate for the course level. \n"
+            "For each lesson: \n"
+            "* Review the lesson content and practice activities. \n"
+            "* Ensure they are aligned with the learning objectives and are appropriate for the course level. \n"
+            "* Ensure they are appropriate for the course level. \n"
+            "Return a JSON that matches the QualityAssurance model with the following fields: \n"
+            "* is_satisfied: Whether the course is satisfied with the quality \n"
+            "* reason: The reason if the satisfied or not, if not it should mention the step that needs to be improved \n"
+        )
+    
+    def handoff_description(self):
+        return self.instructions()
+    
+    def model(self) -> Literal["gpt-4o-mini", "gpt-4o"]:
+        return "gpt-4o-mini"
+    
+class QualityAssurance(BaseModel):
+    is_satisfied: bool = Field(description="Whether the course is satisfied with the quality")
+    reason: str = Field(description="The reason if the satisfied or not, if not it should mention the step that needs to be improved")
+    
+class QAAgent():
+    def __init__(self):
+        instructions = QAAgentInstructions()
+        self.agent = Agent(
+            name=instructions.name(),
+            instructions=instructions.instructions(),
+            model="gpt-4o-mini",
+            handoff_description=instructions.handoff_description(),
+            output_type=QualityAssurance,
+        )
+    
+    
+    def as_tool(self):
+        instructions = QAAgentInstructions()
+        return self.agent.as_tool(tool_name=instructions.name(), tool_description=instructions.handoff_description())

requirements.txt

@@ -0,0 +1,7 @@
+# Main dependencies
+gradio>=5.49.1
+python-dotenv>=1.2.1
+openai[agents]>=1.54.0
+openai-agents>=0.4.2
+pydantic>=2.11.10
+