flowllm 0.1.1__py3-none-any.whl → 0.1.2__py3-none-any.whl

flowllm/__init__.py

@@ -1,12 +1,21 @@
+import os
+
+from flowllm.utils.common_utils import load_env
+
+load_env()
+
 from flowllm import embedding_model
-from flowllm import flow_engine
 from flowllm import llm
-from flowllm import op
-from flowllm import service
 from flowllm import storage
 
-from .app import main
+if not os.environ.get("FLOW_USE_FRAMEWORK", "").lower() == "true":
+    from flowllm import flow
+    from flowllm import op
+
+from flowllm import service
+
+from flowllm.context.service_context import C
+from flowllm.op import BaseOp, BaseRayOp, BaseLLMOp
 
-__version__ = "0.1.1"
+__version__ = "0.1.2"
 
-__all__ = ["main"]

flowllm/app.py

@@ -1,25 +1,15 @@
 import sys
 
 from flowllm.service.base_service import BaseService
-from flowllm.utils.common_utils import load_env
-
-load_env()
-
-from flowllm.config.pydantic_config_parser import PydanticConfigParser
-from flowllm.schema.service_config import ServiceConfig
-from flowllm.context.service_context import C
 
 
 def main():
-    config_parser = PydanticConfigParser(ServiceConfig)
-    service_config: ServiceConfig = config_parser.parse_args(*sys.argv[1:])
-    service_cls = C.resolve_service(service_config.backend)
-    service: BaseService = service_cls(service_config)
-    service()
+    with BaseService.get_service(*sys.argv[1:]) as service:
+        service()
+
 
 if __name__ == "__main__":
     main()
 
-
 # python -m build
-# twine upload dist/*
+# twine upload dist/*

flowllm/client/__init__.py

@@ -0,0 +1,25 @@
+"""
+FlowLLM service clients module
+
+This module provides various client implementations for interacting with FlowLLM services:
+
+- HttpClient: Synchronous HTTP client for FlowLLM HTTP service
+- AsyncHttpClient: Asynchronous HTTP client for FlowLLM HTTP service  
+- MCPClient: Asynchronous client for FlowLLM MCP (Model Context Protocol) service
+- SyncMCPClient: Synchronous wrapper around MCPClient for easier synchronous usage
+
+Each client provides methods to execute tool flows, list available flows, and perform
+health checks on the respective services.
+"""
+
+from .async_http_client import AsyncHttpClient
+from .http_client import HttpClient
+from .mcp_client import MCPClient
+from .sync_mcp_client import SyncMCPClient
+
+__all__ = [
+    "HttpClient",
+    "AsyncHttpClient", 
+    "MCPClient",
+    "SyncMCPClient"
+]

flowllm/client/async_http_client.py

