pluginai 1.0.0__py3-none-any.whl

pluginai/__init__.py

@@ -0,0 +1,54 @@
+"""PluginAI -- Official Python SDK for the PluginAI RAG platform.
+
+Quickstart::
+
+    from pluginai import PluginAI
+
+    client = PluginAI(
+        api_key="your-api-key",
+        workspace="your-workspace",
+    )
+    response = client.query("What is the refund policy?")
+    print(response.answer)
+
+See https://pluginai.space for documentation.
+"""
+
+from __future__ import annotations
+
+from .client import PluginAI
+from .exceptions import (
+    AuthenticationError,
+    ConnectionError,
+    NoDataError,
+    PluginAIError,
+    QuotaExceededError,
+    RateLimitError,
+    ServerError,
+    TimeoutError,
+    WorkspaceNotFoundError,
+)
+from .models import Conversation, ConversationMessage, QueryResponse
+
+__version__ = "1.0.0"
+
+__all__ = [
+    # Client
+    "PluginAI",
+    # Models
+    "QueryResponse",
+    "Conversation",
+    "ConversationMessage",
+    # Exceptions
+    "PluginAIError",
+    "AuthenticationError",
+    "QuotaExceededError",
+    "WorkspaceNotFoundError",
+    "NoDataError",
+    "ConnectionError",
+    "TimeoutError",
+    "RateLimitError",
+    "ServerError",
+    # Metadata
+    "__version__",
+]

pluginai/client.py

