humanrpc 0.1.0__tar.gz

humanrpc-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: humanrpc
+Version: 0.1.0
+Summary: Human-powered typed RPC endpoints for building systems before the real implementation exists.
+Author: cvaz1306
+Author-email: christophervaz160@gmail.com
+Requires-Python: >=3.12
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: fastapi (>=0.136.3,<0.137.0)
+Requires-Dist: httpx (>=0.28.1,<0.29.0)
+Requires-Dist: pydantic (>=2.13.4,<3.0.0)
+Requires-Dist: rich (>=15.0.0,<16.0.0)
+Requires-Dist: typer (>=0.26.6,<0.27.0)
+Requires-Dist: uvicorn (>=0.48.0,<0.49.0)
+Requires-Dist: websockets (>=16.0,<17.0)
+Description-Content-Type: text/markdown
+
+# HumanRPC
+
+HumanRPC is a human-powered RPC server for developing distributed systems before the real implementation exists.
+
+Instead of calling an AI agent, microservice, planner, or capability, your application calls a typed endpoint. A human operator receives the request in a web UI, provides a response, and HumanRPC returns the result to the caller.
+
+The goal is to enable rapid development of orchestration, routing, scheduling, memory, and workflow systems without waiting for every component to be implemented.
+
+## Features
+
+* Pydantic-first API
+* Typed request and response models
+* Async and sync clients
+* Human-powered endpoint implementations
+* Exception simulation
+* Timeout simulation
+* Web UI for handling requests
+* No external infrastructure required
+
+## Example
+
+```python
+from humanrpc import Client
+
+client = Client()
+
+agent = client.endpoint(
+    name="agent",
+    input_model=ChatRequest,
+    response_model=ChatResponse,
+    exceptions=[
+        ValueError,
+        HTTPException,
+    ],
+)
+
+result = await agent.aask(
+    ChatRequest(...)
+)
+```
+
+## Status
+
+Early development.
+
+

humanrpc-0.1.0/README.md

@@ -0,0 +1,45 @@
+# HumanRPC
+
+HumanRPC is a human-powered RPC server for developing distributed systems before the real implementation exists.
+
+Instead of calling an AI agent, microservice, planner, or capability, your application calls a typed endpoint. A human operator receives the request in a web UI, provides a response, and HumanRPC returns the result to the caller.
+
+The goal is to enable rapid development of orchestration, routing, scheduling, memory, and workflow systems without waiting for every component to be implemented.
+
+## Features
+
+* Pydantic-first API
+* Typed request and response models
+* Async and sync clients
+* Human-powered endpoint implementations
+* Exception simulation
+* Timeout simulation
+* Web UI for handling requests
+* No external infrastructure required
+
+## Example
+
+```python
+from humanrpc import Client
+
+client = Client()
+
+agent = client.endpoint(
+    name="agent",
+    input_model=ChatRequest,
+    response_model=ChatResponse,
+    exceptions=[
+        ValueError,
+        HTTPException,
+    ],
+)
+
+result = await agent.aask(
+    ChatRequest(...)
+)
+```
+
+## Status
+
+Early development.
+

humanrpc-0.1.0/humanrpc/__init__.py

@@ -0,0 +1,8 @@
+from humanrpc.client.client import HumanRPCClient
+
+Client = HumanRPCClient
+
+__all__ = [
+    "Client",
+    "HumanRPCClient",
+]

humanrpc-0.1.0/humanrpc/__main__.py