@@ -0,0 +1,81 @@
+from typing import Dict
+
+import httpx
+
+from flowllm.schema.flow_response import FlowResponse
+
+
+class AsyncHttpClient:
+    """Async client for interacting with FlowLLM HTTP service"""
+
+    def __init__(self, base_url: str = "http://localhost:8001", timeout: float = 3600.0):
+        """
+        Initialize async HTTP client
+
+        Args:
+            base_url: Base URL of the FlowLLM HTTP service
+            timeout: Request timeout in seconds
+        """
+        self.base_url = base_url.rstrip('/')  # Remove trailing slash for consistent URL formatting
+        self.timeout = timeout
+        self.client = httpx.AsyncClient(timeout=timeout)  # Create async HTTP client with timeout
+
+    async def __aenter__(self):
+        """Async context manager entry - returns self for 'async with' usage"""
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit - ensures proper cleanup of HTTP client"""
+        await self.client.aclose()
+
+    async def close(self):
+        """Explicitly close the HTTP client connection"""
+        await self.client.aclose()
+
+    async def health_check(self) -> Dict[str, str]:
+        """
+        Perform health check on the FlowLLM service
+        
+        Returns:
+            Dict containing health status information from the service
+            
+        Raises:
+            httpx.HTTPStatusError: If the service is not healthy or unreachable
+        """
+        response = await self.client.get(f"{self.base_url}/health")
+        response.raise_for_status()  # Raise exception for HTTP error status codes
+        return response.json()
+
+    async def execute_tool_flow(self, flow_name: str, **kwargs) -> FlowResponse:
+        """
+        Execute a specific tool flow on the FlowLLM service
+        
+        Args:
+            flow_name: Name of the tool flow to execute
+            **kwargs: Additional parameters to pass to the tool flow
+            
+        Returns:
+            FlowResponse object containing the execution results
+            
+        Raises:
+            httpx.HTTPStatusError: If the request fails or flow execution errors
+        """
+        endpoint = f"{self.base_url}/{flow_name}"
+        response = await self.client.post(endpoint, json=kwargs)  # Send flow parameters as JSON
+        response.raise_for_status()  # Raise exception for HTTP error status codes
+        result_data = response.json()
+        return FlowResponse(**result_data)  # Parse response into FlowResponse schema
+
+    async def list_tool_flows(self) -> list:
+        """
+        Get list of available tool flows from the FlowLLM service
+        
+        Returns:
+            List of available tool flow names and their metadata
+            
+        Raises:
+            httpx.HTTPStatusError: If the service is unreachable or returns an error
+        """
+        response = await self.client.get(f"{self.base_url}/list")
+        response.raise_for_status()  # Raise exception for HTTP error status codes
+        return response.json()

flowllm/client/http_client.py

@@ -0,0 +1,81 @@
+from typing import Dict
+
+import httpx
+
+from flowllm.schema.flow_response import FlowResponse
+
+
+class HttpClient:
+    """Client for interacting with FlowLLM HTTP service"""
+
+    def __init__(self, base_url: str = "http://localhost:8001", timeout: float = 3600.0):
+        """
+        Initialize HTTP client
+        
+        Args:
+            base_url: Base URL of the FlowLLM HTTP service
+            timeout: Request timeout in seconds
+        """
+        self.base_url = base_url.rstrip('/')  # Remove trailing slash for consistent URL formatting
+        self.timeout = timeout
+        self.client = httpx.Client(timeout=timeout)  # Create synchronous HTTP client with timeout
+
+    def __enter__(self):
+        """Context manager entry - returns self for 'with' usage"""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit - ensures proper cleanup of HTTP client"""
+        self.client.close()
+
+    def close(self):
+        """Explicitly close the HTTP client connection"""
+        self.client.close()
+
+    def health_check(self) -> Dict[str, str]:
+        """
+        Perform health check on the FlowLLM service
+        
+        Returns:
+            Dict containing health status information from the service
+            
+        Raises:
+            httpx.HTTPStatusError: If the service is not healthy or unreachable
+        """
+        response = self.client.get(f"{self.base_url}/health")
+        response.raise_for_status()  # Raise exception for HTTP error status codes
+        return response.json()
+
+    def execute_tool_flow(self, flow_name: str, **kwargs) -> FlowResponse:
+        """
+        Execute a specific tool flow on the FlowLLM service
+        
+        Args:
+            flow_name: Name of the tool flow to execute
+            **kwargs: Additional parameters to pass to the tool flow
+            
+        Returns:
+            FlowResponse object containing the execution results
+            
+        Raises:
+            httpx.HTTPStatusError: If the request fails or flow execution errors
+        """
+        endpoint = f"{self.base_url}/{flow_name}"
+        response = self.client.post(endpoint, json=kwargs)  # Send flow parameters as JSON
+        response.raise_for_status()  # Raise exception for HTTP error status codes
+        result_data = response.json()
+        return FlowResponse(**result_data)  # Parse response into FlowResponse schema
+
+    def list_tool_flows(self) -> list:
+        """
+        Get list of available tool flows from the FlowLLM service
+        
+        Returns:
+            List of available tool flow names and their metadata
+            
+        Raises:
+            httpx.HTTPStatusError: If the service is unreachable or returns an error
+        """
+        response = self.client.get(f"{self.base_url}/list")
+        response.raise_for_status()  # Raise exception for HTTP error status codes
+        return response.json()

flowllm/client/mcp_client.py

