fetch-hive-sdk 0.1.0__py3-none-any.whl

fetch_hive_sdk/__init__.py

@@ -0,0 +1,23 @@
+"""
+fetch_hive_sdk — Official Python SDK for the Fetch Hive API.
+
+Quick start::
+
+    from fetch_hive_sdk import FetchHive
+
+    client = FetchHive(api_key="fhk_...")
+
+    # Non-streaming
+    result = client.invoke_agent(agent="my-agent", message="Hello")
+    print(result["response"])
+
+    # Streaming
+    for chunk in client.invoke_agent_stream(agent="my-agent", message="Hello"):
+        if chunk.get("type") == "delta":
+            print(chunk.get("content", ""), end="", flush=True)
+"""
+
+from .client import FetchHive
+from .streaming import aiter_sse, iter_sse
+
+__all__ = ["FetchHive", "iter_sse", "aiter_sse"]

fetch_hive_sdk/client.py

@@ -0,0 +1,250 @@
+"""
+client.py
+
+Idiomatic facade for the Fetch Hive API.
+
+Usage::
+
+    from fetch_hive_sdk import FetchHive
+
+    client = FetchHive(api_key="fhk_...")
+
+    # Non-streaming prompt
+    result = client.invoke_prompt(deployment="my-prompt", inputs={"name": "Alice"})
+    print(result["response"])
+
+    # Streaming agent
+    for chunk in client.invoke_agent_stream(agent="my-agent", message="Hello"):
+        if chunk.get("type") == "delta":
+            print(chunk.get("content", ""), end="", flush=True)
+
+Async::
+
+    async for chunk in client.ainvoke_agent_stream(agent="my-agent", message="Hello"):
+        ...
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, AsyncIterator, Generator, Iterator
+
+import httpx
+
+from .streaming import aiter_sse, iter_sse
+
+DEFAULT_BASE_URL = "https://api.fetchhive.com/v1"
+
+
+class FetchHive:
+    """
+    Fetch Hive API client.
+
+    Args:
+        api_key: Bearer token from the Fetch Hive dashboard.
+                 Defaults to the ``FETCH_HIVE_API_KEY`` environment variable.
+        base_url: API base URL. Defaults to ``https://api.fetchhive.com/v1``.
+        timeout: Request timeout in seconds (default: 120).
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 120.0,
+    ) -> None:
+        resolved_key = api_key or os.environ.get("FETCH_HIVE_API_KEY")
+        if not resolved_key:
+            raise ValueError(
+                "api_key is required. Pass it explicitly or set the "
+                "FETCH_HIVE_API_KEY environment variable."
+            )
+        self._api_key = resolved_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+
+    @property
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self._api_key}",
+            "Content-Type": "application/json",
+        }
+
+    def _url(self, path: str) -> str:
+        return f"{self._base_url}{path}"
+
+    # ── Prompt ────────────────────────────────────────────────────────────────
+
+    def invoke_prompt(
+        self,
+        *,
+        deployment: str,
+        variant: str = "",
+        inputs: dict[str, Any] | None = None,
+        user: str | None = None,
+    ) -> dict[str, Any]:
+        """Invoke a prompt deployment and return the full response."""
+        body: dict[str, Any] = {"deployment": deployment, "streaming": False}
+        if variant:
+            body["variant"] = variant
+        if inputs is not None:
+            body["inputs"] = inputs
+        if user is not None:
+            body["user"] = user
+
+        with httpx.Client(timeout=self._timeout) as client:
+            resp = client.post(self._url("/invoke"), headers=self._headers, json=body)
+            resp.raise_for_status()
+            return resp.json()
+
+    def invoke_prompt_stream(
+        self,
+        *,
+        deployment: str,
+        variant: str = "",
+        inputs: dict[str, Any] | None = None,
+        user: str | None = None,
+    ) -> Generator[dict[str, Any], None, None]:
+        """Invoke a prompt deployment and stream SSE events."""
+        body: dict[str, Any] = {"deployment": deployment, "streaming": True}
+        if variant:
+            body["variant"] = variant
+        if inputs is not None:
+            body["inputs"] = inputs
+        if user is not None:
+            body["user"] = user
+
+        with httpx.Client(timeout=self._timeout) as client:
+            with client.stream("POST", self._url("/invoke"), headers=self._headers, json=body) as resp:
+                yield from iter_sse(resp)
+
+    async def ainvoke_prompt_stream(
+        self,
+        *,
+        deployment: str,
+        variant: str = "",
+        inputs: dict[str, Any] | None = None,
+        user: str | None = None,
+    ) -> AsyncIterator[dict[str, Any]]:
+        """Async: invoke a prompt deployment and stream SSE events."""
+        body: dict[str, Any] = {"deployment": deployment, "streaming": True}
+        if variant:
+            body["variant"] = variant
+        if inputs is not None:
+            body["inputs"] = inputs
+        if user is not None:
+            body["user"] = user
+
+        async with httpx.AsyncClient(timeout=self._timeout) as client:
+            async with client.stream("POST", self._url("/invoke"), headers=self._headers, json=body) as resp:
+                async for chunk in aiter_sse(resp):
+                    yield chunk
+
+    # ── Workflow ──────────────────────────────────────────────────────────────
+
+    def invoke_workflow(
+        self,
+        *,
+        deployment: str,
+        variant: str = "",
+        inputs: dict[str, Any] | None = None,
+        async_mode: bool = False,
+        callback_url: str | None = None,
+        user: str | None = None,
+    ) -> dict[str, Any]:
+        """Invoke a workflow deployment (sync or async)."""
+        body: dict[str, Any] = {"deployment": deployment}
+        if variant:
+            body["variant"] = variant
+        if inputs is not None:
+            body["inputs"] = inputs
+        if user is not None:
+            body["user"] = user
+        if async_mode:
+            body["async"] = {"enabled": True}
+            if callback_url:
+                body["async"]["callback_url"] = callback_url
+
+        with httpx.Client(timeout=self._timeout) as client:
+            resp = client.post(self._url("/workflow/invoke"), headers=self._headers, json=body)
+            resp.raise_for_status()
+            return resp.json()
+
+    # ── Agent ─────────────────────────────────────────────────────────────────
+
+    def invoke_agent(
+        self,
+        *,
+        agent: str,
+        message: str,
+        thread_id: str = "",
+        user: str | None = None,
+        messages: list[dict[str, Any]] | None = None,
+        image_urls: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """Send a message to an agent and return the full response."""
+        body: dict[str, Any] = {"agent": agent, "message": message, "streaming": False}
+        if thread_id:
+            body["thread_id"] = thread_id
+        if user is not None:
+            body["user"] = user
+        if messages is not None:
+            body["messages"] = messages
+        if image_urls:
+            body["image_urls"] = image_urls
+
+        with httpx.Client(timeout=self._timeout) as client:
+            resp = client.post(self._url("/agent/invoke"), headers=self._headers, json=body)
+            resp.raise_for_status()
+            return resp.json()
+
+    def invoke_agent_stream(
+        self,
+        *,
+        agent: str,
+        message: str,
+        thread_id: str = "",
+        user: str | None = None,
+        messages: list[dict[str, Any]] | None = None,
+        image_urls: list[str] | None = None,
+    ) -> Generator[dict[str, Any], None, None]:
+        """Send a message to an agent and stream SSE events."""
+        body: dict[str, Any] = {"agent": agent, "message": message, "streaming": True}
+        if thread_id:
+            body["thread_id"] = thread_id
+        if user is not None:
+            body["user"] = user
+        if messages is not None:
+            body["messages"] = messages
+        if image_urls:
+            body["image_urls"] = image_urls
+
+        with httpx.Client(timeout=self._timeout) as client:
+            with client.stream("POST", self._url("/agent/invoke"), headers=self._headers, json=body) as resp:
+                yield from iter_sse(resp)
+
+    async def ainvoke_agent_stream(
+        self,
+        *,
+        agent: str,
+        message: str,
+        thread_id: str = "",
+        user: str | None = None,
+        messages: list[dict[str, Any]] | None = None,
+        image_urls: list[str] | None = None,
+    ) -> AsyncIterator[dict[str, Any]]:
+        """Async: send a message to an agent and stream SSE events."""
+        body: dict[str, Any] = {"agent": agent, "message": message, "streaming": True}
+        if thread_id:
+            body["thread_id"] = thread_id
+        if user is not None:
+            body["user"] = user
+        if messages is not None:
+            body["messages"] = messages
+        if image_urls:
+            body["image_urls"] = image_urls
+
+        async with httpx.AsyncClient(timeout=self._timeout) as client:
+            async with client.stream("POST", self._url("/agent/invoke"), headers=self._headers, json=body) as resp:
+                async for chunk in aiter_sse(resp):
+                    yield chunk

fetch_hive_sdk/streaming.py

@@ -0,0 +1,90 @@
+"""
+streaming.py
+
+Lightweight Server-Sent Events (SSE) parser for streaming Fetch Hive responses.
+
+Provides both synchronous and asynchronous generators.
+
+Sync example::
+
+    import httpx
+    from fetch_hive_sdk.streaming import iter_sse
+
+    with httpx.stream("POST", url, headers=headers, json=body) as response:
+        for chunk in iter_sse(response):
+            if chunk.get("type") == "delta":
+                print(chunk.get("content", ""), end="", flush=True)
+
+Async example::
+
+    import httpx
+    from fetch_hive_sdk.streaming import aiter_sse
+
+    async with httpx.AsyncClient() as client:
+        async with client.stream("POST", url, headers=headers, json=body) as response:
+            async for chunk in aiter_sse(response):
+                if chunk.get("type") == "delta":
+                    print(chunk.get("content", ""), end="", flush=True)
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, AsyncIterator, Generator, Iterator
+
+import httpx
+
+
+def _parse_line(line: str) -> dict[str, Any] | None:
+    """Parse a single SSE data line. Returns None for non-data lines or [DONE]."""
+    if not line.startswith("data: "):
+        return None
+    payload = line[6:]
+    if payload.strip() == "[DONE]":
+        return None
+    try:
+        return json.loads(payload)
+    except json.JSONDecodeError:
+        return None
+
+
+def iter_sse(response: httpx.Response) -> Generator[dict[str, Any], None, None]:
+    """
+    Synchronous generator that yields parsed SSE events from an httpx streaming
+    response.
+
+    Stops at ``data: [DONE]``.
+    """
+    response.raise_for_status()
+    buf = ""
+    for chunk in response.iter_text():
+        buf += chunk
+        while "\n" in buf:
+            line, buf = buf.split("\n", 1)
+            line = line.rstrip("\r")
+            event = _parse_line(line)
+            if event is None and line.strip() == "data: [DONE]":
+                return
+            if event is not None:
+                yield event
+
+
+async def aiter_sse(response: httpx.Response) -> AsyncIterator[dict[str, Any]]:
+    """
+    Asynchronous generator that yields parsed SSE events from an httpx streaming
+    response.
+
+    Stops at ``data: [DONE]``.
+    """
+    response.raise_for_status()
+    buf = ""
+    async for chunk in response.aiter_text():
+        buf += chunk
+        while "\n" in buf:
+            line, buf = buf.split("\n", 1)
+            line = line.rstrip("\r")
+            if line.strip() == "data: [DONE]":
+                return
+            event = _parse_line(line)
+            if event is not None:
+                yield event

fetch_hive_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: fetch-hive-sdk
+Version: 0.1.0
+Summary: Official Python SDK for the Fetch Hive API
+Project-URL: Homepage, https://fetchhive.com
+Project-URL: Repository, https://github.com/Fetch-Hive/python-sdk
+Project-URL: Documentation, https://docs.fetchhive.com
+Author-email: Fetch Hive <hello@fetchhive.com>
+License: MIT
+Keywords: agents,ai,fetchhive,sdk,workflows
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# fetch-hive-sdk
+
+Official Python SDK for [Fetch Hive](https://fetchhive.com) — invoke AI prompts, workflows, and agents from your application.
+
+[![PyPI version](https://badge.fury.io/py/fetch-hive-sdk.svg)](https://pypi.org/project/fetch-hive-sdk/)
+
+## Installation
+
+```bash
+pip install fetch-hive-sdk
+```
+
+## Quick start
+
+```python
+from fetch_hive_sdk import FetchHive
+
+client = FetchHive(api_key="fhk_...")
+# or: client = FetchHive()  # reads FETCH_HIVE_API_KEY env var
+```
+
+Get your API key from the [Fetch Hive dashboard](https://app.fetchhive.com).
+
+## Invoke a prompt
+
+```python
+result = client.invoke_prompt(
+    deployment="my-prompt",
+    inputs={"name": "Alice", "topic": "machine learning"},
+)
+print(result["response"])
+```
+
+## Invoke a prompt (streaming)
+
+```python
+for chunk in client.invoke_prompt_stream(
+    deployment="my-prompt",
+    inputs={"name": "Alice"},
+):
+    if chunk.get("type") == "delta":
+        print(chunk.get("content", ""), end="", flush=True)
+```
+
+## Invoke a workflow
+
+```python
+run = client.invoke_workflow(
+    deployment="my-workflow",
+    inputs={"customer_id": "42"},
+)
+print(run["status"], run.get("output"))
+```
+
+## Async workflow
+
+```python
+run = client.invoke_workflow(
+    deployment="my-workflow",
+    inputs={"customer_id": "42"},
+    async_mode=True,
+    callback_url="https://example.com/webhook",
+)
+print("Queued:", run["run_id"])
+```
+
+## Invoke an agent (streaming)
+
+```python
+for chunk in client.invoke_agent_stream(
+    agent="my-agent",
+    message="What is the weather in London?",
+    thread_id="session-abc123",  # optional — persist conversation history
+):
+    if chunk.get("type") == "delta":
+        print(chunk.get("content", ""), end="", flush=True)
+    elif chunk.get("type") == "tool_start":
+        print(f"\n[Calling tool: {chunk.get('tool_name')}]")
+```
+
+## Async streaming
+
+```python
+import asyncio
+
+async def main():
+    async for chunk in client.ainvoke_agent_stream(
+        agent="my-agent",
+        message="Hello",
+    ):
+        if chunk.get("type") == "delta":
+            print(chunk.get("content", ""), end="", flush=True)
+
+asyncio.run(main())
+```
+
+## Multimodal (image) inputs
+
+```python
+result = client.invoke_agent(
+    agent="vision-agent",
+    message="Describe this image",
+    image_urls=["https://example.com/photo.jpg"],
+)
+```
+
+## Authentication
+
+Pass the API key to the constructor or set the `FETCH_HIVE_API_KEY` environment variable:
+
+```bash
+export FETCH_HIVE_API_KEY=fhk_...
+```
+
+## Version
+
+0.1.0
+
+## License
+
+MIT — see [LICENSE](LICENSE).

fetch_hive_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+fetch_hive_sdk/__init__.py,sha256=nFoBWeMW9G80tblzOglIBi8RSQxCyyyDstn7fmUbE6E,616
+fetch_hive_sdk/client.py,sha256=OZVWuGLNZp-nqBYB2z3dAgyz3SKyk7QOloqxiyEm2_g,8815
+fetch_hive_sdk/streaming.py,sha256=gdaF0pSYxKnD1-hdTNSynNi9o4KAktLgjB6_8ZbCsHs,2599
+fetch_hive_sdk-0.1.0.dist-info/METADATA,sha256=7i7DjvMJg-pvKaYaiJyouFZ8cXYnKFXsJZQ9S5NFAGw,3561
+fetch_hive_sdk-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+fetch_hive_sdk-0.1.0.dist-info/RECORD,,

fetch_hive_sdk-0.1.0.dist-info/WHEEL

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