Streamlined code, added a clear button and updated the agent instructions. Also updated the environment to make it HuggingFace-GitHub friendly

README.md

@@ -1,6 +1,6 @@
-# instructor_assistant
+# Instructor Assistant
 
-AI Agent helps instructors create lesson plans, course outline, exercise program... any resource needed for faster course preparation and execution.
+An AI-powered multi-agent system that helps instructors create comprehensive course content including lesson plans, curriculum outlines, practice exercises, and quality assurance. The system uses OpenAI's Agent Framework to orchestrate specialized agents that collaborate to produce complete, well-structured course materials.
 
 ## Setup with UV
 
@@ -50,3 +50,168 @@ Create a `.env` file in the project root with your OpenAI API key:
 ```
 OPENAI_API_KEY=your_api_key_here
 ```
+
+## Architecture
+
+The application follows a multi-agent architecture where specialized agents collaborate to create comprehensive course content. Each agent is responsible for a specific aspect of course design.
+
+### Module Overview
+
+#### 1. **coordinator_agent.py** - Main Orchestrator
+The coordinator agent manages the entire course creation workflow by orchestrating all specialized agents.
+
+**Key Components:**
+- `CoordinatorAgent`: Main orchestrator that coordinates the workflow
+- `Course`: Pydantic model representing the complete course with curriculum, instruction, practice, and QA
+- `CoordinatorInstructions`: Defines the workflow and agent responsibilities
+
+**Responsibilities:**
+1. Delegates curriculum design to CurriculumDesignerAgent
+2. Delegates instruction design to InstructionDesignerAgent
+3. Delegates practice exercise creation to PracticeDesignerAgent
+4. Delegates quality assurance to QAAgent
+5. Restarts the workflow if QA agent is not satisfied
+6. Generates final course plan
+
+#### 2. **curriculum_designer_agent.py** - Curriculum Designer
+Creates the structured curriculum with modules, lessons, and activities.
+
+**Key Components:**
+- `CurriculumDesignerAgent`: Designs the overall curriculum structure
+- `Curriculum`: Pydantic model representing the complete curriculum
+- `Module`: Represents a major section containing multiple lessons
+- `Lesson`: Represents a lesson containing multiple activities
+- `Activity`: Represents a learning activity within a lesson
+
+**Responsibilities:**
+- Break topics into logical modules and lessons
+- Define learning objectives for each module
+- Recommend prerequisites and progression flow
+- Structure content hierarchically (modules → lessons → activities)
+
+#### 3. **instruction_designer_agent.py** - Instruction Designer
+Creates engaging and pedagogically sound lesson content.
+
+**Key Components:**
+- `InstructionDesignerAgent`: Designs instructional content
+- `Instruction`: Pydantic model with title and description
+
+**Responsibilities:**
+- Transform curriculum outlines into detailed lesson content
+- Write clear explanations, examples, and step-by-step breakdowns
+- Incorporate pedagogical best practices
+- Maintain appropriate tone for course level
+
+#### 4. **practice_designer_agent.py** - Practice Exercise Creator
+Generates practice exercises and assessments for students.
+
+**Key Components:**
+- `PracticeDesignerAgent`: Creates practice exercises
+- `Practice`: Pydantic model containing questions
+- `Question`: Individual question with answer and explanation
+
+**Responsibilities:**
+- Generate multiple choice questions (MCQs)
+- Create short-answer questions
+- Design case-based and scenario-driven exercises
+- Provide answers and explanations for all items
+- Align difficulty with lesson level
+
+#### 5. **qa_agent.py** - Quality Assurance
+Ensures the course content meets quality standards and learning objectives.
+
+**Key Components:**
+- `QAAgent`: Reviews course quality
+- `QualityAssurance`: Pydantic model with satisfaction status and feedback
+
+**Responsibilities:**
+- Review lesson content and practice activities
+- Verify alignment with learning objectives
+- Ensure appropriate difficulty level
+- Identify areas needing improvement
+- Trigger workflow restart if quality standards aren't met
+
+#### 6. **course_manager.py** - User Interface
+Gradio-based web interface for interacting with the assistant.
+
+**Key Features:**
+- Simple, modern UI built with Gradio
+- Real-time streaming of AI responses
+- Logs textbox (5 lines visible before scrollbar)
+- Interactive course plan display
+- Run and Clear buttons for easy interaction
+- Clear button dynamically enabled only when query text is present
+- Increased max_turns (30) to handle complex multi-agent workflows
+
+**Usage Flow:**
+1. User enters a course topic
+2. System generates curriculum, instruction, practice exercises
+3. QA agent reviews the content
+4. If quality is met, final course plan is displayed
+5. If not, the process repeats with improvements
+
+## Agent Workflow
+
+```
+User Input → Coordinator Agent
+              ↓
+        CurriculumDesignerAgent (Step 1: Design curriculum structure)
+              ↓
+        InstructionDesignerAgent (Step 2: Create lesson content)
+              ↓
+        PracticeDesignerAgent (Step 3: Create practice exercises)
+              ↓
+        QAAgent (Step 4: Quality assurance)
+              ↓
+        [If QA fails, restart from appropriate step]
+              ↓
+        Final Course Plan
+```
+
+## Data Models
+
+All agents use Pydantic models for structured data validation and type safety:
+- **Curriculum**: Hierarchical structure with modules, lessons, and activities
+- **Instruction**: Lesson content with title and description
+- **Practice**: Collection of questions with answers and explanations
+- **QualityAssurance**: QA status with satisfaction flag and feedback
+- **Course**: Complete course containing all components
+
+## Technology Stack
+
+- **Python 3.11+**: Core programming language
+- **UV**: Fast Python package manager and project management
+- **OpenAI Agents Framework**: Multi-agent orchestration and tool calling
+- **OpenAI API**: GPT-4o-mini for agent reasoning
+- **Pydantic**: Data validation and type safety
+- **Gradio 4.44.1**: Web-based user interface
+- **Hugging Face Hub**: Deployment platform integration
+- **Python-dotenv**: Environment variable management
+
+## Dependencies
+
+Main dependencies (see `requirements.txt` or `pyproject.toml`):
+- `gradio==4.44.1` - Web UI framework
+- `python-dotenv==1.2.1` - Environment variable management
+- `openai==2.6.1` - OpenAI API client
+- `pydantic==2.11.10` - Data validation and type safety
+- `mailjet-rest==1.5.1` - Email integration (optional)
+- `openai-agents>=0.4.2` - Multi-agent orchestration
+- `huggingface-hub==0.22.2` - Hugging Face Spaces deployment support
+- `typer>=0.20.0` - CLI interface (optional)
+
+**Note:** Requirements are pinned to specific versions for Hugging Face Spaces deployment compatibility.
+
+## Deployment
+
+### Hugging Face Spaces
+
+This project is configured for easy deployment to Hugging Face Spaces with GitHub repository sync:
+
+1. **Create a new Space** on [Hugging Face](https://huggingface.co/spaces)
+2. **Connect your GitHub repository** to the Space
+3. **Set environment variables** in the Space settings:
+   - `OPENAI_API_KEY`: Your OpenAI API key
+4. **Enable automatic deployment** - the Space will sync with your GitHub repository
+
+The `requirements.txt` file is configured with pinned versions compatible with Hugging Face Spaces. The Gradio app will automatically launch when deployed.

coordinator_agent.py

@@ -1,35 +1,25 @@
 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 curriculum_designer_agent import CurriculumDesignerAgent
+from instruction_designer_agent import InstructionDesignerAgent
+from practice_designer_agent import PracticeDesignerAgent
+from qa_agent import QAAgent
 
 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."
+            "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. " 
+                "\tIf it doesn't have the right quality, you should start the flow again from "
+                "\tthe 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."
         )
         
