Metadata-Version: 2.4
Name: humanrpc
Version: 0.1.6
Summary: Human-powered typed RPC endpoints for building systems before the real implementation exists.
Author-email: cvaz1306 <christophervaz160@gmail.com>
Requires-Python: >=3.12
Requires-Dist: fastapi>=0.100.0
Requires-Dist: httpx>=0.23.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: rich>=12.0.0
Requires-Dist: typer>=0.9.0
Requires-Dist: uvicorn>=0.20.0
Requires-Dist: websockets>=10.0
Description-Content-Type: text/markdown

# HumanRPC

HumanRPC is a human-powered RPC framework designed for developing, staging, and deploying distributed systems. 

Instead of waiting for every microservice, agent, or automated workflow to be fully built, your application calls typed, schema-validated endpoints. A human operator receives incoming requests in a real-time browser dashboard, provides or reviews a response, and HumanRPC delivers the result back to the waiting caller.

As you implement the automated versions of your endpoints, you can transition your code smoothly from human-only mockups to fully automated production services.

---

## Features

* **Pydantic-First Validation**: Fully typed request and response schemas verified at runtime.
* **Synchronous & Asynchronous Loops**: Supports standard blocking `ask()` and async `aask()` client loops over HTTP and WebSockets.
* **Progressive Execution Modes**:
  * `manual`: The human operator writes responses entirely from scratch in the UI.
  * `assisted`: The operator is in control but can trigger a local python function to pre-fill the form on-demand, editing it before submission.
  * `review`: The local function runs automatically to generate a draft. The human reviews, modifies, and approves it before returning the result to the caller.
  * `automated`: The local function runs immediately and returns. The human console is bypassed entirely (while preserving a historical record).
* **Strict Client-Side Security**: Restrict which execution modes are permitted. Setting `lock_mode=True` forces the orchestration server to strictly follow your local client's security settings (e.g., ensuring a human-in-the-loop review can never be bypassed programmatically).
* **Simulated Behaviors**: Mock exceptions, failures, ignores, or timeouts directly from the web dashboard.

---

## Installation

```bash
pip install humanrpc
```

---

## Quick Start

### 1. Boot the Orchestration Server

Start the local service and browser dashboard:

```bash
humanrpc serve
```

Open [http://127.0.0.1:1078](http://127.0.0.1:1078) in your web browser to access the operator workspace.

### 2. Define and Call Endpoints in Python

Below is an example showing how to register a fully human manual endpoint, a secure human-verified endpoint with automated drafts, and a fully automated execution bypass.

```python
import asyncio
from pydantic import BaseModel
from humanrpc import Client

# 1. Define your typed payload contracts
class ChatRequest(BaseModel):
    message: str

class ChatResponse(BaseModel):
    reply: str

# An automated handler that generates drafts or automates the task locally
async def agent_copilot(request: ChatRequest) -> ChatResponse:
    return ChatResponse(reply=f"[Copilot Draft] Received: '{request.message}'")

async def main():
    client = Client(base_url="http://127.0.0.1:1078")

    # A. STRICTLY MANUAL ENDPOINT
    # Human writes the response from scratch in the browser console
    human_agent = client.endpoint(
        name="human_only",
        input_model=ChatRequest,
        response_model=ChatResponse,
        default_mode="manual"
    )

    # B. HITL GUARD / REVIEW ENDPOINT WITH CLIENT-SIDE SAFETY LOCK
    # The client-side 'agent_copilot' automatically drafts a response.
    # The human reviews, modifies, and approves it in the UI.
    # 'lock_mode=True' blocks the server from ever bypassing the human verification step.
    reviewed_agent = client.endpoint(
        name="reviewed_agent",
        input_model=ChatRequest,
        response_model=ChatResponse,
        handler=agent_copilot,
        default_mode="review",
        lock_mode=True
    )

    # C. FULLY AUTOMATED BYPASS
    # The client-side handler executes immediately and resolves programmatically.
    # No pending tasks ever appear in the human console.
    auto_agent = client.endpoint(
        name="automated_agent",
        input_model=ChatRequest,
        response_model=ChatResponse,
        handler=agent_copilot,
        default_mode="automated"
    )

    # Dispatch tasks asynchronously
    task1 = asyncio.create_task(human_agent.aask(ChatRequest(message="Hello Human!")))
    task2 = asyncio.create_task(reviewed_agent.aask(ChatRequest(message="Safety Guard Chat")))
    task3 = asyncio.create_task(auto_agent.aask(ChatRequest(message="Speedy Auto Chat")))

    # Resolve executions
    # Task 3 completes instantly. Task 1 and 2 wait for your actions in http://127.0.0.1:1078
    print(await task3)
    print(await task2)
    print(await task1)

if __name__ == "__main__":
    asyncio.run(main())
```

---

## CLI Inspection Utilities

Inspect backend state and manually register or mock responses directly from your terminal:

```bash
# List all registered endpoint interfaces
humanrpc inspect endpoints

# Show all current pending tasks awaiting human review
humanrpc inspect pending

# Force-resolve a request with a successful mock payload
humanrpc respond success <request_id> '{"reply": "Forced success"}'

# Force-resolve a request with a simulated client exception
humanrpc respond exception <request_id> ValueError '{"message": "Invalid value"}'
```

## Status

Early development.