@@ -0,0 +1,133 @@
+from typing import Dict, Any, List, Optional
+
+from fastmcp import Client
+from loguru import logger
+from mcp.types import CallToolResult, Tool
+
+
+class MCPClient:
+    """Client for interacting with FlowLLM MCP service"""
+
+    def __init__(self, transport: str = "sse", host: str = "0.0.0.0", port: int = 8001):
+        """
+        Initialize MCP client
+        
+        Args:
+            transport: Transport type ("sse" or "stdio")
+            host: Host address for SSE transport
+            port: Port number for SSE transport
+        """
+        self.transport = transport
+        self.host = host
+        self.port = port
+
+        # Configure connection URL based on transport type
+        if transport == "sse":
+            # Server-Sent Events transport over HTTP
+            self.connection_url = f"http://{host}:{port}/sse/"
+        elif transport == "stdio":
+            # Standard input/output transport for local processes
+            self.connection_url = "stdio"
+        else:
+            raise ValueError(f"Unsupported transport: {transport}")
+
+        self.client: Client | None = None  # MCP client instance, initialized on connect
+
+    async def __aenter__(self):
+        """Async context manager entry - automatically connects to MCP service"""
+        await self.connect()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit - ensures proper cleanup and disconnection"""
+        await self.disconnect()
+
+    async def connect(self):
+        """
+        Establish connection to the MCP service
+        
+        Creates and initializes the MCP client based on the configured transport type.
+        For stdio transport, connects to a local process. For SSE transport, connects
+        to the HTTP endpoint.
+        
+        Raises:
+            ConnectionError: If unable to connect to the MCP service
+        """
+        if self.transport == "stdio":
+            self.client = Client("stdio")  # Connect to stdio-based MCP server
+        else:
+            self.client = Client(self.connection_url)  # Connect to HTTP-based MCP server
+
+        await self.client.__aenter__()  # Initialize the client connection
+        logger.info(f"Connected to MCP service at {self.connection_url}")
+
+    async def disconnect(self):
+        """
+        Disconnect from the MCP service and clean up resources
+        
+        Safely closes the MCP client connection and resets the client instance.
+        """
+        if self.client:
+            await self.client.__aexit__(None, None, None)  # Properly close the client connection
+            self.client = None  # Reset client reference
+
+    async def list_tools(self) -> List[Tool]:
+        """
+        Retrieve list of available tools from the MCP service
+        
+        Returns:
+            List of Tool objects representing available MCP tools
+            
+        Raises:
+            RuntimeError: If client is not connected
+            ConnectionError: If communication with MCP service fails
+        """
+        if not self.client:
+            raise RuntimeError("Client not connected. Call connect() first or use context manager.")
+        
+        tools = await self.client.list_tools()
+        logger.info(f"Found {len(tools)} available tools")
+        return tools
+
+    async def get_tool(self, tool_name: str) -> Optional[Tool]:
+        """
+        Get a specific tool by name from the MCP service
+        
+        Args:
+            tool_name: Name of the tool to retrieve
+            
+        Returns:
+            Tool object if found, None otherwise
+            
+        Raises:
+            RuntimeError: If client is not connected
+            ConnectionError: If communication with MCP service fails
+        """
+        tools = await self.list_tools()  # Get all available tools
+        
+        # Search for the requested tool by name
+        for tool in tools:
+            if tool.name == tool_name:
+                return tool
+        return None  # Tool not found
+
+    async def call_tool(self, tool_name: str, arguments: Dict[str, Any]) -> CallToolResult:
+        """
+        Execute a tool on the MCP service with the provided arguments
+        
+        Args:
+            tool_name: Name of the tool to execute
+            arguments: Dictionary of arguments to pass to the tool
+            
+        Returns:
+            CallToolResult containing the tool execution results
+            
+        Raises:
+            RuntimeError: If client is not connected
+            ValueError: If tool_name is invalid or arguments are malformed
+            ConnectionError: If communication with MCP service fails
+        """
+        if not self.client:
+            raise RuntimeError("Client not connected. Call connect() first or use context manager.")
+            
+        return await self.client.call_tool(tool_name, arguments=arguments)

flowllm/client/sync_mcp_client.py

@@ -0,0 +1,116 @@
+import asyncio
+from typing import Dict, Any, List, Optional
+
+from mcp.types import CallToolResult, Tool
+
+from flowllm.client import MCPClient
+
+
+class SyncMCPClient:
+    """Synchronous wrapper for MCPClient"""
+
+    def __init__(self, transport: str = "sse", host: str = "0.0.0.0", port: int = 8001):
+        """
+        Initialize synchronous MCP client
+
+        This client wraps the asynchronous MCPClient to provide a synchronous interface.
+        It manages its own event loop for executing async operations synchronously.
+
+        Args:
+            transport: Transport type ("sse" or "stdio")
+            host: Host address for SSE transport
+            port: Port number for SSE transport
+        """
+        self.async_client = MCPClient(transport, host, port)  # Create underlying async client
+        self._loop: asyncio.AbstractEventLoop | None = None  # Event loop for async operations
+
+    def __enter__(self):
+        """
+        Context manager entry - sets up event loop and connects to MCP service
+        
+        Creates a new event loop, establishes connection to the MCP service,
+        and returns self for use in 'with' statements.
+        
+        Returns:
+            self for context manager usage
+        """
+        self._loop = asyncio.new_event_loop()  # Create new event loop for this client
+        asyncio.set_event_loop(self._loop)  # Set as current event loop
+        self._loop.run_until_complete(self.async_client.connect())  # Connect synchronously
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """
+        Context manager exit - disconnects from MCP service and cleans up event loop
+        
+        Ensures proper cleanup by disconnecting from the MCP service and
+        closing the event loop.
+        """
+        if self._loop:
+            self._loop.run_until_complete(self.async_client.disconnect())  # Disconnect synchronously
+            self._loop.close()  # Close the event loop
+            self._loop = None  # Reset loop reference
+
+    def _run_async(self, coro):
+        """
+        Execute an async coroutine synchronously using the managed event loop
+        
+        Args:
+            coro: Coroutine to execute
+            
+        Returns:
+            Result of the coroutine execution
+            
+        Raises:
+            RuntimeError: If client is not connected (no event loop available)
+        """
+        if not self._loop:
+            raise RuntimeError("Client not connected. Use context manager first.")
+        return self._loop.run_until_complete(coro)  # Run coroutine to completion
+
+    def list_tools(self) -> List[Tool]:
+        """
+        Synchronously retrieve list of available tools from the MCP service
+        
+        Returns:
+            List of Tool objects representing available MCP tools
+            
+        Raises:
+            RuntimeError: If client is not connected
+            ConnectionError: If communication with MCP service fails
+        """
+        return self._run_async(self.async_client.list_tools())
+
+    def get_tool(self, tool_name: str) -> Optional[Tool]:
+        """
+        Synchronously get a specific tool by name from the MCP service
+        
+        Args:
+            tool_name: Name of the tool to retrieve
+            
+        Returns:
+            Tool object if found, None otherwise
+            
+        Raises:
+            RuntimeError: If client is not connected
+            ConnectionError: If communication with MCP service fails
+        """
+        return self._run_async(self.async_client.get_tool(tool_name))
+
+    def call_tool(self, tool_name: str, arguments: Dict[str, Any]) -> CallToolResult:
+        """
+        Synchronously execute a tool on the MCP service with the provided arguments
+        
+        Args:
+            tool_name: Name of the tool to execute
+            arguments: Dictionary of arguments to pass to the tool
+            
+        Returns:
+            CallToolResult containing the tool execution results
+            
+        Raises:
+            RuntimeError: If client is not connected
+            ValueError: If tool_name is invalid or arguments are malformed
+            ConnectionError: If communication with MCP service fails
+        """
+        return self._run_async(self.async_client.call_tool(tool_name, arguments))

flowllm/config/__init__.py

@@ -0,0 +1 @@
+from .pydantic_config_parser import PydanticConfigParser

flowllm/config/{default_config.yaml → default.yaml}

@@ -2,7 +2,7 @@
 backend: mcp
 language: ""
 thread_pool_max_workers: 32
-ray_max_workers: 8
+ray_max_workers: 1
 
 mcp:
   transport: sse
@@ -15,11 +15,6 @@ http:
   timeout_keep_alive: 600
   limit_concurrency: 64
 
-
-flow_engine:
-  backend: simple
-
-
 flow:
   get_a_stock_infos:
     flow_content: get_ak_a_code_op >> get_ak_a_info_op >> get_ak_a_spot_op >> get_ak_a_money_flow_op >> get_ak_a_financial_info_op >> merge_ak_a_info_op
@@ -37,7 +32,7 @@ flow:
         type: "str"
         description: "user question"
 
-  mock_flow:
+  mock_expression_flow:
     flow_content: mock1_op>>((mock4_op>>mock2_op)|mock5_op)>>(mock3_op|mock6_op)
     description: "mock flow"
     input_schema:
@@ -62,6 +57,7 @@ llm:
     model_name: qwen3-30b-a3b-thinking-2507
     params:
       temperature: 0.6
+
   qwen3_30b_instruct:
     backend: openai_compatible
     model_name: qwen3-30b-a3b-instruct-2507
@@ -79,4 +75,3 @@ vector_store:
     embedding_model: default
     params:
       hosts: "http://localhost:9200"
-

flowllm/config/empty.yaml

@@ -0,0 +1,37 @@
+# default config.yaml
+backend: http
+language: ""
+thread_pool_max_workers: 32
+ray_max_workers: 1
+
+mcp:
+  transport: sse
+  host: "0.0.0.0"
+  port: 8001
+
+http:
+  host: "0.0.0.0"
+  port: 8001
+  timeout_keep_alive: 600
+  limit_concurrency: 64
+
+llm:
+  default:
+    backend: openai_compatible
+    model_name: qwen3-30b-a3b-thinking-2507
+    params:
+      temperature: 0.6
+
+embedding_model:
+  default:
+    backend: openai_compatible
+    model_name: text-embedding-v4
+    params:
+      dimensions: 1024
+
+vector_store:
+  default:
+    backend: elasticsearch
+    embedding_model: default
+    params:
+      hosts: "http://localhost:9200"

flowllm/config/pydantic_config_parser.py

@@ -11,6 +11,9 @@ T = TypeVar('T', bound=BaseModel)
 
 
 class PydanticConfigParser(Generic[T]):
+    current_file: str = __file__
+    default_config_name: str = ""
+
     """
     Pydantic Configuration Parser
     
