loopuman 1.0.0__tar.gz

loopuman-1.0.0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: loopuman
+Version: 1.0.0
+Summary: The Human API for AI - Give your AI agents instant access to humans
+Home-page: https://github.com/loopuman/loopuman-python
+Author: Loopuman
+Author-email: hello@loopuman.com
+Keywords: ai human-in-the-loop microtasks langchain agents
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.7
+Requires-Dist: requests>=2.25.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

loopuman-1.0.0/README.md

@@ -0,0 +1,88 @@
+# Loopuman Python SDK
+
+**The Human API for AI** - Give your AI agents instant access to humans.
+
+## Installation
+```bash
+pip install loopuman
+```
+
+## Quick Start
+```python
+from loopuman import Loopuman
+
+client = Loopuman(api_key="your_key")
+
+# Ask a human and wait for response
+result = client.ask("Is this content appropriate for children?")
+print(result.response)  # "Yes" or "No" from human
+```
+
+## Use Cases
+
+### Content Moderation
+```python
+result = client.ask(
+    question="Is this image appropriate?",
+    context="Image shows: a sunset over mountains",
+    budget_cents=25
+)
+```
+
+### Fact Verification
+```python
+result = client.ask(
+    question="Is this claim accurate: 'The Eiffel Tower is 300m tall'",
+    budget_cents=50
+)
+```
+
+### AI Agent Oversight
+```python
+# Before sending an important message
+result = client.ask(
+    question=f"Should I send this message? '{draft_message}'",
+    budget_cents=30
+)
+if "yes" in result.response.lower():
+    send_message(draft_message)
+```
+
+## LangChain Integration
+```python
+from loopuman.langchain_tool import LoopumanTool
+from langchain.agents import initialize_agent
+
+tool = LoopumanTool(api_key="your_key")
+agent = initialize_agent([tool], llm, agent="zero-shot-react-description")
+
+# Agent can now ask humans for help
+response = agent.run("Verify if this product review is genuine: '...'")
+```
+
+## Async Tasks (with webhooks)
+```python
+# Create task and receive webhook when complete
+task = client.create_task(
+    title="Review this document",
+    description="Check for errors",
+    budget_cents=100,
+    webhook_url="https://your-app.com/webhook"
+)
+
+print(f"Task created: {task.id}")
+# Your webhook will receive the result when a human completes it
+```
+
+## Pricing
+
+- Minimum: $0.10 per task
+- Typical: $0.25 - $1.00 per task
+- You pay budget + 20% platform fee
+- Workers receive budget - 20%
+
+## Links
+
+- Website: https://loopuman.com
+- API Docs: https://loopuman.com/docs
+- Dashboard: https://loopuman.com/dashboard

loopuman-1.0.0/loopuman/__init__.py

