release: v1.0.0-beta - LLM AI Refactoring & Bug Fixes

- Redesigned AI explanation panel with black/white minimalist theme
- Added unavailable state UI when LLM not configured
- Improved prompt templates with clearer JSON output format
- Multi-strategy JSON parsing with fallback mechanisms
- Thread-safe caching with TTL for explanations
- Case-insensitive model name matching
- Fixed model not loading when clicking Load button
- Fixed UI stuck at loading state
- Fixed false 'loaded' display when model not actually loaded
- Fixed React Hooks error (useMemo order)
- Added custom event system for cross-component communication

Author: ChidcGithub

README.md

@@ -13,11 +13,11 @@
 
 # PyVizAST
 
-[![Version](https://img.shields.io/badge/Version-1.0.0--alpha-blue.svg)](https://github.com/ChidcGithub/PyVizAST)
+[![Version](https://img.shields.io/badge/Version-1.0.0--beta-blue.svg)](https://github.com/ChidcGithub/PyVizAST)
 [![Python](https://img.shields.io/badge/Python-3.9%2B-brightgreen.svg)](https://www.python.org/)
 [![License](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](LICENSE)
 [![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)](https://github.com/ChidcGithub/PyVizAST)
-[![Status](https://img.shields.io/badge/Status-alpha-red.svg)](https://github.com/ChidcGithub/PyVizAST)
+[![Status](https://img.shields.io/badge/Status-beta-orange.svg)](https://github.com/ChidcGithub/PyVizAST)
 ![CI Build Status](https://github.com/ChidcGithub/PyVizAST/actions/workflows/ci.yml/badge.svg)
 
 A Python AST Visualizer & Static Analyzer that transforms code into interactive graphs. Detect complexity, performance bottlenecks, and code smells with actionable refactoring suggestions.
@@ -48,7 +48,7 @@ A Python AST Visualizer & Static Analyzer that transforms code into interactive
 - **Beginner Mode**: Display Python documentation when hovering over AST nodes
 - **Challenge Mode**: Identify performance issues in provided code samples
 
-### LLM AI Features (v1.0.0-alpha)
+### LLM AI Features (v1.0.0-beta)
 - **Local LLM Integration**: Powered by Ollama for privacy-first AI features
 - **Auto Install Ollama**: One-click automatic Ollama installation and configuration
 - **AI Node Explanations**: Get intelligent explanations for any AST node
@@ -235,6 +235,57 @@ Contributions are welcome. Please submit pull requests to the main repository.
 
 <summary>Version History</summary>
 
+<details>
+<summary>v1.0.0-beta (2026-03-21)</summary>
+
+**LLM AI Refactoring & Bug Fixes**
+
+**LLM Explanation Panel Refactoring:**
+- Redesigned AI explanation panel with premium black/white minimalist theme
+- Added unavailable state UI with helpful messages when LLM not configured
+- Added fullscreen modal for detailed reading
+- Improved loading states and error handling
+- Auto-retry on failure (up to 2 times)
+
+**Backend LLM Service Refactoring:**
+- Improved prompt templates with clearer JSON output format requirements
+- Multi-strategy JSON parsing with fallback mechanisms
+- Thread-safe caching with TTL for explanation caching
+- Case-insensitive model name matching (codeLlama:7b vs codellama:7b)
+- Separated error handling for availability check and model listing
+- Added shorter timeouts to avoid UI hanging
+
+**Frontend LLM Integration Improvements:**
+- Added custom event system (`llmConfigChanged`) for cross-component communication
+- Fixed React Hooks order issue (useMemo before early return)
+- Fixed incorrect default status value (`'ready'` → `'unavailable'`)
+- Improved SSE parsing with type annotations
+- Better error feedback and loading states
+
+**Files Added:**
+- `frontend/src/components/LLMExplanationPanel.js` - AI explanation panel component
+- `frontend/src/components/LLMExplanationPanel.css` - Black/white minimalist styles
+
+**Files Modified:**
+- `backend/llm/prompts.py` - Improved prompt templates
+- `backend/llm/service.py` - Multi-strategy parsing, caching, status handling
+- `backend/llm/ollama_client.py` - Shorter timeouts
+- `backend/routers/llm.py` - Unified error responses, detailed logging
+- `frontend/src/api.js` - SSE parsing, shorter timeouts
+- `frontend/src/components/LLMSettings.js` - Event dispatching, improved status handling
+- `frontend/src/components/ASTVisualizer.js` - Event listeners, fixed default status
+- `frontend/src/components/ASTVisualizer3D.js` - Event listeners, fixed default status
+- `frontend/src/components/components.css` - LLM explanation panel styles
+
+**Bug Fixes:**
+- Fixed model not loading when clicking Load button
+- Fixed UI stuck at loading state (timeout optimization)
+- Fixed false "loaded" display when model not actually loaded
+- Fixed React Hooks error (useMemo called after early return)
+- Fixed model name case sensitivity matching
+
+</details>
+
 <details>
 <summary>v1.0.0-alpha (2026-03-16)</summary>
 

backend/ast_parser/node_builder.py

@@ -262,18 +262,6 @@ def _count_structures(self, node: ast.AST) -> Dict[str, int]:
 
         return counts
 
-    def _count_branches(self, node: ast.AST) -> int:
-        """Count number of if/elif/else branches - deprecated, use _count_structures"""
-        return self._count_structures(node)['branches']
-    
-    def _count_loops(self, node: ast.AST) -> int:
-        """Count number of loops - deprecated, use _count_structures"""
-        return self._count_structures(node)['loops']
-    
-    def _count_exception_handlers(self, node: ast.AST) -> int:
-        """Count number of except handlers - deprecated, use _count_structures"""
-        return self._count_structures(node)['exception_handlers']
-    
     def _generate_detailed_label(self, ast_node: ast.AST, node_type: NodeType, 
                                   name: Optional[str], attributes: Dict[str, Any]) -> str:
         """Generate detailed node label for better understanding"""

backend/config.py

@@ -3,6 +3,6 @@
 All version numbers are managed in this single file for easy updates.
 """
 
-VERSION = "1.0.0-alpha"
-BUILD = "3230"
+VERSION = "1.0.0-beta"
+BUILD = "3300"
 FULL_VERSION = f"v{VERSION}"

backend/llm/ollama_client.py

@@ -9,6 +9,7 @@
 import logging
 import httpx
 from typing import List, Optional, Dict, Any, AsyncIterator
+import atexit
 
 from .models import ModelInfo, LLMConfig
 
@@ -21,27 +22,97 @@ class OllamaError(Exception):
 
 
 class OllamaClient:
-    """Client for Ollama API"""
+    """Client for Ollama API with connection pooling"""
+    
+    # Shared client instance for connection pooling
+    _shared_client: Optional[httpx.AsyncClient] = None
+    
+    @classmethod
+    def _get_shared_client(cls, timeout: httpx.Timeout) -> httpx.AsyncClient:
+        """Get or create shared HTTP client for connection pooling"""
+        if cls._shared_client is None or cls._shared_client.is_closed:
+            cls._shared_client = httpx.AsyncClient(
+                timeout=timeout,
+                limits=httpx.Limits(
+                    max_connections=10,
+                    max_keepalive_connections=5,
+                    keepalive_expiry=30.0
+                )
+            )
+        return cls._shared_client
+    
+    @classmethod
+    def close_shared_client(cls):
+        """Close shared client (call on shutdown)
+        
+        This method is registered with atexit but may not work reliably
+        for async clients. Prefer using shutdown_async() in FastAPI lifespan.
+        """
+        if cls._shared_client and not cls._shared_client.is_closed:
+            import asyncio
+            client = cls._shared_client
+            cls._shared_client = None  # Clear reference first to prevent double close
+            
+            try:
+                # Try to get running loop
+                loop = asyncio.get_running_loop()
+                # If we have a running loop, schedule the close
+                loop.call_soon_threadsafe(lambda: loop.create_task(client.aclose()))
+            except RuntimeError:
+                # No running loop available
+                try:
+                    # Try to create a new loop and run the close
+                    loop = asyncio.new_event_loop()
+                    asyncio.set_event_loop(loop)
+                    try:
+                        loop.run_until_complete(client.aclose())
+                    finally:
+                        loop.close()
+                except Exception as e:
+                    # Last resort: just set to None and let GC handle it
+                    logger.debug(f"Could not close HTTP client gracefully: {e}")
+    
+    @classmethod
+    async def shutdown_async(cls):
+        """Async shutdown for use in FastAPI lifespan context"""
+        if cls._shared_client and not cls._shared_client.is_closed:
+            client = cls._shared_client
+            cls._shared_client = None
+            try:
+                await client.aclose()
+                logger.debug("HTTP client closed successfully")
+            except Exception as e:
+                logger.warning(f"Error closing HTTP client: {e}")
 
     def __init__(self, config: LLMConfig):
         self.config = config
         self.base_url = config.base_url.rstrip("/")
         self.timeout = httpx.Timeout(config.timeout)
 
+    @property
+    def client(self) -> httpx.AsyncClient:
+        """Get shared HTTP client"""
+        return self._get_shared_client(self.timeout)
+    
     async def is_available(self) -> bool:
         """Check if Ollama server is running"""
         try:
+            # Use a quick timeout for availability check
             async with httpx.AsyncClient(timeout=5.0) as client:
                 response = await client.get(f"{self.base_url}/api/tags")
                 return response.status_code == 200
-        except Exception as e:
+        except (httpx.ConnectError, httpx.TimeoutException, httpx.NetworkError) as e:
             logger.debug(f"Ollama not available: {e}")
             return False
+        except httpx.HTTPStatusError as e:
+            logger.warning(f"Ollama returned error status: {e}")
+            return False
 
     async def list_models(self) -> List[ModelInfo]:
         """List all pulled models"""
         try:
-            async with httpx.AsyncClient(timeout=self.timeout) as client:
+            # Use a shorter timeout for listing models
+            async with httpx.AsyncClient(timeout=10.0) as client:
                 response = await client.get(f"{self.base_url}/api/tags")
                 response.raise_for_status()
                 data = response.json()
@@ -56,21 +127,23 @@ async def list_models(self) -> List[ModelInfo]:
                         details=model.get("details")
                     ))
                 return models
+        except (httpx.ConnectError, httpx.TimeoutException, httpx.NetworkError) as e:
+            logger.debug(f"Failed to list models (network error): {e}")
+            raise OllamaError(f"Failed to connect to Ollama: {e}")
         except httpx.HTTPError as e:
             logger.error(f"Failed to list models: {e}")
             raise OllamaError(f"Failed to list models: {e}")
 
     async def get_model_info(self, model_name: str) -> Optional[Dict[str, Any]]:
         """Get information about a specific model"""
         try:
-            async with httpx.AsyncClient(timeout=self.timeout) as client:
-                response = await client.post(
-                    f"{self.base_url}/api/show",
-                    json={"name": model_name}
-                )
-                if response.status_code == 200:
-                    return response.json()
-                return None
+            response = await self.client.post(
+                f"{self.base_url}/api/show",
+                json={"name": model_name}
+            )
+            if response.status_code == 200:
+                return response.json()
+            return None
         except Exception as e:
             logger.error(f"Failed to get model info: {e}")
             return None
@@ -99,12 +172,11 @@ async def pull_model(self, model_name: str) -> AsyncIterator[Dict[str, Any]]:
     async def delete_model(self, model_name: str) -> bool:
         """Delete a model"""
         try:
-            async with httpx.AsyncClient(timeout=self.timeout) as client:
-                response = await client.delete(
-                    f"{self.base_url}/api/delete",
-                    json={"name": model_name}
-                )
-                return response.status_code == 200
+            response = await self.client.delete(
+                f"{self.base_url}/api/delete",
+                json={"name": model_name}
+            )
+            return response.status_code == 200
         except Exception as e:
             logger.error(f"Failed to delete model: {e}")
             return False
@@ -135,14 +207,13 @@ async def generate(
             payload["system"] = system
 
         try:
-            async with httpx.AsyncClient(timeout=self.timeout) as client:
-                response = await client.post(
-                    f"{self.base_url}/api/generate",
-                    json=payload
-                )
-                response.raise_for_status()
-                data = response.json()
-                return data.get("response", "")
+            response = await self.client.post(
+                f"{self.base_url}/api/generate",
+                json=payload
+            )
+            response.raise_for_status()
+            data = response.json()
+            return data.get("response", "")
         except httpx.HTTPError as e:
             logger.error(f"Generation failed: {e}")
             raise OllamaError(f"Generation failed: {e}")
@@ -213,14 +284,17 @@ async def chat(
         }
 
         try:
-            async with httpx.AsyncClient(timeout=self.timeout) as client:
-                response = await client.post(
-                    f"{self.base_url}/api/chat",
-                    json=payload
-                )
-                response.raise_for_status()
-                data = response.json()
-                return data.get("message", {}).get("content", "")
+            response = await self.client.post(
+                f"{self.base_url}/api/chat",
+                json=payload
+            )
+            response.raise_for_status()
+            data = response.json()
+            return data.get("message", {}).get("content", "")
         except httpx.HTTPError as e:
             logger.error(f"Chat failed: {e}")
             raise OllamaError(f"Chat failed: {e}")
+
+
+# Register cleanup on exit
+atexit.register(OllamaClient.close_shared_client)