@@ -187,18 +190,22 @@ class PydanticConfigParser(Generic[T]):
             else:
                 filter_args.append(arg)
 
-        if config:
-            if not config.endswith(".yaml"):
-                config += ".yaml"
+        if not config:
+            if self.default_config_name:
+                config = self.default_config_name
+            assert config, "add `config=<config_file>` in cmd!"
+
+        if not config.endswith(".yaml"):
+            config += ".yaml"
 
-            # load pre-built configs
-            config_path = Path(__file__).parent / config
-            if not config_path.exists():
-                config_path = Path(config)
+        # load pre-built configs
+        config_path = Path(self.current_file).parent / config
+        if not config_path.exists():
+            config_path = Path(config)
 
-            yaml_config = self.load_from_yaml(config_path)
-            logger.info(f"flowllm using config={config_path}")
-            configs_to_merge.append(yaml_config)
+        yaml_config = self.load_from_yaml(config_path)
+        logger.info(f"flowllm using config={config_path}")
+        configs_to_merge.append(yaml_config)
 
         # 3. Command line override configuration
         if args:
@@ -233,10 +240,3 @@ class PydanticConfigParser(Generic[T]):
         final_config = self.merge_configs(copy.deepcopy(self.config_dict), override_config)
 
         return self.config_class.model_validate(final_config)
