gohumanloop 0.0.1__py3-none-any.whl → 0.0.2__py3-none-any.whl

gohumanloop/providers/ghl_provider.py

@@ -0,0 +1,64 @@
+import os
+from typing import Dict, Any, Optional
+from pydantic import BaseModel, Field, field_validator, SecretStr
+
+from gohumanloop.models.glh_model import GoHumanLoopConfig
+from gohumanloop.providers.api_provider import APIProvider
+from gohumanloop.utils import get_secret_from_env
+
+class GoHumanLoopProvider(APIProvider):
+    """
+    GoHumanLoop platform provider class.
+    This class is a concrete implementation of the `APIProvider` class.
+    The `GoHumanLoopProvider` class is responsible for interacting with the GoHumanLoop platform.
+    """
+    def __init__(
+        self,
+        name: str,
+        request_timeout: int = 30,
+        poll_interval: int = 5,
+        max_retries: int = 3,
+        default_platform: Optional[str] = "GoHumanLoop",
+        config: Optional[Dict[str, Any]] = None
+    ):
+        """Initialize GoHumanLoop provider
+        
+        Args:
+            name: Provider name
+            api_key: GoHumanLoop API key, if not provided will be fetched from environment variables
+            api_base_url: GoHumanLoop API base URL, if not provided will use default value
+            default_platform: Default platform, e.g. "wechat", "feishu" etc.
+            request_timeout: API request timeout in seconds
+            poll_interval: Polling interval in seconds
+            max_retries: Maximum number of retries
+            config: Additional configuration parameters
+        """
+        # Get API key from environment variables (if not provided)
+        api_key = get_secret_from_env("GOHUMANLOOP_API_KEY")
+            
+        # Get API base URL from environment variables (if not provided)
+        api_base_url = os.environ.get("GOHUMANLOOP_API_BASE_URL", "https://www.gohumanloop.com")
+        
+        # Validate configuration using pydantic model
+        ghl_config = GoHumanLoopConfig(
+            api_key=api_key,
+            api_base_url=api_base_url
+        )
+        
+        super().__init__(
+            name=name,
+            api_base_url=ghl_config.api_base_url,
+            api_key=ghl_config.api_key,
+            default_platform=default_platform,
+            request_timeout=request_timeout,
+            poll_interval=poll_interval,
+            max_retries=max_retries,
+            config=config
+        )
+    
+    def __str__(self) -> str:
+        """Returns a string description of this instance"""
+        base_str = super().__str__()
+        ghl_info = f"- GoHumanLoop Provider: Connected to GoHumanLoop Official Platform\n"
+        return f"{ghl_info}{base_str}"
+    

gohumanloop/providers/terminal_provider.py

