fluidtalk 1.0.0__py3-none-any.whl

fluidtalk/__init__.py

@@ -0,0 +1,16 @@
+from .client import (
+    FluidTalk,
+    FluidTalkError,
+    ChatResult,
+    ActionResult,
+    UploadResult,
+)
+
+__all__ = [
+    "FluidTalk",
+    "FluidTalkError",
+    "ChatResult",
+    "ActionResult",
+    "UploadResult",
+]
+__version__ = "1.0.0"

fluidtalk/client.py

@@ -0,0 +1,206 @@
+"""FluidTalk Handshake API — official Python client.
+
+You own your chatbot's orchestration (when to open a chat, when to follow up, ...);
+this client turns FluidTalk's persona/engine into one method call so you don't have to
+rebuild the HTTP/auth/multipart layer.
+
+A conversation can start four ways (builder name -> method):
+    Inbound Chat  (the lead messages first)     -> inbound_chat()
+    AI Opener     (your persona messages first) -> ai_opener()
+    Event Trigger (a platform event fires)      -> event_trigger()
+    Follow-up     (re-engage a quiet lead)      -> follow_up()
+Plus upload_image() to host a local image and get a URL for visual context.
+
+A conversation is keyed by (persona, target): reuse the same ``target`` for the same
+lead and the engine keeps phase/state across turns. The persona+engine are fixed by your key.
+"""
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+import requests
+
+DEFAULT_BASE_URL = "https://api-talk.fluidvip.com"
+
+
+class FluidTalkError(Exception):
+    """Raised on a non-2xx response. ``status`` is the HTTP code, ``detail`` the parsed body."""
+
+    def __init__(self, status: int, detail: Any, message: str):
+        super().__init__(message)
+        self.status = status
+        self.detail = detail
+
+
+@dataclass
+class ChatResult:
+    reply: str
+    replies: List[str]
+    should_send_photo: bool
+    photo_url: Optional[str]
+    session_id: str
+    ignored: bool
+    ignore_reason: Optional[str]
+
+
+@dataclass
+class ActionResult:
+    session_id: str
+    message: str
+    ignored: bool
+    ignore_reason: Optional[str]
+
+
+@dataclass
+class UploadResult:
+    url: str
+
+
+class FluidTalk:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        own_username: Optional[str] = None,
+        timeout: float = 60.0,
+    ):
+        if not api_key:
+            raise ValueError("FluidTalk: api_key is required.")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.own_username = own_username
+        self.timeout = timeout
+
+    def inbound_chat(
+        self,
+        target: str,
+        message: str,
+        own_username: Optional[str] = None,
+        image_url: Optional[str] = None,
+        image_path: Optional[str] = None,
+    ) -> ChatResult:
+        """Inbound Chat — the lead messaged first (or continue an ongoing conversation). POST /chat."""
+        body = self._post(
+            "/api/v1/bot/chat",
+            {
+                "target": target,
+                "message": message,
+                "own_username": own_username or self.own_username,
+                "image_url": image_url,
+            },
+            image_path=image_path,
+        )
+        return ChatResult(
+            reply=body.get("reply", ""),
+            replies=body.get("replies", []),
+            should_send_photo=bool(body.get("should_send_photo")),
+            photo_url=body.get("photo_url"),
+            session_id=body.get("session_id"),
+            ignored=bool(body.get("ignored")),
+            ignore_reason=body.get("ignore_reason"),
+        )
+
+    def ai_opener(
+        self,
+        target: str,
+        own_username: Optional[str] = None,
+        image_url: Optional[str] = None,
+        image_path: Optional[str] = None,
+    ) -> ActionResult:
+        """AI Opener — your persona sends the first message to a new lead. action=OUTREACH."""
+        return self._action(
+            {"target": target, "action": "OUTREACH", "own_username": own_username or self.own_username, "image_url": image_url},
+            image_path,
+        )
+
+    def event_trigger(
+        self,
+        target: str,
+        event_type: str,
+        context: Optional[Dict[str, Any]] = None,
+        own_username: Optional[str] = None,
+        image_url: Optional[str] = None,
+        image_path: Optional[str] = None,
+    ) -> ActionResult:
+        """Event Trigger — a platform event fires; ``event_type`` must match an Event Trigger
+        node's event id in the engine. action=ENTRY_POINT."""
+        return self._action(
+            {
+                "target": target,
+                "action": "ENTRY_POINT",
+                "entry_type": event_type,
+                "entry_context": json.dumps(context) if context else None,
+                "own_username": own_username or self.own_username,
+                "image_url": image_url,
+            },
+            image_path,
+        )
+
+    def follow_up(self, target: str, own_username: Optional[str] = None) -> ActionResult:
+        """Follow-up — re-engage a lead who went quiet (conversation must already exist). action=FOLLOW_UP."""
+        return self._action(
+            {"target": target, "action": "FOLLOW_UP", "own_username": own_username or self.own_username},
+            None,
+        )
+
+    def upload_image(
+        self,
+        path: Optional[str] = None,
+        data: Optional[bytes] = None,
+        filename: Optional[str] = None,
+    ) -> UploadResult:
+        """Upload a local image (or bytes) and get a hosted URL for visual context. POST /upload."""
+        if path and data is None:
+            with open(path, "rb") as f:
+                data = f.read()
+            filename = filename or os.path.basename(path)
+        if data is None:
+            raise ValueError("upload_image: provide path= or data= (with filename=).")
+        body = self._post("/api/v1/bot/upload", {}, file=(filename or "image.jpg", data))
+        return UploadResult(url=body.get("url"))
+
+    # --- internals ---
+    def _action(self, fields: Dict[str, Optional[str]], image_path: Optional[str]) -> ActionResult:
+        body = self._post("/api/v1/bot/action", fields, image_path=image_path)
+        return ActionResult(
+            session_id=body.get("session_id"),
+            message=body.get("message", ""),
+            ignored=bool(body.get("ignored")),
+            ignore_reason=body.get("ignore_reason"),
+        )
+
+    def _post(
+        self,
+        path: str,
+        fields: Dict[str, Optional[str]],
+        image_path: Optional[str] = None,
+        file: Optional[tuple] = None,
+    ) -> Dict[str, Any]:
+        data = {k: v for k, v in fields.items() if v is not None and v != ""}
+        files = None
+        if file is not None:
+            files = {"file": file}
+        elif image_path:
+            with open(image_path, "rb") as f:
+                files = {"file": (os.path.basename(image_path), f.read())}
+        try:
+            res = requests.post(
+                self.base_url + path,
+                headers={"X-API-Key": self.api_key},
+                data=data,
+                files=files,
+                timeout=self.timeout,
+            )
+        except requests.RequestException as e:
+            raise FluidTalkError(0, {"error": "network_error"}, f"Network error reaching FluidTalk: {e}")
+        try:
+            body = res.json()
+        except ValueError:
+            body = {"detail": res.text}
+        if not res.ok:
+            detail = body.get("detail") if isinstance(body, dict) else body
+            raise FluidTalkError(res.status_code, body, f"FluidTalk {res.status_code}: {detail}")
+        return body

