Add detailed comments to improve code readability

Author: hirune924

README.md

@@ -15,11 +15,13 @@ A reference implementation for building chat applications with LangGraph and Str
 - **Multimodal Support**: Image input handling for compatible models
 - **Extensible Agent System**: Abstract base class (`AgentConfig`) makes it straightforward to add custom agents with their own configuration UI
 
-## Supported Providers
+## Implemented Providers
 
 - **OpenAI**: GPT-4o, GPT-4 Turbo, o1, o3-mini
 - **Anthropic**: Claude Sonnet 4, Claude 3.7 Sonnet, Claude 3.5 Sonnet/Haiku
 
+Additional providers can be easily added by implementing the `AgentConfig` interface (see [Adding Custom Agents](#adding-custom-agents)).
+
 ## Quick Start
 
 1. **Clone and install:**

app/app.py

@@ -20,20 +20,24 @@
 
 
 def main():
+    """Main Streamlit application for LangGraph Agent Chat."""
     st.title("LangGraph Agent Chat")
     initialize_checkpoint()
 
+    # === Sidebar: Conversation and Agent Management ===
     with st.sidebar:
         st.header("💬 Conversations")
 
-        # Thread management
+        # Thread management: Get existing threads and determine current thread
         threads, latest = get_threads(st.session_state.checkpoint)
         current = st.session_state.get('thread_id') or latest or str(uuid.uuid4())
         st.session_state.thread_id = current
 
+        # Ensure current thread appears in the list
         if current not in threads:
             threads.insert(0, current)
 
+        # Thread selection dropdown
         st.selectbox(
             "Select thread",
             threads,
@@ -45,6 +49,7 @@ def main():
         st.button("New chat", on_click=lambda: setattr(st.session_state, 'thread_id', str(uuid.uuid4())))
         st.button("Delete current chat", on_click=on_delete_thread, args=(st.session_state.thread_id,))
 
+        # Streaming toggle
         use_streaming = st.checkbox(
             "Enable Streaming",
             value=True,
@@ -55,7 +60,7 @@ def main():
         st.divider()
         st.header("⚙️ Agent Settings")
 
-        # Agent selection
+        # Agent selection: Display available agents
         agent_names = [agent.get_name() for agent in AVAILABLE_AGENTS]
         if not agent_names:
             st.warning("No agents configured. Please add agents to AVAILABLE_AGENTS.")
@@ -73,10 +78,11 @@ def main():
             st.warning("No agents configured. Please add agents to AVAILABLE_AGENTS.")
             st.stop()
 
+        # Render agent-specific configuration UI
         st.subheader("Agent Options")
         options = selected_agent_config.render_options()
 
-        # Rebuild agent if needed
+        # Rebuild agent if configuration changed
         prev_name = st.session_state.get("current_agent_name")
         needs_rebuild = (
             prev_name != selected_name or
@@ -90,65 +96,75 @@ def main():
                 st.session_state.current_agent_name = selected_name
                 st.session_state.agent_options = options
 
+    # === Main Area: Chat Interface ===
+    # Chat input with multimodal support (text + images)
     submission = st.chat_input(
         "Ask me anything!",
         accept_file=True,
         file_type=["jpg", "jpeg", "png"],
     )
 
+    # Display conversation history
     display_chat_history(st.session_state.checkpoint, st.session_state.thread_id)
 
+    # Handle new user input
     if submission:
-        # Parse submission
+        # Parse submission (handles both dict and object formats)
         if isinstance(submission, dict):
             user_text = submission.get("text", "")
             user_files = submission.get("files", [])
         else:
             user_text = getattr(submission, "text", submission if isinstance(submission, str) else "")
             user_files = getattr(submission, "files", [])
 
+        # Convert to LangChain message format
         content = convert_input_to_content(user_text, user_files)
 
         # Display user message
         with st.chat_message("user"):
             render_content(content)
 
-        # Assistant response
+        # Generate and display assistant response
         use_streaming = st.session_state.get("use_streaming", True)
 
         with st.chat_message("assistant"):
             if use_streaming:
-                # Stream response with fixed order: thinking → tools → text
+                # Streaming mode: Display thinking, tools, and text in separate containers
+                # This ensures proper ordering even when messages arrive out of order
                 thinking_container = st.container()
                 tools_container = st.container()
                 text_container = st.container()
                 text_buffer = []
 
                 def render_to_container(title, payload):
+                    """Route thinking/tool messages to appropriate containers."""
                     target = thinking_container if "Thinking" in title else tools_container
                     with target:
                         render_tool(title, payload)
 
                 with text_container:
                     text_element = st.empty()
 
+                # Stream agent response
                 stream = st.session_state.agent.stream(
                     {"messages": [HumanMessage(content=content)]},  # type: ignore[arg-type]
                     config={"configurable": {"thread_id": st.session_state.thread_id}},
                     stream_mode="messages",
                 )
 
+                # Process stream and display text chunks incrementally
                 for text_chunk in extract_text_chunks(stream, tool_callback=render_to_container):
                     text_buffer.append(text_chunk)
                     text_element.markdown("".join(text_buffer))
             else:
-                # Invoke (non-streaming)
+                # Non-streaming mode: Invoke agent and wait for complete response
                 with st.spinner("Processing..."):
                     st.session_state.agent.invoke(
                         {"messages": [HumanMessage(content=content)]},  # type: ignore[arg-type]
                         config={"configurable": {"thread_id": st.session_state.thread_id}},
                     )
 
+        # Rerun to display the new message from history
         st.rerun()
 
 

app/utils.py

@@ -20,15 +20,31 @@ def extract_text_chunks(
     message_stream: Iterator[Any],
     tool_callback: Callable[[str, Any], None] | None = None
 ) -> Iterator[str]:
-    """Extract text chunks from a stream, handling tool and thinking messages separately."""
+    """Extract text chunks from a stream, handling tool and thinking messages separately.
+
+    This function processes streaming responses from LLM agents and separates:
+    - Text content: Yielded for display
+    - Thinking blocks: Buffered and sent via callback
+    - Tool calls: Sent via callback immediately
+
+    Args:
+        message_stream: Stream of message events from the agent
+        tool_callback: Optional callback for tool/thinking messages
+
+    Yields:
+        Text chunks to be displayed to the user
+    """
+    # Buffer for accumulating thinking content before displaying
     thinking_buffer: list[str] = []
 
     def flush_thinking() -> None:
+        """Send buffered thinking content via callback and clear buffer."""
         if thinking_buffer and tool_callback:
             tool_callback("💭 Thinking", "".join(thinking_buffer))
             thinking_buffer.clear()
 
     for event in message_stream:
+        # Unwrap event tuple if needed
         chunk = event[0] if isinstance(event, tuple) else event
         msg_type = getattr(chunk, "type", None)
 
@@ -42,7 +58,7 @@ def flush_thinking() -> None:
 
         content = getattr(chunk, "content", None)
 
-        # Anthropic: content is list of parts
+        # Anthropic: content is a list of parts (multimodal/thinking/text)
         if isinstance(content, list):
             for part in content:
                 if not isinstance(part, dict):
@@ -51,19 +67,23 @@ def flush_thinking() -> None:
                 part_type = part.get("type")
 
                 if part_type == "thinking":
+                    # Accumulate thinking content in buffer
                     thinking_buffer.append(part.get("thinking", ""))
                 elif part_type == "tool_use":
+                    # Flush thinking before tool use
                     flush_thinking()
                 elif part_type == "text":
+                    # Flush thinking before displaying text
                     flush_thinking()
                     if text := part.get("text"):
                         yield text
 
-        # OpenAI: content is string
+        # OpenAI: content is a simple string
         elif isinstance(content, str):
             flush_thinking()
             yield content
 
+    # Flush any remaining thinking content at the end
     flush_thinking()
 
 
@@ -143,14 +163,29 @@ def render_content(content: str | list[Any]) -> None:
 
 
 def convert_input_to_content(user_text: str, user_files: list[Any]) -> str | list[dict[str, Any]]:
-    """Convert Streamlit chat input to LangChain message content format."""
+    """Convert Streamlit chat input to LangChain message content format.
+
+    Handles both text-only and multimodal (text + images) inputs.
+    - Text only: Returns simple string
+    - Text + images: Returns list of content parts with base64-encoded images
+
+    Args:
+        user_text: User's text input
+        user_files: List of uploaded files from Streamlit
+
+    Returns:
+        String for text-only, or list of content parts for multimodal input
+    """
+    # Text-only input: return as simple string
     if not user_files:
         return user_text.strip() if isinstance(user_text, str) else ""
 
+    # Multimodal input: build list of content parts
     parts: list[dict[str, Any]] = []
     if isinstance(user_text, str) and user_text.strip():
         parts.append({"type": "text", "text": user_text.strip()})
 
+    # Convert uploaded images to base64 data URLs
     for f in user_files:
         mime_type = getattr(f, 'type', None) or 'image/png'
         encoded = base64.b64encode(f.getvalue()).decode('utf-8')