flowra-sdk 0.1.1__tar.gz

flowra_sdk-0.1.1/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: flowra-sdk
+Version: 0.1.1
+Summary: Official Python SDK for the Flowra API
+Author: Flowra
+License: MIT
+Project-URL: Homepage, https://flowra.dev
+Project-URL: Documentation, https://docs.flowra.dev
+Project-URL: Repository, https://github.com/flowradev/sdk
+Project-URL: Issues, https://github.com/flowradev/sdk/issues
+Keywords: flowra,sdk,agents,workflows,tools
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# flowra
+
+Python SDK for the Flowra API. Stdlib only (no extra runtime deps). Requires Python 3.10+.
+
+## Install
+
+PyPI name is `flowra-sdk`. Import stays `flowra`. Do **not** `pip install flowra` — that package is unrelated.
+
+```bash
+pip install flowra-sdk
+```
+
+From this repo:
+
+```bash
+pip install -e "./python"
+```
+
+## Quickstart
+
+```python
+import os
+from flowra import Flowra
+
+flowra = Flowra(api_key=os.environ["FLOWRA_API_KEY"])
+
+profile = flowra.get_profile()
+tools = flowra.tools.list(limit=10)
+run = flowra.workflows.run("WORKFLOW_ID", {"input": {"message": "hello"}})
+```
+
+Act as an external user:
+
+```python
+user_client = flowra.as_user("customer_42")
+user_client.connections.create_link({"authConfigId": "..."})
+```
+
+## Namespaces
+
+`tools`, `toolkits`, `skills`, `workflows`, `connections`, `auth_configs`, `users`, `triggers`, `chat`, `files`, `knowledge`, `database`, `sandbox`, `mcp`, `llm`, `browser`, `usage`
+
+Method names are snake_case mirrors of the TypeScript facade (e.g. `create_link`, `set_active`, `ingest_url`).
+
+## Chat streaming and usage
+
+```python
+from flowra import Flowra
+
+flowra = Flowra(api_key="...")
+
+for event in flowra.chat.stream(thread_id, {"input": {"messages": [...]}}, as_events=True):
+    if event["event"] == "usage":
+        print(event["data"])
+```
+
+```python
+balance = flowra.usage.balance()
+ledger = flowra.usage.list(threadId="...")
+```
+
+## Files
+
+```python
+flowra.files.upload("document", "/path/to/file.pdf")
+content = flowra.files.download(file_id)  # bytes
+```
+
+## Escape hatch
+
+```python
+flowra.request("GET", "/api/v1/toolkits", query={"limit": 5})
+```
+
+HTTP failures raise `FlowraAPIError` (`status_code`, `body`).

flowra_sdk-0.1.1/README.md

@@ -0,0 +1,75 @@
+# flowra
+
+Python SDK for the Flowra API. Stdlib only (no extra runtime deps). Requires Python 3.10+.
+
+## Install
+
+PyPI name is `flowra-sdk`. Import stays `flowra`. Do **not** `pip install flowra` — that package is unrelated.
+
+```bash
+pip install flowra-sdk
+```
+
+From this repo:
+
+```bash
+pip install -e "./python"
+```
+
+## Quickstart
+
+```python
+import os
+from flowra import Flowra
+
+flowra = Flowra(api_key=os.environ["FLOWRA_API_KEY"])
+
+profile = flowra.get_profile()
+tools = flowra.tools.list(limit=10)
+run = flowra.workflows.run("WORKFLOW_ID", {"input": {"message": "hello"}})
+```
+
+Act as an external user:
+
+```python
+user_client = flowra.as_user("customer_42")
+user_client.connections.create_link({"authConfigId": "..."})
+```
+
+## Namespaces
+
+`tools`, `toolkits`, `skills`, `workflows`, `connections`, `auth_configs`, `users`, `triggers`, `chat`, `files`, `knowledge`, `database`, `sandbox`, `mcp`, `llm`, `browser`, `usage`
+
+Method names are snake_case mirrors of the TypeScript facade (e.g. `create_link`, `set_active`, `ingest_url`).
+
+## Chat streaming and usage
+
+```python
+from flowra import Flowra
+
+flowra = Flowra(api_key="...")
+
+for event in flowra.chat.stream(thread_id, {"input": {"messages": [...]}}, as_events=True):
+    if event["event"] == "usage":
+        print(event["data"])
+```
+
+```python
+balance = flowra.usage.balance()
+ledger = flowra.usage.list(threadId="...")
+```
+
+## Files
+
+```python
+flowra.files.upload("document", "/path/to/file.pdf")
+content = flowra.files.download(file_id)  # bytes
+```
+
+## Escape hatch
+
+```python
+flowra.request("GET", "/api/v1/toolkits", query={"limit": 5})
+```
+
+HTTP failures raise `FlowraAPIError` (`status_code`, `body`).

