sunholo 0.144.2__py3-none-any.whl → 0.144.4__py3-none-any.whl

sunholo/agents/fastapi/vac_routes.py

@@ -113,31 +113,92 @@ class VACRoutesFastAPI:
     
     ## Basic Usage
     
+    ### Simplified Setup (Recommended)
+    
+    Use the helper method for automatic lifespan management:
+    
     ```python
-    from fastapi import FastAPI
     from sunholo.agents.fastapi import VACRoutesFastAPI
     
-    app = FastAPI()
-    
     async def my_stream_interpreter(question, vector_name, chat_history, callback, **kwargs):
         # Your streaming VAC logic here
         # Use callback.async_on_llm_new_token(token) for streaming
-        # Return final result with sources
         return {"answer": "Response", "sources": []}
     
-    # Create VAC routes with MCP server enabled
+    # Single call sets up everything with MCP server and proper lifespan management
+    app, vac_routes = VACRoutesFastAPI.create_app_with_mcp(
+        title="My VAC Application",
+        stream_interpreter=my_stream_interpreter
+        # MCP server is automatically enabled when using this method
+    )
+    
+    # Add custom endpoints if needed
+    @app.get("/custom")
+    async def custom_endpoint():
+        return {"message": "Hello"}
+    
+    # Run the app
+    if __name__ == "__main__":
+        import uvicorn
+        uvicorn.run(app, host="0.0.0.0", port=8000)
+    ```
+    
+    ### Manual Setup (Advanced)
+    
+    For more control over lifespan management:
+    
+    ```python
+    from contextlib import asynccontextmanager
+    from fastapi import FastAPI
+    from sunholo.agents.fastapi import VACRoutesFastAPI
+    
+    async def my_stream_interpreter(question, vector_name, chat_history, callback, **kwargs):
+        return {"answer": "Response", "sources": []}
+    
+    # Define your app's lifespan
+    @asynccontextmanager
+    async def app_lifespan(app: FastAPI):
+        print("Starting up...")
+        yield
+        print("Shutting down...")
+    
+    # Create temp app to get MCP lifespan
+    temp_app = FastAPI()
+    vac_routes_temp = VACRoutesFastAPI(
+        temp_app,
+        stream_interpreter=my_stream_interpreter,
+        enable_mcp_server=True
+    )
+    
+    # Get MCP lifespan
+    mcp_lifespan = vac_routes_temp.get_mcp_lifespan()
+    
+    # Combine lifespans
+    @asynccontextmanager
+    async def combined_lifespan(app: FastAPI):
+        async with app_lifespan(app):
+            if mcp_lifespan:
+                async with mcp_lifespan(app):
+                    yield
+            else:
+                yield
+    
+    # Create app with combined lifespan
+    app = FastAPI(title="My VAC Application", lifespan=combined_lifespan)
+    
+    # Initialize VAC routes
     vac_routes = VACRoutesFastAPI(
         app=app,
         stream_interpreter=my_stream_interpreter,
-        enable_mcp_server=True  # Enable MCP server for Claude Desktop/Code
+        enable_mcp_server=True
     )
-    
-    # Your FastAPI app now includes:
-    # - All VAC endpoints
-    # - MCP server at /mcp (for Claude Desktop/Code to connect)
-    # - Built-in VAC tools: vac_stream, vac_query, list_available_vacs, get_vac_info
     ```
     
+    Your FastAPI app now includes:
+    - All VAC endpoints  
+    - MCP server at /mcp (for Claude Desktop/Code to connect)
+    - Built-in VAC tools: vac_stream, vac_query, list_available_vacs, get_vac_info
+    
     ## Adding Custom MCP Tools
     
     ### Method 1: Using Decorators
@@ -416,6 +477,158 @@ class VACRoutesFastAPI:
         
         self.register_routes()
     