@@ -0,0 +1,145 @@
+import json
+from pathlib import Path
+from importlib.resources import files
+
+import httpx
+import typer
+import uvicorn
+
+from rich import print
+from rich.table import Table
+
+from humanrpc.server.app import create_app
+
+cli = typer.Typer(help="HumanRPC CLI")
+
+inspect_cli = typer.Typer(help="Inspect server state")
+respond_cli = typer.Typer(help="Manually respond to requests")
+
+cli.add_typer(inspect_cli, name="inspect")
+cli.add_typer(respond_cli, name="respond")
+
+
+@cli.command()
+def serve(
+    host: str = "127.0.0.1",
+    port: int = 1078,
+    no_static: bool = False,
+):
+    app = create_app(
+        serve_static=not no_static,
+    )
+
+    uvicorn.run(
+        app,
+        host=host,
+        port=port,
+        reload=False,
+    )
+
+
+@cli.command("static-path")
+def static_path():
+    path = files("humanrpc").joinpath("static")
+    print(Path(path))
+
+
+@inspect_cli.command("endpoints")
+def inspect_endpoints(
+    endpoint: str = "http://127.0.0.1:1078",
+):
+    r = httpx.get(f"{endpoint}/endpoints")
+    data = r.json()
+
+    table = Table(title="Registered Endpoints")
+    table.add_column("Name")
+
+    for name in data.keys():
+        table.add_row(name)
+
+    print(table)
+
+
+@inspect_cli.command("request")
+def inspect_request(
+    request_id: str,
+    endpoint: str = "http://127.0.0.1:1078",
+):
+    r = httpx.get(f"{endpoint}/requests/{request_id}")
+    data = r.json()
+
+    print(data)
+
+
+@inspect_cli.command("pending")
+def inspect_pending(
+    endpoint: str = "http://127.0.0.1:1078",
+):
+    r = httpx.get(f"{endpoint}/requests/pending")
+    data = r.json()
+
+    print(data)
+
+
+@respond_cli.command("success")
+def respond_success(
+    request_id: str,
+    payload: str,
+    endpoint: str = "http://127.0.0.1:1078",
+):
+    data = json.loads(payload)
+
+    httpx.post(
+        f"{endpoint}/respond/success/{request_id}",
+        json=data,
+    )
+
+    print("[green]Response sent (success)[/green]")
+
+
+@respond_cli.command("exception")
+def respond_exception(
+    request_id: str,
+    exception_type: str,
+    payload: str,
+    endpoint: str = "http://127.0.0.1:1078",
+):
+    data = json.loads(payload)
+
+    httpx.post(
+        f"{endpoint}/respond/exception/{request_id}",
+        params={"exception_type": exception_type},
+        json=data,
+    )
+
+    print(
+        f"[yellow]Response sent (exception: {exception_type})[/yellow]"
+    )
+
+
+@respond_cli.command("timeout")
+def respond_timeout(
+    request_id: str,
+    endpoint: str = "http://127.0.0.1:1078",
+):
+    httpx.post(f"{endpoint}/respond/timeout/{request_id}")
+
+    print("[blue]Response sent (timeout)[/blue]")
+
+
+@respond_cli.command("ignore")
+def respond_ignore(
+    request_id: str,
+    endpoint: str = "http://127.0.0.1:1078",
+):
+    httpx.post(f"{endpoint}/respond/ignore/{request_id}")
+
+    print("[dim]Response sent (ignore)[/dim]")
+
+
+def main():
+    cli()
+
+
+if __name__ == "__main__":
+    main()

humanrpc-0.1.0/humanrpc/client/client.py

@@ -0,0 +1,46 @@
+import httpx
+
+from humanrpc.client.endpoint import Endpoint
+from humanrpc.models.endpoint import (
+    EndpointDefinition,
+    ExceptionDefinition,
+)
+
+
+class HumanRPCClient:
+    def __init__(self, base_url: str = "http://127.0.0.1:1078"):
+        self.base_url = base_url
+
+    def endpoint(
+        self,
+        *,
+        name: str,
+        input_model,
+        response_model,
+        exceptions=None,
+    ) -> Endpoint:
+        exceptions = exceptions or []
+
+        definition = EndpointDefinition(
+            name=name,
+            input_schema=input_model.model_json_schema(),
+            response_schema=response_model.model_json_schema(),
+            exceptions=[
+                ExceptionDefinition(name=exc.__name__)
+                for exc in exceptions
+            ],
+        )
+
+        httpx.post(
+            f"{self.base_url}/endpoints",
+            json=definition.model_dump(),
+            timeout=5.0,
+        )
+
+        return Endpoint(
+            name=name,
+            input_model=input_model,
+            response_model=response_model,
+            exceptions=exceptions,
+            base_url=self.base_url,
+        )

