plures 1.0.0__tar.gz

plures-1.0.0/.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+__pycache__/
+*.egg-info/
+.venv/
+mcp/package-lock.json

plures-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Plures Labs LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

plures-1.0.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.5
+Name: plures
+Version: 1.0.0
+Summary: Human judgment as an API for AI agents. Send a decision to ID verified people and get their consensus back.
+Project-URL: Homepage, https://plures.si/developers
+Project-URL: Documentation, https://plures.si/docs
+Project-URL: Source, https://github.com/plureslabs/plures
+Author-email: Plures Labs LLC <hello@plures.si>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai-agents,hitl,human-approval,human-in-the-loop,human-review,llm,plures
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# plures
+
+The official Python client for [Plures](https://plures.si): human judgment as an API for AI agents. Send a decision to ID verified people and get their consensus back before your agent acts. A human in the loop step you can call like any other API.
+
+```bash
+pip install plures
+```
+
+Python 3.8+, standard library only.
+
+## Use it
+
+```python
+from plures import Plures
+
+plures = Plures()  # reads PLURES_API_KEY, or Plures("pk_test_...")
+
+task = plures.verify(
+    "Does the invoice match the order?",
+    ["Matches", "Does not match"],
+    context="Order: 48 chairs, $4,218. Invoice: 48 chairs plus $180 freight, $4,398.",
+    verifiers=3,
+)
+result = task["result"]
+if result and result["agreement"] == 1:
+    print("Act on:", result["answer"])
+else:
+    print("Not unanimous: send to the team")
+```
+
+Get a free test key at [plures.si](https://plures.si/?for=developers#join). Test keys complete at once with the first option (or `metadata["test_answer"]`) and never reach real people.
+
+## Production: webhooks
+
+```python
+plures.create_task(
+    "Should this customer get a refund?", ["Approve", "Decline"],
+    context=ticket_text, webhook_url="https://your.app/plures",
+    metadata={"order_id": order_id}, idempotency_key="refund-%s" % order_id,
+)
+
+# In your webhook handler (Flask shown), pass the raw body exactly as received
+from plures import verify_webhook
+event = verify_webhook(request.get_data(), request.headers.get("Plures-Signature"), WEBHOOK_SECRET)
+```
+
+## API
+
+- `create_task(question, options, idempotency_key=None, **fields)`: fields are `context`, `image_url`, `instructions`, `verifiers` (1, 3, 5, 7 or 9), `max_verifiers`, `presence_check` (default True), `webhook_url`, `metadata`, `expires_in`
+- `get_task(id)`, `list_tasks(status=None, limit=None, starting_after=None)`, `cancel_task(id)`
+- `wait_for(id, timeout=600, interval=3)`: poll until settled
+- `verify(question, options, timeout=600, **fields)`: create and wait
+- `verify_webhook(raw_body, signature_header, secret)`: check a webhook and return the event
+
+Errors raise `PluresError` with `.status` and `.type`. Server errors are retried twice.
+
+Examples for LangGraph and the OpenAI Agents SDK: [github.com/plureslabs/plures](https://github.com/plureslabs/plures/tree/main/examples). Full reference: [plures.si/docs](https://plures.si/docs).

plures-1.0.0/README.md

@@ -0,0 +1,57 @@
+# plures
+
+The official Python client for [Plures](https://plures.si): human judgment as an API for AI agents. Send a decision to ID verified people and get their consensus back before your agent acts. A human in the loop step you can call like any other API.
+
+```bash
+pip install plures
+```
+
+Python 3.8+, standard library only.
+
+## Use it
+
+```python
+from plures import Plures
+
+plures = Plures()  # reads PLURES_API_KEY, or Plures("pk_test_...")
+
+task = plures.verify(
+    "Does the invoice match the order?",
+    ["Matches", "Does not match"],
+    context="Order: 48 chairs, $4,218. Invoice: 48 chairs plus $180 freight, $4,398.",
+    verifiers=3,
+)
+result = task["result"]
+if result and result["agreement"] == 1:
+    print("Act on:", result["answer"])
+else:
+    print("Not unanimous: send to the team")
+```
+
+Get a free test key at [plures.si](https://plures.si/?for=developers#join). Test keys complete at once with the first option (or `metadata["test_answer"]`) and never reach real people.
+
+## Production: webhooks
+
+```python
+plures.create_task(
+    "Should this customer get a refund?", ["Approve", "Decline"],
+    context=ticket_text, webhook_url="https://your.app/plures",
+    metadata={"order_id": order_id}, idempotency_key="refund-%s" % order_id,
+)
+
+# In your webhook handler (Flask shown), pass the raw body exactly as received
+from plures import verify_webhook
+event = verify_webhook(request.get_data(), request.headers.get("Plures-Signature"), WEBHOOK_SECRET)
+```
+
+## API
+
+- `create_task(question, options, idempotency_key=None, **fields)`: fields are `context`, `image_url`, `instructions`, `verifiers` (1, 3, 5, 7 or 9), `max_verifiers`, `presence_check` (default True), `webhook_url`, `metadata`, `expires_in`
+- `get_task(id)`, `list_tasks(status=None, limit=None, starting_after=None)`, `cancel_task(id)`
+- `wait_for(id, timeout=600, interval=3)`: poll until settled
+- `verify(question, options, timeout=600, **fields)`: create and wait
+- `verify_webhook(raw_body, signature_header, secret)`: check a webhook and return the event
+
+Errors raise `PluresError` with `.status` and `.type`. Server errors are retried twice.
+
+Examples for LangGraph and the OpenAI Agents SDK: [github.com/plureslabs/plures](https://github.com/plureslabs/plures/tree/main/examples). Full reference: [plures.si/docs](https://plures.si/docs).

plures-1.0.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "plures"
+version = "1.0.0"
+description = "Human judgment as an API for AI agents. Send a decision to ID verified people and get their consensus back."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.8"
+authors = [{ name = "Plures Labs LLC", email = "hello@plures.si" }]
+keywords = ["human-in-the-loop", "hitl", "ai-agents", "human-review", "human-approval", "llm", "agents", "plures"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Intended Audience :: Developers",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://plures.si/developers"
+Documentation = "https://plures.si/docs"
+Source = "https://github.com/plureslabs/plures"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/plures"]

plures-1.0.0/src/plures/__init__.py

@@ -0,0 +1,110 @@
+"""Plures: human judgment as an API for AI agents.
+
+Send a decision to ID verified people and get their consensus back.
+Python 3.8+, standard library only. Docs: https://plures.si/docs
+"""
+import hashlib
+import hmac
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+__version__ = "1.0.0"
+__all__ = ["Plures", "PluresError", "verify_webhook", "__version__"]
+
+
+class PluresError(Exception):
+    def __init__(self, message, status, type_):
+        super().__init__(message)
+        self.status = status
+        self.type = type_
+
+
+class Plures:
+    def __init__(self, api_key=None, base_url=None, timeout=30):
+        api_key = api_key or os.environ.get("PLURES_API_KEY")
+        if not api_key:
+            raise ValueError("Pass your Plures API key, or set PLURES_API_KEY. Get a free test key at https://plures.si/?for=developers#join")
+        base_url = base_url or os.environ.get("PLURES_BASE_URL") or "https://plures.si"
+        self.api_key = api_key
+        self.base = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def _req(self, method, path, body=None, headers=None):
+        data = json.dumps(body).encode() if body is not None else None
+        h = {"authorization": "Bearer " + self.api_key, "user-agent": "plures-python/" + __version__}
+        if data is not None:
+            h["content-type"] = "application/json"
+        h.update(headers or {})
+        for attempt in range(3):
+            req = urllib.request.Request(self.base + path, data=data, method=method, headers=h)
+            try:
+                with urllib.request.urlopen(req, timeout=self.timeout) as r:
+                    return json.loads(r.read() or b"{}")
+            except urllib.error.HTTPError as e:
+                if e.code >= 500 and attempt < 2:
+                    time.sleep(0.5 * 2 ** attempt)
+                    continue
+                try:
+                    err = json.loads(e.read()).get("error", {})
+                except Exception:
+                    err = {}
+                raise PluresError(err.get("message", "HTTP %d" % e.code), e.code, err.get("type", "api_error"))
+
+    def create_task(self, question, options, idempotency_key=None, **fields):
+        """Sends a question to verified people.
+
+        fields: context, image_url, instructions, verifiers (odd, 1 to 9), max_verifiers,
+        presence_check (default True), webhook_url, metadata, expires_in (seconds).
+        """
+        body = dict(fields, question=question, options=options)
+        headers = {"idempotency-key": idempotency_key} if idempotency_key else None
+        return self._req("POST", "/api/v1/tasks", body, headers)
+
+    def get_task(self, task_id):
+        return self._req("GET", "/api/v1/tasks/" + urllib.parse.quote(task_id))
+
+    def list_tasks(self, status=None, limit=None, starting_after=None):
+        q = {k: v for k, v in {"status": status, "limit": limit, "starting_after": starting_after}.items() if v is not None}
+        return self._req("GET", "/api/v1/tasks" + ("?" + urllib.parse.urlencode(q) if q else ""))
+
+    def cancel_task(self, task_id):
+        return self._req("POST", "/api/v1/tasks/" + urllib.parse.quote(task_id) + "/cancel")
+
+    def wait_for(self, task_id, timeout=600, interval=3):
+        """Polls until the task is settled. Prefer webhooks in production."""
+        end = time.time() + timeout
+        while True:
+            t = self.get_task(task_id)
+            if t["status"] != "pending" or time.time() > end:
+                return t
+            time.sleep(interval)
+
+    def verify(self, question, options, timeout=600, idempotency_key=None, **fields):
+        """Creates a task and waits for people to answer it."""
+        t = self.create_task(question, options, idempotency_key=idempotency_key, **fields)
+        return t if t["status"] != "pending" else self.wait_for(t["id"], timeout=timeout)
+
+
+def verify_webhook(raw_body, signature_header, secret, tolerance=300):
+    """Checks the Plures-Signature header and returns the parsed event.
+
+    raw_body must be the exact bytes or string received. Raises ValueError if invalid.
+    """
+    if isinstance(raw_body, bytes):
+        raw_body = raw_body.decode()
+    parts = dict(p.split("=", 1) for p in (signature_header or "").split(",") if "=" in p)
+    try:
+        t = int(parts["t"])
+        v1 = parts["v1"]
+    except (KeyError, ValueError):
+        raise ValueError("Missing Plures-Signature header")
+    if abs(time.time() - t) > tolerance:
+        raise ValueError("Webhook timestamp is too old")
+    expected = hmac.new(secret.encode(), ("%d.%s" % (t, raw_body)).encode(), hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(expected, v1):
+        raise ValueError("Webhook signature does not match")
+    return json.loads(raw_body)