+    @staticmethod
+    def create_app_with_mcp(
+        title: str = "VAC Application",
+        stream_interpreter: Optional[callable] = None,
+        vac_interpreter: Optional[callable] = None,
+        app_lifespan: Optional[callable] = None,
+        **kwargs
+    ) -> tuple[FastAPI, 'VACRoutesFastAPI']:
+        """
+        Helper method to create a FastAPI app with proper MCP lifespan management.
+        
+        This method simplifies the setup process by handling the lifespan combination
+        automatically, avoiding the need for the double initialization pattern.
+        MCP server is automatically enabled when using this method.
+        
+        Args:
+            title: Title for the FastAPI app
+            stream_interpreter: Streaming interpreter function
+            vac_interpreter: Non-streaming interpreter function  
+            app_lifespan: Optional app lifespan context manager
+            **kwargs: Additional arguments passed to VACRoutesFastAPI (except enable_mcp_server)
+            
+        Returns:
+            Tuple of (FastAPI app, VACRoutesFastAPI instance)
+            
+        Example:
+            ```python
+            from sunholo.agents.fastapi import VACRoutesFastAPI
+            
+            async def my_interpreter(question, vector_name, chat_history, callback, **kwargs):
+                # Your logic here
+                return {"answer": "response", "sources": []}
+            
+            # Single call to set up everything (MCP is automatically enabled)
+            app, vac_routes = VACRoutesFastAPI.create_app_with_mcp(
+                title="My VAC App",
+                stream_interpreter=my_interpreter
+            )
+            
+            # Add custom endpoints
+            @app.get("/custom")
+            async def custom_endpoint():
+                return {"message": "Custom endpoint"}
+            
+            if __name__ == "__main__":
+                import uvicorn
+                uvicorn.run(app, host="0.0.0.0", port=8000)
+            ```
+        """
+        from contextlib import asynccontextmanager
+        
+        # Default app lifespan if not provided
+        if app_lifespan is None:
+            @asynccontextmanager
+            async def app_lifespan(app: FastAPI):
+                yield
+        
+        # Import here to avoid circular imports
+        if VACMCPServer:
+            from fastmcp import FastMCP
+            
+            # Create MCP server directly to get its lifespan
+            mcp_server = FastMCP("sunholo-vac-fastapi-server")
+            
+            # Register built-in VAC tools directly
+            from sunholo.mcp.vac_tools import register_vac_tools
+            register_vac_tools(mcp_server, None)
+            
+            # Get the MCP app with path="" so when mounted at /mcp it's accessible at /mcp
+            mcp_app = mcp_server.http_app(path="", stateless_http=True)
+            
+            # Create combined lifespan
+            @asynccontextmanager  
+            async def combined_lifespan(app: FastAPI):
+                async with app_lifespan(app):
+                    async with mcp_app.lifespan(app):
+                        yield
+            
+            # Create the actual app with combined lifespan
+            app = FastAPI(
+                title=title,
+                lifespan=combined_lifespan
+            )
+            
+            # Mount the MCP app at /mcp
+            app.mount("/mcp", mcp_app)
+            
+            # Now create VAC routes WITHOUT MCP (since we already mounted it)
+            vac_routes = VACRoutesFastAPI(
+                app,
+                stream_interpreter=stream_interpreter,
+                vac_interpreter=vac_interpreter,
+                enable_mcp_server=False,  # Don't enable again since we manually mounted
+                **kwargs
+            )
+            
+            # Store reference to MCP server for tool registration
+            vac_routes.vac_mcp_server = type('MockMCPServer', (), {
+                'add_tool': lambda self, func, name=None, desc=None: mcp_server.tool(func) if name is None else mcp_server.tool(name=name)(func),
+                'server': mcp_server
+            })()
+        else:
+            # No MCP support available
+            app = FastAPI(
+                title=title,
+                lifespan=app_lifespan
+            )
+            
+            vac_routes = VACRoutesFastAPI(
+                app,
+                stream_interpreter=stream_interpreter,
+                vac_interpreter=vac_interpreter,
+                enable_mcp_server=False,
+                **kwargs
+            )
+        
+        return app, vac_routes
+    
+    def get_mcp_lifespan(self):
+        """
+        Get the MCP app's lifespan for manual lifespan management.
+        
+        Returns:
+            The MCP app's lifespan if MCP server is enabled, None otherwise.
+            
+        Example:
+            ```python
+            from contextlib import asynccontextmanager
+            
+            # Create temp app to get MCP lifespan
+            temp_app = FastAPI()
+            vac_routes = VACRoutesFastAPI(temp_app, ..., enable_mcp_server=True)
+            mcp_lifespan = vac_routes.get_mcp_lifespan()
+            
+            # Combine with your app's lifespan
+            @asynccontextmanager
+            async def combined_lifespan(app: FastAPI):
+                async with my_app_lifespan(app):
+                    if mcp_lifespan:
+                        async with mcp_lifespan(app):
+                            yield
+                    else:
+                        yield
+            
+            app = FastAPI(lifespan=combined_lifespan)
+            ```
+        """
+        if self.vac_mcp_server:
+            mcp_app = self.vac_mcp_server.get_http_app()
+            return mcp_app.lifespan
+        return None
+    
     async def vac_interpreter_default(self, question: str, vector_name: str, chat_history=None, **kwargs):
         """Default VAC interpreter that uses the stream interpreter without streaming."""
         class NoOpCallback:
