rillpy 0.1.0__py3-none-any.whl

rill/__init__.py

@@ -0,0 +1,3 @@
+"""Rill - AI Agent Framework"""
+
+__version__ = "0.1.0"

rill/flow.py

@@ -0,0 +1,489 @@
+"""DAG-based flow orchestration with parallel execution and dynamic routing.
+
+Typical usage:
+    class MyFlow(Flow):
+        @node(start=True, goto="process")
+        def start(self, inputs):
+            return {"data": inputs}
+        
+        @node(goto=DYNAMIC)
+        async def process(self, inputs):
+            if needs_parallel:
+                return goto([self.taskA, self.taskB], inputs)  # parallel
+            return goto(self.finalize, inputs)  # single path
+        
+        @node()
+        def finalize(self, merged):
+            return "done"
+    
+    await MyFlow().run(initial_data)
+"""
+from typing import Any, Callable, Dict, List, Union, Optional, Literal, Set
+import inspect
+import asyncio
+import sys
+from pydantic import BaseModel
+from dataclasses import dataclass
+
+from .utils.logger import logger
+
+# Interned constants for routing control
+DYNAMIC = sys.intern("__dynamic__")  # Runtime-determined routing
+END = sys.intern("__end__")          # Terminal state marker
+
+@dataclass
+class Route:
+    """Encapsulates routing decision for DYNAMIC nodes."""
+    to: Union[Callable, str, List[Union[Callable, str]]]  # Target(s): method ref, name, or list
+    data: Any = None  # Payload forwarded to target(s)
+    
+    def resolve(self) -> tuple:
+        """Normalize targets to name strings.
+        
+        Returns:
+            (str, data) for single target or (List[str], data) for parallel targets
+        """
+        if isinstance(self.to, list):
+            names = [t.__name__ if callable(t) else t for t in self.to]
+            return names, self.data
+        if callable(self.to):
+            return self.to.__name__, self.data
+        return self.to, self.data
+
+def goto(target: Union[Callable, str, List[Union[Callable, str]]], data: Any = None) -> Route:
+    """Construct routing decision for DYNAMIC nodes.
+    
+    Args:
+        target: Single node or list of nodes (triggers parallel execution for lists)
+        data: Payload passed to target(s); duplicated for parallel targets
+    
+    Returns:
+        Route object for flow execution engine
+    
+    Example:
+        @node(goto=DYNAMIC, max_loop=3)
+        async def evaluate(self, inputs):
+            if quality_ok:
+                return goto(self.finalize, result)
+            else:
+                return goto([self.research, self.notify], feedback)  # parallel dispatch
+    """
+    return Route(to=target, data=data)
+
+class FlowState(BaseModel):
+    """Shared mutable state container with Pydantic validation."""
+    model_config = {"extra": "allow"}  # Permits runtime field injection
+
+class Node:
+    """Decorator marking methods as executable flow nodes."""
+    def __init__(self, 
+                 start: bool = False,
+                 goto: Union[str, Callable, List[Union[str, Callable]], Literal["__dynamic__"], None] = None,
+                 max_loop: Optional[int] = None):
+        self.start = start
+        self.max_loop = max_loop
+        self.goto = self._normalize_goto(goto)
+    
+    def _normalize_goto(self, goto: Union[str, Callable, List[Union[str, Callable]], Literal["__dynamic__"], None]) -> Union[str, List[str], Literal["__dynamic__"], None]:
+        """Convert callable references to name strings for internal routing."""
+        if goto is None or goto is DYNAMIC:
+            return goto  # type: ignore
+        elif isinstance(goto, str):
+            return goto
+        elif callable(goto):
+            return goto.__name__
+        elif isinstance(goto, list):
+            return [g.__name__ if callable(g) else g for g in goto]
+        return goto  # type: ignore
+    
+    def __call__(self, func):
+        func._is_flow_node = True
+        func._start_node = self.start
+        func._goto_targets = self.goto
+        func._max_loop = self.max_loop
+        return func
+
+node = Node  # Pythonic lowercase alias
+
+class Flow:
+    """Orchestrates DAG execution with automatic parallelization and input merging."""
+    def __init__(self, 
+                 initial_state: Optional[Union[Dict[str, Any], BaseModel]] = None,
+                 max_steps: int = 1000,
+                 validate: bool = True):
+        if isinstance(initial_state, BaseModel):
+            self.state = initial_state
+        elif isinstance(initial_state, dict):
+            self.state = FlowState(**initial_state)
+        else:
+            self.state = FlowState()
+        
+        self.max_steps = max_steps  # Prevent infinite loops in malformed graphs
+        self._nodes = {}
+        self._loop_counters = {}  # Tracks per-node execution count
+        self._node_timings = {}  # Profiling data: {node: {start, end, duration}}
+        self._flow_start_time = 0.0
+        self._flow_end_time = 0.0
+        self._collect_nodes()
+        
+        if validate:
+            self._validate_graph()
+    
+    def _collect_nodes(self):
+        """Scan instance for @node-decorated methods."""
+        for name, method in inspect.getmembers(self, predicate=inspect.ismethod):
+            if hasattr(method, '_is_flow_node'):
+                self._nodes[name] = method
+    
+    def _build_execution_graph(self):
+        """Build reverse dependency map for multi-input node detection.
+        
+        Returns graph where keys are target nodes and values are lists of 
+        predecessor nodes pointing to them (enables input merging logic).
+        """
+        graph = {}
+        
+        for node_name, node_method in self._nodes.items():
+            goto_targets = getattr(node_method, '_goto_targets', None)
+            
+            if goto_targets:
+                target_nodes = []
+                if isinstance(goto_targets, str):
+                    target_nodes = [goto_targets]
+                elif isinstance(goto_targets, list):
+                    target_nodes = goto_targets
+                elif isinstance(goto_targets, dict):
+                    target_nodes = list(goto_targets.values())
+                
+                for target in target_nodes:
+                    if target not in graph:
+                        graph[target] = []
+                    graph[target].append(node_name)
+        
+        return graph
+    
+    def _validate_graph(self):
+        """Pre-flight DAG sanity checks to catch common errors early."""
+        issues = []
+        
+        start_nodes = [n for n, m in self._nodes.items() 
+                      if getattr(m, '_start_node', False)]
+        if len(start_nodes) == 0:
+            issues.append("❌ Error: No start node found (need @node(start=True))")
+        elif len(start_nodes) > 1:
+            issues.append(f"❌ Error: Multiple start nodes found {start_nodes}")
+        
+        cycles = self._detect_cycles()
+        for cycle in cycles:
+            nodes_without_limit = [n for n in cycle 
+                                  if not getattr(self._nodes[n], '_max_loop', None)]
+            if nodes_without_limit:
+                issues.append(f"❌ Error: Cycle detected {cycle}, "
+                            f"nodes {nodes_without_limit} need max_loop")
+        
+        # Skip unreachable check if DYNAMIC nodes exist (runtime-determined routing)
+        dynamic_nodes = [n for n, m in self._nodes.items()
+                        if getattr(m, '_goto_targets', None) is DYNAMIC]
+        
+        if start_nodes and not dynamic_nodes:
+            # Only check reachability for fully static graphs
+            reachable = self._get_reachable_nodes(start_nodes[0])
+            unreachable = set(self._nodes.keys()) - reachable
+            if unreachable:
+                issues.append(f"⚠️  Warning: Unreachable nodes {unreachable}")
+        
+        # Note: max_loop is optional for DYNAMIC nodes (user's responsibility)
+        # Removed the overly strict warning since simple DYNAMIC routing is safe
+        
+        if issues:
+            error_msg = "DAG validation result:\n" + "\n".join(issues)
+            errors = [i for i in issues if i.startswith("❌")]
+            if errors:
+                raise ValueError(error_msg)
+            else:
+                logger.debug(error_msg)
+    
+    def _detect_cycles(self) -> List[List[str]]:
+        """DFS-based cycle detection using recursion stack tracking."""
+        cycles = []
+        visited = set()
+        rec_stack = set()
+        
+        def dfs(node: str, path: List[str]):
+            if node in rec_stack:
+                if node in path:
+                    cycle_start = path.index(node)
+                    cycle = path[cycle_start:]
+                    if cycle not in cycles:
+                        cycles.append(cycle)
+                return
+            
+            if node in visited:
+                return
+            
+            visited.add(node)
+            rec_stack.add(node)
+            path.append(node)
+            
+            neighbors = self._get_neighbors(node)
+            for neighbor in neighbors:
+                dfs(neighbor, path.copy())
+            
+            rec_stack.remove(node)
+        
+        for node_name in self._nodes:
+            if node_name not in visited:
+                dfs(node_name, [])
+        
+        return cycles
+    
+    def _get_neighbors(self, node_name: str) -> List[str]:
+        """Extract static outgoing edges (excludes DYNAMIC which is runtime-determined)."""
+        node = self._nodes[node_name]
+        goto = getattr(node, '_goto_targets', None)
+        
+        if not goto or goto is DYNAMIC:
+            return []
+        elif isinstance(goto, str):
+            return [goto]
+        elif isinstance(goto, list):
+            return goto
+        return []
+    
+    def _get_reachable_nodes(self, start: str) -> Set[str]:
+        """BFS to find all nodes accessible from start (for dead code detection)."""
+        reachable = set()
+        queue = [start]
+        
+        while queue:
+            current = queue.pop(0)
+            if current in reachable:
+                continue
+            reachable.add(current)
+            
+            neighbors = self._get_neighbors(current)
+            queue.extend(neighbors)
+        
+        return reachable
+    
+    async def run(self, initial_input: Any = None):
+        """Execute DAG with automatic parallelization and input merging.
+        
+        Core execution model:
+        - Nodes with multiple predecessors receive merged dict: {pred_name: output}
+        - List targets trigger asyncio.gather for true parallel execution
+        - DYNAMIC nodes decide routing at runtime via goto() return value
+        """
+        import time
+        
+        self._flow_start_time = time.time()
+        
+        logger.debug("========= Flow execution started ==========")
+        logger.debug(f"Initial input: {initial_input}")
+        
+        execution_graph = self._build_execution_graph()
+        logger.debug(f"Execution graph: {execution_graph}")
+        
+        start_nodes = [node for node in self._nodes.values() 
+                      if getattr(node, '_start_node', False)]
+        
+        if not start_nodes:
+            raise ValueError("No start node found")
+        
+        if len(start_nodes) > 1:
+            raise ValueError("Multiple start nodes found")
+        
+        node_outputs = {}
+        pending_nodes = {}
+        
+        queue = [(start_nodes[0].__name__, initial_input)]
+        executed = set()
+        step = 0
+        
+        while queue:
+            step += 1
+            
+            if step > self.max_steps:
+                raise RuntimeError(f"Flow exceeded max_steps limit ({self.max_steps}), possible infinite loop")
+            
+            current_node_name, current_input = queue.pop(0)
+            
+            if current_node_name in executed:
+                continue
+            
+            current_node = self._nodes[current_node_name]
+            
+            max_loop = getattr(current_node, '_max_loop', None)
+            if max_loop:
+                self._loop_counters[current_node_name] = self._loop_counters.get(current_node_name, 0) + 1
+                if self._loop_counters[current_node_name] > max_loop:
+                    raise RuntimeError(f"Node '{current_node_name}' exceeded max_loop limit ({max_loop})")
+                logger.debug(f"Loop counter: {current_node_name} [{self._loop_counters[current_node_name]}/{max_loop}]")
+            
+            logger.debug(f"--- Step {step} ---")
+            logger.debug(f"Executing node: {current_node_name}")
+            logger.debug(f"Input data: {current_input}")
+            
+            import time
+            if current_node_name not in self._node_timings:
+                self._node_timings[current_node_name] = {}
+            self._node_timings[current_node_name]["start"] = time.time()
+            
+            result = await current_node(current_input) if asyncio.iscoroutinefunction(current_node) else current_node(current_input)
+            
+            import time
+            end_time = time.time()
+            self._node_timings[current_node_name]["end"] = end_time
+            start_time = self._node_timings[current_node_name].get("start", end_time)
+            self._node_timings[current_node_name]["duration"] = end_time - start_time
+            
+            logger.debug(f"Output result: {result}")
+            
+            node_outputs[current_node_name] = result
+            executed.add(current_node_name)
+            
+            goto_targets = getattr(current_node, '_goto_targets', None)
+            
+            if not goto_targets:
+                logger.debug(f"Node {current_node_name} has no successors")
+                continue
+            
+            next_nodes = []
+            next_input = result
+            
+            if goto_targets is DYNAMIC:
+                if isinstance(result, Route):
+                    resolved_target, next_input = result.resolve()
+                    if isinstance(resolved_target, list):
+                        next_nodes = resolved_target
+                        logger.debug(f"DYNAMIC routing (parallel): {next_nodes}")
+                    else:
+                        next_nodes = [resolved_target]
+                        logger.debug(f"DYNAMIC routing: {resolved_target}")
+                elif isinstance(result, tuple) and len(result) == 2:
+                    target, next_input = result
+                    if callable(target):
+                        next_node_name = target.__name__
+                    else:
+                        next_node_name = target
+                    next_nodes = [next_node_name]
+                    logger.debug(f"DYNAMIC routing: {next_node_name} (tuple format, recommend using goto())")
+                else:
+                    raise ValueError(
+                        f"DYNAMIC node '{current_node_name}' must return:\n"
+                        f"  - goto(target, data)  [recommended]\n"
+                        f"  - (target, data)      [legacy format]"
+                    )
+            elif isinstance(goto_targets, list):
+                next_nodes = goto_targets
+                logger.debug(f"Parallel execution: {next_nodes}")
+            elif isinstance(goto_targets, str):
+                next_nodes = [goto_targets]
+                logger.debug(f"Next node: {goto_targets}")
+            else:
+                raise ValueError(f"Unsupported goto type: {type(goto_targets)}")
+            
+            if len(next_nodes) > 1:
+                logger.debug(f"Using asyncio.gather to execute {len(next_nodes)} nodes in parallel")
+                
+                import time
+                
+                async def execute_with_timing(node_name, node_func, node_input):
+                    """Wrapper to capture execution metrics for parallel nodes."""
+                    if node_name not in self._node_timings:
+                        self._node_timings[node_name] = {}
+                    self._node_timings[node_name]["start"] = time.time()
+                    
+                    if asyncio.iscoroutinefunction(node_func):
+                        result = await node_func(node_input)
+                    else:
+                        result = node_func(node_input)
+                    
+                    end_time = time.time()
+                    self._node_timings[node_name]["end"] = end_time
+                    start_time = self._node_timings[node_name].get("start", end_time)
+                    self._node_timings[node_name]["duration"] = end_time - start_time
+                    
+                    return result
+                
+                tasks = []
+                for next_node_name in next_nodes:
+                    next_node = self._nodes[next_node_name]
+                    tasks.append(execute_with_timing(next_node_name, next_node, next_input))
+                
+                results = await asyncio.gather(*tasks)
+                
+                for node_name, node_result in zip(next_nodes, results):
+                    logger.debug(f"  - {node_name} completed: {node_result}")
+                    node_outputs[node_name] = node_result
+                    executed.add(node_name)
+                    
+                    node_method = self._nodes[node_name]
+                    node_goto = getattr(node_method, '_goto_targets', None)
+                    
+                    if node_goto:
+                        if node_goto is DYNAMIC:
+                            subsequent_nodes = []
+                        elif isinstance(node_goto, str):
+                            subsequent_nodes = [node_goto]
+                        elif isinstance(node_goto, list):
+                            subsequent_nodes = node_goto
+                        else:
+                            subsequent_nodes = []
+                        
+                        for sub_node in subsequent_nodes:
+                            if sub_node in execution_graph:
+                                predecessors = execution_graph[sub_node]
+                                if all(pred in executed for pred in predecessors):
+                                    merged_input = {pred: node_outputs[pred] for pred in predecessors}
+                                    logger.debug(f"Node {sub_node}: all predecessors completed, merging inputs: {list(merged_input.keys())}")
+                                    queue.append((sub_node, merged_input))
+                            else:
+                                queue.append((sub_node, node_result))
+            else:
+                for next_node_name in next_nodes:
+                    if next_node_name in execution_graph:
+                        predecessors = execution_graph[next_node_name]
+                        if all(pred in executed for pred in predecessors):
+                            if len(predecessors) > 1:
+                                merged_input = {pred: node_outputs[pred] for pred in predecessors}
+                                logger.debug(f"Node {next_node_name}: all predecessors completed, merging inputs: {list(merged_input.keys())}")
+                                queue.append((next_node_name, merged_input))
+                            else:
+                                queue.append((next_node_name, next_input))
+                        else:
+                            waiting = [p for p in predecessors if p not in executed]
+                            logger.debug(f"Node {next_node_name} waiting for predecessors: {waiting}")
+                    else:
+                        queue.append((next_node_name, next_input))
+        
+        import time
+        self._flow_end_time = time.time()
+        
+        logger.debug("========== Flow execution completed ==========")
+        logger.debug(f"Final state: {self.state}")
+        return self.state
+    
+    def stats(self) -> dict:
+        """Extract profiling metrics collected during flow execution.
+        
+        Returns dict with timing breakdown by node and total flow duration.
+        Useful for identifying bottlenecks in complex workflows.
+        """
+        total_duration = self._flow_end_time - self._flow_start_time if self._flow_end_time > 0 else 0
+        
+        node_stats = {}
+        for node_name, timing in self._node_timings.items():
+            duration = timing.get("duration", 0)
+            percentage = (duration / total_duration * 100) if total_duration > 0 else 0
+            node_stats[node_name] = {
+                "duration": round(duration, 2),
+                "percentage": round(percentage, 2)
+            }
+        
+        return {
+            "timing": {
+                "total_duration": round(total_duration, 2),
+                "nodes": node_stats
+            }
+        }

