roviers 0.1.0__tar.gz

roviers-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+/target
+/roviers_data
+*.log
+citizen_id.json
+alice_id.json
+

roviers-0.1.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.5
+Name: roviers
+Version: 0.1.0
+Summary: Python client SDK for Roviers: High-Throughput Service Intake & Claim-Check Vault
+Author: Sunil K Sundaram
+License-Expression: MIT
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: agents
+Requires-Dist: langchain-core>=0.2.0; extra == 'agents'
+Description-Content-Type: text/markdown
+
+# Roviers Python SDK 🤖
+
+Broker & Agent Asynchronous Task & Claim-Check Vault Client for AI Agents, LLM Orchestrators (LangGraph, CrewAI, AutoGen), and distributed microservices.
+
+## Installation
+
+```bash
+pip install ./clients/python
+# Or in editable mode:
+pip install -e ./clients/python
+```
+
+## Quick Start
+
+```python
+import asyncio
+from roviers import RoviersBrokerClient
+
+async def main():
+    # 1. Connect to Roviers Broker
+    broker = RoviersBrokerClient(base_url="http://127.0.0.1:8080")
+
+    # 2. Issue or load Agent Token
+    await broker.issue_agent_token(
+        agent_id="AGENT-RESEARCH-01",
+        agent_name="Autonomous Research Agent",
+        save_path="agent_token.json"
+    )
+
+    # 3. Submit heavy asynchronous request (returns in ~2ms with Receipt Token)
+    receipt = await broker.submit(
+        service_name="service.finance.risk_model",
+        payload={"portfolio_id": "port_9921", "simulations": 10000}
+    )
+    print(f"Receipt received: #{receipt.receipt_id} (Status: {receipt.status})")
+
+    # 4. Wait for real-time SSE signal and redeem outcome from Broker Vault
+    outcome = await broker.wait_for_outcome(receipt.receipt_id)
+    print("Vault Outcome:", outcome.result)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## LangGraph / CrewAI Agent Tool Integration
+
+```python
+from roviers import RoviersBrokerClient, RoviersTool
+
+broker = RoviersBrokerClient(base_url="http://127.0.0.1:8080", token="agent_token.json")
+
+# Expose as a non-blocking agent tool
+deep_research_tool = RoviersTool(
+    broker=broker,
+    service_name="service.ai.deep_research",
+    name="deep_research",
+    description="Runs deep multi-source research asynchronously without blocking agent loops"
+)
+```

roviers-0.1.0/README.md

@@ -0,0 +1,59 @@
+# Roviers Python SDK 🤖
+
+Broker & Agent Asynchronous Task & Claim-Check Vault Client for AI Agents, LLM Orchestrators (LangGraph, CrewAI, AutoGen), and distributed microservices.
+
+## Installation
+
+```bash
+pip install ./clients/python
+# Or in editable mode:
+pip install -e ./clients/python
+```
+
+## Quick Start
+
+```python
+import asyncio
+from roviers import RoviersBrokerClient
+
+async def main():
+    # 1. Connect to Roviers Broker
+    broker = RoviersBrokerClient(base_url="http://127.0.0.1:8080")
+
+    # 2. Issue or load Agent Token
+    await broker.issue_agent_token(
+        agent_id="AGENT-RESEARCH-01",
+        agent_name="Autonomous Research Agent",
+        save_path="agent_token.json"
+    )
+
+    # 3. Submit heavy asynchronous request (returns in ~2ms with Receipt Token)
+    receipt = await broker.submit(
+        service_name="service.finance.risk_model",
+        payload={"portfolio_id": "port_9921", "simulations": 10000}
+    )
+    print(f"Receipt received: #{receipt.receipt_id} (Status: {receipt.status})")
+
+    # 4. Wait for real-time SSE signal and redeem outcome from Broker Vault
+    outcome = await broker.wait_for_outcome(receipt.receipt_id)
+    print("Vault Outcome:", outcome.result)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## LangGraph / CrewAI Agent Tool Integration
+
+```python
+from roviers import RoviersBrokerClient, RoviersTool
+
+broker = RoviersBrokerClient(base_url="http://127.0.0.1:8080", token="agent_token.json")
+
+# Expose as a non-blocking agent tool
+deep_research_tool = RoviersTool(
+    broker=broker,
+    service_name="service.ai.deep_research",
+    name="deep_research",
+    description="Runs deep multi-source research asynchronously without blocking agent loops"
+)
+```

roviers-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "roviers"
+version = "0.1.0"
+description = "Python client SDK for Roviers: High-Throughput Service Intake & Claim-Check Vault"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+    { name = "Sunil K Sundaram" }
+]
+dependencies = [
+    "httpx>=0.25.0",
+]
+
+[project.scripts]
+roviers = "roviers.cli:main"
+roviers-server = "roviers.installer:run_server"
+
+[project.optional-dependencies]
+agents = [
+    "langchain-core>=0.2.0",
+]
+