@@ -0,0 +1,263 @@
+"""
+Loopuman Python SDK
+The Human API for AI - Give your AI agents instant access to humans
+
+Usage:
+    from loopuman import Loopuman
+    
+    client = Loopuman(api_key="your_key")
+    
+    # Synchronous - waits for human response
+    result = client.ask("Is this content appropriate?", budget_cents=50)
+    print(result.response)
+    
+    # Async - returns immediately, check later
+    task = client.create_task("Review this document", budget_cents=100)
+    # ... later ...
+    result = client.get_result(task.id)
+"""
+
+import requests
+from dataclasses import dataclass
+from typing import Optional, List, Dict, Any
+
+__version__ = "1.0.0"
+
+@dataclass
+class TaskResult:
+    status: str  # "completed", "timeout", "pending"
+    task_id: str
+    response: Optional[str] = None
+    worker_id: Optional[str] = None
+    completed_in_seconds: Optional[int] = None
+
+@dataclass
+class Task:
+    id: str
+    title: str
+    status: str
+    budget: int
+
+class LoopumanError(Exception):
+    """Base exception for Loopuman errors"""
+    pass
+
+class Loopuman:
+    """
+    Loopuman client - The Human API for AI
+    
+    Args:
+        api_key: Your Loopuman API key
+        base_url: API base URL (default: https://api.loopuman.com)
+    """
+    
+    def __init__(self, api_key: str, base_url: str = "https://api.loopuman.com"):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self._session = requests.Session()
+        self._session.headers.update({
+            "X-API-Key": api_key,
+            "Content-Type": "application/json"
+        })
+    
+    def ask(
+        self,
+        question: str,
+        context: str = "",
+        budget_cents: int = 50,
+        timeout_seconds: int = 300,
+        auto_approve: bool = True
+    ) -> TaskResult:
+        """
+        Ask a human a question and wait for the response.
+        
+        This is a synchronous call - it blocks until a human responds
+        or the timeout is reached.
+        
+        Args:
+            question: The question to ask
+            context: Additional context for the human
+            budget_cents: Payment in cents (min 10, typical 25-100)
+            timeout_seconds: Max time to wait (default 5 minutes)
+            auto_approve: Auto-approve the submission (default True)
+        
+        Returns:
+            TaskResult with the human's response
+        
+        Example:
+            result = client.ask("Is this image appropriate?")
+            if result.status == "completed":
+                print(f"Human said: {result.response}")
+        """
+        response = self._session.post(
+            f"{self.base_url}/api/v1/tasks/sync",
+            json={
+                "title": question,
+                "description": context,
+                "budget": budget_cents,
+                "timeout_seconds": timeout_seconds,
+                "auto_approve": auto_approve
+            }
+        )
+        
+        if response.status_code != 200:
+            raise LoopumanError(f"API error: {response.text}")
+        
+        data = response.json()
+        return TaskResult(
+            status=data.get("status", "error"),
+            task_id=data.get("task_id", ""),
+            response=data.get("response"),
+            worker_id=data.get("worker_id"),
+            completed_in_seconds=data.get("completed_in_seconds")
+        )
+    
+    def create_task(
+        self,
+        title: str,
+        description: str = "",
+        category: str = "ai_training",
+        budget_cents: int = 50,
+        webhook_url: Optional[str] = None
+    ) -> Task:
+        """
+        Create a task asynchronously.
+        
+        Use this when you don't need to wait for the response inline.
+        You can check for results later or receive a webhook.
+        
+        Args:
+            title: Task title
+            description: Task description
+            category: Task category (default: ai_training)
+            budget_cents: Payment in cents
+            webhook_url: URL to receive completion webhook
+        
+        Returns:
+            Task object with the task ID
+        """
+        payload = {
+            "tasks": [{
+                "title": title,
+                "description": description,
+                "category": category,
+                "budget": budget_cents
+            }]
+        }
+        if webhook_url:
+            payload["webhook_url"] = webhook_url
+        
+        response = self._session.post(
+            f"{self.base_url}/api/v1/tasks/bulk",
+            json=payload
+        )
+        
+        if response.status_code != 200:
+            raise LoopumanError(f"API error: {response.text}")
+        
+        data = response.json()
+        task_id = data.get("task_ids", [None])[0]
+        
+        return Task(
+            id=task_id,
+            title=title,
+            status="active",
+            budget=budget_cents
+        )
+    
+    def get_result(self, task_id: str) -> Optional[TaskResult]:
+        """
+        Check if a task has been completed.
+        
+        Args:
+            task_id: The task ID to check
+        
+        Returns:
+            TaskResult if completed, None if still pending
+        """
+        response = self._session.get(
+            f"{self.base_url}/api/v1/tasks/{task_id}"
+        )
+        
+        if response.status_code != 200:
+            raise LoopumanError(f"API error: {response.text}")
+        
+        data = response.json()
+        if data.get("submissions"):
+            sub = data["submissions"][0]
+            return TaskResult(
+                status="completed",
+                task_id=task_id,
+                response=sub.get("content"),
+                worker_id=sub.get("worker_id")
+            )
+        
+        return None
+    
+    def bulk_create(
+        self,
+        tasks: List[Dict[str, Any]],
+        webhook_url: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Create multiple tasks at once.
+        
+        Args:
+            tasks: List of task dicts with title, description, budget
+            webhook_url: URL to receive completion webhooks
+        
+        Returns:
+            Dict with batch_id and task_ids
+        
+        Example:
+            result = client.bulk_create([
+                {"title": "Review image 1", "budget": 25},
+                {"title": "Review image 2", "budget": 25},
+            ])
+        """
+        payload = {"tasks": tasks}
+        if webhook_url:
+            payload["webhook_url"] = webhook_url
+        
+        response = self._session.post(
+            f"{self.base_url}/api/v1/tasks/bulk",
+            json=payload
+        )
+        
+        if response.status_code != 200:
+            raise LoopumanError(f"API error: {response.text}")
+        
+        return response.json()
+
+
+# LangChain Tool Integration
+def get_langchain_tool():
+    """
+    Get a LangChain-compatible tool for human-in-the-loop.
+    
+    Usage:
+        from loopuman import get_langchain_tool
+        
+        human_tool = get_langchain_tool()
+        agent = initialize_agent([human_tool, ...], llm)
+    """
+    try:
+        from langchain.tools import Tool
+    except ImportError:
+        raise ImportError("langchain is required: pip install langchain")
+    
+    import os
+    client = Loopuman(api_key=os.environ.get("LOOPUMAN_API_KEY", ""))
+    
+    def ask_human(query: str) -> str:
+        """Ask a human for help with verification or judgment."""
+        result = client.ask(query, timeout_seconds=300)
+        if result.status == "completed":
+            return result.response
+        return f"No human responded. Task ID: {result.task_id}"
+    
+    return Tool(
+        name="AskHuman",
+        func=ask_human,
+        description="Ask a human for help with verification, judgment, or subjective evaluation. Use when AI is uncertain or needs human oversight."
+    )

loopuman-1.0.0/loopuman/langchain_tool.py

@@ -0,0 +1,61 @@
+"""
+LangChain integration for Loopuman
+
+Usage:
+    from loopuman.langchain_tool import LoopumanTool
+    
+    tool = LoopumanTool(api_key="your_key")
+    agent = initialize_agent([tool], llm)
+"""
+
+import os
+from typing import Optional
+
+try:
+    from langchain.tools import BaseTool
+    from pydantic import Field
+except ImportError:
+    raise ImportError("langchain is required: pip install langchain")
+
+from . import Loopuman
+
+class LoopumanTool(BaseTool):
+    """LangChain tool that gives agents access to human workers."""
+    
+    name: str = "ask_human"
+    description: str = """Ask a human worker to help with a task. 
+Use this tool when you need:
+- Verification of facts or content
+- Subjective judgment (is this appropriate, offensive, accurate?)
+- Real-world information (what's at this location?)
+- Human oversight for important decisions
+
+Input should be a clear question or task description.
+Returns the human's response as a string."""
+    
+    client: Loopuman = Field(default=None, exclude=True)
+    budget_cents: int = 50
+    timeout_seconds: int = 300
+    
+    def __init__(self, api_key: Optional[str] = None, **kwargs):
+        super().__init__(**kwargs)
+        key = api_key or os.environ.get("LOOPUMAN_API_KEY")
+        if not key:
+            raise ValueError("LOOPUMAN_API_KEY required")
+        self.client = Loopuman(api_key=key)
+    
+    def _run(self, query: str) -> str:
+        """Execute the tool."""
+        result = self.client.ask(
+            question=query,
+            budget_cents=self.budget_cents,
+            timeout_seconds=self.timeout_seconds
+        )
+        
+        if result.status == "completed":
+            return result.response
+        return f"No human responded within {self.timeout_seconds}s. Task ID: {result.task_id}"
+    
+    async def _arun(self, query: str) -> str:
+        """Async not implemented yet."""
+        return self._run(query)

loopuman-1.0.0/loopuman.egg-info/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: loopuman
+Version: 1.0.0
+Summary: The Human API for AI - Give your AI agents instant access to humans
+Home-page: https://github.com/loopuman/loopuman-python
+Author: Loopuman
+Author-email: hello@loopuman.com
+Keywords: ai human-in-the-loop microtasks langchain agents
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.7
+Requires-Dist: requests>=2.25.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

loopuman-1.0.0/loopuman.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+setup.py
+loopuman/__init__.py
+loopuman/langchain_tool.py
+loopuman.egg-info/PKG-INFO
+loopuman.egg-info/SOURCES.txt
+loopuman.egg-info/dependency_links.txt
+loopuman.egg-info/requires.txt
+loopuman.egg-info/top_level.txt

loopuman-1.0.0/loopuman.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

loopuman-1.0.0/loopuman.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.25.0

loopuman-1.0.0/loopuman.egg-info/top_level.txt

@@ -0,0 +1 @@
+loopuman

loopuman-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

loopuman-1.0.0/setup.py

@@ -0,0 +1,21 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="loopuman",
+    version="1.0.0",
+    description="The Human API for AI - Give your AI agents instant access to humans",
+    author="Loopuman",
+    author_email="hello@loopuman.com",
+    url="https://github.com/loopuman/loopuman-python",
+    packages=find_packages(),
+    install_requires=["requests>=2.25.0"],
+    python_requires=">=3.7",
+    classifiers=[
+        "Development Status :: 4 - Beta",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3",
+        "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    ],
+    keywords="ai human-in-the-loop microtasks langchain agents",
+)