rugbe-client 0.1.0__tar.gz

rugbe_client-0.1.0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.3
+Name: rugbe-client
+Version: 0.1.0
+Summary: Typed HTTP + SSE client (sync and async) for rugbe-agent-runtime
+Requires-Dist: httpx>=0.27,<1.0
+Requires-Dist: pydantic>=2.6,<3.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# rugbe-client (Python)
+
+Typed HTTP + SSE client for rugbe-agent-runtime, sync and async. Backend subset of
+`@bhanux/rugbe-client`: workflows, runs (streaming), sessions, files, skills, models,
+me, node types, health.
+
+```python
+from rugbe_client import RuntimeClient
+
+with RuntimeClient(
+    "https://runtime.example.com",
+    get_auth_headers=lambda: {"Authorization": f"Bearer {key}"},
+    on_auth_error=lambda: refresh_key(),  # optional: called once on 401
+) as rt:
+    session = rt.sessions.create(subject="user-42")
+    for event in rt.runs.stream(session.workflow_id, input={"message": "hi"}, view="chat"):
+        if event.type == "text":
+            print(event.content, end="")
+```
+
+`AsyncRuntimeClient` has the same surface with `async`/`await` (`async for` on
+`runs.stream`); its credential hooks may be coroutines.
+
+- Errors: every non-2xx raises `RuntimeApiError` (`status`, `kind`, `issues`, `detail`).
+  `to_draft_conflict(err)` reads a lost-update 409 on `workflows.save_draft`.
+- Only **401** triggers `on_auth_error`, once; a refreshed credential that is refused
+  again surfaces. 403 is never retried.
+- Unknown stream event types arrive as `UnknownEvent` instead of raising.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check . --fix && uv run ruff format src tests
+```
+
+`tests/test_conformance.py` compares model fields to
+`packages/rugbe-client/openapi.json` (refresh with `bun run generate-types` there).

rugbe_client-0.1.0/README.md

@@ -0,0 +1,39 @@
+# rugbe-client (Python)
+
+Typed HTTP + SSE client for rugbe-agent-runtime, sync and async. Backend subset of
+`@bhanux/rugbe-client`: workflows, runs (streaming), sessions, files, skills, models,
+me, node types, health.
+
+```python
+from rugbe_client import RuntimeClient
+
+with RuntimeClient(
+    "https://runtime.example.com",
+    get_auth_headers=lambda: {"Authorization": f"Bearer {key}"},
+    on_auth_error=lambda: refresh_key(),  # optional: called once on 401
+) as rt:
+    session = rt.sessions.create(subject="user-42")
+    for event in rt.runs.stream(session.workflow_id, input={"message": "hi"}, view="chat"):
+        if event.type == "text":
+            print(event.content, end="")
+```
+
+`AsyncRuntimeClient` has the same surface with `async`/`await` (`async for` on
+`runs.stream`); its credential hooks may be coroutines.
+
+- Errors: every non-2xx raises `RuntimeApiError` (`status`, `kind`, `issues`, `detail`).
+  `to_draft_conflict(err)` reads a lost-update 409 on `workflows.save_draft`.
+- Only **401** triggers `on_auth_error`, once; a refreshed credential that is refused
+  again surfaces. 403 is never retried.
+- Unknown stream event types arrive as `UnknownEvent` instead of raising.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check . --fix && uv run ruff format src tests
+```
+
+`tests/test_conformance.py` compares model fields to
+`packages/rugbe-client/openapi.json` (refresh with `bun run generate-types` there).