@@ -0,0 +1,347 @@
+"""The main :class:`PluginAI` client.
+
+This is the entry point developers use to talk to a PluginAI backend::
+
+    from pluginai import PluginAI
+
+    client = PluginAI(
+        api_key="your-api-key",
+        workspace="your-workspace",
+    )
+    response = client.query("What is the refund policy?")
+    print(response.answer)
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional
+
+import requests
+from requests.adapters import HTTPAdapter
+
+try:  # urllib3 ships with requests; Retry moved namespaces across versions.
+    from urllib3.util.retry import Retry
+except ImportError:  # pragma: no cover - very old urllib3
+    from requests.packages.urllib3.util.retry import Retry  # type: ignore
+
+from .exceptions import (
+    AuthenticationError,
+    ConnectionError,
+    NoDataError,
+    PluginAIError,
+    QuotaExceededError,
+    RateLimitError,
+    ServerError,
+    TimeoutError,
+    WorkspaceNotFoundError,
+)
+from .models import QueryResponse
+from .utils import (
+    generate_conversation_id,
+    validate_api_key,
+    validate_query,
+    validate_workspace,
+)
+
+__version__ = "1.0.0"
+
+# Sent on every request so the backend can identify SDK traffic.
+USER_AGENT = f"pluginai-python/{__version__}"
+
+# Server-side statuses that are safe to retry (transient gateway failures only).
+_RETRY_STATUSES = (502, 503, 504)
+
+# Backend endpoints, appended to ``base_url``.
+_QUERY_PATH = "/call/user/query/user_api_query"
+_AGENT_QUERY_PATH = "/call/user/query/agent_query"
+
+
+class PluginAI:
+    """A synchronous client for the PluginAI Query API.
+
+    Args:
+        api_key: Your workspace API key. Required.
+        workspace: The workspace name to query. Required.
+        base_url: Base URL of the PluginAI backend. Defaults to the hosted
+            PluginAI API; only override it if you self-host. A trailing slash is
+            stripped.
+        conversation_id: Continue an existing conversation by passing its id.
+            When omitted, a fresh id is generated automatically.
+        timeout: Per-request timeout in seconds (default 30).
+        max_retries: Number of retries on transient server errors (502/503/504)
+            only -- 4xx responses are never retried (default 2).
+        on_error: Optional callback invoked with the exception instance right
+            before any error is raised. Handy for centralised logging/metrics.
+
+    Raises:
+        ValueError: If ``api_key`` or ``workspace`` is missing or invalid.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        workspace: str,
+        base_url: str = "https://api.pluginai.space",
+        conversation_id: Optional[str] = None,
+        timeout: int = 30,
+        max_retries: int = 2,
+        on_error: Optional[Callable[[PluginAIError], None]] = None,
+    ) -> None:
+        validate_api_key(api_key)
+        validate_workspace(workspace)
+
+        self.api_key = api_key
+        self.workspace = workspace
+        self.base_url = base_url.rstrip("/")
+        self.conversation_id = conversation_id or generate_conversation_id()
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.on_error = on_error
+
+        self._session = self._build_session(max_retries)
+
+    # ------------------------------------------------------------------ #
+    # Session setup
+    # ------------------------------------------------------------------ #
+    def _build_session(self, max_retries: int) -> requests.Session:
+        """Create a pooled :class:`requests.Session` with a retry policy."""
+        session = requests.Session()
+        session.headers.update(
+            {
+                "Content-Type": "application/json",
+                "User-Agent": USER_AGENT,
+            }
+        )
+
+        # Only retry the transient gateway statuses -- never 4xx. ``total`` is
+        # driven by ``max_retries`` so callers can tune (or disable) retries.
+        retry = Retry(
+            total=max_retries,
+            status_forcelist=list(_RETRY_STATUSES),
+            allowed_methods=frozenset(["POST"]),
+            backoff_factor=0.5,
+            raise_on_status=False,
+        )
+        adapter = HTTPAdapter(max_retries=retry)
+        session.mount("http://", adapter)
+        session.mount("https://", adapter)
+        return session
+
+    # ------------------------------------------------------------------ #
+    # Public API
+    # ------------------------------------------------------------------ #
+    def query(self, message: str) -> QueryResponse:
+        """Send a question and return a grounded :class:`QueryResponse`.
+
+        Uses the standard retrieval pipeline. For complex, multi-step questions
+        see :meth:`agent_query`.
+
+        Args:
+            message: The natural-language question to ask.
+
+        Returns:
+            A :class:`~pluginai.QueryResponse` with the answer, status and timing.
+
+        Raises:
+            ValueError: If ``message`` is empty, whitespace-only or too long.
+            NoDataError: If the workspace has no relevant/indexed documents.
+            AuthenticationError: On an invalid or inactive API key (401/403).
+            QuotaExceededError: When a usage quota/limit has been hit (403).
+            WorkspaceNotFoundError: If the workspace does not exist (404).
+            RateLimitError: When too many requests are sent (429).
+            ServerError: On a backend error (5xx).
+            TimeoutError: If the request exceeds ``timeout``.
+            ConnectionError: If the backend cannot be reached.
+            PluginAIError: For any other SDK-level failure.
+        """
+        return self._do_query(self._QUERY_URL, message)
+
+    def agent_query(self, message: str) -> QueryResponse:
+        """Send a question through the Agentic RAG pipeline.
+
+        Behaves exactly like :meth:`query` -- same arguments, return type and
+        errors -- but routes to the agent endpoint, which performs multi-step
+        reasoning and tool use for complex questions. It may take longer than a
+        plain :meth:`query`, so consider raising ``timeout`` accordingly.
+
+        Args:
+            message: The natural-language question to ask.
+
+        Returns:
+            A :class:`~pluginai.QueryResponse` with the answer, status and timing.
+
+        Raises:
+            Same exceptions as :meth:`query`.
+        """
+        return self._do_query(self._AGENT_QUERY_URL, message)
+
+    def reset_conversation(self) -> str:
+        """Start a new conversation and return the new id.
+
+        Generates a fresh ``conversation_id``; every subsequent :meth:`query`
+        and :meth:`agent_query` call is grouped under it.
+
+        Returns:
+            The newly generated conversation id.
+        """
+        self.conversation_id = generate_conversation_id()
+        return self.conversation_id
+
+    def close(self) -> None:
+        """Close the underlying HTTP session and free pooled connections."""
+        self._session.close()
+
+    # ------------------------------------------------------------------ #
+    # Internal request/response handling
+    # ------------------------------------------------------------------ #
+    @property
+    def _QUERY_URL(self) -> str:
+        return f"{self.base_url}{_QUERY_PATH}"
+
+    @property
+    def _AGENT_QUERY_URL(self) -> str:
+        return f"{self.base_url}{_AGENT_QUERY_PATH}"
+
+    def _do_query(self, url: str, message: str) -> QueryResponse:
+        """Validate, POST, and translate the response into a model or error."""
+        validate_query(message)
+
+        payload: Dict[str, Any] = {
+            "query": message,
+            "workspace_name": self.workspace,
+            "Api_key": self.api_key,
+            "unique_id": self.conversation_id,
+        }
+
+        try:
+            response = self._session.post(url, json=payload, timeout=self.timeout)
+        except requests.Timeout as exc:
+            raise self._fail(
+                TimeoutError(
+                    f"Request timed out after {self.timeout}s. Try increasing "
+                    "the `timeout` parameter.",
+                    status_code=None,
+                )
+            ) from exc
+        except requests.ConnectionError as exc:
+            raise self._fail(
+                ConnectionError(
+                    f"Could not reach the PluginAI backend at {self.base_url}. "
+                    "Check the `base_url` and your network connection.",
+                    status_code=None,
+                )
+            ) from exc
+        except requests.RequestException as exc:
+            raise self._fail(
+                PluginAIError(f"Request failed: {exc}", status_code=None)
+            ) from exc
+
+        if response.status_code == 200:
+            return self._parse_success(response)
+
+        raise self._raise_for_status(response)
+
+    def _parse_success(self, response: requests.Response) -> QueryResponse:
+        """Turn a 200 response into a :class:`QueryResponse` (or NoDataError)."""
+        data = self._json_or_empty(response)
+
+        # The backend returns the answer under the key ``respons``; fall back to
+        # the correctly-spelled ``response`` so a backend fix can't break us.
+        answer = data.get("respons") or data.get("response") or ""
+        status = data.get("status", "success")
+        response_time = float(data.get("response_time_seconds", 0.0) or 0.0)
+
+        if status == "no_data":
+            # A successful call that found nothing relevant -- surface the
+            # backend's own message so callers know to upload documents.
+            raise self._fail(
+                NoDataError(
+                    answer or "No relevant data found for this query.",
+                    status_code=200,
+                )
+            )
+
+        return QueryResponse(
+            answer=answer,
+            status=status,
+            response_time=response_time,
+            conversation_id=self.conversation_id,
+        )
+
+    def _raise_for_status(self, response: requests.Response) -> PluginAIError:
+        """Map a non-200 response to the appropriate exception instance."""
+        code = response.status_code
+        detail = self._extract_detail(response)
+
+        if code == 401:
+            exc: PluginAIError = AuthenticationError(detail, status_code=code)
+        elif code == 403:
+            lowered = detail.lower()
+            if "quota" in lowered or "limit" in lowered:
+                exc = QuotaExceededError(detail, status_code=code)
+            else:
+                exc = AuthenticationError(detail, status_code=code)
+        elif code == 404:
+            exc = WorkspaceNotFoundError(detail, status_code=code)
+        elif code == 429:
+            exc = RateLimitError(detail, status_code=code)
+        elif 500 <= code < 600:
+            exc = ServerError(detail, status_code=code)
+        else:
+            exc = PluginAIError(detail, status_code=code)
+
+        return self._fail(exc)
+
+    # ------------------------------------------------------------------ #
+    # Small helpers
+    # ------------------------------------------------------------------ #
+    @staticmethod
+    def _json_or_empty(response: requests.Response) -> Dict[str, Any]:
+        """Return parsed JSON, or an empty dict if the body isn't JSON."""
+        try:
+            data = response.json()
+        except ValueError:
+            return {}
+        return data if isinstance(data, dict) else {}
+
+    def _extract_detail(self, response: requests.Response) -> str:
+        """Pull the ``detail`` error message from a response body."""
+        data = self._json_or_empty(response)
+        detail = data.get("detail")
+        if isinstance(detail, str) and detail:
+            return detail
+        return f"Request failed with HTTP {response.status_code}."
+
+    def _fail(self, exc: PluginAIError) -> PluginAIError:
+        """Invoke the ``on_error`` callback (if any) and return the exception.
+
+        Returning the exception lets callers write ``raise self._fail(exc)`` so
+        the ``raise`` stays visible at the call site while the callback still
+        fires exactly once before propagation.
+        """
+        if self.on_error is not None:
+            try:
+                self.on_error(exc)
+            except Exception:
+                # A misbehaving callback must never mask the real error.
+                pass
+        return exc
+
+    # ------------------------------------------------------------------ #
+    # Dunder / lifecycle
+    # ------------------------------------------------------------------ #
+    def __enter__(self) -> "PluginAI":
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        # Never expose the API key -- show only non-sensitive identity.
+        return (
+            f"PluginAI(workspace={self.workspace!r}, "
+            f"conversation_id={self.conversation_id!r})"
+        )
+
+
+__all__ = ["PluginAI"]

