update docs

app.py

@@ -5,135 +5,151 @@ from io import BytesIO
 from PIL import Image
 import matplotlib.patches as mpatches
 import mplcursors
+import json
 
-# Initialize the lesson plan graph as a directed graph
-lesson_graph = nx.DiGraph()
-
-# Define color map for node types
-color_map = {
-    "User": "#FF9999",  # Light Red
-    "Subject": "#66B2FF",  # Light Blue
-    "Grade Level": "#99FF99",  # Light Green
-    "Learning Objective": "#FFCC99",  # Light Orange
-    "Activity": "#FF99FF",  # Light Purple
-    "Assessment": "#FFFF99",  # Light Yellow
-    "Resource": "#99FFFF",  # Light Cyan
-    "School Board": "#CCCCCC"  # Light Gray
-}
-
-def add_to_graph(teacher_name, subject, grade_level, learning_objective, activity, assessment, resource, school_board):
-    global lesson_graph
-    
-    # Clear previous graph
-    lesson_graph.clear()
-    
-    # Add nodes to the graph with more properties
-    lesson_graph.add_node(teacher_name, type="User", role="Teacher")
-    lesson_graph.add_node(subject, type="Subject", description="Core subject area")
-    lesson_graph.add_node(grade_level, type="Grade Level", description="Target grade for the lesson")
-    lesson_graph.add_node(learning_objective, type="Learning Objective", description="Main goal of the lesson")
-    lesson_graph.add_node(activity, type="Activity", description="Main class activity")
-    lesson_graph.add_node(assessment, type="Assessment", description="Method of evaluating learning")
-    lesson_graph.add_node(resource, type="Resource", description="Materials needed for the lesson")
-    lesson_graph.add_node(school_board, type="School Board", description="Governing educational body")
-    
-    # Add edges to the graph (maintaining directional relationships)
-    lesson_graph.add_edge(teacher_name, subject, relationship="TEACHES")
-    lesson_graph.add_edge(subject, learning_objective, relationship="COVERS")
-    lesson_graph.add_edge(subject, grade_level, relationship="HAS_GRADE")
-    lesson_graph.add_edge(activity, learning_objective, relationship="ACHIEVES")
-    lesson_graph.add_edge(activity, resource, relationship="REQUIRES")
-    lesson_graph.add_edge(learning_objective, assessment, relationship="EVALUATED_BY")
-    lesson_graph.add_edge(teacher_name, school_board, relationship="BELONGS_TO")
-    lesson_graph.add_edge(learning_objective, school_board, relationship="ALIGNS_WITH")
-    
-    # Generate search string
-    search_string = f"{subject} {grade_level} {learning_objective} {activity} {resource}".strip()
-    
-    # Visualize the graph using Matplotlib
-    fig, ax = plt.subplots(figsize=(14, 10))
-    pos = nx.spring_layout(lesson_graph, k=0.9, iterations=50)
-    
-    # Draw nodes with color coding
-    node_colors = [color_map[lesson_graph.nodes[node]['type']] for node in lesson_graph.nodes()]
-    nx.draw_networkx_nodes(lesson_graph, pos, node_color=node_colors, node_size=3000, alpha=0.8, ax=ax)
-    
-    # Draw edges with arrows to show direction
-    nx.draw_networkx_edges(lesson_graph, pos, edge_color='gray', arrows=True, arrowsize=20, ax=ax)
-    nx.draw_networkx_labels(lesson_graph, pos, font_size=10, font_weight="bold", ax=ax)
-    
-    # Add edge labels
-    edge_labels = nx.get_edge_attributes(lesson_graph, 'relationship')
-    nx.draw_networkx_edge_labels(lesson_graph, pos, edge_labels=edge_labels, font_size=8, ax=ax)
-    
-    # Create a legend that categorizes node types
-    legend_elements = [mpatches.Patch(color=color, label=node_type) for node_type, color in color_map.items()]
-    plt.legend(handles=legend_elements, loc='upper left', bbox_to_anchor=(1, 1), title="Node Types")
-    
-    plt.title("Your Educational Landscape", fontsize=16)
-    plt.axis('off')
-    plt.tight_layout()
-    
-    # Add hover functionality
-    cursor = mplcursors.cursor(hover=True)
-    
-    @cursor.connect("add")
-    def on_add(sel):
-        node = list(lesson_graph.nodes())[sel.target.index]
-        node_data = lesson_graph.nodes[node]
-        sel.annotation.set_text(f"Node: {node}\nType: {node_data['type']}\n{node_data.get('description', '')}")
-    
-    # Save the plot to a bytes object
-    buf = BytesIO()
-    plt.savefig(buf, format="png", dpi=300, bbox_inches="tight")
-    buf.seek(0)
-    plt.close(fig)
-    
-    # Convert BytesIO to PIL Image
-    image = Image.open(buf)
-    
-    return search_string, image
-
-def clear_graph():
-    global lesson_graph
-    lesson_graph.clear()
-    return "Landscape cleared. You can start a new lesson plan."
 
