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

flowllm/__init__.py

@@ -0,0 +1,21 @@
+import os
+
+from flowllm.utils.common_utils import load_env
+
+load_env()
+
+from flowllm import embedding_model
+from flowllm import llm
+from flowllm import storage
+
+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.2"
+

flowllm/app.py

@@ -0,0 +1,15 @@
+import sys
+
+from flowllm.service.base_service import BaseService
+
+
+def main():
+    with BaseService.get_service(*sys.argv[1:]) as service:
+        service()
+
+
+if __name__ == "__main__":
+    main()
+
+# python -m build
+# 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.yaml

@@ -0,0 +1,77 @@
+# default config.yaml
+backend: mcp
+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
+
+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
+    description: "Retrieve the A-share stock codes from the query, and fetch information about these stocks, including company basic information, current stock price and its change percentage, capital inflow and outflow data for the most recent day, and financial information from the latest quarter."
+    input_schema:
+      query:
+        type: "str"
+        description: "user question"
+
+  get_a_stock_news:
+    flow_content: get_ak_a_code_op >> get_ak_a_news_op >> merge_ak_a_info_op
+    description: "Retrieve the A-share stock codes from the query, and obtain the latest news information about these stocks."
+    input_schema:
+      query:
+        type: "str"
+        description: "user question"
+
+  mock_expression_flow:
+    flow_content: mock1_op>>((mock4_op>>mock2_op)|mock5_op)>>(mock3_op|mock6_op)
+    description: "mock flow"
+    input_schema:
+      a:
+        type: "str"
+        description: "mock attr a"
+        required: true
+      b:
+        type: "str"
+        description: "mock attr b"
+        required: true
+
+op:
+  mock1_op:
+    backend: mock1_op
+    llm: default
+    vector_store: default
+
+llm:
+  default:
+    backend: openai_compatible
+    model_name: qwen3-30b-a3b-thinking-2507
+    params:
+      temperature: 0.6
+
+  qwen3_30b_instruct:
+    backend: openai_compatible
+    model_name: qwen3-30b-a3b-instruct-2507
+
+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/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"