pluginai/exceptions.py

@@ -0,0 +1,96 @@
+"""Exception hierarchy for the PluginAI SDK.
+
+Every error raised by the SDK inherits from :class:`PluginAIError`, so callers
+can catch that single base class to handle *any* SDK failure, or catch a more
+specific subclass when they want to react differently (e.g. prompt the user to
+upload documents on :class:`NoDataError`, or upgrade their plan on
+:class:`QuotaExceededError`).
+
+All exceptions carry two attributes:
+
+* ``message`` -- a human-readable description of what went wrong.
+* ``status_code`` -- the HTTP status code that triggered the error, or ``None``
+  when the failure happened before/without an HTTP response (e.g. a connection
+  or timeout error).
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class PluginAIError(Exception):
+    """Base class for every error raised by the PluginAI SDK.
+
+    Catch this to handle any SDK failure in a single ``except`` block.
+    """
+
+    def __init__(self, message: str, status_code: Optional[int] = None) -> None:
+        super().__init__(message)
+        self.message: str = message
+        self.status_code: Optional[int] = status_code
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        if self.status_code is not None:
+            return f"[{self.status_code}] {self.message}"
+        return self.message
+
+
+class AuthenticationError(PluginAIError):
+    """Raised on HTTP 401/403 when the API key is wrong, missing, or inactive."""
+
+
+class QuotaExceededError(PluginAIError):
+    """Raised on HTTP 403 when the response mentions a quota or usage limit."""
+
+
+class WorkspaceNotFoundError(PluginAIError):
+    """Raised on HTTP 404 when the requested workspace does not exist."""
+
+
+class NoDataError(PluginAIError):
+    """Raised when the backend returns ``status == "no_data"``.
+
+    This means the query succeeded but no relevant documents were found -- most
+    often because none have been uploaded/indexed in the workspace yet.
+    """
+
+
+class ConnectionError(PluginAIError):
+    """Raised when the backend server cannot be reached at all.
+
+    .. note::
+       This shadows the built-in :class:`ConnectionError` *within this package*
+       on purpose, so SDK users get a consistent ``pluginai``-namespaced error
+       type. Import the built-in explicitly if you need it alongside this one.
+    """
+
+
+class TimeoutError(PluginAIError):
+    """Raised when a request takes longer than the configured ``timeout``.
+
+    .. note::
+       This shadows the built-in :class:`TimeoutError` *within this package* on
+       purpose, mirroring :class:`ConnectionError` above.
+    """
+
+
+class RateLimitError(PluginAIError):
+    """Raised on HTTP 429 when too many requests are sent in a short window."""
+
+
+class ServerError(PluginAIError):
+    """Raised on HTTP 5xx when the backend encounters an internal error."""
+
+
+__all__ = [
+    "PluginAIError",
+    "AuthenticationError",
+    "QuotaExceededError",
+    "WorkspaceNotFoundError",
+    "NoDataError",
+    "ConnectionError",
+    "TimeoutError",
+    "RateLimitError",
+    "ServerError",
+]

pluginai/models.py

@@ -0,0 +1,118 @@
+"""Data models returned and used by the PluginAI SDK.
+
+These are plain :mod:`dataclasses` -- no third-party dependency -- so they are
+cheap to construct, easy to inspect, and printable.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import List
+
+# Backend status strings.
+STATUS_SUCCESS = "success"
+STATUS_NO_DATA = "no_data"
+
+
+@dataclass
+class QueryResponse:
+    """The result of a :meth:`pluginai.PluginAI.query` call.
+
+    Attributes:
+        answer: The AI-generated answer text.
+        status: Backend status -- ``"success"`` or ``"no_data"``.
+        response_time: Seconds the backend spent producing the answer.
+        conversation_id: The conversation id the query was grouped under.
+        cached: Reserved for a future caching layer; always ``False`` for now.
+    """
+
+    answer: str
+    status: str
+    response_time: float
+    conversation_id: str
+    cached: bool = False
+
+    @property
+    def is_success(self) -> bool:
+        """``True`` when the backend reported a successful answer."""
+        return self.status == STATUS_SUCCESS
+
+    @property
+    def has_data(self) -> bool:
+        """``True`` unless the backend reported ``"no_data"``."""
+        return self.status != STATUS_NO_DATA
+
+    def __str__(self) -> str:
+        # Printing a response should just show the answer, so callers can do
+        # ``print(client.query("..."))`` and get the text they expect.
+        return self.answer
+
+
+@dataclass
+class ConversationMessage:
+    """A single message within a :class:`Conversation`.
+
+    Attributes:
+        role: Who produced the message -- ``"user"`` or ``"assistant"``.
+        content: The message text.
+        timestamp: When the message was created (defaults to now).
+    """
+
+    role: str
+    content: str
+    timestamp: datetime = field(default_factory=datetime.now)
+
+
+@dataclass
+class Conversation:
+    """A client-side record of a multi-turn conversation.
+
+    This is a convenience container for tracking history in your own app -- the
+    backend keys conversations off ``conversation_id``; this class just mirrors
+    the exchange locally.
+
+    Attributes:
+        conversation_id: The id shared by every message in this conversation.
+        messages: The ordered list of messages.
+    """
+
+    conversation_id: str
+    messages: List[ConversationMessage] = field(default_factory=list)
+
+    def add_message(self, role: str, content: str) -> ConversationMessage:
+        """Append a message and return the created :class:`ConversationMessage`.
+
+        Args:
+            role: ``"user"`` or ``"assistant"``.
+            content: The message text.
+
+        Returns:
+            The message that was appended.
+        """
+        message = ConversationMessage(role=role, content=content)
+        self.messages.append(message)
+        return message
+
+    def get_history(self, last_n: int = 10) -> List[ConversationMessage]:
+        """Return the most recent ``last_n`` messages.
+
+        Args:
+            last_n: How many trailing messages to return (default 10).
+
+        Returns:
+            Up to ``last_n`` messages, oldest first.
+        """
+        if last_n <= 0:
+            return []
+        return self.messages[-last_n:]
+
+    def clear(self) -> None:
+        """Remove every message from the conversation."""
+        self.messages.clear()
+
+    def __len__(self) -> int:
+        return len(self.messages)
+
+
+__all__ = ["QueryResponse", "ConversationMessage", "Conversation"]