rill/utils/logger.py

@@ -0,0 +1,133 @@
+"""统一的日志模块
+
+基于 loguru 的简单易用的日志系统，可以在任何地方直接 import 使用。
+
+使用方式：
+    from rill.utils.logger import logger
+    
+    logger.info("这是一条信息")
+    logger.debug("调试信息")
+    logger.warning("警告信息")
+    logger.error("错误信息")
+
+配置方式：
+    通过环境变量配置：
+    - LOG_LEVEL: 日志级别（DEBUG/INFO/WARNING/ERROR）默认 INFO
+    - LOG_TO_FILE: 是否输出到文件（true/false）默认 false
+    - LOG_FILE: 日志文件路径，默认 logs/rill.log
+"""
+
+import os
+import sys
+from pathlib import Path
+
+from loguru import logger as _logger
+
+# 移除 loguru 的默认 handler
+_logger.remove()
+
+# ===== 配置参数（从环境变量读取） =====
+LOG_LEVEL = os.getenv("LOG_LEVEL", "INFO").upper()
+LOG_TO_FILE = os.getenv("LOG_TO_FILE", "false").lower() == "true"
+LOG_FILE = os.getenv("LOG_FILE", "logs/rill.log")
+
+# ===== 日志格式 =====
+# 简洁格式：时间 | 级别 | 消息
+SIMPLE_FORMAT = (
+    "<green>{time:YYYY-MM-DD HH:mm:ss}</green> | "
+    "<level>{level: <8}</level> | "
+    "<level>{message}</level>"
+)
+
+# 详细格式：时间 | 级别 | 位置 | 消息
+DETAILED_FORMAT = (
+    "<green>{time:YYYY-MM-DD HH:mm:ss}</green> | "
+    "<level>{level: <8}</level> | "
+    "<cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> | "
+    "<level>{message}</level>"
+)
+
+# 根据日志级别选择格式（DEBUG 使用详细格式，其他使用简洁格式）
+LOG_FORMAT = DETAILED_FORMAT if LOG_LEVEL == "DEBUG" else SIMPLE_FORMAT
+
+
+# ===== 配置 logger =====
+_logger_initialized = False
+
+def _setup_logger():
+    """配置 logger（延迟初始化，第一次使用时自动执行）"""
+    global _logger_initialized
+    if _logger_initialized:
+        return
+    
+    # 读取环境变量
+    log_level = os.getenv("LOG_LEVEL", "INFO").upper()
+    log_to_file = os.getenv("LOG_TO_FILE", "false").lower() == "true"
+    log_file = os.getenv("LOG_FILE", "logs/rill.log")
+    log_format = DETAILED_FORMAT if log_level == "DEBUG" else SIMPLE_FORMAT
+    
+    # 1. 控制台输出（始终开启）
+    _logger.add(
+        sys.stdout,
+        format=log_format,
+        level=log_level,
+        colorize=True,
+        backtrace=True,
+        diagnose=True
+    )
+    
+    # 2. 文件输出（可选）
+    if log_to_file:
+        # 确保日志目录存在
+        log_file_path = Path(log_file)
+        log_file_path.parent.mkdir(parents=True, exist_ok=True)
+        
+        _logger.add(
+            log_file,
+            format=DETAILED_FORMAT,  # 文件始终使用详细格式
+            level=log_level,
+            rotation="10 MB",  # 单文件最大 10MB
+            retention="30 days",  # 保留 30 天
+            compression="zip",  # 压缩旧日志
+            backtrace=True,
+            diagnose=True,
+            encoding="utf-8"
+        )
+        _logger.info(f"日志文件输出已启用: {log_file}")
+    
+    _logger_initialized = True
+
+
+# 包装 logger，实现延迟初始化
+class _LazyLogger:
+    """延迟初始化的 logger 包装器"""
+    
+    def __getattr__(self, name):
+        # 第一次访问任何方法时，先初始化 logger
+        _setup_logger()
+        # 然后返回真正的 logger 的属性
+        return getattr(_logger, name)
+
+
+# 导出 logger（用户直接使用这个）
+logger = _LazyLogger()
+
+def set_level(level: str):
+    """运行时动态设置日志级别
+    
+    Args:
+        level: 日志级别 (DEBUG/INFO/WARNING/ERROR)
+    """
+    level = level.upper()
+    _logger.remove()  # 移除所有 handler
+    # 重新添加控制台输出
+    _logger.add(
+        sys.stdout,
+        format=DETAILED_FORMAT if level == "DEBUG" else SIMPLE_FORMAT,
+        level=level,
+        colorize=True,
+        backtrace=True,
+        diagnose=True
+    )
+
+__all__ = ["logger", "set_level"]