@@ -38,13 +28,6 @@ class CoordinatorInstructions():
     
     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():
@@ -76,4 +59,7 @@ class CoordinatorAgent():
 
     def as_tool(self):
         instructions = CoordinatorInstructions()
-        return self.agent.as_tool(tool_name=instructions.name(), tool_description=instructions.handoff_description())
+        return self.agent.as_tool(
+            tool_name=instructions.name(),
+            tool_description=instructions.handoff_description()
+        )

course_manager.py

@@ -9,7 +9,7 @@ load_dotenv(override=True)
 
 async def run(query: str):
     coordinator_agent = CoordinatorAgent().get_agent()
-    result = Runner.run_streamed(coordinator_agent, input=query)
+    result = Runner.run_streamed(coordinator_agent, input=query, max_turns=30)
     response = ""
     status = ""
     async for event in result.stream_events():
@@ -26,14 +26,24 @@ async def run(query: str):
                 status += log_msg
                 yield response, status
 
-with gr.Blocks(theme=gr.themes.Soft(primary_hue="blue")) as ui:
+def clear_fields():
+    return "", ""
+
+def update_clear_button(query: str):
+    return gr.update(interactive=bool(query.strip()))
+
+with gr.Blocks(theme=gr.themes.Glass(primary_hue="fuchsia")) 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")
+    with gr.Row():
+        run_button = gr.Button("Run", variant="primary")
+        clear_button = gr.Button("Clear", variant="secondary", interactive=False)
+    logs = gr.Textbox(label="Logs", placeholder="Logs will appear here", lines=5)
     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])
+    clear_button.click(fn=clear_fields, outputs=[query_textbox, logs])
+    query_textbox.change(fn=update_clear_button, inputs=query_textbox, outputs=clear_button)
 
-ui.launch(inbrowser=True)
+ui.launch(share=True, inbrowser=True)

curriculum_designer_agent.py

@@ -14,10 +14,14 @@ class CurriculumDesignerInstructions():
             "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"
+            "* There should be a minimum of 3 modules and a maximum of 5 modules. \n"
+            "* Each module should have a minimum of 3 lessons and a maximum of 5 lessons. \n"
+            "* Each lesson should have a minimum of 3 activities and a maximum of 5 activities. \n"
+            "* Each activity should have a minimum of 2 resources and a maximum of 5 resources. \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. "
+            "* Each activity should have a title, description, and a list of resources. \n"
+            "* Recommend prerequisites and progression flow. \n"
         )
     
     def handoff_description(self):

qa_agent.py

@@ -16,7 +16,6 @@ class QAAgentInstructions():
             "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"
@@ -38,7 +37,7 @@ class QAAgent():
         self.agent = Agent(
             name=instructions.name(),
             instructions=instructions.instructions(),
-            model="gpt-4o-mini",
+            model=instructions.model(),
             handoff_description=instructions.handoff_description(),
             output_type=QualityAssurance,
         )

requirements.txt

@@ -1,7 +1,9 @@
 # Main dependencies
-gradio>=5.49.1
-python-dotenv>=1.2.1
-openai[agents]>=1.54.0
+gradio==4.44.1
+python-dotenv==1.2.1
+openai==2.6.1
+pydantic==2.11.10
+mailjet-rest==1.5.1
 openai-agents>=0.4.2
-pydantic>=2.11.10
-
+huggingface-hub==0.22.2
+typer>=0.20.0