@@ -484,11 +697,35 @@ class VACRoutesFastAPI:
         if self.enable_mcp_server and self.vac_mcp_server:
             try:
                 mcp_app = self.vac_mcp_server.get_http_app()
-                self.app.mount("/mcp", mcp_app)
-                log.info("MCP server mounted at /mcp endpoint")
+                
+                # Note: FastAPI doesn't expose lifespan as a public attribute,
+                # so we can't easily check if it's configured. The error will be
+                # caught below if lifespan is missing.
+                
+                # Mount at root - the MCP app already has /mcp path configured
+                self.app.mount("", mcp_app)
+                log.info("✅ MCP server mounted at /mcp endpoint")
+                
+            except RuntimeError as e:
+                if "Task group is not initialized" in str(e):
+                    error_msg = (
+                        "MCP server initialization failed: Lifespan not configured properly.\n"
+                        "The FastAPI app must be created with the MCP lifespan.\n\n"
+                        "Quick fix: Use the helper method:\n"
+                        "  app, vac_routes = VACRoutesFastAPI.create_app_with_mcp(\n"
+                        "      stream_interpreter=your_interpreter,\n"
+                        "      enable_mcp_server=True\n"
+                        "  )\n\n"
+                        "Or manually configure the lifespan - see documentation for details."
+                    )
+                    log.error(error_msg)
+                    raise RuntimeError(error_msg) from e
+                else:
+                    log.error(f"Failed to mount MCP server: {e}")
+                    raise RuntimeError(f"MCP server initialization failed: {e}") from e
             except Exception as e:
                 log.error(f"Failed to mount MCP server: {e}")
-                raise RuntimeError(f"MCP server initialization failed: {e}")
+                raise RuntimeError(f"MCP server initialization failed: {e}") from e
         
         # A2A agent endpoints
         if self.enable_a2a_agent:

sunholo/mcp/__init__.py

@@ -26,4 +26,13 @@ except ImportError as e:
     print(f"Warning: VACMCPServer not available - {e}")
     VACMCPServer = None
 
-__all__ = ['MCPClientManager', 'VACMCPServer']
+# SSE utilities are always available
+from .sse_utils import parse_sse_response, is_sse_response, extract_sse_data
+
+__all__ = [
+    'MCPClientManager', 
+    'VACMCPServer',
+    'parse_sse_response',
+    'is_sse_response', 
+    'extract_sse_data'
+]

sunholo/mcp/sse_utils.py