-
-
-def get_default_config():
-    from flowllm.schema.service_config import ServiceConfig
-
-    config_parser = PydanticConfigParser(ServiceConfig)
-    return config_parser.parse_args("config=default_config")

flowllm/context/base_context.py

@@ -1,13 +1,20 @@
-from typing import List
-
-
 class BaseContext:
     def __init__(self, **kwargs):
         self._data = {**kwargs}
 
     def __getattr__(self, name: str):
-        if name in self._data:
-            return self._data[name]
+        # Avoid infinite recursion when _data is not yet initialized
+        if name == '_data':
+            raise AttributeError(f"'{self.__class__.__name__}' has no attribute '{name}'")
+        
+        # Use object.__getattribute__ to safely access _data
+        try:
+            data = object.__getattribute__(self, '_data')
+        except AttributeError:
+            raise AttributeError(f"'{self.__class__.__name__}' has no attribute '{name}'")
+            
+        if name in data:
+            return data[name]
 
         raise AttributeError(f"'{self.__class__.__name__}' has no attribute '{name}'")
 
@@ -34,13 +41,26 @@ class BaseContext:
     def dump(self) -> dict:
         return self._data
 
+    def get(self, key: str, default=None):
+        return self._data.get(key, default)
+
     @property
-    def keys(self) -> List[str]:
-        return sorted(self._data.keys())
+    def keys(self):
+        return self._data.keys()
 
     def update(self, **kwargs):
         self._data.update(kwargs)
 
+    def items(self):
+        return self._data.items()
+
+    def __getstate__(self):
+        """Support for pickle serialization"""
+        return {'_data': self._data}
+    
+    def __setstate__(self, state):
+        """Support for pickle deserialization"""
+        self._data = state['_data']
 
 if __name__ == "__main__":
     ctx = BaseContext(**{"name": "Alice", "age": 30, "city": "New York"})