5dive 0.1.0__py3-none-any.whl

5dive-0.1.0.dist-info/METADATA

@@ -0,0 +1,95 @@
+Metadata-Version: 2.5
+Name: 5dive
+Version: 0.1.0
+Summary: Python client for the 5dive CLI — read the task queue, agents and org chart of a 5dive box.
+Project-URL: Homepage, https://5dive.ai
+Project-URL: Source, https://github.com/5dive-ai/5dive
+Project-URL: Issues, https://github.com/5dive-ai/5dive/issues
+Author: 5dive
+License: MIT
+License-File: LICENSE
+Keywords: 5dive,agents,automation,cli,multi-agent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# 5dive
+
+Python client for the [5dive](https://5dive.ai) CLI — read the task queue, agent
+seats and org chart of a 5dive box from Python.
+
+5dive runs a team of AI coding agents on your own machine. State lives on that
+box and the CLI is the interface with a stable contract over it, so this package
+is a thin, dependency-free wrapper over `5dive <verb> --json` rather than an HTTP
+client.
+
+## Install
+
+```bash
+pip install 5dive
+```
+
+The distribution is named `5dive`; the import name is `fivedive`, because a
+Python identifier cannot begin with a digit.
+
+## Use
+
+```python
+from fivedive import FiveDive
+
+fd = FiveDive()
+
+for t in fd.tasks("--status=todo"):
+    print(t["ident"], t["assignee"], t["title"])
+
+print(fd.task("DIVE-3903")["status"])
+
+for a in fd.agents():
+    print(a["name"], a["active"])
+```
+
+Anything the CLI can answer in JSON is reachable, whether or not this package
+has a named helper for it:
+
+```python
+fd.raw("org", "tree")
+fd.raw("task", "ls", "--assignee=main")
+```
+
+## Errors are raised, not returned
+
+Every `--json` verb answers in one envelope:
+
+```json
+{"ok": true,  "data": {...}}
+{"ok": false, "error": {"code": 4, "class": "not_found", "message": "no such task: NOPE-1"}}
+```
+
+An unchecked `ok` is the bug this package exists to prevent, so the false branch
+raises instead of handing back a dict you have to remember to test:
+
+```python
+from fivedive import FiveDive, FiveDiveError, CliNotFound
+
+try:
+    fd.task("NOPE-1")
+except FiveDiveError as e:
+    print(e.err_class, e.code, e)   # not_found 4 no such task: NOPE-1
+```
+
+Branch on `err_class`, not on message text — the class is the stable contract.
+`CliNotFound` is raised when the `5dive` binary is not on `PATH`.
+
+## Requirements
+
+Python 3.9+, no third-party dependencies, and a 5dive box with the CLI
+installed. Get the CLI at [5dive.ai](https://5dive.ai) or
+[github.com/5dive-ai/5dive](https://github.com/5dive-ai/5dive).
+
+## Licence
+
+MIT.

5dive-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+fivedive/__init__.py,sha256=TgyYOkwsX4um9RRjNFnPAqkRgkMnMVixqiFS9bKmGdA,408
+fivedive/client.py,sha256=IBmFhrgbkJqarBfB-LCGyglYdJZBnsJBP-8HbPsxHTE,4829
+5dive-0.1.0.dist-info/METADATA,sha256=jr5prAYjjsm2eRYq7PPn8n85YG8zlxPHjdGMSW4MUlI,2648
+5dive-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+5dive-0.1.0.dist-info/licenses/LICENSE,sha256=TOFzH6yOF3dLJJDk_P5xWlCy-5-MhO0WzA-cXO07ARg,1062
+5dive-0.1.0.dist-info/RECORD,,

5dive-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

5dive-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 5dive
+
+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.

fivedive/__init__.py

@@ -0,0 +1,14 @@
+"""Python client for the 5dive CLI.
+
+The distribution is named ``5dive``; the import name is ``fivedive`` because a
+Python identifier cannot begin with a digit.
+
+    from fivedive import FiveDive
+    for t in FiveDive().tasks():
+        print(t["ident"], t["status"])
+"""
+
+from .client import FiveDive, FiveDiveError, CliNotFound
+
+__all__ = ["FiveDive", "FiveDiveError", "CliNotFound"]
+__version__ = "0.1.0"

fivedive/client.py

@@ -0,0 +1,120 @@
+"""A thin, dependency-free wrapper over the local ``5dive`` CLI's JSON mode.
+
+WHY THIS IS A WRAPPER AND NOT AN HTTP CLIENT: 5dive's state lives on the box the
+agents run on, and the CLI is the only interface with a stable contract over it.
+Every ``--json`` verb answers in one envelope::
+
+    {"ok": true,  "data": {...}}
+    {"ok": false, "error": {"code": 4, "class": "not_found", "message": "..."}}
+
+so the whole job of this module is to run the binary, parse that envelope, and
+raise on the false branch instead of handing back a dict the caller has to
+remember to check. An unchecked ``ok`` is the bug this exists to prevent.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from typing import Any, Dict, List, Optional, Sequence
+
+
+class FiveDiveError(RuntimeError):
+    """The CLI answered with ``ok: false``.
+
+    Carries the machine-readable fields so callers can branch on ``err_class``
+    rather than matching on message text, which is not a stable contract.
+    """
+
+    def __init__(self, message: str, code: Optional[int] = None, err_class: Optional[str] = None):
+        super().__init__(message)
+        self.code = code
+        self.err_class = err_class
+
+
+class CliNotFound(FiveDiveError):
+    """The ``5dive`` binary is not on PATH."""
+
+
+class FiveDive:
+    """Run 5dive CLI verbs and return parsed JSON.
+
+    :param binary: path to the CLI, if it is not simply ``5dive`` on PATH.
+    :param timeout: seconds before a call is abandoned. ``None`` waits forever,
+        which is rarely what you want from a library.
+    """
+
+    def __init__(self, binary: str = "5dive", timeout: Optional[float] = 30.0):
+        self.binary = binary
+        self.timeout = timeout
+
+    # -- the one place a subprocess is run -------------------------------
+    def raw(self, *args: str) -> Any:
+        """Run ``5dive <args> --json`` and return the ``data`` payload.
+
+        ``--json`` is appended only when the caller has not already passed it,
+        so ``raw("task", "ls", "--json")`` and ``raw("task", "ls")`` agree.
+        """
+        argv: List[str] = [self.binary, *args]
+        if "--json" not in argv:
+            argv.append("--json")
+
+        if shutil.which(self.binary) is None and "/" not in self.binary:
+            raise CliNotFound(f"{self.binary!r} is not on PATH — is this a 5dive box?")
+
+        try:
+            proc = subprocess.run(argv, capture_output=True, text=True, timeout=self.timeout)
+        except FileNotFoundError as exc:  # binary named by path, but absent
+            raise CliNotFound(f"cannot execute {self.binary!r}: {exc}") from exc
+        except subprocess.TimeoutExpired as exc:
+            raise FiveDiveError(f"{' '.join(argv)} timed out after {self.timeout}s") from exc
+
+        # A non-zero exit still carries a JSON envelope on the error path, so
+        # parse BEFORE judging the status: the envelope's message is better than
+        # "exited 4", and falling back to stderr only when there is no envelope
+        # keeps a genuine crash legible instead of masking it as a parse error.
+        payload = None
+        if proc.stdout.strip():
+            try:
+                payload = json.loads(proc.stdout)
+            except json.JSONDecodeError:
+                payload = None
+
+        if payload is None:
+            detail = (proc.stderr or proc.stdout or "").strip() or f"exited {proc.returncode}"
+            raise FiveDiveError(f"{' '.join(argv)}: no JSON envelope — {detail}")
+
+        if not payload.get("ok", False):
+            err = payload.get("error") or {}
+            raise FiveDiveError(
+                err.get("message", "unknown error"),
+                code=err.get("code"),
+                err_class=err.get("class"),
+            )
+        return payload.get("data")
+
+    # -- convenience readers ---------------------------------------------
+    def tasks(self, *flags: str) -> List[Dict[str, Any]]:
+        """The task queue. Extra flags pass straight through, e.g.
+        ``tasks("--status=todo", "--assignee=main")``."""
+        data = self.raw("task", "ls", *flags) or {}
+        return data.get("tasks", [])
+
+    def task(self, ident: str) -> Dict[str, Any]:
+        """One task by ident, e.g. ``task("DIVE-3903")``."""
+        return self.raw("task", "show", ident) or {}
+
+    def agents(self, *flags: str) -> List[Dict[str, Any]]:
+        """The agent seats on this box."""
+        data = self.raw("agent", "list", *flags)
+        if isinstance(data, list):
+            return data
+        return (data or {}).get("agents", [])
+
+    def version(self) -> str:
+        """The CLI's version string (does not use the JSON envelope)."""
+        proc = subprocess.run(
+            [self.binary, "--version"], capture_output=True, text=True, timeout=self.timeout
+        )
+        return proc.stdout.strip()