@@ -0,0 +1,302 @@
+import asyncio
+from email import message
+import sys
+import json
+from typing import Dict, Any, Optional, List
+from datetime import datetime
+
+from gohumanloop.core.interface import (HumanLoopResult, HumanLoopStatus, HumanLoopType)
+from gohumanloop.providers.base import BaseProvider
+
+class TerminalProvider(BaseProvider):
+    """Terminal-based human-in-the-loop provider implementation
+    
+    This provider interacts with users through command line interface, suitable for testing and simple scenarios.
+    Users can respond to requests via terminal input, supporting approval, information collection and conversation type interactions.
+    """
+    
+    def __init__(self, name: str, config: Optional[Dict[str, Any]] = None):
+        """Initialize terminal provider
+        
+        Args:
+            name: Provider name
+            config: Configuration options, may include:
+        """
+        super().__init__(name, config) 
+    def __str__(self) -> str:
+        base_str = super().__str__()
+        terminal_info = f"- Terminal Provider: Terminal-based human-in-the-loop implementation\n"
+        return f"{terminal_info}{base_str}"
+    
+    async def request_humanloop(
+        self,
+        task_id: str,
+        conversation_id: str,
+        loop_type: HumanLoopType,
+        context: Dict[str, Any],
+        metadata: Optional[Dict[str, Any]] = None,
+        timeout: Optional[int] = None
+    ) -> HumanLoopResult:
+        """Request human-in-the-loop interaction through terminal
+        
+        Args:
+            task_id: Task identifier
+            conversation_id: Conversation ID for multi-turn dialogs
+            loop_type: Loop type
+            context: Context information provided to human
+            metadata: Additional metadata
+            timeout: Request timeout in seconds
+            
+        Returns:
+            HumanLoopResult: Result object containing request ID and initial status
+        """
+        # Generate request ID
+        request_id = self._generate_request_id()
+        
+        # Store request information
+        self._store_request(
+            conversation_id=conversation_id,
+            request_id=request_id,
+            task_id=task_id,
+            loop_type=loop_type,
+            context=context,
+            metadata=metadata or {},
+            timeout=timeout
+        )
+        
+        # Create initial result object
+        result = HumanLoopResult(
+            conversation_id=conversation_id,
+            request_id=request_id,
+            loop_type=loop_type,
+            status=HumanLoopStatus.PENDING
+        )
+        
+        # Start async task to process user input
+        asyncio.create_task(self._process_terminal_interaction(conversation_id, request_id))
+        
+        # Create timeout task if timeout is specified
+        if timeout:
+            self._create_timeout_task(conversation_id, request_id, timeout)
+        
+        return result
+        
+    async def check_request_status(
+        self,
+        conversation_id: str,
+        request_id: str
+    ) -> HumanLoopResult:
+        """Check request status
+        
+        Args:
+            conversation_id: Conversation identifier
+            request_id: Request identifier
+            
+        Returns:
+            HumanLoopResult: Result object containing current status
+        """
+        request_info = self._get_request(conversation_id, request_id)
+        if not request_info:
+            return HumanLoopResult(
+                conversation_id=conversation_id,
+                request_id=request_id,
+                loop_type=HumanLoopType.CONVERSATION,
+                status=HumanLoopStatus.ERROR,
+                error=f"Request '{request_id}' not found in conversation '{conversation_id}'"
+            )
+        
+        # Build result object
+        result = HumanLoopResult(
+            conversation_id=conversation_id,
+            request_id=request_id,
+            loop_type=request_info.get("loop_type", HumanLoopType.CONVERSATION),
+            status=request_info.get("status", HumanLoopStatus.PENDING),
+            response=request_info.get("response", {}),
+            feedback=request_info.get("feedback", {}),
+            responded_by=request_info.get("responded_by", None),
+            responded_at=request_info.get("responded_at", None),
+            error=request_info.get("error", None)
+        )
+        
+        return result
+        
+    async def continue_humanloop(
+        self,
+        conversation_id: str,
+        context: Dict[str, Any],
+        metadata: Optional[Dict[str, Any]] = None,
+        timeout: Optional[int] = None,
+    ) -> HumanLoopResult:
+        """Continue human-in-the-loop interaction for multi-turn conversations
+        
+        Args:
+            conversation_id: Conversation identifier
+            context: Context information provided to human
+            metadata: Additional metadata
+            timeout: Request timeout in seconds
+            
+        Returns:
+            HumanLoopResult: Result object containing request ID and status
+        """
+        # Check if conversation exists
+        conversation_info = self._get_conversation(conversation_id)
+        if not conversation_info:
+            return HumanLoopResult(
+                conversation_id=conversation_id,
+                request_id="",
+                loop_type=HumanLoopType.CONVERSATION,
+                status=HumanLoopStatus.ERROR,
+                error=f"Conversation '{conversation_id}' not found"
+            )
+        
+        # Generate new request ID
+        request_id = self._generate_request_id()
+        
+        # Get task ID
+        task_id = conversation_info.get("task_id", "unknown_task")
+        
+        # Store request information
+        self._store_request(
+            conversation_id=conversation_id,
+            request_id=request_id,
+            task_id=task_id,
+            loop_type=HumanLoopType.CONVERSATION,  # Default to conversation type for continued dialog
+            context=context,
+            metadata=metadata or {},
+            timeout=timeout
+        )
+        
+        # Create initial result object
+        result = HumanLoopResult(
+            conversation_id=conversation_id,
+            request_id=request_id,
+            loop_type=HumanLoopType.CONVERSATION,
+            status=HumanLoopStatus.PENDING
+        )
+        
+        # Start async task to process user input
+        asyncio.create_task(self._process_terminal_interaction(conversation_id, request_id))
+        
+        # Create timeout task if timeout is specified
+        if timeout:
+            self._create_timeout_task(conversation_id, request_id, timeout)
+        
+        return result
+    
+    async def _process_terminal_interaction(self, conversation_id: str, request_id: str):
+        request_info = self._get_request(conversation_id, request_id)
+        if not request_info:
+            return 
+
+        prompt = self.build_prompt(
+            task_id=request_info["task_id"],
+            conversation_id=conversation_id,
+            request_id=request_id,
+            loop_type=request_info["loop_type"],
+            created_at=request_info.get("created_at", ""),
+            context=request_info["context"],
+            metadata=request_info.get("metadata")
+        )
+
+        loop_type = request_info["loop_type"]
+        
+        # Display prompt message
+        print(prompt)
+        
+        # Handle different interaction types based on loop type
+        if loop_type == HumanLoopType.APPROVAL:
+            await self._handle_approval_interaction(conversation_id, request_id, request_info)
+        elif loop_type == HumanLoopType.INFORMATION:
+            await self._handle_information_interaction(conversation_id, request_id, request_info)
+        else:  # HumanLoopType.CONVERSATION
+            await self._handle_conversation_interaction(conversation_id, request_id, request_info)
+
+            
+    async def _handle_approval_interaction(self, conversation_id: str, request_id: str, request_info: Dict[str, Any]):
+        """Handle approval type interaction
+        
+        Args:
+            conversation_id: Conversation ID
+            request_id: Request ID
+            request_info: Request information
+        """
+        print("\nPlease enter your decision (approve/reject):")
+        
+        # Execute blocking input() call in thread pool using run_in_executor
+        loop = asyncio.get_event_loop()
+        response = await loop.run_in_executor(None, input)
+
+        # Process response
+        response = response.strip().lower()
+        if response in ["approve", "yes", "y", "同意", "批准"]:
+            status = HumanLoopStatus.APPROVED
+            response_data = ""
+        elif response in ["reject", "no", "n", "拒绝", "不同意"]:
+            status = HumanLoopStatus.REJECTED
+            print("\nPlease enter the reason for rejection:")
+            reason = await loop.run_in_executor(None, input)
+            response_data = reason
+        else:
+            print("\nInvalid input, please enter 'approve' or 'reject'")
+            # Recursively handle approval interaction
+            await self._handle_approval_interaction(conversation_id, request_id, request_info)
+            return
+        
+        # Update request information
+        request_info["status"] = status
+        request_info["response"] = response_data
+        request_info["responded_by"] = "terminal_user"
+        request_info["responded_at"] = datetime.now().isoformat()
+        
+        print(f"\nYour decision has been recorded: {status.value}")
+    
+    async def _handle_information_interaction(self, conversation_id: str, request_id: str, request_info: Dict[str, Any]):
+        """Handle information collection type interaction
+        
+        Args:
+            conversation_id: Conversation ID
+            request_id: Request ID
+            request_info: Request information
+        """
+        print("\nPlease provide the required information:")
+        
+        # Execute blocking input() call in thread pool using run_in_executor
+        loop = asyncio.get_event_loop()
+        response = await loop.run_in_executor(None, input)
+        
+        # Update request information
+        request_info["status"] = HumanLoopStatus.COMPLETED
+        request_info["response"] = response
+        request_info["responded_by"] = "terminal_user"
+        request_info["responded_at"] = datetime.now().isoformat()
+        
+        print("\nYour information has been recorded")
+    
+    async def _handle_conversation_interaction(self, conversation_id: str, request_id: str, request_info: Dict[str, Any]):
+        """Handle conversation type interaction
+        
+        Args:
+            conversation_id: Conversation ID
+            request_id: Request ID
+            request_info: Request information
+        """
+        print("\nPlease enter your response (type 'exit' to end conversation):")
+        
+        # Execute blocking input() call in thread pool using run_in_executor
+        loop = asyncio.get_event_loop()
+        response = await loop.run_in_executor(None, input)
+        
+        # Process response
+        if response.strip().lower() in ["exit", "quit", "结束", "退出"]:
+            status = HumanLoopStatus.COMPLETED
+            print("\nConversation ended")
+        else:
+            status = HumanLoopStatus.INPROGRESS
+
+        # Update request information
+        request_info["status"] = status
+        request_info["response"] = response
+        request_info["responded_by"] = "terminal_user"
+        request_info["responded_at"] = datetime.now().isoformat()
+        
+        print("\nYour response has been recorded")