flowra_sdk-0.1.1/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "flowra-sdk"
+version = "0.1.1"
+description = "Official Python SDK for the Flowra API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Flowra" }]
+keywords = ["flowra", "sdk", "agents", "workflows", "tools"]
+dependencies = []
+
+[project.urls]
+Homepage = "https://flowra.dev"
+Documentation = "https://docs.flowra.dev"
+Repository = "https://github.com/flowradev/sdk"
+Issues = "https://github.com/flowradev/sdk/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+flowra = ["py.typed"]

flowra_sdk-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

flowra_sdk-0.1.1/src/flowra/__init__.py

@@ -0,0 +1,20 @@
+"""Flowra Python SDK."""
+
+from .client import Flowra
+from .errors import FlowraAPIError
+from .stream_usage import (
+    ParsedSseEvent,
+    StreamUsageEvent,
+    extract_stream_usage,
+    parse_sse_chunk,
+)
+
+__all__ = [
+    "Flowra",
+    "FlowraAPIError",
+    "ParsedSseEvent",
+    "StreamUsageEvent",
+    "extract_stream_usage",
+    "parse_sse_chunk",
+]
+__version__ = "0.1.1"

flowra_sdk-0.1.1/src/flowra/_http.py

@@ -0,0 +1,237 @@
+"""HTTP helpers for the Flowra SDK."""
+
+from __future__ import annotations
+
+import json
+import mimetypes
+import uuid
+from pathlib import Path
+from typing import Any, BinaryIO, Iterator, Mapping, MutableMapping, Optional, Union
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode, urljoin
+from urllib.request import Request, urlopen
+
+from .errors import FlowraAPIError
+
+FileBody = Union[str, Path, bytes, BinaryIO]
+
+
+class HttpClient:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = "https://flowra.dev",
+        username: Optional[str] = None,
+        timeout: float = 60.0,
+    ) -> None:
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.username = username
+        self.timeout = timeout
+
+    def _build_url(
+        self,
+        path: str,
+        query: Optional[Mapping[str, Any]] = None,
+    ) -> str:
+        url = urljoin(f"{self.base_url}/", path.lstrip("/"))
+        if query:
+            filtered = {
+                key: value
+                for key, value in query.items()
+                if value is not None
+            }
+            if filtered:
+                url = f"{url}?{urlencode(filtered, doseq=True)}"
+        return url
+
+    def _base_headers(
+        self,
+        *,
+        accept: str = "application/json",
+    ) -> MutableMapping[str, str]:
+        headers: MutableMapping[str, str] = {
+            "Accept": accept,
+            "x-api-key": self.api_key,
+        }
+        if self.username:
+            headers["x-username"] = self.username
+        return headers
+
+    def _raise_http_error(self, exc: HTTPError) -> None:
+        body: Any
+        try:
+            body = json.loads(exc.read().decode("utf-8"))
+        except Exception:
+            body = None
+        message = None
+        if isinstance(body, dict):
+            message = body.get("message") or body.get("error")
+        raise FlowraAPIError(
+            message or f"HTTP {exc.code}",
+            status_code=exc.code,
+            body=body,
+        ) from exc
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Mapping[str, Any]] = None,
+        json_body: Any = None,
+        binary: bool = False,
+        extra_headers: Optional[Mapping[str, str]] = None,
+    ) -> Any:
+        url = self._build_url(path, query)
+        headers = self._base_headers(
+            accept="application/octet-stream" if binary else "application/json",
+        )
+        if extra_headers:
+            headers.update(extra_headers)
+
+        data: Optional[bytes] = None
+        if json_body is not None:
+            headers["Content-Type"] = "application/json"
+            data = json.dumps(json_body).encode("utf-8")
+
+        request = Request(url, data=data, headers=dict(headers), method=method.upper())
+        try:
+            with urlopen(request, timeout=self.timeout) as response:
+                raw = response.read()
+                if not raw:
+                    return None
+                if binary:
+                    return raw
+                content_type = response.headers.get("Content-Type", "")
+                if "application/json" in content_type:
+                    return json.loads(raw.decode("utf-8"))
+                return raw.decode("utf-8")
+        except HTTPError as exc:
+            self._raise_http_error(exc)
+        except URLError as exc:
+            raise FlowraAPIError(str(exc.reason)) from exc
+
+    def request_multipart(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Mapping[str, Any]] = None,
+        fields: Optional[Mapping[str, Any]] = None,
+        files: Optional[Mapping[str, FileBody]] = None,
+        file_field: str = "file",
+    ) -> Any:
+        """POST/PUT multipart/form-data (used for file upload)."""
+        url = self._build_url(path, query)
+        boundary = f"----FlowraFormBoundary{uuid.uuid4().hex}"
+        body = bytearray()
+
+        for key, value in (fields or {}).items():
+            if value is None:
+                continue
+            body.extend(f"--{boundary}\r\n".encode("utf-8"))
+            body.extend(
+                f'Content-Disposition: form-data; name="{key}"\r\n\r\n'.encode("utf-8")
+            )
+            body.extend(str(value).encode("utf-8"))
+            body.extend(b"\r\n")
+
+        for name, file_value in (files or {}).items():
+            filename, content, content_type = self._read_file(file_value)
+            field_name = name or file_field
+            body.extend(f"--{boundary}\r\n".encode("utf-8"))
+            body.extend(
+                (
+                    f'Content-Disposition: form-data; name="{field_name}"; '
+                    f'filename="{filename}"\r\n'
+                ).encode("utf-8")
+            )
+            body.extend(f"Content-Type: {content_type}\r\n\r\n".encode("utf-8"))
+            body.extend(content)
+            body.extend(b"\r\n")
+
+        body.extend(f"--{boundary}--\r\n".encode("utf-8"))
+
+        headers = self._base_headers()
+        headers["Content-Type"] = f"multipart/form-data; boundary={boundary}"
+
+        request = Request(
+            url,
+            data=bytes(body),
+            headers=dict(headers),
+            method=method.upper(),
+        )
+        try:
+            with urlopen(request, timeout=self.timeout) as response:
+                raw = response.read()
+                if not raw:
+                    return None
+                content_type = response.headers.get("Content-Type", "")
+                if "application/json" in content_type:
+                    return json.loads(raw.decode("utf-8"))
+                return raw.decode("utf-8")
+        except HTTPError as exc:
+            self._raise_http_error(exc)
+        except URLError as exc:
+            raise FlowraAPIError(str(exc.reason)) from exc
+
+    def stream_text(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Mapping[str, Any]] = None,
+        json_body: Any = None,
+        extra_headers: Optional[Mapping[str, str]] = None,
+        chunk_size: int = 1024,
+    ) -> Iterator[str]:
+        """Yield decoded text chunks from a streaming response (SSE)."""
+        url = self._build_url(path, query)
+        headers = self._base_headers(accept="text/event-stream")
+        if extra_headers:
+            headers.update(extra_headers)
+        data: Optional[bytes] = None
+        if json_body is not None:
+            headers["Content-Type"] = "application/json"
+            data = json.dumps(json_body).encode("utf-8")
+
+        request = Request(url, data=data, headers=dict(headers), method=method.upper())
+        try:
+            response = urlopen(request, timeout=self.timeout)
+        except HTTPError as exc:
+            self._raise_http_error(exc)
+            return  # pragma: no cover
+        except URLError as exc:
+            raise FlowraAPIError(str(exc.reason)) from exc
+
+        try:
+            while True:
+                chunk = response.read(chunk_size)
+                if not chunk:
+                    break
+                yield chunk.decode("utf-8", errors="replace")
+        finally:
+            response.close()
+
+    @staticmethod
+    def _read_file(file_value: FileBody) -> tuple[str, bytes, str]:
+        if isinstance(file_value, (str, Path)):
+            path = Path(file_value)
+            content = path.read_bytes()
+            filename = path.name
+            content_type = mimetypes.guess_type(filename)[0] or "application/octet-stream"
+            return filename, content, content_type
+
+        if isinstance(file_value, bytes):
+            return "upload.bin", file_value, "application/octet-stream"
+
+        # BinaryIO / file-like
+        name = getattr(file_value, "name", "upload.bin")
+        filename = Path(str(name)).name if name else "upload.bin"
+        content = file_value.read()
+        if isinstance(content, str):
+            content = content.encode("utf-8")
+        content_type = mimetypes.guess_type(filename)[0] or "application/octet-stream"
+        return filename, content, content_type