roviers-0.1.0/roviers/__init__.py

@@ -0,0 +1,15 @@
+"""
+Roviers Python SDK - Broker & Agent Asynchronous Task & Claim-Check Vault Engine.
+Optimized for Autonomous AI Agents, LLM Orchestrators (LangGraph, CrewAI, AutoGen), and distributed workers.
+"""
+
+from .client import RoviersBrokerClient, RoviersClient, RoviersReceipt, RoviersOutcome, RoviersTool
+
+__all__ = [
+    "RoviersBrokerClient",
+    "RoviersClient",
+    "RoviersReceipt",
+    "RoviersOutcome",
+    "RoviersTool",
+]
+__version__ = "0.1.0"

roviers-0.1.0/roviers/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()
+

roviers-0.1.0/roviers/cli.py

@@ -0,0 +1,28 @@
+"""
+Roviers Python CLI Entrypoints
+"""
+
+import sys
+from .installer import install_roviers, run_server, get_binary_path
+
+
+def main() -> None:
+    if len(sys.argv) > 1 and sys.argv[1] == "install":
+        version = sys.argv[2] if len(sys.argv) > 2 else "latest"
+        install_roviers(version=version)
+    elif len(sys.argv) > 1 and sys.argv[1] == "server":
+        run_server(sys.argv[2:])
+    elif len(sys.argv) > 1 and sys.argv[1] == "which":
+        path = get_binary_path("roviers-server")
+        print(f"roviers-server binary: {path} (exists: {path.is_file()})")
+    else:
+        print("Roviers CLI & Server Manager (Python)")
+        print("\nCommands:")
+        print("  roviers install [version]    Download & install native binaries")
+        print("  roviers server [args...]     Start native roviers-server")
+        print("  roviers which                Display installed binary paths")
+
+
+if __name__ == "__main__":
+    main()
+

roviers-0.1.0/roviers/client.py