gohumanloop/utils/__init__.py

@@ -0,0 +1 @@
+from .utils import run_async_safely, get_secret_from_env

gohumanloop/utils/context_formatter.py

@@ -0,0 +1,59 @@
+from typing import Dict, Any, List, Optional, Union
+import json
+
+class ContextFormatter:
+    """上下文格式化工具"""
+    
+    @staticmethod
+    def format_for_human(context: Dict[str, Any]) -> str:
+        """将上下文格式化为人类可读的文本"""
+        result = []
+        
+        # 添加标题（如果有）
+        if "title" in context:
+            result.append(f"# {context['title']}\n")
+            
+        # 添加描述（如果有）
+        if "description" in context:
+            result.append(f"{context['description']}\n")
+            
+        # 添加任务信息
+        if "task" in context:
+            result.append(f"## 任务\n{context['task']}\n")
+            
+        # 添加代理信息
+        if "agent" in context:
+            result.append(f"## 代理\n{context['agent']}\n")
+            
+        # 添加操作信息
+        if "action" in context:
+            result.append(f"## 请求的操作\n{context['action']}\n")
+            
+        # 添加原因
+        if "reason" in context:
+            result.append(f"## 原因\n{context['reason']}\n")
+            
+        # 添加其他键值对
+        other_keys = [k for k in context.keys() if k not in ["title", "description", "task", "agent", "action", "reason"]]
+        if other_keys:
+            result.append("## 附加信息\n")
+            for key in other_keys:
+                value = context[key]
+                if isinstance(value, (dict, list)):
+                    value = json.dumps(value, ensure_ascii=False, indent=2)
+                result.append(f"### {key}\n```\n{value}\n```\n")
+                
+        return "\n".join(result)
+        
+    @staticmethod
+    def format_for_api(context: Dict[str, Any]) -> Dict[str, Any]:
+        """将上下文格式化为API友好的格式"""
+        # 复制上下文以避免修改原始数据
+        formatted = context.copy()
+        
+        # 确保所有值都是可序列化的
+        for key, value in formatted.items():
+            if not isinstance(value, (str, int, float, bool, list, dict, type(None))):
+                formatted[key] = str(value)
+                
+        return formatted