humanrpc-0.1.0/humanrpc/client/endpoint.py

@@ -0,0 +1,119 @@
+import uuid
+import httpx
+import asyncio
+import json
+import time
+import websockets
+
+from pydantic import BaseModel
+
+
+class Endpoint:
+    def __init__(
+        self,
+        *,
+        name: str,
+        input_model,
+        response_model,
+        exceptions: list[type[Exception]],
+        base_url: str,
+    ):
+        self.name = name
+        self.input_model = input_model
+        self.response_model = response_model
+        self.exceptions = exceptions
+        self.base_url = base_url
+
+    async def aask(self, request: BaseModel):
+        payload = request.model_dump()
+        request_id = str(uuid.uuid4())
+
+        # Use AsyncClient to avoid blocking the loop
+        async with httpx.AsyncClient() as client:
+            await client.post(
+                f"{self.base_url}/requests",
+                json={
+                    "request_id": request_id,
+                    "endpoint_name": self.name,
+                    "payload": payload,
+                },
+                timeout=5.0,
+            )
+
+        ws_url = self.base_url.replace("http", "ws")
+        ws_url = f"{ws_url}/ws/requests/{request_id}"
+
+        async with websockets.connect(ws_url) as ws:
+            await ws.send("ready")
+
+            while True:
+                msg = await ws.recv()
+                record = json.loads(msg)
+
+                response = record.get("response")
+                if not response:
+                    continue
+
+                kind = response.get("kind")
+
+                if kind == "success":
+                    return self.response_model.model_validate(response["payload"])
+
+                if kind == "exception":
+                    exc_type = response["exception_type"]
+
+                    for exc in self.exceptions:
+                        if exc.__name__ == exc_type:
+                            raise exc(**response["payload"])
+
+                    raise Exception(f"Unknown exception: {exc_type}")
+
+                if kind == "timeout":
+                    raise TimeoutError()
+
+                if kind == "ignore":
+                    return None
+
+    def ask(self, request: BaseModel):
+        request_id = str(uuid.uuid4())
+        
+        with httpx.Client() as client:
+            client.post(
+                f"{self.base_url}/requests",
+                json={
+                    "request_id": request_id,
+                    "endpoint_name": self.name,
+                    "payload": request.model_dump(),
+                },
+                timeout=5.0,
+            )
+
+            # Poll for resolution
+            while True:
+                r = client.get(f"{self.base_url}/requests/{request_id}")
+                if r.status_code == 200:
+                    record = r.json()
+                    if record.get("status") == "completed":
+                        response = record.get("response")
+                        if not response:
+                            raise Exception("Request completed with no response payload.")
+
+                        kind = response.get("kind")
+
+                        if kind == "success":
+                            return self.response_model.model_validate(response["payload"])
+
+                        if kind == "exception":
+                            exc_type = response["exception_type"]
+                            for exc in self.exceptions:
+                                if exc.__name__ == exc_type:
+                                    raise exc(**response["payload"])
+                            raise Exception(f"Unknown exception: {exc_type}")
+
+                        if kind == "timeout":
+                            raise TimeoutError()
+
+                        if kind == "ignore":
+                            return None
+
+                time.sleep(0.2)

humanrpc-0.1.0/humanrpc/models/endpoint.py

@@ -0,0 +1,14 @@
+from pydantic import BaseModel, Field
+
+
+class ExceptionDefinition(BaseModel):
+    name: str
+
+
+class EndpointDefinition(BaseModel):
+    name: str
+
+    input_schema: dict
+    response_schema: dict
+
+    exceptions: list[ExceptionDefinition] = Field(default_factory=list)

humanrpc-0.1.0/humanrpc/models/request.py