@@ -0,0 +1,105 @@
+#   Copyright [2024] [Holosun ApS]
+#
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+
+"""
+Utilities for parsing Server-Sent Events (SSE) responses from MCP servers.
+"""
+
+import json
+from typing import Any, Dict, Optional
+
+
+def parse_sse_response(text: str) -> Dict[str, Any]:
+    """
+    Parse SSE-formatted response from MCP server.
+    
+    FastMCP returns responses in SSE format when using HTTP transport,
+    even with stateless_http=True. This function extracts the JSON data
+    from the SSE format.
+    
+    Args:
+        text: Raw response text from MCP server
+        
+    Returns:
+        Parsed JSON data from the SSE response
+        
+    Raises:
+        ValueError: If the response cannot be parsed
+        
+    Example:
+        >>> response_text = 'event: message\\ndata: {"jsonrpc": "2.0", "id": 1, "result": {...}}'
+        >>> data = parse_sse_response(response_text)
+        >>> print(data['result'])
+    """
+    # Check if it's SSE format
+    if text.startswith('event:') or text.startswith('data:'):
+        # Parse SSE format - extract JSON from data: line
+        lines = text.split('\n')
+        
+        # Find the data line
+        data_line = None
+        for line in lines:
+            if line.startswith('data:'):
+                data_line = line
+                break
+        
+        if data_line:
+            # Remove 'data:' prefix and parse JSON
+            json_str = data_line[5:].strip()
+            try:
+                return json.loads(json_str)
+            except json.JSONDecodeError as e:
+                raise ValueError(f"Failed to parse JSON from SSE data: {e}")
+        else:
+            raise ValueError("No data line found in SSE response")
+    else:
+        # Try parsing as regular JSON
+        try:
+            return json.loads(text)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Response is not valid JSON or SSE format: {e}")
+
+
+def is_sse_response(text: str) -> bool:
+    """
+    Check if a response is in SSE format.
+    
+    Args:
+        text: Response text to check
+        
+    Returns:
+        True if the response appears to be SSE format
+    """
+    return text.startswith('event:') or text.startswith('data:')
+
+
+def extract_sse_data(text: str) -> Optional[str]:
+    """
+    Extract the data portion from an SSE response.
+    
+    Args:
+        text: SSE-formatted response text
+        
+    Returns:
+        The extracted data string, or None if not found
+    """
+    if not is_sse_response(text):
+        return None
+    
+    lines = text.split('\n')
+    for line in lines:
+        if line.startswith('data:'):
+            return line[5:].strip()
+    
+    return None

sunholo/mcp/vac_mcp_server_fastmcp.py

@@ -73,7 +73,8 @@ class VACMCPServer:
     
     def get_http_app(self):
         """Get the HTTP app for mounting in FastAPI."""