@@ -0,0 +1,250 @@
+"""
+Roviers Python Client Library
+Broker & Agent Paradigm for Asynchronous Service Intake & Claim-Check Vault Engine
+"""
+
+from __future__ import annotations
+import asyncio
+import json
+from dataclasses import dataclass
+from typing import Any, AsyncGenerator, Dict, Optional, Union
+import httpx
+
+
+@dataclass
+class RoviersReceipt:
+    receipt_id: str
+    agent_id: str
+    service_name: str
+    issued_at: int
+    status: str
+    estimated_ready_secs: Optional[int] = None
+    callback_url: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> RoviersReceipt:
+        return cls(
+            receipt_id=str(data["receipt_id"]),
+            agent_id=data.get("agent_id") or data.get("citizen_id") or data.get("client_id", ""),
+            service_name=data["service_name"],
+            issued_at=data["issued_at"],
+            status=data["status"],
+            estimated_ready_secs=data.get("estimated_ready_secs"),
+            callback_url=data.get("callback_url"),
+        )
+
+
+@dataclass
+class RoviersOutcome:
+    receipt_id: str
+    agent_id: str
+    service_name: str
+    completed_at: int
+    result: Any
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> RoviersOutcome:
+        return cls(
+            receipt_id=str(data["receipt_id"]),
+            agent_id=data.get("agent_id") or data.get("citizen_id") or data.get("client_id", ""),
+            service_name=data["service_name"],
+            completed_at=data["completed_at"],
+            result=data["result"],
+        )
+
+
+class RoviersBrokerClient:
+    """
+    Client for interacting with Roviers Broker ingress and Outcome Vault.
+    """
+
+    def __init__(
+        self,
+        base_url: str = "http://127.0.0.1:8080",
+        token: Optional[Union[Dict[str, Any], str]] = None,
+        timeout: float = 10.0,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.token_data: Optional[Dict[str, Any]] = None
+
+        if isinstance(token, str):
+            with open(token, "r", encoding="utf-8") as f:
+                self.token_data = json.load(f)
+        elif isinstance(token, dict):
+            self.token_data = token
+
+    @property
+    def agent_id(self) -> str:
+        if not self.token_data:
+            raise ValueError("Agent token has not been loaded or configured.")
+        creds = self.token_data["credentials"]
+        return creds.get("agent_id") or creds.get("citizen_id") or creds.get("client_id", "")
+
+    async def issue_agent_token(
+        self,
+        agent_id: str,
+        agent_name: str = "Autonomous Agent",
+        validity_days: int = 365,
+        save_path: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Requests an official Ed25519-signed agent credential from the Roviers Broker.
+        """
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            resp = await client.post(
+                f"{self.base_url}/api/v1/auth/agent",
+                json={
+                    "agent_id": agent_id,
+                    "agent_name": agent_name,
+                    "validity_days": validity_days,
+                },
+            )
+            resp.raise_for_status()
+            token = resp.json()
+
+        self.token_data = token
+        if save_path:
+            with open(save_path, "w", encoding="utf-8") as f:
+                json.dump(token, f, indent=2)
+
+        return token
+
+    # Backwards compatibility alias
+    issue_token = issue_agent_token
+
+    async def submit(
+        self,
+        service_name: str,
+        payload: Dict[str, Any],
+        callback_url: Optional[str] = None,
+    ) -> RoviersReceipt:
+        """
+        Dispatches a service request to the Broker ingress.
+        Returns a Claim-Check Receipt immediately (HTTP 202 Accepted).
+        """
+        if not self.token_data:
+            raise ValueError("Agent token must be provided before submitting requests.")
+
+        body = {
+            "service_name": service_name,
+            "agent_token": self.token_data,
+            "payload": payload,
+            "callback_url": callback_url,
+        }
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            resp = await client.post(
+                f"{self.base_url}/api/v1/services/{service_name}",
+                json=body,
+            )
+            resp.raise_for_status()
+            return RoviersReceipt.from_dict(resp.json())
+
+    async def get_receipt(self, receipt_id: str) -> RoviersReceipt:
+        """
+        Inspects the current state of a receipt (Queued, Processing, ReadyForPickup, Fulfilled).
+        """
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            resp = await client.get(f"{self.base_url}/api/v1/receipts/{receipt_id}")
+            resp.raise_for_status()
+            return RoviersReceipt.from_dict(resp.json())
+
+    async def pickup(self, receipt_id: str) -> Optional[RoviersOutcome]:
+        """
+        Presents the Receipt ID and cryptographic proof of agent identity to redeem the outcome from the Vault.
+        Returns None if outcome is still being processed (HTTP 202).
+        """
+        if not self.token_data:
+            raise ValueError("Token must be loaded before picking up outcomes.")
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            resp = await client.post(
+                f"{self.base_url}/api/v1/receipts/{receipt_id}/pickup",
+                json={"agent_token": self.token_data},
+            )
+            if resp.status_code == 202:
+                return None
+            resp.raise_for_status()
+            return RoviersOutcome.from_dict(resp.json())
+
+    async def complete(self, receipt_id: str, result: Any) -> None:
+        """
+        Worker capability: deposits a finished execution outcome into the Vault.
+        """
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            resp = await client.post(
+                f"{self.base_url}/api/v1/receipts/{receipt_id}/complete",
+                json={"result": result},
+            )
+            resp.raise_for_status()
+
+    async def listen_signals(
+        self,
+        timeout_secs: Optional[float] = None,
+    ) -> AsyncGenerator[Dict[str, Any], None]:
+        """
+        Subscribes to the real-time Server-Sent Events (SSE) signal stream.
+        Yields completion signals the instant any task for this agent is ready.
+        """
+        aid = self.agent_id
+        url = f"{self.base_url}/api/v1/agents/{aid}/stream"
+
+        timeout = httpx.Timeout(timeout_secs if timeout_secs else None, connect=10.0)
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            async with client.stream("GET", url) as stream:
+                async for line in stream.aiter_lines():
+                    if line.startswith("data:"):
+                        raw = line[5:].strip()
+                        if raw:
+                            yield json.loads(raw)
+
+    async def wait_for_outcome(
+        self,
+        receipt_id: str,
+        timeout_secs: float = 60.0,
+    ) -> RoviersOutcome:
+        """
+        High-level helper: waits for the specific receipt outcome using zero-polling SSE signals,
+        then automatically redeems and returns the outcome from the Broker Vault.
+        """
+        # First check if it's already ready
+        immediate = await self.pickup(receipt_id)
+        if immediate is not None:
+            return immediate
+
+        loop = asyncio.get_running_loop()
+        end_time = loop.time() + timeout_secs
+
+        async for signal in self.listen_signals(timeout_secs=timeout_secs):
+            if signal.get("receipt_id") == receipt_id:
+                outcome = await self.pickup(receipt_id)
+                if outcome is not None:
+                    return outcome
+
+            if loop.time() > end_time:
+                break
+
+        raise TimeoutError(f"Timed out waiting for receipt #{receipt_id} outcome.")
+
+
+# Backwards compatibility alias
+RoviersClient = RoviersBrokerClient
+
+
+class RoviersTool:
+    """
+    Adapter for AI Agent Frameworks (LangGraph, CrewAI, AutoGen).
+    Wraps heavy tasks into non-blocking claim-check operations.
+    """
+
+    def __init__(self, broker: RoviersBrokerClient, service_name: str, name: str, description: str):
+        self.broker = broker
+        self.service_name = service_name
+        self.name = name
+        self.description = description
+
+    async def run(self, **kwargs) -> Any:
+        receipt = await self.broker.submit(self.service_name, kwargs)
+        outcome = await self.broker.wait_for_outcome(receipt.receipt_id)
+        return outcome.result

roviers-0.1.0/roviers/installer.py

@@ -0,0 +1,115 @@
+"""
+Roviers Native Binary Installer & Runner
+Enables `pip install roviers` to download, manage, and launch native `roviers-server` and `roviers-cli` binaries.
+"""
+
+from __future__ import annotations
+import os
+import platform
+import shutil
+import subprocess
+import sys
+import urllib.request
+from pathlib import Path
+
+GITHUB_REPO = "sunilksundaram/roviers"
+DEFAULT_INSTALL_DIR = Path.home() / ".roviers" / "bin"
+
+
+def get_platform_asset_name() -> str:
+    system = platform.system().lower()
+    machine = platform.machine().lower()
+
+    if "windows" in system:
+        return "roviers-windows-x86_64.zip"
+    elif "darwin" in system:
+        if "arm" in machine or "aarch64" in machine:
+            return "roviers-macos-aarch64.tar.gz"
+        return "roviers-macos-x86_64.tar.gz"
+    elif "linux" in system:
+        if "arm" in machine or "aarch64" in machine:
+            return "roviers-linux-aarch64.tar.gz"
+        return "roviers-linux-x86_64.tar.gz"
+    else:
+        raise RuntimeError(f"Unsupported operating system: {system} {machine}")
+
+
+def get_binary_path(name: str = "roviers-server") -> Path:
+    ext = ".exe" if platform.system().lower() == "windows" else ""
+    binary_name = f"{name}{ext}"
+
+    # 1. Check system PATH
+    which_path = shutil.which(binary_name)
+    if which_path:
+        return Path(which_path)
+
+    # 2. Check ~/.roviers/bin
+    local_path = DEFAULT_INSTALL_DIR / binary_name
+    if local_path.is_file() and os.access(local_path, os.X_OK):
+        return local_path
+
+    # 3. Check workspace target/release (if local repo build)
+    target_path = Path.cwd() / "target" / "release" / binary_name
+    if target_path.is_file():
+        return target_path
+
+    return local_path
+
+
+def install_roviers(version: str = "latest", dest_dir: Path = DEFAULT_INSTALL_DIR) -> Path:
+    """
+    Installs the native roviers-server and roviers-cli binaries into ~/.roviers/bin
+    """
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    asset_name = get_platform_asset_name()
+
+    if version == "latest":
+        url = f"https://github.com/{GITHUB_REPO}/releases/latest/download/{asset_name}"
+    else:
+        url = f"https://github.com/{GITHUB_REPO}/releases/download/{version}/{asset_name}"
+
+    archive_path = dest_dir / asset_name
+    print(f"📦 Downloading Roviers native binaries from {url}...")
+    try:
+        urllib.request.urlretrieve(url, archive_path)
+    except Exception as e:
+        print(f"⚠️ Could not download pre-built binary: {e}")
+        # Try cargo install as fallback
+        if shutil.which("cargo"):
+            print("🔨 Found cargo! Building and installing via cargo...")
+            subprocess.check_call(["cargo", "install", "--git", f"https://github.com/{GITHUB_REPO}.git", "roviers-server", "roviers-cli"])
+            print("✅ Successfully built and installed via cargo!")
+            return get_binary_path("roviers-server")
+        raise RuntimeError(f"Failed to install native binaries: {e}")
+
+    # Extract archive
+    print(f"📂 Extracting {archive_path.name} to {dest_dir}...")
+    shutil.unpack_archive(archive_path, dest_dir)
+    archive_path.unlink(missing_ok=True)
+
+    # Ensure executable permissions on Unix
+    for binary_name in ["roviers-server", "roviers-cli"]:
+        p = dest_dir / binary_name
+        if p.exists():
+            p.chmod(0o755)
+
+    print(f"✅ Roviers successfully installed to {dest_dir}")
+    print(f"💡 Add {dest_dir} to your PATH to run `roviers-server` directly.")
+    return get_binary_path("roviers-server")
+
+
+def run_server(args: list[str] | None = None) -> None:
+    """
+    Launches the native `roviers-server` binary, installing it first if missing.
+    """
+    binary = get_binary_path("roviers-server")
+    if not binary.is_file():
+        print("🔍 roviers-server binary not found locally.")
+        binary = install_roviers()
+
+    cmd = [str(binary)] + (args or sys.argv[1:])
+    try:
+        subprocess.run(cmd)
+    except KeyboardInterrupt:
+        pass
+