rillpy-0.1.0.dist-info/METADATA

@@ -0,0 +1,478 @@
+Metadata-Version: 2.4
+Name: rillpy
+Version: 0.1.0
+Summary: Rill - AI Agent Framework
+Author: zhixiangxue
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/zhixiangxue/rill-ai
+Project-URL: Repository, https://github.com/zhixiangxue/rill-ai
+Project-URL: Issues, https://github.com/zhixiangxue/rill-ai/issues
+Keywords: ai,agent,framework,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: loguru>=0.7.0
+Requires-Dist: chakpy>=0.1.4
+Dynamic: license-file
+
+<div align="center">
+
+<a href="https://github.com/zhixiangxue/rill-ai"><img src="https://raw.githubusercontent.com/zhixiangxue/rill-ai/main/docs/assets/logo.png" alt="Rill Logo" width="120"></a>
+
+[![PyPI version](https://badge.fury.io/py/rillpy.svg)](https://badge.fury.io/py/rillpy)
+[![Python Version](https://img.shields.io/pypi/pyversions/rillpy)](https://pypi.org/project/rillpy/)
+[![License](https://img.shields.io/github/license/zhixiangxue/rill-ai)](https://github.com/zhixiangxue/rill-ai/blob/main/LICENSE)
+[![Downloads](https://img.shields.io/pypi/dm/rillpy)](https://pypi.org/project/rillpy/)
+[![GitHub Stars](https://img.shields.io/github/stars/zhixiangxue/rill-ai?style=social)](https://github.com/zhixiangxue/rill-ai)
+
+**A zero-dependency flow orchestration kernel for building AI workflows your way.**
+
+**A minimal orchestration layer that lets you use any LLM client, any tools, any storage to build your AI agent applications.**
+
+Inspired by CrewAI and LangGraph, designed to be lighter and simpler.
+
+</div>
+
+---
+
+## Why Rill?
+
+Building AI agents shouldn't require heavy frameworks. Sometimes you just need a simple orchestration piece:
+
+- Want to use your own LLM client (chak / OpenAI SDK / Anthropic SDK)? ✅
+- Want to use your own tools (functions / MCP servers / custom implementations)? ✅
+- Want to keep your codebase lightweight and dependencies minimal? ✅
+- Prefer code over YAML/JSON configs? Code is the orchestration. ✅
+
+**Rill is just an orchestration component** - bring your own pieces, Rill handles the flow.
+
+---
+
+## Core Philosophy
+
+Rill embraces the **"code is flow"** design philosophy pioneered by CrewAI - use decorators to define nodes, use Python functions to express logic, no YAML or JSON configs needed.
+
+Built on this foundation, Rill adds:
+
+1. **Forward routing**: Declare next steps with `goto` right where you are, not reverse subscription
+2. **Zero binding**: Framework handles orchestration only, everything else is your call
+
+*Special thanks to CrewAI and LangGraph for inspiring Rill's design.*
+
+---
+
+## Quick Start
+
+### Installation
+
+```bash
+# From PyPI (coming soon)
+pip install rillpy
+
+# From GitHub
+pip install git+https://github.com/zhixiangxue/rill-ai.git@main
+
+# Local development
+git clone https://github.com/zhixiangxue/rill-ai.git
+cd rill-ai
+pip install -e .
+```
+
+### Build a RAG workflow in 30 seconds
+
+```python
+from rill import Flow, node, DYNAMIC, goto
+
+class MyRAGFlow(Flow):
+    @node(start=True, goto=DYNAMIC)
+    async def query(self, user_input):
+        # Use your own LLM client (e.g., chak)
+        from chak import Conversation
+        conv = Conversation("openai/gpt-4o-mini", api_key="YOUR_KEY")
+        result = await conv.asend(user_input)
+        
+        # Decide routing based on LLM response
+        if "search" in result.content.lower():
+            # List means parallel: trigger vector search and web search simultaneously
+            return goto([self.vector_search, self.web_search], user_input)
+        return goto(self.answer, result.content)
+    
+    @node(goto="answer")
+    async def vector_search(self, query):
+        # Use your favorite vector database
+        return await my_chromadb.search(query)
+    
+    @node(goto="answer")
+    async def web_search(self, query):
+        # Use your own search tool
+        return await my_searxng.search(query)
+    
+    @node()
+    async def answer(self, sources):
+        # Multiple predecessors auto-merge: sources = {"vector_search": [...], "web_search": [...]}
+        from chak import Conversation
+        conv = Conversation("openai/gpt-4o-mini", api_key="YOUR_KEY")
+        return await conv.asend(str(sources))
+
+# Run
+await MyRAGFlow().run("What is quantum entanglement?")
+```
+
+**Notice:**
+- ✅ LLM client: `chak` (or OpenAI SDK / Anthropic SDK, your choice)
+- ✅ Vector database: `chromadb` (or Pinecone / Qdrant, your choice)
+- ✅ Search tool: your own implementation (or MCP / LangChain Tools, your choice)
+- ✅ Rill only handles: which node first, which ones parallel, how to merge inputs
+- ✅ Data flows through return values (node → node) and shared state (`self.state`)
+
+---
+
+## Core Features
+
+### 🌱 Zero Binding
+
+Framework doesn't care what LLM, tools, or databases you use. Only provides orchestration.
+
+### 🪴 Code is Flow
+
+Define nodes with `@node` decorator, declare routing with `goto`, no DSL needed.
+
+### 🌻 Forward Declaration
+
+Use `goto(next, data)` to directly specify next step in current node. Matches how humans think.
+
+### 🌾 List Means Parallel
+
+`goto([A, B], data)` automatically triggers `asyncio.gather` for parallel execution.
+
+### 🌿 Auto Input Merge
+
+When multiple predecessors point to same node, framework auto-merges outputs as `{pred_name: output}` dict.
+
+### 🍀 Safety Guards
+
+Graph validation (start point / cycles / reachability) + `max_loop` to prevent infinite loops.
+
+### 🌲 Observable
+
+`Flow.stats()` tracks node execution time, `logger` traces execution flow.
+
+### 🪴 Shared State Management
+
+Rill provides `FlowState` for sharing data across nodes. Simpler than LangGraph's in-node state updates.
+
+**TODO**: Parallel nodes updating state simultaneously may have thread-safety issues. Community contributions welcome.
+
+### 🌾 Return Value as Input
+
+Predecessor node's return value becomes successor node's input parameter. No need to put everything in state.
+
+---
+
+## Common Patterns
+
+### Conditional Branching + Parallel Execution
+
+```python
+class ResearchFlow(Flow):
+    @node(start=True, goto=DYNAMIC)
+    async def decide(self, topic):
+        complexity = await self.analyze_complexity(topic)
+        
+        if complexity > 0.8:
+            # High complexity: parallel deep research
+            return goto([self.academic_search, self.expert_interview], topic)
+        else:
+            # Low complexity: quick search
+            return goto(self.web_search, topic)
+    
+    @node(goto="synthesize")
+    async def academic_search(self, topic):
+        return await search_papers(topic)
+    
+    @node(goto="synthesize")
+    async def expert_interview(self, topic):
+        return await interview_experts(topic)
+    
+    @node(goto="synthesize")
+    async def web_search(self, topic):
+        return await search_web(topic)
+    
+    @node()
+    async def synthesize(self, sources):
+        # Auto-merge: sources could be {"academic_search": ..., "expert_interview": ...}
+        # or just web_search output (single predecessor)
+        return await generate_report(sources)
+```
+
+### Loop + Exit Condition
+
+```python
+class IterativeFlow(Flow):
+    @node(start=True, goto=DYNAMIC, max_loop=5)
+    async def generate(self, prompt):
+        result = await llm_generate(prompt)
+        quality = await self.evaluate(result)
+        
+        if quality > 0.9:
+            return goto(self.finalize, result)
+        else:
+            # Loop back with feedback
+            return goto(self.generate, {"prompt": prompt, "feedback": quality})
+    
+    @node()
+    async def finalize(self, result):
+        return result
+```
+
+### Using Shared State
+
+```python
+class MyWorkflow(Flow):
+    @node(start=True, goto=["fetch_data", "process_config"])
+    async def begin(self, inputs):
+        # Store inputs in state for other nodes to access
+        self.state.user_id = inputs["user_id"]
+        self.state.query = inputs["query"]
+        self.state.results = []  # Initialize shared collection
+    
+    @node(goto="merge")
+    async def fetch_data(self, previous_result):
+        # Access state from parallel node
+        data = await api_call(self.state.user_id, self.state.query)
+        
+        # Accumulate results in state
+        self.state.results.append({"source": "api", "data": data})
+        return data
+    
+    @node(goto="merge")
+    async def process_config(self, previous_result):
+        # Another parallel node accessing same state
+        config = load_config(self.state.user_id)
+        
+        # Also update shared state
+        self.state.config = config
+        return config
+    
+    @node()
+    async def merge(self, inputs):
+        # inputs = {"fetch_data": ..., "process_config": ...}
+        # state contains accumulated data from all nodes
+        final_result = combine(
+            inputs["fetch_data"],
+            inputs["process_config"],
+            self.state.results  # Access shared state
+        )
+        
+        self.state.final_output = final_result
+        return final_result
+
+# Run the workflow
+flow = MyWorkflow()
+final_state = await flow.run({
+    "user_id": 123,
+    "query": "hello"
+})  # 🎯 Rill auto-converts your dict to a Pydantic FlowState object!
+
+# Access final state (Pydantic model)
+print(final_state.final_output)  # 🎉 Flow.run() returns the final FlowState
+print(final_state.user_id)        # Access any field stored during execution
+print(final_state.results)         # All accumulated data persists here
+```
+
+**State vs Return Value:**
+- **Return value**: Direct data passing from predecessor to successor (the main data pipeline)
+- **State**: Shared context accessible from any node (for metadata, counters, cross-branch data)
+- **Key difference**: Return values flow through edges, state persists across the entire workflow
+- Use return values for primary data flow, use state for auxiliary data that multiple nodes need
+
+**Known Issue:**
+- ⚠️ Parallel nodes updating state simultaneously may cause race conditions
+- 🔧 TODO: Need thread-safe state update mechanism (community contributions welcome)
+
+---
+
+## When to Use Rill?
+
+| Your Situation | Recommendation |
+|----------------|----------------|
+| Quick GPT app, don't want to manage anything | 👉 LangChain / LangGraph (all-in-one convenience) |
+| Want to use my own LLM client (chak / OpenAI SDK) + custom tools | 👉 **Rill** (orchestration freedom) |
+| Just want pure orchestration layer, pick other components myself | 👉 **Rill** |
+
+---
+
+## FAQ
+
+**Q: What's the difference between Rill and LangGraph?**  
+A: LangGraph is an all-in-one suite (orchestration + LLM + tools + memory), Rill only handles orchestration layer, other components are your choice.
+
+**Q: I'm already using LangChain Tools, can I use Rill?**  
+A: Yes! Rill doesn't care where your tools come from, just call them directly in nodes.
+
+**Q: Does Rill support state persistence?**  
+A: Current `FlowState` is in-memory state (Pydantic model), persistence is your choice (Redis / PostgreSQL / files), no binding to any storage solution.
+
+**Q: I want to use my own LLM client (e.g., chak), how to integrate?**  
+A: Just `import chak` in nodes and call it, Rill doesn't care which LLM you use. Example:
+```python
+@node(start=True, goto="process")
+async def query(self, user_input):
+    from chak import Conversation  # Your LLM client
+    conv = Conversation("openai/gpt-4o-mini", api_key="YOUR_KEY")
+    return await conv.asend(user_input)
+```
+
+**Q: When do I need `max_loop`?**  
+A: When your flow has cycles (e.g., "generate → evaluate → regenerate"), use `max_loop` to limit loop iterations and prevent infinite loops.
+
+**Q: How does input merging work?**  
+A: When multiple predecessor nodes point to the same target node, and all predecessors complete, the framework merges their outputs as a dict `{pred_name: output}` and passes it to the target node.
+
+**Q: What's the difference between state and return value?**  
+A: They serve different purposes:
+- **Node return value**: Passes data to the next node(s) through the flow edge. This is the main data pipeline.
+- **State (`self.state`)**: A shared Pydantic object accessible from all nodes throughout the workflow. Use it for metadata, counters, configuration, or data that multiple branches need to access.
+- **Example**: Return the processed result to next node, but store statistics/metadata in state.
+
+**Q: Is state update thread-safe in parallel nodes?**  
+A: Not yet. Parallel nodes updating state simultaneously may cause race conditions. This is a known TODO. For now, avoid state updates in parallel nodes or use return values instead.
+
+---
+
+## API Reference
+
+### `Flow`
+
+Orchestration engine, inherit to define your workflow.
+
+```python
+class MyFlow(Flow):
+    def __init__(self, initial_state=None, max_steps=1000, validate=True):
+        super().__init__(initial_state, max_steps, validate)
+```
+
+- `initial_state`: Initial state dict or Pydantic model
+- `max_steps`: Max execution steps (prevent infinite loops)
+- `validate`: Whether to validate graph before execution
+
+### `@node`
+
+Decorator to mark methods as executable flow nodes.
+
+```python
+@node(start=False, goto=None, max_loop=None)
+def my_node(self, inputs):
+    pass
+```
+
+- `start`: Whether this is the start node
+- `goto`: Next node(s), can be:
+  - `None`: No successors (end node)
+  - `"node_name"`: Single next node
+  - `["node1", "node2"]`: Multiple nodes (parallel execution)
+  - `DYNAMIC`: Runtime-determined routing (must return `goto(...)` in node)
+- `max_loop`: Max loop count for this node (for cycle detection)
+
+### `goto(target, data)`
+
+Construct routing decision for DYNAMIC nodes.
+
+```python
+@node(goto=DYNAMIC)
+async def decide(self, inputs):
+    if condition:
+        return goto(self.next_node, data)
+    else:
+        return goto([self.task_a, self.task_b], data)  # Parallel
+```
+
+- `target`: Single node or list of nodes (list triggers parallel execution)
+- `data`: Payload passed to target node(s)
+
+### `DYNAMIC`
+
+Constant for runtime-determined routing. Use with `goto()`.
+
+### `FlowState`
+
+Shared mutable state container (Pydantic model).
+
+```python
+# Access state from any node
+self.state.custom_field = "value"  # Runtime field injection
+self.state.user_id = 123
+self.state.results = []  # Shared collection
+
+# Two independent data channels:
+# 1. Return value: flows through edges (node → successor)
+# 2. State: shared context persists across entire workflow
+```
+
+**Known Issue**: Parallel nodes updating state simultaneously may cause race conditions (TODO).
+
+### `Flow.run(initial_input)`
+
+Execute the flow.
+
+```python
+result_state = await flow.run({"user_input": "Hello"})
+```
+
+### `Flow.stats()`
+
+Get execution statistics.
+
+```python
+stats = flow.stats()
+# {
+#     "timing": {
+#         "total_duration": 2.35,
+#         "nodes": {
+#             "query": {"duration": 1.2, "percentage": 51.06},
+#             "search": {"duration": 0.8, "percentage": 34.04}
+#         }
+#     }
+# }
+```
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│      Your Application Layer             │
+│  LLM: chak / OpenAI / Anthropic / ...   │
+│  Tools: MCP / Functions / LangChain     │
+│  Storage: ChromaDB / PostgreSQL / Redis │
+└──────────────┬──────────────────────────┘
+               │ Only depends on Rill for orchestration
+┌──────────────▼──────────────────────────┐
+│         Rill Orchestration Layer        │
+│  @node + goto + parallel + State        │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## Dependencies
+
+- Python >= 3.8
+- pydantic >= 2.0.0
+- loguru >= 0.7.0
+
+---
+
+## License
+
+MIT License - see LICENSE file for details.
+
+<div align="right"><a href="https://github.com/zhixiangxue/rill-ai"><img src="https://raw.githubusercontent.com/zhixiangxue/rill-ai/main/docs/assets/logo.png" alt="Demo Video" width="120"></a></div>

rillpy-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+rill/__init__.py,sha256=FiHnnChtBeXkCupRcRETBESSpF1AYuSX0PTN65DMUc8,54
+rill/flow.py,sha256=48peKx_6q-ZHGCRaXgR1lebw9t_Lzx6luXyRjuq2-DE,20551
+rill/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rill/utils/logger.py,sha256=rYLXRoZeTnw6PAd0HhstsPQhyJ1Swezhj_UXxMmZfmE,3873
+rillpy-0.1.0.dist-info/licenses/LICENSE,sha256=keVEnzyfJEBdd59gWSskOiqqKiqqKzRKjZqtdLpUK1s,1068
+rillpy-0.1.0.dist-info/METADATA,sha256=NaUwI8uM9hl7IkCvUhF-As1FLYfqivLn-3EzDLBCWpM,16449
+rillpy-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+rillpy-0.1.0.dist-info/top_level.txt,sha256=5sx8p7zijGPad64hI4HjSCZv4cs4T5bivv4ysPjfALw,5
+rillpy-0.1.0.dist-info/RECORD,,

rillpy-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

rillpy-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 zhixiangxue
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rillpy-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+rill