pluginai/utils.py

@@ -0,0 +1,116 @@
+"""Internal helper functions for the PluginAI SDK.
+
+These are implementation details -- they are intentionally *not* re-exported
+from :mod:`pluginai`. They handle conversation-id generation and input
+validation so the client and models stay focused on their own concerns.
+"""
+
+from __future__ import annotations
+
+import re
+import uuid
+
+# A workspace name may only contain letters, digits, hyphens and underscores.
+_WORKSPACE_RE = re.compile(r"^[A-Za-z0-9_-]+$")
+
+# Maximum length (in characters) accepted for a single query.
+MAX_QUERY_LENGTH = 2000
+
+# Minimum length (in characters) accepted for an API key.
+MIN_API_KEY_LENGTH = 8
+
+
+def generate_conversation_id() -> str:
+    """Return a fresh, unique conversation id.
+
+    The id looks like ``conv_1a2b3c4d5e6f`` -- the ``conv_`` prefix makes it
+    easy to recognise in logs, followed by the first 12 hex chars of a UUID4.
+
+    Returns:
+        A new conversation id string.
+    """
+    return "conv_" + uuid.uuid4().hex[:12]
+
+
+def validate_api_key(api_key: str) -> None:
+    """Validate an API key, raising :class:`ValueError` when it is unusable.
+
+    Args:
+        api_key: The workspace API key to check.
+
+    Raises:
+        ValueError: If ``api_key`` is empty, ``None`` or shorter than
+            :data:`MIN_API_KEY_LENGTH` characters.
+    """
+    if not api_key or not isinstance(api_key, str):
+        raise ValueError("api_key is required and must be a non-empty string.")
+    if len(api_key) < MIN_API_KEY_LENGTH:
+        raise ValueError(
+            f"api_key looks invalid: it must be at least {MIN_API_KEY_LENGTH} "
+            "characters long."
+        )
+
+
+def validate_workspace(workspace_name: str) -> None:
+    """Validate a workspace name, raising :class:`ValueError` when invalid.
+
+    Args:
+        workspace_name: The workspace name to check.
+
+    Raises:
+        ValueError: If ``workspace_name`` is empty, ``None`` or contains any
+            character other than letters, digits, hyphens or underscores.
+    """
+    if not workspace_name or not isinstance(workspace_name, str):
+        raise ValueError("workspace is required and must be a non-empty string.")
+    if not _WORKSPACE_RE.match(workspace_name):
+        raise ValueError(
+            "workspace may only contain letters, numbers, hyphens and "
+            f"underscores (got {workspace_name!r})."
+        )
+
+
+def validate_query(query: str) -> None:
+    """Validate a query string, raising :class:`ValueError` when invalid.
+
+    Args:
+        query: The natural-language question to check.
+
+    Raises:
+        ValueError: If ``query`` is empty, ``None``, whitespace-only, or longer
+            than :data:`MAX_QUERY_LENGTH` characters.
+    """
+    if not query or not isinstance(query, str) or not query.strip():
+        raise ValueError("query must be a non-empty, non-whitespace string.")
+    if len(query) > MAX_QUERY_LENGTH:
+        raise ValueError(
+            f"query is too long: {len(query)} characters "
+            f"(maximum is {MAX_QUERY_LENGTH})."
+        )
+
+
+def mask_api_key(api_key: str) -> str:
+    """Return a masked version of an API key that is safe to log or display.
+
+    Keeps the last four characters visible and replaces everything else with
+    asterisks, e.g. ``"sk-abcdef1234"`` -> ``"********1234"``. Short or empty
+    keys are fully masked.
+
+    Args:
+        api_key: The API key to mask.
+
+    Returns:
+        The masked key.
+    """
+    if not api_key or not isinstance(api_key, str) or len(api_key) <= 4:
+        return "****"
+    return "*" * (len(api_key) - 4) + api_key[-4:]
+
+
+__all__ = [
+    "generate_conversation_id",
+    "validate_api_key",
+    "validate_workspace",
+    "validate_query",
+    "mask_api_key",
+]