gohumanloop/utils/threadsafedict.py

@@ -0,0 +1,243 @@
+from typing import Dict, Any, Optional, TypeVar, Generic
+import asyncio
+import threading
+
+
+K = TypeVar('K')
+V = TypeVar('V')
+
+class ThreadSafeDict(Generic[K, V]):
+    """
+    线程安全的字典，同时支持同步和异步操作，两种方式都保证线程安全
+    - 双重锁机制 ：
+
+    - 使用 threading.RLock 保护同步操作
+    - 使用 asyncio.Lock 保护异步操作
+    - 使用键级别锁减少锁竞争
+    - 同步方法的线程安全 ：
+
+    - 所有同步方法都使用 self._sync_lock 保护
+    - 返回容器类型的方法（如 keys() 、 values() 、 items() ）返回列表副本而非迭代器，避免迭代过程中的并发修改问题
+    - 异步方法的线程安全 ：
+
+    - 所有异步方法都使用 self._async_lock 保护
+    - 对于写操作，还使用键级别锁进一步减少锁竞争
+    - 键级别锁 ：
+
+    - 为每个键创建独立的锁，减少不同键之间的锁竞争
+    - 使用全局锁 self._global_lock 保护键级别锁的创建和删除
+    """
+    
+    def __init__(self):
+        self._dict = {}
+        # 使用 threading.RLock 支持同步操作的线程安全
+        self._sync_lock = threading.RLock()
+        # 使用 asyncio.Lock 支持异步操作的线程安全
+        self._async_lock = asyncio.Lock()
+        # 键级别锁字典
+        self._key_locks = {}
+        # 键级别锁的全局锁
+        self._global_lock = asyncio.Lock()
+        
+    async def _get_key_lock(self, key):
+        """获取指定键的锁，如果不存在则创建"""
+        async with self._global_lock:
+            if key not in self._key_locks:
+                self._key_locks[key] = asyncio.Lock()
+            return self._key_locks[key]
+    
+    # 同步方法 - 使用 threading.RLock 保证线程安全
+    def __getitem__(self, key: K) -> V:
+        """获取值 - 同步方法，用于 dict[key] 语法"""
+        with self._sync_lock:
+            return self._dict[key]
+    
+    def __setitem__(self, key: K, value: V) -> None:
+        """设置值 - 同步方法，用于 dict[key] = value 语法"""
+        with self._sync_lock:
+            self._dict[key] = value
+    
+    def __delitem__(self, key: K) -> None:
+        """删除键 - 同步方法，用于 del dict[key] 语法"""
+        with self._sync_lock:
+            del self._dict[key]
+    
+    def __contains__(self, key: K) -> bool:
+        """检查键是否存在 - 同步方法，用于 key in dict 语法"""
+        with self._sync_lock:
+            return key in self._dict
+    
+    def get(self, key: K, default: Optional[V] = None) -> Optional[V]:
+        """获取值，如果不存在则返回默认值 - 同步方法"""
+        with self._sync_lock:
+            return self._dict.get(key, default)
+    
+    def __len__(self) -> int:
+        """获取字典长度 - 同步方法，用于 len(dict) 语法"""
+        with self._sync_lock:
+            return len(self._dict)
+    
+    def keys(self):
+        """获取所有键 - 同步方法"""
+        with self._sync_lock:
+            return list(self._dict.keys())
+    
+    def values(self):
+        """获取所有值 - 同步方法"""
+        with self._sync_lock:
+            return list(self._dict.values())
+    
+    def items(self):
+        """获取所有键值对 - 同步方法"""
+        with self._sync_lock:
+            return list(self._dict.items())
+            
+    def update(self, key: K, updates: Dict[str, Any]) -> bool:
+        """更新字典中的值 - 同步方法"""
+        with self._sync_lock:
+            if key in self._dict and isinstance(self._dict[key], dict):
+                self._dict[key].update(updates)
+                return True
+            return False
+            
+    def update_item(self, key: K, item_key: Any, item_value: Any) -> bool:
+        """更新字典中的单个项 - 同步方法"""
+        with self._sync_lock:
+            if key in self._dict and isinstance(self._dict[key], dict):
+                self._dict[key][item_key] = item_value
+                return True
+            return False
+    
+    # 异步方法 - 使用 asyncio.Lock 保证线程安全
+    async def aget(self, key: K, default: Optional[V] = None) -> Optional[V]:
+        """安全地获取值 - 异步方法"""
+        async with self._async_lock:
+            return self._dict.get(key, default)
+    
+    async def aset(self, key: K, value: V) -> None:
+        """安全地设置值 - 异步方法"""
+        key_lock = await self._get_key_lock(key)
+        async with key_lock:
+            async with self._async_lock:
+                self._dict[key] = value
+            
+    async def adelete(self, key: K) -> bool:
+        """安全地删除键 - 异步方法"""
+        key_lock = await self._get_key_lock(key)
+        async with key_lock:
+            async with self._async_lock:
+                if key in self._dict:
+                    del self._dict[key]
+                    # 也可以选择删除锁
+                    async with self._global_lock:
+                        if key in self._key_locks:
+                            del self._key_locks[key]
+                    return True
+                return False
+    
+    async def aupdate(self, key: K, updates: Dict[str, Any]) -> bool:
+        """安全地更新值 - 异步方法"""
+        key_lock = await self._get_key_lock(key)
+        async with key_lock:
+            async with self._async_lock:
+                if key in self._dict and isinstance(self._dict[key], dict):
+                    self._dict[key].update(updates)
+                    return True
+                return False
+    
+    async def aupdate_item(self, key: K, item_key: Any, item_value: Any) -> bool:
+        """安全地更新字典中的单个项 - 异步方法"""
+        key_lock = await self._get_key_lock(key)
+        async with key_lock:
+            async with self._async_lock:
+                if key in self._dict and isinstance(self._dict[key], dict):
+                    self._dict[key][item_key] = item_value
+                    return True
+                return False
+    
+    async def acontains(self, key: K) -> bool:
+        """安全地检查键是否存在 - 异步方法"""
+        async with self._async_lock:
+            return key in self._dict
+            
+    async def alen(self) -> int:
+        """安全地获取字典长度 - 异步方法"""
+        async with self._async_lock:
+            return len(self._dict)
+            
+    async def akeys(self):
+        """安全地获取所有键 - 异步方法"""
+        async with self._async_lock:
+            return list(self._dict.keys())
+            
+    async def avalues(self):
+        """安全地获取所有值 - 异步方法"""
+        async with self._async_lock:
+            return list(self._dict.values())
+            
+    async def aitems(self):
+        """安全地获取所有键值对 - 异步方法"""
+        async with self._async_lock:
+            return list(self._dict.items())
+
+if __name__ == "__main__":
+    # 测试同步方法
+    def test_sync_methods():
+        print("\n=== 测试同步方法 ===")
+        sync_dict = ThreadSafeDict()
+        
+        # 测试基本的增删改查操作
+        sync_dict["key1"] = "value1"
+        print("设置并获取:", sync_dict["key1"])  # value1
+        print("键存在性检查:", "key1" in sync_dict)  # True
+        print("获取默认值:", sync_dict.get("not_exist", "default"))  # default
+        
+        # 测试字典长度
+        print("字典长度:", len(sync_dict))  # 1
+        
+        # 测试字典方法
+        sync_dict["key2"] = "value2"
+        print("所有键:", sync_dict.keys())  # ['key1', 'key2']
+        print("所有值:", sync_dict.values())  # ['value1', 'value2']
+        print("所有键值对:", sync_dict.items())  # [('key1', 'value1'), ('key2', 'value2')]
+        
+        # 测试嵌套字典更新
+        sync_dict["nested"] = {"a": 1}
+        sync_dict.update("nested", {"b": 2})
+        sync_dict.update_item("nested", "c", 3)
+        print("嵌套字典:", sync_dict["nested"])  # {'a': 1, 'b': 2, 'c': 3}
+        
+        # 测试删除操作
+        del sync_dict["key1"]
+        print("删除后检查:", "key1" in sync_dict)  # False
+
+    # 测试异步方法
+    async def test_async_methods():
+        print("\n=== 测试异步方法 ===")
+        async_dict = ThreadSafeDict()
+        
+        # 测试基本的异步增删改查
+        await async_dict.aset("key1", "value1")
+        print("异步获取:", await async_dict.aget("key1"))  # value1
+        print("异步键检查:", await async_dict.acontains("key1"))  # True
+        
+        # 测试异步字典操作
+        await async_dict.aset("key2", "value2")
+        print("异步长度:", await async_dict.alen())  # 2
+        print("异步所有键:", await async_dict.akeys())  # ['key1', 'key2']
+        print("异步所有值:", await async_dict.avalues())  # ['value1', 'value2']
+        print("异步所有键值对:", await async_dict.aitems())  # [('key1', 'value1'), ('key2', 'value2')]
+        
+        # 测试异步嵌套字典更新
+        await async_dict.aset("nested", {"x": 1})
+        await async_dict.aupdate("nested", {"y": 2})
+        await async_dict.aupdate_item("nested", "z", 3)
+        print("异步嵌套字典:", await async_dict.aget("nested"))  # {'x': 1, 'y': 2, 'z': 3}
+        
+        # 测试异步删除
+        await async_dict.adelete("key1")
+        print("异步删除后检查:", await async_dict.acontains("key1"))  # False
+        
+    # 运行测试
+    test_sync_methods()
+    asyncio.run(test_async_methods())