@@ -0,0 +1,13 @@
+from uuid import uuid4
+from datetime import datetime
+from pydantic import BaseModel, Field
+
+
+class RequestEnvelope(BaseModel):
+    request_id: str = Field(default_factory=lambda: str(uuid4()))
+
+    endpoint_name: str
+
+    payload: dict
+
+    created_at: datetime = Field(default_factory=datetime.utcnow)

humanrpc-0.1.0/humanrpc/models/response.py

@@ -0,0 +1,33 @@
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class SuccessResponse(BaseModel):
+    kind: Literal["success"] = "success"
+
+    payload: dict
+
+
+class ExceptionResponse(BaseModel):
+    kind: Literal["exception"] = "exception"
+
+    exception_type: str
+
+    payload: dict
+
+
+class TimeoutResponse(BaseModel):
+    kind: Literal["timeout"] = "timeout"
+
+
+class IgnoreResponse(BaseModel):
+    kind: Literal["ignore"] = "ignore"
+
+ResponseEnvelope = (
+    SuccessResponse
+    | ExceptionResponse
+    | TimeoutResponse
+    | IgnoreResponse
+)
+

humanrpc-0.1.0/humanrpc/server/app.py

@@ -0,0 +1,37 @@
+from importlib.resources import files
+
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+
+from starlette.routing import Mount
+
+from humanrpc.server.routes import router as core_router
+from humanrpc.server.manual import router as manual_router
+from humanrpc.server.ws import router as ws_router
+
+
+def create_app(*, serve_static: bool = True) -> FastAPI:
+    app = FastAPI()
+
+    app.include_router(ws_router)
+    app.include_router(core_router)
+    app.include_router(manual_router)
+
+    if serve_static:
+        static_dir = files("humanrpc").joinpath("static")
+
+        app.mount(
+            "/",
+            StaticFiles(
+                directory=str(static_dir),
+                html=True,
+            ),
+            name="static",
+        )
+
+    return app
+
+
+app = create_app()
+
+app.routes.sort(key=lambda r: 1 if isinstance(r, Mount) and r.path == "/" else 0)

humanrpc-0.1.0/humanrpc/server/manual.py

@@ -0,0 +1,71 @@
+from datetime import datetime
+from fastapi import APIRouter
+
+from humanrpc.server.state import state
+from humanrpc.models.response import (
+    SuccessResponse,
+    ExceptionResponse,
+    TimeoutResponse,
+    IgnoreResponse,
+)
+
+router = APIRouter()
+
+
+async def _complete(request_id: str):
+    await state.notify(request_id)
+
+
+@router.post("/respond/success/{request_id}")
+async def respond_success(request_id: str, payload: dict):
+    record = state.requests.get(request_id)
+
+    if record:
+        record.status = "completed"
+        record.response = SuccessResponse(payload=payload)
+        record.responded_at = datetime.utcnow()
+        await _complete(request_id)
+
+    return {"ok": True}
+
+
+@router.post("/respond/exception/{request_id}")
+async def respond_exception(request_id: str, exception_type: str, payload: dict):
+    record = state.requests.get(request_id)
+
+    if record:
+        record.status = "completed"
+        record.response = ExceptionResponse(
+            exception_type=exception_type,
+            payload=payload,
+        )
+        record.responded_at = datetime.utcnow()
+        await _complete(request_id)
+
+    return {"ok": True}
+
+
+@router.post("/respond/timeout/{request_id}")
+async def respond_timeout(request_id: str):
+    record = state.requests.get(request_id)
+
+    if record:
+        record.status = "completed"
+        record.response = TimeoutResponse()
+        record.responded_at = datetime.utcnow()
+        await _complete(request_id)
+
+    return {"ok": True}
+
+
+@router.post("/respond/ignore/{request_id}")
+async def respond_ignore(request_id: str):
+    record = state.requests.get(request_id)
+
+    if record:
+        record.status = "completed"
+        record.response = IgnoreResponse()
+        record.responded_at = datetime.utcnow()
+        await _complete(request_id)
+
+    return {"ok": True}