pluginai-1.0.0.dist-info/METADATA

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: pluginai
+Version: 1.0.0
+Summary: Official Python SDK for PluginAI RAG Platform
+Home-page: https://pluginai.space
+Author: Plugin AI
+Author-email: Plugin AI <support@pluginai.space>
+License: MIT
+Project-URL: Homepage, https://pluginai.space
+Project-URL: Documentation, https://pluginai.space/docs
+Project-URL: Source, https://pluginai.space
+Keywords: pluginai,rag,chatbot,ai,llm,knowledge-base
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: responses>=0.23; extra == "dev"
+Requires-Dist: build>=0.10; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# PluginAI Python SDK
+
+Official Python SDK for the **PluginAI** RAG platform. Turn your documents into
+an intelligent, API-accessible assistant, and query it from any Python app in
+under five minutes.
+
+- 🐍 Pure Python, one dependency (`requests`)
+- 🔁 Synchronous — works in scripts, notebooks, Flask, Django, FastAPI, anywhere
+- 💬 Built-in multi-turn conversation tracking
+- 🧯 Rich, catchable exception hierarchy
+- ✅ Python 3.8 – 3.12
+
+---
+
+## Installation
+
+```bash
+pip install pluginai
+```
+
+---
+
+## Quickstart
+
+```python
+from pluginai import PluginAI
+
+client = PluginAI(
+    api_key="your-api-key",
+    workspace="your-workspace-name",
+)
+
+response = client.query("What is the refund policy?")
+print(response.answer)
+```
+
+`print(response)` also works — a `QueryResponse` stringifies to its answer text.
+
+---
+
+## Multi-turn conversations
+
+Every query from the same client shares one `conversation_id`, so the backend
+keeps context across turns. Start over with `reset_conversation()`.
+
+```python
+client.query("What products do you offer?")
+client.query("Which is cheapest?")     # remembers the previous turn
+
+new_id = client.reset_conversation()   # fresh conversation from here on
+client.query("Let's start over.")
+```
+
+Use it as a context manager to close the HTTP session automatically:
+
+```python
+with PluginAI(api_key="...", workspace="...") as client:
+    print(client.query("Hello").answer)
+```
+
+---
+
+## Agentic queries
+
+For complex, multi-step questions, use `agent_query()` — same signature and
+return type as `query()`, but routed through the Agentic RAG pipeline:
+
+```python
+response = client.agent_query(
+    "Compare the 2023 and 2024 refund policies and summarize what changed."
+)
+```
+
+---
+
+## Configuration
+
+All constructor parameters:
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `api_key` | `str` | **required** | Your workspace API key. |
+| `workspace` | `str` | **required** | The workspace name to query. |
+| `base_url` | `str` | hosted PluginAI API | PluginAI backend URL. Only override if you self-host (trailing slash stripped). |
+| `conversation_id` | `str` | auto-generated | Pass to continue an existing conversation. |
+| `timeout` | `int` | `30` | Per-request timeout, in seconds. |
+| `max_retries` | `int` | `2` | Retries on transient server errors (502/503/504) only. |
+| `on_error` | `callable` | `None` | Called with the exception right before any error is raised. |
+
+---
+
+## The response object
+
+`client.query(...)` returns a `QueryResponse`:
+
+| Attribute / property | Type | Description |
+|---|---|---|
+| `answer` | `str` | The AI-generated answer text. |
+| `status` | `str` | `"success"` or `"no_data"`. |
+| `response_time` | `float` | Seconds the backend took. |
+| `conversation_id` | `str` | The conversation the query belonged to. |
+| `cached` | `bool` | Reserved for future use (always `False`). |
+| `is_success` | `bool` | `True` when `status == "success"`. |
+| `has_data` | `bool` | `False` when `status == "no_data"`. |
+
+---
+
+## Error handling
+
+Every SDK error inherits from `PluginAIError`, so you can catch that one base
+class or handle specific cases:
+
+```python
+from pluginai import (
+    PluginAI,
+    AuthenticationError,
+    NoDataError,
+    QuotaExceededError,
+    TimeoutError,
+    PluginAIError,
+)
+
+try:
+    response = client.query("What is the refund policy?")
+    print(response.answer)
+except AuthenticationError:
+    print("Check your API key.")
+except NoDataError:
+    print("Upload documents to this workspace first.")
+except QuotaExceededError:
+    print("Upgrade your plan.")
+except TimeoutError:
+    print("Increase the `timeout` parameter.")
+except PluginAIError as exc:
+    print(f"Something went wrong: {exc}")
+```
+
+| Exception | Raised when |
+|---|---|
+| `PluginAIError` | Base class for all SDK errors. |
+| `AuthenticationError` | HTTP 401/403 — wrong or inactive API key. |
+| `QuotaExceededError` | HTTP 403 mentioning a quota / usage limit. |
+| `WorkspaceNotFoundError` | HTTP 404 — workspace doesn't exist. |
+| `NoDataError` | Backend returned `status == "no_data"`. |
+| `ConnectionError` | Backend unreachable. |
+| `TimeoutError` | Request exceeded `timeout`. |
+| `RateLimitError` | HTTP 429 — too many requests. |
+| `ServerError` | HTTP 5xx — backend error. |
+
+Every exception carries `.message` (str) and `.status_code` (int or `None`).
+
+---
+
+## Framework integration
+
+See the [`examples/`](examples/) directory for runnable samples:
+
+- [`basic_usage.py`](examples/basic_usage.py)
+- [`multi_turn_conversation.py`](examples/multi_turn_conversation.py)
+- [`error_handling.py`](examples/error_handling.py)
+- [`flask_integration.py`](examples/flask_integration.py)
+- [`django_integration.py`](examples/django_integration.py)
+
+**Tip:** create the client **once** at app startup and reuse it — that keeps the
+connection pool warm instead of paying setup cost on every request.
+
+---
+
+## Development
+
+```bash
+git clone <repo-url>
+cd pluginai-python
+pip install -e ".[dev]"      # or: pip install -r requirements-dev.txt
+pytest tests/
+```
+
+---
+
+## Publishing to PyPI
+
+```bash
+pip install build twine
+python -m build              # builds sdist + wheel into dist/
+pytest tests/                # make sure everything is green
+twine check dist/*
+twine upload dist/*          # prompts for your PyPI token
+```
+
+---
+
+## License
+
+[MIT](LICENSE) © Plugin AI

