pluginai 1.0.0__tar.gz

pluginai-1.0.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to the `pluginai` Python SDK are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-07-10
+
+### Added
+- Initial public release.
+- `PluginAI` synchronous client with `query()` and `agent_query()` methods.
+- `base_url` defaults to the hosted PluginAI API (`https://api.pluginai.space`),
+  so callers only need to pass `api_key` and `workspace`. Override `base_url`
+  only when self-hosting.
+- Automatic conversation tracking via `conversation_id`, with
+  `reset_conversation()` to start a fresh conversation.
+- Context-manager support (`with PluginAI(...) as client:`).
+- Configurable `timeout`, `max_retries` (transient 502/503/504 only), and an
+  `on_error` callback.
+- `QueryResponse`, `Conversation`, and `ConversationMessage` data models.
+- Full exception hierarchy rooted at `PluginAIError`
+  (`AuthenticationError`, `QuotaExceededError`, `WorkspaceNotFoundError`,
+  `NoDataError`, `ConnectionError`, `TimeoutError`, `RateLimitError`,
+  `ServerError`).
+- Input validation for API keys, workspace names, and queries.
+- Answer parsing tolerant of both `respons` and `response` backend keys.
+- Examples for basic usage, multi-turn conversations, error handling, and
+  Flask / Django integration.
+- Test suite covering the client, models, and exceptions.

pluginai-1.0.0/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/MANIFEST.in

@@ -0,0 +1,9 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include requirements.txt
+include requirements-dev.txt
+recursive-include examples *.py
+recursive-exclude tests *
+global-exclude __pycache__
+global-exclude *.py[cod]

pluginai-1.0.0/PKG-INFO

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

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

@@ -0,0 +1,30 @@
+"""Basic usage: send a single query and inspect the response.
+
+Run with:
+    python examples/basic_usage.py
+
+Set your real credentials below (or read them from environment variables).
+"""
+
+import os
+
+from pluginai import PluginAI
+
+API_KEY = os.getenv("PLUGINAI_API_KEY", "your-api-key")
+WORKSPACE = os.getenv("PLUGINAI_WORKSPACE", "your-workspace")
+
+
+def main() -> None:
+    client = PluginAI(api_key=API_KEY, workspace=WORKSPACE)
+
+    response = client.query("What is the refund policy?")
+
+    print("Answer:", response.answer)
+    print("Response time:", response.response_time, "seconds")
+    print("Success?", response.is_success)
+
+    client.close()
+
+
+if __name__ == "__main__":
+    main()

pluginai-1.0.0/examples/django_integration.py

@@ -0,0 +1,86 @@
+"""Django integration: a /chat view backed by a single shared PluginAI client.
+
+This is a single-file sketch showing the recommended wiring. In a real project,
+split these pieces into their proper Django files (``apps.py``, ``views.py``,
+``urls.py``). The key idea: create the client **once** in ``AppConfig.ready()``
+and reuse it for every request.
+
+--------------------------------------------------------------------------- #
+# myapp/apps.py
+--------------------------------------------------------------------------- #
+
+    import os
+    from django.apps import AppConfig
+    from pluginai import PluginAI
+
+    class MyAppConfig(AppConfig):
+        name = "myapp"
+        pluginai_client = None  # populated in ready()
+
+        def ready(self):
+            # ready() runs once at startup -- ideal for the shared client.
+            MyAppConfig.pluginai_client = PluginAI(
+                api_key=os.getenv("PLUGINAI_API_KEY", "your-api-key"),
+                workspace=os.getenv("PLUGINAI_WORKSPACE", "your-workspace"),
+            )
+
+--------------------------------------------------------------------------- #
+# myapp/views.py
+--------------------------------------------------------------------------- #
+"""
+
+import json
+
+from django.apps import apps
+from django.http import JsonResponse
+from django.views.decorators.csrf import csrf_exempt
+from django.views.decorators.http import require_POST
+
+from pluginai import (
+    AuthenticationError,
+    NoDataError,
+    PluginAIError,
+    QuotaExceededError,
+)
+
+
+@csrf_exempt
+@require_POST
+def chat(request):
+    """POST {"message": "..."} -> {"answer": "..."}."""
+    try:
+        body = json.loads(request.body or b"{}")
+    except json.JSONDecodeError:
+        return JsonResponse({"error": "Invalid JSON body."}, status=400)
+
+    message = body.get("message")
+    if not message:
+        return JsonResponse({"error": "Field 'message' is required."}, status=400)
+
+    # Pull the shared client created in AppConfig.ready().
+    client = apps.get_app_config("myapp").pluginai_client
+
+    try:
+        response = client.query(message)
+        return JsonResponse({"answer": response.answer})
+
+    except NoDataError:
+        return JsonResponse({"error": "No documents indexed."}, status=404)
+    except AuthenticationError:
+        return JsonResponse({"error": "Authentication failed."}, status=401)
+    except QuotaExceededError:
+        return JsonResponse({"error": "Usage quota exceeded."}, status=429)
+    except PluginAIError as exc:
+        return JsonResponse({"error": str(exc)}, status=502)
+
+
+# --------------------------------------------------------------------------- #
+# myapp/urls.py
+# --------------------------------------------------------------------------- #
+#
+#     from django.urls import path
+#     from . import views
+#
+#     urlpatterns = [
+#         path("chat", views.chat, name="chat"),
+#     ]

pluginai-1.0.0/examples/error_handling.py

@@ -0,0 +1,50 @@
+"""Error handling: catch specific exceptions and react appropriately.
+
+Run with:
+    python examples/error_handling.py
+"""
+
+import os
+
+from pluginai import (
+    AuthenticationError,
+    NoDataError,
+    PluginAI,
+    PluginAIError,
+    QuotaExceededError,
+    TimeoutError,
+)
+
+API_KEY = os.getenv("PLUGINAI_API_KEY", "your-api-key")
+WORKSPACE = os.getenv("PLUGINAI_WORKSPACE", "your-workspace")
+
+
+def main() -> None:
+    client = PluginAI(api_key=API_KEY, workspace=WORKSPACE)
+
+    try:
+        response = client.query("What is the refund policy?")
+        print("Answer:", response.answer)
+
+    except AuthenticationError:
+        print("Your API key is invalid or inactive -- double-check it.")
+
+    except NoDataError:
+        print("No documents found -- upload some to this workspace first.")
+
+    except QuotaExceededError:
+        print("You've hit your plan's usage limit -- consider upgrading.")
+
+    except TimeoutError:
+        print("The request timed out -- try increasing the `timeout` parameter.")
+
+    except PluginAIError as exc:
+        # Catch-all for any other SDK error (server errors, rate limits, etc.).
+        print(f"Something went wrong: {exc}")
+
+    finally:
+        client.close()
+
+
+if __name__ == "__main__":
+    main()