fluidtalk-1.0.0.dist-info/METADATA

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: fluidtalk
+Version: 1.0.0
+Summary: Official Python client for the FluidTalk Handshake API — drop FluidTalk AI persona replies into your own chatbot backend.
+Author: FluidTalk
+License: MIT
+Project-URL: Homepage, https://talk.fluidvip.com
+Keywords: fluidtalk,chatbot,ai,handshake,sdk
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25
+Dynamic: license-file
+
+# fluidtalk (Python)
+
+Official Python client for the **FluidTalk Handshake API**. Drop FluidTalk's AI persona replies into your own chatbot backend without rebuilding the HTTP/auth/multipart layer.
+
+You keep your own orchestration (when to open a chat, when to follow up, where to send messages); this client just gives you the persona's reply in one call.
+
+```bash
+pip install fluidtalk
+```
+
+```python
+from fluidtalk import FluidTalk, FluidTalkError
+
+ft = FluidTalk(
+    api_key="ft_sk_...",            # scoped to one persona + engine
+    own_username="@my_account",     # optional default for tracking / dedup
+    # base_url="https://api-talk.fluidvip.com"  (default)
+)
+
+# A lead messaged you -> get the persona's reply and relay it on your platform
+res = ft.inbound_chat(target="@john_doe", message="hey, saw your post!")
+for bubble in res.replies:
+    my_chat.send("@john_doe", bubble)
+if res.should_send_photo and res.photo_url:
+    my_chat.send_image("@john_doe", res.photo_url)
+```
+
+## Concepts → methods
+
+A conversation can start four ways. The builder names map to these methods (the API wire value is handled for you):
+
+| Builder name | When | Method |
+| :-- | :-- | :-- |
+| **Inbound Chat** | the lead messages first (or an ongoing chat) | `ft.inbound_chat(target, message)` |
+| **AI Opener** | your persona messages first | `ft.ai_opener(target)` |
+| **Event Trigger** | a platform event fires | `ft.event_trigger(target, event_type, context)` |
+| **Follow-up** | re-engage a quiet lead | `ft.follow_up(target)` |
+| — | host a local image for context | `ft.upload_image(path=...)` |
+
+A conversation is keyed by **(persona, `target`)** — reuse the same `target` for the same lead and the engine keeps phase/state across turns.
+
+## Examples
+
+```python
+# AI opener (optionally with a profile screenshot for better targeting)
+opener = ft.ai_opener(target="@lead", image_path="./profile.jpg")
+my_chat.send("@lead", opener.message)
+
+# Platform event (event_type must match an Event Trigger configured in your engine)
+ev = ft.event_trigger(target="@lead", event_type="story_reaction", context={"reaction": "🔥"})
+
+# Re-engage a ghost (needs an existing conversation)
+fu = ft.follow_up(target="@lead")
+
+# Attach an image the lead sent
+url = ft.upload_image(path="./incoming.jpg").url
+r = ft.inbound_chat(target="@lead", message="what do you think?", image_url=url)
+```
+
+Results: `inbound_chat` → `ChatResult(reply, replies, should_send_photo, photo_url, session_id, ignored, ignore_reason)`; `ai_opener`/`event_trigger`/`follow_up` → `ActionResult(session_id, message, ignored, ignore_reason)`; `upload_image` → `UploadResult(url)`. Send `replies` as separate bubbles; when `should_send_photo`, also send `photo_url`.
+
+## Behaviour to handle
+
+```python
+try:
+    res = ft.inbound_chat(target="@lead", message="hi")
+    if res.ignored:
+        return  # duplicate lead, already owned by another account — send nothing
+    for bubble in res.replies:
+        my_chat.send("@lead", bubble)
+except FluidTalkError as e:
+    if e.status == 402:   # out of tokens (insufficient_tokens)
+        ...
+    elif e.status == 400: # conversation already DONE / sealed -> stop messaging
+        ...
+    elif e.status == 404: # no conversation yet (follow_up before any contact)
+        ...
+```
+
+- **One token per conversation** — starting a new conversation costs one token; out of tokens → `FluidTalkError(status=402)`.
+- **Sealed conversation** — when finished, the next `inbound_chat` raises `FluidTalkError(status=400)` ("This session is DONE").
+
+API keys are **action-only**: send messages and upload images, never change personas/engines/billing (that stays in the dashboard). Keep your `ft_sk_` key secret.

fluidtalk-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+fluidtalk/__init__.py,sha256=pIcttJTuB-AbdMO08dO0Uab7m_VPn7M7KJE3GRb9_Ow,245
+fluidtalk/client.py,sha256=8IqXrFHLngR2Uqcltnq0NMHI7mqBbEPXoqy2bFCYso8,7221
+fluidtalk-1.0.0.dist-info/licenses/LICENSE,sha256=NvvvC0l_fBzu9YB-5cho2Pz_n9kAZfivp3h3MQEhyC4,1066
+fluidtalk-1.0.0.dist-info/METADATA,sha256=Z7JSbUUeq-xcOqE2jsFbG5rZx9hnbKMpv2ecViEkBLg,4461
+fluidtalk-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+fluidtalk-1.0.0.dist-info/top_level.txt,sha256=utS1x8HPJKj2Q3_Yj0kj3-Yxl8QiYH5RqeSkq5GoCtA,10
+fluidtalk-1.0.0.dist-info/RECORD,,

fluidtalk-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fluidtalk-1.0.0.dist-info/licenses/LICENSE

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

fluidtalk-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+fluidtalk