pluginai-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+pluginai/__init__.py,sha256=o3zvaTvquLuyanp3Ah6TjIJcyEvXJ0FqG4CTC-m0ffw,1107
+pluginai/client.py,sha256=kWpK4Fr4Bh_zOZbpa0zth0v_68qr5QDd04oyxUn_BP0,12899
+pluginai/exceptions.py,sha256=yhAt0skCtlKCLaCXeQJlx1bf0j_W_xNcBhzYsPRPpRY,3026
+pluginai/models.py,sha256=zMDu3VkT37SQNS3HH--jf8Rsto2KTRAKQkCtTIHgbvs,3506
+pluginai/utils.py,sha256=53pxq8dkuOQ-Jh0TvxuAe_csfpUSfx_a27IZ3XvFVSk,3695
+pluginai-1.0.0.dist-info/licenses/LICENSE,sha256=eAGkb790yiMccWHJieRf1lbpNuIzOMd1mb6kAKcy3B0,1066
+pluginai-1.0.0.dist-info/METADATA,sha256=lGycRstlxjcBL2GzxR6az7q6cgPhbVAlQ9b_M_OEEq4,7009
+pluginai-1.0.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+pluginai-1.0.0.dist-info/top_level.txt,sha256=sS-FHsI4QZzDnFc6VlFUp6_IkXqJxQicRqqo9tjDRJE,9
+pluginai-1.0.0.dist-info/RECORD,,

pluginai-1.0.0.dist-info/WHEEL

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

pluginai-1.0.0.dist-info/licenses/LICENSE

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

pluginai-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pluginai