fetch-hive-sdk 0.1.0__tar.gz

fetch_hive_sdk-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build twine
+
+      - name: Build distribution
+        run: python -m build
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload dist/*
+
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "${{ github.ref_name }}" \
+            --title "${{ github.ref_name }}" \
+            --generate-notes

fetch_hive_sdk-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,121 @@
+# 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/examples/invoke_agent_stream.py

@@ -0,0 +1,25 @@
+"""
+Example: Invoke an agent with streaming.
+
+Run:
+    FETCH_HIVE_API_KEY=fhk_... python examples/invoke_agent_stream.py
+"""
+from fetch_hive_sdk import FetchHive
+
+client = FetchHive()
+
+print("Streaming agent response:\n")
+
+for chunk in client.invoke_agent_stream(
+    agent="my-agent",
+    message="Tell me a short story",
+):
+    event_type = chunk.get("type")
+    if event_type == "delta":
+        print(chunk.get("content", ""), end="", flush=True)
+    elif event_type == "tool_start":
+        print(f"\n[Calling tool: {chunk.get('tool_name')}]")
+    elif event_type == "done":
+        print("\n\n[Done]")
+        if chunk.get("usage"):
+            print("Usage:", chunk["usage"])

fetch_hive_sdk-0.1.0/examples/invoke_prompt.py

@@ -0,0 +1,18 @@
+"""
+Example: Invoke a prompt deployment.
+
+Run:
+    FETCH_HIVE_API_KEY=fhk_... python examples/invoke_prompt.py
+"""
+from fetch_hive_sdk import FetchHive
+
+client = FetchHive()
+
+result = client.invoke_prompt(
+    deployment="my-prompt",
+    inputs={"name": "Alice", "topic": "machine learning"},
+)
+
+print("Response:", result.get("response"))
+print("Model:", result.get("model"))
+print("Usage:", result.get("usage"))

fetch_hive_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fetch-hive-sdk"
+version = "0.1.0"
+description = "Official Python SDK for the Fetch Hive API"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Fetch Hive", email = "hello@fetchhive.com" }]
+keywords = ["fetchhive", "ai", "agents", "workflows", "sdk"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+requires-python = ">=3.9"
+dependencies = [
+  "httpx>=0.25.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0",
+  "pytest-asyncio>=0.21",
+  "respx>=0.20",
+]
+
+[project.urls]
+Homepage = "https://fetchhive.com"
+Repository = "https://github.com/Fetch-Hive/python-sdk"
+Documentation = "https://docs.fetchhive.com"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fetch_hive_sdk"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

fetch_hive_sdk-0.1.0/src/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-0.1.0/src/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