-import json
+class LessonGraph:
+    """
+    Class to handle the lesson plan graph construction and manipulation.
+    This encapsulates graph-related logic and avoids using global variables.
+    """
 
-import json
+    def __init__(self):
+        self.graph = nx.DiGraph()
+        self.color_map = {
+            "User": "#FF9999",  # Light Red
+            "Subject": "#66B2FF",  # Light Blue
+            "Grade Level": "#99FF99",  # Light Green
+            "Learning Objective": "#FFCC99",  # Light Orange
+            "Activity": "#FF99FF",  # Light Purple
+            "Assessment": "#FFFF99",  # Light Yellow
+            "Resource": "#99FFFF",  # Light Cyan
+            "School Board": "#CCCCCC"  # Light Gray
+        }
 
-def graph_to_json():
-    try:
-        # Convert the lesson_graph to a dictionary format
-        graph_data = {
-            "nodes": [
-                {
-                    "id": node,
-                    "type": lesson_graph.nodes[node]["type"],
-                    "description": lesson_graph.nodes[node].get("description", "")
-                }
-                for node in lesson_graph.nodes()
-            ],
-            "edges": [
-                {
-                    "source": u,
-                "target": v,
-                    "relationship": lesson_graph.edges[u, v]["relationship"]
-                }
-                for u, v in lesson_graph.edges()
-            ]
+    def add_lesson_plan(self, teacher_name, subject, grade_level, learning_objective, activity, assessment, resource, school_board):
+        """
+        Add nodes and edges to the lesson plan graph for the given inputs.
+        """
+        self.graph.clear()  # Clear previous graph
+        
+        # Define node details and add them to the graph
+        nodes = {
+            teacher_name: {"type": "User", "role": "Teacher"},
+            subject: {"type": "Subject", "description": "Core subject area"},
+            grade_level: {"type": "Grade Level", "description": "Target grade for the lesson"},
+            learning_objective: {"type": "Learning Objective", "description": "Main goal of the lesson"},
+            activity: {"type": "Activity", "description": "Main class activity"},
+            assessment: {"type": "Assessment", "description": "Method of evaluating learning"},
+            resource: {"type": "Resource", "description": "Materials needed for the lesson"},
+            school_board: {"type": "School Board", "description": "Governing educational body"}
         }
+
+        for node, attributes in nodes.items():
+            self.graph.add_node(node, **attributes)
+
+        # Define the relationships between nodes
+        self.graph.add_edges_from([
+            (teacher_name, subject, {"relationship": "TEACHES"}),
+            (subject, learning_objective, {"relationship": "COVERS"}),
+            (subject, grade_level, {"relationship": "HAS_GRADE"}),
+            (activity, learning_objective, {"relationship": "ACHIEVES"}),
+            (activity, resource, {"relationship": "REQUIRES"}),
+            (learning_objective, assessment, {"relationship": "EVALUATED_BY"}),
+            (teacher_name, school_board, {"relationship": "BELONGS_TO"}),
+            (learning_objective, school_board, {"relationship": "ALIGNS_WITH"})
+        ])
+
+        # Return search string for content discovery
+        return f"{subject} {grade_level} {learning_objective} {activity} {resource}".strip()
+
+    def draw_graph(self):
+        """
+        Visualize the graph using Matplotlib, handling layout, labels, and interactivity.
+        """
+        fig, ax = plt.subplots(figsize=(14, 10))
+        pos = nx.spring_layout(self.graph, k=0.9, iterations=50)
+
+        # Draw nodes with color coding
+        node_colors = [self.color_map[self.graph.nodes[node]['type']] for node in self.graph.nodes()]
+        nx.draw_networkx_nodes(self.graph, pos, node_color=node_colors, node_size=3000, alpha=0.8, ax=ax)
+        
+        # Draw edges and labels
+        nx.draw_networkx_edges(self.graph, pos, edge_color='gray', arrows=True, arrowsize=20, ax=ax)
+        nx.draw_networkx_labels(self.graph, pos, font_size=10, font_weight="bold", ax=ax)
+
+        edge_labels = nx.get_edge_attributes(self.graph, 'relationship')
+        nx.draw_networkx_edge_labels(self.graph, pos, edge_labels=edge_labels, font_size=8, ax=ax)
         
-        # Convert dictionary to JSON string
-        json_data = json.dumps(graph_data, indent=4)
+        # Add legend for node types
+        legend_elements = [mpatches.Patch(color=color, label=node_type) for node_type, color in self.color_map.items()]
+        plt.legend(handles=legend_elements, loc='upper left', bbox_to_anchor=(1, 1), title="Node Types")
         
-        # Instead of writing to a file, return the JSON data as a message
-        return f"Graph Data in JSON Format:\n{json_data}"
+        plt.title("Your Educational Landscape", fontsize=16)
+        plt.axis('off')
+        plt.tight_layout()
+        
+        # Add interactivity for hovering over nodes
+        cursor = mplcursors.cursor(hover=True)
+        @cursor.connect("add")
+        def on_add(sel):
+            node = list(self.graph.nodes())[sel.target.index]
+            node_data = self.graph.nodes[node]
+            sel.annotation.set_text(f"Node: {node}\nType: {node_data['type']}\n{node_data.get('description', '')}")
+        
+        # Save the plot to a BytesIO object
+        buf = BytesIO()
+        plt.savefig(buf, format="png", dpi=300, bbox_inches="tight")
+        buf.seek(0)
+        plt.close(fig)
+
+        return Image.open(buf)
+
+    def clear_graph(self):
+        """
+        Clears the lesson plan graph, allowing users to start fresh.
+        """
+        self.graph.clear()
+        return "Landscape cleared. You can start a new lesson plan."
+
+    def graph_to_json(self):
+        """
+        Converts the current lesson plan graph into a JSON string format and returns the result.
 
-    except Exception as e:
-        # If any error occurs, catch it and display it in the message_output
-        return f"An error occurred: {str(e)}"
+        Returns:
+        - str: JSON string representation of the graph or an error message.
+        """
+        try:
+            # Convert the lesson_graph to a dictionary format
+            graph_data = {
+                "nodes": [
+                    {
+                        "id": node,
+                        "type": self.graph.nodes[node]["type"],
+                        "description": self.graph.nodes[node].get("description", "")
+                    }
+                    for node in self.graph.nodes()
+                ],
+                "edges": [
+                    {
+                        "source": u,
+                        "target": v,
+                        "relationship": self.graph.edges[u, v]["relationship"]
+                    }
+                    for u, v in self.graph.edges()
+                ]
+            }
+            
+            # Convert dictionary to JSON string
+            return json.dumps(graph_data, indent=4)
+
+        except Exception as e:
+            # If any error occurs, catch it and display it in the message_output
+            return f"An error occurred: {str(e)}"
+
+
+# Instantiate the LessonGraph class
+lesson_graph = LessonGraph()
 
 # Gradio interface
 demo = gr.Blocks()
@@ -160,9 +176,9 @@ with demo:
     
     with gr.Row():
         generate_btn = gr.Button("Map Your Lesson Plan")
+        graph_btn = gr.Button("Display Graph (JSON)")
         clear_btn = gr.Button("Clear Landscape")
 
-
     examples = [
         ["Sarah Johnson", "Oakville District School Board", "Earth Science", "Grade 7", "Understand the water cycle and its impact on Earth's climate", "Create a terrarium to model the water cycle", "Group presentation on terrarium observations", "Terrarium kit, climate diagrams"],
         ["Marek Nowak", "Warsaw School District", "Matematyka", "Klasa 2", "Zrozumienie podstawowych operacji matematycznych", "Rozwiązywanie prostych zadań tekstowych", "Praca grupowa nad rozwiązywaniem zadań", "Podręcznik, karty pracy, tablica interaktywna"]
@@ -172,21 +188,47 @@ with demo:
     
     search_output = gr.Textbox(label="Content Discovery Search String")
     graph_output = gr.Image(label="Your Educational Landscape")
-    graph_btn = gr.Button("Display Graph (JSON)")
     message_output = gr.Textbox(label="Landscape Status")
     
     generate_btn.click(
-        add_to_graph, 
+        lesson_graph.add_lesson_plan, 
         inputs=[teacher_name, subject, grade_level, learning_objective, activity, assessment, resource, school_board],
         outputs=[search_output, graph_output]
     )
     
     graph_btn.click(
-        graph_to_json,
+        lesson_graph.graph_to_json,
         outputs=[message_output]
     )
     
-    clear_btn.click(clear_graph, outputs=message_output)
+    clear_btn.click(lesson_graph.clear_graph, outputs=message_output)
+
+    # Add Markdown section explaining the purpose and use of the app
+    gr.Markdown("""
+    ## Purpose of EduScape: Understanding Lesson Plans as a Graph
+
+    EduScape helps educators visualize lesson plans as a graph, where key lesson elements (teacher, subject, grade level, learning objectives, activities, assessments, and resources) are represented as nodes with logical relationships. This structure allows teachers to better understand the connections between different parts of their lessons, facilitating clearer planning and discovery of resources.
 
+    ### Key Features:
+    - **User Input-Driven Graph Construction**: Educators can input details like teacher name, subject, grade level, learning objective, activity, assessment, and resources to automatically construct a lesson plan graph.
+    - **Graph Visualization**: Each element of the lesson plan is represented as a node, and the connections between these elements (like how an activity achieves the learning objective) are visualized through edges.
+    - **Content Discovery**: The system generates a search string based on input, which can help the teacher discover content or resources to support their lesson plan.
+
+    ### Logical Flow of the Knowledge Graph:
+    1. The **Teacher** node connects to the **Subject** node (representing what the teacher teaches).
+    2. The **Subject** node connects to both the **Grade Level** and **Learning Objective** (defining what is taught and to whom).
+    3. The **Activity** node links to the **Learning Objective** (showing how the objective is achieved through student engagement).
+    4. The **Assessment** node connects to the **Learning Objective** (indicating how learning is evaluated).
+    5. The **Resource** node connects to the **Activity** (detailing what materials are needed for the activity).
+    6. The **Teacher** also connects to the **School Board** (showing which governing body the teacher belongs to).
+    7. The **Learning Objective** aligns with **School Board** standards (ensuring that the lesson adheres to curriculum requirements).
+
+    ### Example Use Case:
+    A teacher, Sarah Johnson, inputs her lesson plan for Grade 7 Earth Science focused on understanding the water cycle. She adds an activity where students create a terrarium and a group presentation for assessment. The system visualizes the relationships between these elements in the graph and generates a content discovery string to help her find additional resources like a terrarium kit or climate diagrams. 
+
+    EduScape ensures that teachers can organize their lessons effectively while aligning with the curriculum and potentially discovering paid or free resources to enhance their lesson delivery.
+    """)
+    
 # Launch the EduScape app
 demo.launch()
+