rugbe_client-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "rugbe-client"
+version = "0.1.0"
+description = "Typed HTTP + SSE client (sync and async) for rugbe-agent-runtime"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.27,<1.0",
+    "pydantic>=2.6,<3.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "respx>=0.21",
+    "ruff>=0.6",
+]
+
+[build-system]
+requires = ["uv_build>=0.8.14,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 88
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

rugbe_client-0.1.0/src/rugbe_client/__init__.py

@@ -0,0 +1,50 @@
+"""Typed HTTP + SSE client (sync and async) for rugbe-agent-runtime."""
+
+from .client import AsyncRuntimeClient, RuntimeClient
+from .errors import (
+    DraftConflict,
+    RuntimeApiError,
+    ValidationIssue,
+    to_draft_conflict,
+)
+from .events import RunStreamEvent, UnknownEvent, parse_event
+from .models import (
+    Me,
+    ModelOption,
+    RunOut,
+    RunStatus,
+    RunStepOut,
+    RunSummary,
+    SessionOut,
+    Skill,
+    ValidationResult,
+    WorkflowFile,
+    WorkflowGraph,
+    WorkflowOut,
+    WorkflowSummary,
+)
+
+__all__ = [
+    "AsyncRuntimeClient",
+    "DraftConflict",
+    "Me",
+    "ModelOption",
+    "RunOut",
+    "RunStatus",
+    "RunStepOut",
+    "RunStreamEvent",
+    "RunSummary",
+    "RuntimeApiError",
+    "RuntimeClient",
+    "SessionOut",
+    "Skill",
+    "UnknownEvent",
+    "ValidationIssue",
+    "ValidationResult",
+    "WorkflowFile",
+    "WorkflowGraph",
+    "WorkflowOut",
+    "WorkflowSummary",
+    "parse_event",
+    "to_draft_conflict",
+]

rugbe_client-0.1.0/src/rugbe_client/_calls.py

@@ -0,0 +1,408 @@
+"""Every endpoint as a :class:`Call` builder, shared by the sync and async clients.
+
+Keeping the path/body/parse knowledge here means the two clients are two-line
+wrappers that cannot drift from each other.
+"""
+
+from __future__ import annotations
+
+import mimetypes
+import os
+from typing import Any, BinaryIO
+from urllib.parse import quote
+
+from pydantic import BaseModel, TypeAdapter
+
+from ._transport import Call
+from .models import (
+    ElicitationReceipt,
+    Me,
+    ModelOption,
+    RunOut,
+    RunReceipt,
+    RunStepOut,
+    RunSummary,
+    RuntimeReadiness,
+    SessionOut,
+    Skill,
+    SkillFile,
+    SkillUpload,
+    ValidationResult,
+    WorkflowFile,
+    WorkflowGraph,
+    WorkflowOut,
+    WorkflowSummary,
+)
+
+FileInput = str | os.PathLike[str] | bytes | BinaryIO
+
+
+def _model(cls: type[BaseModel]) -> Any:
+    return cls.model_validate
+
+
+def _list(cls: type[BaseModel]) -> Any:
+    adapter = TypeAdapter(list[cls])  # type: ignore[valid-type]
+    return adapter.validate_python
+
+
+def _dump(value: BaseModel | dict[str, Any]) -> dict[str, Any]:
+    if isinstance(value, BaseModel):
+        return value.model_dump(mode="json", exclude_none=True)
+    return value
+
+
+def _seg(value: str) -> str:
+    return quote(value, safe="")
+
+
+def _upload(file: FileInput, name: str | None) -> tuple[str, Any, str]:
+    if isinstance(file, (str, os.PathLike)):
+        path = os.fspath(file)
+        with open(path, "rb") as fh:
+            content = fh.read()
+        name = name or os.path.basename(path)
+    elif isinstance(file, bytes):
+        content = file
+        if name is None:
+            raise ValueError("name is required when uploading raw bytes")
+    else:
+        content = file.read()
+        name = name or os.path.basename(getattr(file, "name", "") or "") or None
+        if name is None:
+            raise ValueError("name is required for a file object without a name")
+    mime = mimetypes.guess_type(name)[0] or "application/octet-stream"
+    return name, content, mime
+
+
+# -- workflows ---------------------------------------------------------------
+
+
+def workflows_list() -> Call:
+    return Call("GET", "/v1/workflows", parse=_list(WorkflowSummary))
+
+
+def workflows_get(workflow_id: str) -> Call:
+    return Call("GET", f"/v1/workflows/{_seg(workflow_id)}", parse=_model(WorkflowOut))
+
+
+def workflows_create(
+    name: str | None, description: str | None, graph: WorkflowGraph | None
+) -> Call:
+    body: dict[str, Any] = {}
+    if name is not None:
+        body["name"] = name
+    if description is not None:
+        body["description"] = description
+    if graph is not None:
+        body["graph"] = _dump(graph)
+    return Call("POST", "/v1/workflows", body=body, parse=_model(WorkflowOut))
+
+
+def workflows_update(
+    workflow_id: str, name: str | None, description: str | None
+) -> Call:
+    body = {
+        k: v
+        for k, v in {"name": name, "description": description}.items()
+        if v is not None
+    }
+    return Call(
+        "PATCH",
+        f"/v1/workflows/{_seg(workflow_id)}",
+        body=body,
+        parse=_model(WorkflowOut),
+    )
+
+
+def workflows_delete(workflow_id: str) -> Call:
+    return Call("DELETE", f"/v1/workflows/{_seg(workflow_id)}")
+
+
+def workflows_save_draft(workflow_id: str, graph: WorkflowGraph, if_match: int) -> Call:
+    return Call(
+        "PUT",
+        f"/v1/workflows/{_seg(workflow_id)}/draft",
+        body={"graph": _dump(graph)},
+        headers={"If-Match": str(if_match)},
+        parse=_model(WorkflowOut),
+    )
+
+
+def workflows_validate(workflow_id: str, graph: WorkflowGraph) -> Call:
+    return Call(
+        "POST",
+        f"/v1/workflows/{_seg(workflow_id)}/validate",
+        body={"graph": _dump(graph)},
+        parse=_model(ValidationResult),
+    )
+
+
+def workflows_publish(workflow_id: str) -> Call:
+    return Call(
+        "POST", f"/v1/workflows/{_seg(workflow_id)}/publish", parse=_model(WorkflowOut)
+    )
+
+
+def workflows_contract(workflow_id: str) -> Call:
+    return Call("GET", f"/v1/workflows/{_seg(workflow_id)}/contract")
+
+
+def workflows_transcript(workflow_id: str, thread_id: str) -> Call:
+    return Call(
+        "GET",
+        f"/v1/workflows/{_seg(workflow_id)}/threads/{_seg(thread_id)}/transcript",
+    )
+
+
+def workflows_publish_event(
+    workflow_id: str,
+    event_type: str,
+    data: Any = None,
+    *,
+    id: str | None = None,
+    subject: str | None = None,
+    draft: bool = False,
+) -> Call:
+    body: dict[str, Any] = {"event_type": event_type, "draft": draft}
+    if data is not None:
+        body["data"] = data
+    if id is not None:
+        body["id"] = id
+    if subject is not None:
+        body["subject"] = subject
+    return Call("POST", f"/v1/workflows/{_seg(workflow_id)}/events", body=body)
+
+
+# -- runs --------------------------------------------------------------------
+
+
+def runs_stream_path(workflow_id: str) -> str:
+    return f"/v1/workflows/{_seg(workflow_id)}/runs"
+
+
+def runs_body(
+    *,
+    input: dict[str, Any] | None = None,
+    params: dict[str, Any] | None = None,
+    answers: dict[str, Any] | None = None,
+    approvals: list[dict[str, Any]] | None = None,
+    surface_action: dict[str, Any] | None = None,
+    thread_id: str | None = None,
+    turn_id: str | None = None,
+    globals: dict[str, Any] | None = None,
+    view: str | None = None,
+) -> dict[str, Any]:
+    fields = {
+        "input": input,
+        "params": params,
+        "answers": answers,
+        "approvals": approvals,
+        "surface_action": surface_action,
+        "thread_id": thread_id,
+        "turn_id": turn_id,
+        "globals": globals,
+        "view": view,
+    }
+    return {k: v for k, v in fields.items() if v is not None}
+
+
+def runs_answer_elicitation(
+    workflow_id: str, elicitation_id: str, action: str, content: Any, thread_id: str
+) -> Call:
+    return Call(
+        "POST",
+        f"/v1/workflows/{_seg(workflow_id)}/elicitations/{_seg(elicitation_id)}",
+        body={"action": action, "content": content, "thread_id": thread_id},
+        parse=_model(ElicitationReceipt),
+    )
+
+
+def runs_trigger(workflow_id: str, params: dict[str, Any] | None) -> Call:
+    return Call(
+        "POST",
+        f"/v1/workflows/{_seg(workflow_id)}/trigger",
+        body={"params": params or {}},
+        parse=_model(RunReceipt),
+    )
+
+
+def _run_query(
+    limit: int | None, status: str | None, before: str | None
+) -> dict[str, Any]:
+    return {"limit": limit, "status": status, "before": before}
+
+
+def runs_list(
+    workflow_id: str, limit: int | None, status: str | None, before: str | None
+) -> Call:
+    return Call(
+        "GET",
+        f"/v1/workflows/{_seg(workflow_id)}/runs",
+        params=_run_query(limit, status, before),
+        parse=_list(RunSummary),
+    )
+
+
+def runs_get(run_id: str) -> Call:
+    return Call("GET", f"/v1/runs/{_seg(run_id)}", parse=_model(RunOut))
+
+
+def runs_steps(run_id: str) -> Call:
+    return Call("GET", f"/v1/runs/{_seg(run_id)}/steps", parse=_list(RunStepOut))
+
+
+def automation_list(
+    workflow_id: str, limit: int | None, status: str | None, before: str | None
+) -> Call:
+    return Call(
+        "GET",
+        f"/v1/workflows/{_seg(workflow_id)}/automation/runs",
+        params=_run_query(limit, status, before),
+        parse=_list(RunSummary),
+    )
+
+
+def automation_get(workflow_id: str, run_id: str) -> Call:
+    return Call(
+        "GET",
+        f"/v1/workflows/{_seg(workflow_id)}/automation/runs/{_seg(run_id)}",
+        parse=_model(RunOut),
+    )
+
+
+# -- sessions ----------------------------------------------------------------
+
+
+def sessions_create(
+    *,
+    context: dict[str, Any] | None = None,
+    secrets: dict[str, str] | None = None,
+    subject: str | None = None,
+    tenant_id: str | None = None,
+    ttl_seconds: int | None = None,
+    max_runs: int | None = None,
+    resume_thread_id: str | None = None,
+    thread_key: str | None = None,
+) -> Call:
+    fields = {
+        "context": context,
+        "secrets": secrets,
+        "subject": subject,
+        "tenant_id": tenant_id,
+        "ttl_seconds": ttl_seconds,
+        "max_runs": max_runs,
+        "resume_thread_id": resume_thread_id,
+        "thread_key": thread_key,
+    }
+    body = {k: v for k, v in fields.items() if v is not None}
+    return Call("POST", "/v1/sessions", body=body, parse=_model(SessionOut))
+
+
+def sessions_refresh() -> Call:
+    return Call("POST", "/v1/sessions/refresh", parse=_model(SessionOut))
+
+
+def sessions_revoke(session_id: str) -> Call:
+    return Call("DELETE", f"/v1/sessions/{_seg(session_id)}")
+
+
+# -- files -------------------------------------------------------------------
+
+
+def files_list(workflow_id: str, thread_id: str | None) -> Call:
+    return Call(
+        "GET",
+        f"/v1/workflows/{_seg(workflow_id)}/files",
+        params={"thread_id": thread_id},
+        parse=_list(WorkflowFile),
+    )
+
+
+def files_upload(
+    workflow_id: str, thread_id: str, file: FileInput, name: str | None
+) -> Call:
+    return Call(
+        "POST",
+        f"/v1/workflows/{_seg(workflow_id)}/files",
+        files={"file": _upload(file, name)},
+        data={"thread_id": thread_id},
+        parse=_model(WorkflowFile),
+    )
+
+
+def files_get(file_id: str) -> Call:
+    return Call("GET", f"/v1/files/{_seg(file_id)}", parse=_model(WorkflowFile))
+
+
+def files_content(file_id: str) -> Call:
+    return Call("GET", f"/v1/files/{_seg(file_id)}/content", raw=True)
+
+
+def files_delete(file_id: str) -> Call:
+    return Call("DELETE", f"/v1/files/{_seg(file_id)}")
+
+
+# -- skills ------------------------------------------------------------------
+
+
+def skills_list(workflow_id: str) -> Call:
+    return Call("GET", f"/v1/workflows/{_seg(workflow_id)}/skills", parse=_list(Skill))
+
+
+def skills_upload(
+    workflow_id: str, file: FileInput, name: str | None, allow_unknown_types: bool
+) -> Call:
+    return Call(
+        "POST",
+        f"/v1/workflows/{_seg(workflow_id)}/skills",
+        files={"file": _upload(file, name)},
+        data={"allow_unknown_types": "true"} if allow_unknown_types else {},
+        parse=_model(SkillUpload),
+    )
+
+
+def skills_get(skill_id: str) -> Call:
+    return Call("GET", f"/v1/skills/{_seg(skill_id)}", parse=_model(Skill))
+
+
+def _skill_files(value: Any) -> dict[str, SkillFile]:
+    return {k: SkillFile.model_validate(v) for k, v in value["files"].items()}
+
+
+def skills_files(skill_id: str) -> Call:
+    return Call("GET", f"/v1/skills/{_seg(skill_id)}/files", parse=_skill_files)
+
+
+def skills_file_content(skill_id: str, path: str) -> Call:
+    # ``path`` may hold slashes: the route takes the rest of the path.
+    return Call(
+        "GET", f"/v1/skills/{_seg(skill_id)}/files/{quote(path, safe='/')}", raw=True
+    )
+
+
+def skills_delete(skill_id: str) -> Call:
+    return Call("DELETE", f"/v1/skills/{_seg(skill_id)}")
+
+
+# -- small reads -------------------------------------------------------------
+
+
+def me_get() -> Call:
+    return Call("GET", "/v1/me", parse=_model(Me))
+
+
+def models_list() -> Call:
+    return Call("GET", "/v1/models", parse=_list(ModelOption))
+
+
+def node_types_list() -> Call:
+    return Call("GET", "/v1/node-types")
+
+
+def health_live() -> Call:
+    return Call("GET", "/health")
+
+
+def health_ready() -> Call:
+    return Call("GET", "/health/ready", parse=_model(RuntimeReadiness))