-        return self.server.get_app()
+        # Following FastMCP docs: when mounted at root "", path="/mcp" gives us /mcp endpoint
+        return self.server.http_app(path="/mcp")
     
     def add_tool(self, func: Callable, name: str = None, description: str = None):
         """

sunholo/mcp/vac_tools.py

@@ -54,12 +54,9 @@ def get_vac_config(vector_name: str = None) -> 'ConfigManager':
         
     default_vac = os.getenv("DEFAULT_VAC_NAME", "demo")
     vac_name = vector_name or default_vac
-    vac_config_folder = os.getenv("VAC_CONFIG_FOLDER")
     
-    if vac_config_folder:
-        return ConfigManager(vac_name, config_folder=vac_config_folder)
-    else:
-        return ConfigManager(vac_name)
+    # ConfigManager uses VAC_CONFIG_FOLDER env var automatically
+    return ConfigManager(vac_name)
 
 
 async def call_vac_async(question: str, vector_name: str, chat_history: List[Dict[str, str]] = None) -> str:
@@ -241,9 +238,10 @@ def register_vac_tools(server: 'FastMCP', registry: 'MCPToolRegistry' = None):
     
     # Register tools in registry if provided
     if registry:
-        registry.register_tool("vac_stream", vac_stream)
-        registry.register_tool("vac_query", vac_query) 
-        registry.register_tool("list_available_vacs", list_available_vacs)
-        registry.register_tool("get_vac_info", get_vac_info)
+        # Extract the underlying function from FunctionTool objects
+        registry.register_tool("vac_stream", vac_stream.fn if hasattr(vac_stream, 'fn') else vac_stream)
+        registry.register_tool("vac_query", vac_query.fn if hasattr(vac_query, 'fn') else vac_query) 
+        registry.register_tool("list_available_vacs", list_available_vacs.fn if hasattr(list_available_vacs, 'fn') else list_available_vacs)
+        registry.register_tool("get_vac_info", get_vac_info.fn if hasattr(get_vac_info, 'fn') else get_vac_info)
     
     log.info("Registered built-in VAC tools with MCP server")

{sunholo-0.144.2.dist-info → sunholo-0.144.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sunholo
-Version: 0.144.2
+Version: 0.144.4
 Summary: AI DevOps - a package to help deploy GenAI to the Cloud.
 Author-email: Holosun ApS <multivac@sunholo.com>
 License: Apache License, Version 2.0

{sunholo-0.144.2.dist-info → sunholo-0.144.4.dist-info}/RECORD

@@ -16,7 +16,7 @@ sunholo/agents/swagger.py,sha256=2tzGmpveUMmTREykZvVnDj3j295wyOMu7mUFDnXdY3c,106
 sunholo/agents/fastapi/__init__.py,sha256=f7x7kiEjaNyBiOwJHLJ4vdOiePqkXdI52sIAAHtS-ms,141
 sunholo/agents/fastapi/base.py,sha256=W-cyF8ZDUH40rc-c-Apw3-_8IIi2e4Y9qRtnoVnsc1Q,2521
 sunholo/agents/fastapi/qna_routes.py,sha256=lKHkXPmwltu9EH3RMwmD153-J6pE7kWQ4BhBlV3to-s,3864
-sunholo/agents/fastapi/vac_routes.py,sha256=jV7Kb9CG4qdlntSHZuI_8UALjFuwYOh5ovrZpDkixzg,51909
+sunholo/agents/fastapi/vac_routes.py,sha256=tDZ-2U6UAHlloFpH-5HDd2Ob_80GiOr5CMO6XZPDGXM,60877
 sunholo/agents/flask/__init__.py,sha256=dEoByI3gDNUOjpX1uVKP7uPjhfFHJubbiaAv3xLopnk,63
 sunholo/agents/flask/base.py,sha256=vnpxFEOnCmt9humqj-jYPLfJcdwzsop9NorgkJ-tSaU,1756
 sunholo/agents/flask/vac_routes.py,sha256=kaPUDyIH5KhCgeCEtag97qErGVZfqpY1ZEiX3y1_r-s,57505
@@ -115,15 +115,16 @@ sunholo/llamaindex/llamaindex_class.py,sha256=PnpPoc7LpP7xvKIXYu-UvI4ehj67pGhE1E
 sunholo/llamaindex/user_history.py,sha256=ZtkecWuF9ORduyGB8kF8gP66bm9DdvCI-ZiK6Kt-cSE,2265
 sunholo/lookup/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sunholo/lookup/model_lookup.yaml,sha256=O7o-jP53MLA06C8pI-ILwERShO-xf6z_258wtpZBv6A,739
-sunholo/mcp/__init__.py,sha256=Bi0ZYMvWuf1AL_QSrMAREVVdTZFiIokGwrytBXKBJyc,1028
+sunholo/mcp/__init__.py,sha256=hvVdBeXrYZq1saa57xlN88e7KIi4oA0VFEpgLJttTcs,1228
 sunholo/mcp/cli.py,sha256=RyTrTBQMUaNMAZ1Nyh-XKb9qGnCA5hMxpKp5-9lqfrI,821
 sunholo/mcp/cli_fastmcp.py,sha256=MWx7kJ4RHX0tTygWs247aOYr4bCKOwjnmccOPjcTVnc,6104
 sunholo/mcp/extensible_mcp_server.py,sha256=docJT800-wJLApU6kEa3lwu9FHyy1yvtJIk8JI05Z3o,8960
 sunholo/mcp/mcp_manager.py,sha256=g75vv6XvM24U7uz366slE-p76Qs4AvVcsarHSF9qIvE,5061
+sunholo/mcp/sse_utils.py,sha256=LBugTxAIccQmcU2ueKIcvVlR2GjhVajwqHDnVn2s6e8,3173
 sunholo/mcp/stdio_http_bridge.py,sha256=IunHOtnjKAkRWef3SJnqnAL2r2qBRpCH2k_Q_y0Tdf8,3237
 sunholo/mcp/vac_mcp_server.py,sha256=MotoCw5lDsxCeVtwh1499yGFku9w-78xXhGkIHTUo3w,838
-sunholo/mcp/vac_mcp_server_fastmcp.py,sha256=ZZ0Que7XErlUQlaiMiQ8pesTttq24l7mfG7BiKk4ohs,4450
-sunholo/mcp/vac_tools.py,sha256=26IW5iTSEI1orbHYAlcjbBkZ1yjqQhqGqerjYkTVhko,8464
+sunholo/mcp/vac_mcp_server_fastmcp.py,sha256=Xvcwl3-kqqap-yRvOrxYHmNPQi1RBAznoZKXk8b3ydQ,4556
+sunholo/mcp/vac_tools.py,sha256=T7JmN4rAWYGmXbnXdpJlgE91DZGi4byzK9uWENndROA,8642
 sunholo/ollama/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sunholo/ollama/ollama_images.py,sha256=H2cpcNu88R4TwyfL_nnqkQhdvBQ2FPCAy4Ok__0yQmo,2351
 sunholo/pubsub/__init__.py,sha256=DfTEk4zmCfqn6gFxRrqDO0pOrvXTDqH-medpgYO4PGw,117
@@ -181,9 +182,9 @@ sunholo/vertex/init.py,sha256=1OQwcPBKZYBTDPdyU7IM4X4OmiXLdsNV30C-fee2scQ,2875
 sunholo/vertex/memory_tools.py,sha256=tBZxqVZ4InTmdBvLlOYwoSEWu4-kGquc-gxDwZCC4FA,7667
 sunholo/vertex/safety.py,sha256=S9PgQT1O_BQAkcqauWncRJaydiP8Q_Jzmu9gxYfy1VA,2482
 sunholo/vertex/type_dict_to_json.py,sha256=uTzL4o9tJRao4u-gJOFcACgWGkBOtqACmb6ihvCErL8,4694
-sunholo-0.144.2.dist-info/licenses/LICENSE.txt,sha256=SdE3QjnD3GEmqqg9EX3TM9f7WmtOzqS1KJve8rhbYmU,11345
-sunholo-0.144.2.dist-info/METADATA,sha256=QrQ-DLWAPoqQU4Jb0QVWLc7qDOJTe58siJ3AsEdGq60,18700
-sunholo-0.144.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-sunholo-0.144.2.dist-info/entry_points.txt,sha256=bZuN5AIHingMPt4Ro1b_T-FnQvZ3teBes-3OyO0asl4,49
-sunholo-0.144.2.dist-info/top_level.txt,sha256=wt5tadn5--5JrZsjJz2LceoUvcrIvxjHJe-RxuudxAk,8
-sunholo-0.144.2.dist-info/RECORD,,
+sunholo-0.144.4.dist-info/licenses/LICENSE.txt,sha256=SdE3QjnD3GEmqqg9EX3TM9f7WmtOzqS1KJve8rhbYmU,11345
+sunholo-0.144.4.dist-info/METADATA,sha256=anqykTQweoYFxojD32NfblATFycMbT3x8-SYQ4uHwys,18700
+sunholo-0.144.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+sunholo-0.144.4.dist-info/entry_points.txt,sha256=bZuN5AIHingMPt4Ro1b_T-FnQvZ3teBes-3OyO0asl4,49
+sunholo-0.144.4.dist-info/top_level.txt,sha256=wt5tadn5--5JrZsjJz2LceoUvcrIvxjHJe-RxuudxAk,8
+sunholo-0.144.4.dist-info/RECORD,,