quillbot 0.1.0__tar.gz

quillbot-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: quillbot
+Version: 0.1.0
+Summary: Lightweight Python SDK for QuillBot's paraphrasing and summarization APIs.
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Requires-Dist: platformdirs>=4.0.0
+Requires-Dist: mcp>=1.2.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+
+# QuillBot Python SDK
+
+A lightweight, purely HTTP-based Python SDK for interacting with the QuillBot API.
+This SDK allows you to easily integrate QuillBot's paraphrasing and summarizing capabilities into your applications, LLM agents, or command-line tools.
+
+## Features
+
+- **Paraphrasing**: Rewrite text using QuillBot's sophisticated paraphrasing engine.
+- **Bulk Thesaurus**: Automatically fetch synonym suggestions for every word/phrase in the paraphrased text in a single request.
+- **Summarization**: Condense long texts into brief, readable summaries.
+- **Frozen Words**: Prevent specific words or phrases from being altered during paraphrasing.
+- **Pure HTTP**: No browser automation (Selenium/Playwright) required. Fast and lightweight.
+
+## Installation
+
+This SDK requires Python 3.10+.
+
+Clone the repository and install the dependencies (we recommend using a virtual environment):
+
+```bash
+# Example for installing with pip
+pip install -r requirements.txt
+```
+
+If you are using `pytest` for running tests, install it using:
+```bash
+pip install pytest httpx --break-system-packages
+```
+*(Note: `--break-system-packages` may be required on some modern Linux distributions if you are not using a virtual environment.)*
+
+## Authentication
+
+To use the SDK, you need a valid QuillBot `useridtoken`. 
+You can obtain this token by logging into QuillBot in your web browser, opening Developer Tools, and inspecting the cookies or request headers for `useridtoken`.
+
+Create a `.env` file in the root directory and add your token:
+
+```env
+QUILLBOT_USERIDTOKEN=your_actual_token_here
+```
+
+## Quick Start
+
+### Paraphrasing
+
+```python
+from quillbot import QuillBot
+import os
+
+# Initialize the client with your token
+token = os.getenv("QUILLBOT_USERIDTOKEN")
+bot = QuillBot(token)
+
+# Basic Paraphrasing
+text = "The quick brown fox jumps over the lazy dog."
+result = bot.paraphrase(text, strength=9)
+
+print(f"Original: {result.original_text}")
+print(f"Paraphrased: {result.text}")
+print(f"Phrases found: {result.phrases}")
+
+# Accessing Synonym Suggestions (Interactive Editing)
+if result.synonyms:
+    first_word = result.phrases[0]
+    suggestions = result.available_replacements(first_word)
+    print(f"Suggestions for '{first_word}': {suggestions}")
+
+# Paraphrasing with Frozen Words
+frozen_result = bot.paraphrase(
+    "Python is a great programming language.",
+    frozen_words=["Python"]
+)
+```
+
+### Summarization
+
+```python
+long_text = (
+    "Artificial intelligence (AI) is intelligence demonstrated by machines, "
+    "as opposed to the natural intelligence displayed by animals including humans. "
+    "Leading AI textbooks define the field as the study of intelligent agents: "
+    "any system that perceives its environment and takes actions that maximize "
+    "its chance of achieving its goals."
+)
+
+summary = bot.summarize(long_text)
+print("Summary:", summary)
+```
+
+## Core Architecture
+
+The SDK is intentionally designed to be thin and close to the QuillBot API. 
+QuillBot already provides the heavily optimized NLP features (synonym suggestions, phrase grouping, grammar context). The SDK exposes these capabilities rather than reinventing a local document engine.
+
+- The application (your script) is responsible for decision-making (e.g., deciding which word to replace with which synonym).
+- The SDK purely provides the data (rewritten text and synonym maps).
+
+## Running Tests
+
+The test suite runs live integration tests against the actual QuillBot servers (as configured). Mocks are not used to ensure we accurately reflect the live API.
+
+1. Ensure your `.env` contains a valid `QUILLBOT_USERIDTOKEN`.
+2. Run the tests:
+
+```bash
+pytest tests/test_unit.py -v -s
+```
+
+## Disclaimer
+
+This is an unofficial SDK. Use responsibly and ensure you comply with QuillBot's Terms of Service.

quillbot-0.1.0/README.md

@@ -0,0 +1,111 @@
+# QuillBot Python SDK
+
+A lightweight, purely HTTP-based Python SDK for interacting with the QuillBot API.
+This SDK allows you to easily integrate QuillBot's paraphrasing and summarizing capabilities into your applications, LLM agents, or command-line tools.
+
+## Features
+
+- **Paraphrasing**: Rewrite text using QuillBot's sophisticated paraphrasing engine.
+- **Bulk Thesaurus**: Automatically fetch synonym suggestions for every word/phrase in the paraphrased text in a single request.
+- **Summarization**: Condense long texts into brief, readable summaries.
+- **Frozen Words**: Prevent specific words or phrases from being altered during paraphrasing.
+- **Pure HTTP**: No browser automation (Selenium/Playwright) required. Fast and lightweight.
+
+## Installation
+
+This SDK requires Python 3.10+.
+
+Clone the repository and install the dependencies (we recommend using a virtual environment):
+
+```bash
+# Example for installing with pip
+pip install -r requirements.txt
+```
+
+If you are using `pytest` for running tests, install it using:
+```bash
+pip install pytest httpx --break-system-packages
+```
+*(Note: `--break-system-packages` may be required on some modern Linux distributions if you are not using a virtual environment.)*
+
+## Authentication
+
+To use the SDK, you need a valid QuillBot `useridtoken`. 
+You can obtain this token by logging into QuillBot in your web browser, opening Developer Tools, and inspecting the cookies or request headers for `useridtoken`.
+
+Create a `.env` file in the root directory and add your token:
+
+```env
+QUILLBOT_USERIDTOKEN=your_actual_token_here
+```
+
+## Quick Start
+
+### Paraphrasing
+
+```python
+from quillbot import QuillBot
+import os
+
+# Initialize the client with your token
+token = os.getenv("QUILLBOT_USERIDTOKEN")
+bot = QuillBot(token)
+
+# Basic Paraphrasing
+text = "The quick brown fox jumps over the lazy dog."
+result = bot.paraphrase(text, strength=9)
+
+print(f"Original: {result.original_text}")
+print(f"Paraphrased: {result.text}")
+print(f"Phrases found: {result.phrases}")
+
+# Accessing Synonym Suggestions (Interactive Editing)
+if result.synonyms:
+    first_word = result.phrases[0]
+    suggestions = result.available_replacements(first_word)
+    print(f"Suggestions for '{first_word}': {suggestions}")
+
+# Paraphrasing with Frozen Words
+frozen_result = bot.paraphrase(
+    "Python is a great programming language.",
+    frozen_words=["Python"]
+)
+```
+
+### Summarization
+
+```python
+long_text = (
+    "Artificial intelligence (AI) is intelligence demonstrated by machines, "
+    "as opposed to the natural intelligence displayed by animals including humans. "
+    "Leading AI textbooks define the field as the study of intelligent agents: "
+    "any system that perceives its environment and takes actions that maximize "
+    "its chance of achieving its goals."
+)
+
+summary = bot.summarize(long_text)
+print("Summary:", summary)
+```
+
+## Core Architecture
+
+The SDK is intentionally designed to be thin and close to the QuillBot API. 
+QuillBot already provides the heavily optimized NLP features (synonym suggestions, phrase grouping, grammar context). The SDK exposes these capabilities rather than reinventing a local document engine.
+
+- The application (your script) is responsible for decision-making (e.g., deciding which word to replace with which synonym).
+- The SDK purely provides the data (rewritten text and synonym maps).
+
+## Running Tests
+
+The test suite runs live integration tests against the actual QuillBot servers (as configured). Mocks are not used to ensure we accurately reflect the live API.
+
+1. Ensure your `.env` contains a valid `QUILLBOT_USERIDTOKEN`.
+2. Run the tests:
+
+```bash
+pytest tests/test_unit.py -v -s
+```
+
+## Disclaimer
+
+This is an unofficial SDK. Use responsibly and ensure you comply with QuillBot's Terms of Service.

quillbot-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "quillbot"
+version = "0.1.0"
+description = "Lightweight Python SDK for QuillBot's paraphrasing and summarization APIs."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = [
+    "httpx>=0.27",
+    "platformdirs>=4.0.0",
+    "mcp>=1.2.1",
+]
+
+[project.scripts]
+quillbot-mcp = "quillbot.server:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+]

quillbot-0.1.0/quillbot/__init__.py

@@ -0,0 +1,21 @@
+"""quillbot -- Lightweight Python SDK for QuillBot."""
+
+from quillbot.client import QuillBot
+from quillbot.models import ParaphraseResult, SynonymMap, SummarizeResult
+from quillbot.exceptions import (
+    QuillBotError,
+    AuthenticationError,
+    RateLimitError,
+    APIError,
+)
+
+__all__ = [
+    "QuillBot",
+    "ParaphraseResult",
+    "SynonymMap",
+    "SummarizeResult",
+    "QuillBotError",
+    "AuthenticationError",
+    "RateLimitError",
+    "APIError",
+]

quillbot-0.1.0/quillbot/auth.py

@@ -0,0 +1,367 @@
+"""Authentication utilities for the QuillBot SDK.
+
+Supports two authentication methods:
+
+1. **Email/Password** (recommended): Logs in via Firebase Auth and
+   automatically refreshes the token when it expires.
+2. **Raw token**: Directly provide a ``useridtoken`` JWT (manual management).
+
+This module handles credential loading, Firebase login, and token refresh.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import platformdirs
+import re
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+
+from quillbot.exceptions import AuthenticationError
+
+# Firebase project id used by QuillBot.
+_FIREBASE_PROJECT_ID = "paraphraser-472c1"
+
+# Firebase Web API key extracted from QuillBot's frontend source.
+# Stored reversed to prevent false-positive GitHub secret scanning alerts.
+_FIREBASE_API_KEY = "Qk7YTRNxx2URumJwqe6oL-YjGsWgh7XhAySazIA"[::-1]
+
+# Endpoints for Firebase REST Auth.
+_SIGN_IN_URL = (
+    "https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword"
+    f"?key={_FIREBASE_API_KEY}"
+)
+_REFRESH_URL = (
+    "https://securetoken.googleapis.com/v1/token"
+    f"?key={_FIREBASE_API_KEY}"
+)
+
+# Buffer in seconds before the token's actual expiry to trigger a refresh.
+_EXPIRY_BUFFER_SECONDS = 300  # refresh 5 minutes early
+
+
+def _get_cache_path() -> str:
+    """Get the path to the authentication cache file."""
+    if "QUILLBOT_AUTH_FILE" in os.environ:
+        return os.environ["QUILLBOT_AUTH_FILE"]
+    cache_dir = platformdirs.user_cache_dir("quillbot", "quillbot")
+    # ensure directory exists
+    try:
+        os.makedirs(cache_dir, exist_ok=True)
+    except Exception:
+        pass
+    return os.path.join(cache_dir, "auth.json")
+
+
+def _firebase_sign_in(email: str, password: str) -> dict:
+    """Sign in to Firebase with email/password and return the response dict.
+
+    Returns a dict with keys: idToken, refreshToken, expiresIn, localId, etc.
+
+    Raises:
+        AuthenticationError: On invalid credentials or network failure.
+    """
+    payload = json.dumps({
+        "email": email,
+        "password": password,
+        "returnSecureToken": True,
+    }).encode("utf-8")
+
+    req = urllib.request.Request(
+        _SIGN_IN_URL,
+        data=payload,
+        headers={
+            "Content-Type": "application/json",
+            "Referer": "https://quillbot.com/",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        body = exc.read().decode("utf-8", errors="replace")
+        raise AuthenticationError(
+            f"Firebase login failed (HTTP {exc.code}): {body[:300]}"
+        ) from exc
+    except urllib.error.URLError as exc:
+        raise AuthenticationError(
+            f"Firebase login failed (network error): {exc.reason}"
+        ) from exc
+
+
+def _firebase_refresh(refresh_token: str) -> dict:
+    """Exchange a Firebase refresh token for a new id token.
+
+    Returns a dict with keys: id_token, refresh_token, expires_in, etc.
+
+    Raises:
+        AuthenticationError: On invalid refresh token or network failure.
+    """
+    payload = json.dumps({
+        "grant_type": "refresh_token",
+        "refresh_token": refresh_token,
+    }).encode("utf-8")
+
+    req = urllib.request.Request(
+        _REFRESH_URL,
+        data=payload,
+        headers={
+            "Content-Type": "application/json",
+            "Referer": "https://quillbot.com/",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        body = exc.read().decode("utf-8", errors="replace")
+        raise AuthenticationError(
+            f"Firebase token refresh failed (HTTP {exc.code}): {body[:300]}"
+        ) from exc
+    except urllib.error.URLError as exc:
+        raise AuthenticationError(
+            f"Firebase token refresh failed (network error): {exc.reason}"
+        ) from exc
+
+
+def _fetch_account_details(useridtoken: str, local_id: str, email: str) -> dict[str, str | bool | None]:
+    """Fetch the connect.sid session cookie and premium status from Quillbot's backend."""
+    url = "https://quillbot.com/api/auth/get-account-details"
+    payload = {
+        "uid": local_id,
+        "email": email,
+        "fullName": "SDK User",
+        "isSubscribedToEmail": True,
+        "lang": "en-US"
+    }
+    req = urllib.request.Request(
+        url,
+        data=json.dumps(payload).encode("utf-8"),
+        headers={
+            "Content-Type": "application/json",
+            "User-Agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/150.0.0.0 Safari/537.36",
+            "Origin": "https://quillbot.com",
+            "Referer": "https://quillbot.com/login",
+            "platform-type": "webapp",
+            "qb-product": "LOGIN",
+            "useridtoken": useridtoken,
+            "webapp-version": "44.1.0"
+        }
+    )
+    result = {"connect_sid": None, "premium": False}
+    try:
+        with urllib.request.urlopen(req) as resp:
+            cookie_header = resp.info().get("Set-Cookie", "")
+            m = re.search(r'connect\.sid=([^;]+)', cookie_header)
+            if m:
+                result["connect_sid"] = m.group(1)
+            
+            # Parse JSON body to find premium status
+            data = json.loads(resp.read().decode("utf-8"))
+            if "data" in data and "profile" in data["data"]:
+                result["premium"] = data["data"]["profile"].get("premium", False)
+    except Exception:
+        pass
+    return result
+
+
+@dataclass(slots=True)
+class Credentials:
+    """Container for QuillBot authentication state.
+
+    Supports two construction patterns:
+
+    1. ``Credentials.from_login(email, password)`` -- recommended.
+       Performs Firebase login and manages token refresh automatically.
+    2. ``Credentials(useridtoken="...")`` -- manual mode.
+       You are responsible for providing a valid, non-expired token.
+
+    Attributes:
+        useridtoken: Firebase JWT used by QuillBot's API.
+        connect_sid: Express session cookie (optional).
+    """
+
+    useridtoken: str
+    connect_sid: str | None = None
+    is_premium: bool = False
+
+    # Private fields for managing auto-refresh.
+    _email: str | None = field(default=None, repr=False)
+    _password: str | None = field(default=None, repr=False)
+    _refresh_token: str | None = field(default=None, repr=False)
+    _token_expiry: float = field(default=0.0, repr=False)
+
+    @property
+    def can_refresh(self) -> bool:
+        """Return True if this credential set supports automatic refresh."""
+        return self._refresh_token is not None
+
+    @property
+    def is_expired(self) -> bool:
+        """Return True if the token has expired or is about to expire."""
+        if self._token_expiry == 0.0:
+            return False  # manual token mode, no expiry tracking
+        return time.time() >= (self._token_expiry - _EXPIRY_BUFFER_SECONDS)
+
+    def refresh_if_needed(self) -> bool:
+        """Refresh the token if it is expired. Returns True if refreshed."""
+        if not self.can_refresh or not self.is_expired:
+            return False
+        result = _firebase_refresh(self._refresh_token)
+        self.useridtoken = result["id_token"]
+        self._refresh_token = result["refresh_token"]
+        self._token_expiry = time.time() + int(result.get("expires_in", 3600))
+        
+        # Save updated tokens to cache
+        cache_path = _get_cache_path()
+        try:
+            if os.path.exists(cache_path):
+                with open(cache_path, "r", encoding="utf-8") as f:
+                    data = json.load(f)
+                data["useridtoken"] = self.useridtoken
+                data["refresh_token"] = self._refresh_token
+                data["token_expiry"] = self._token_expiry
+                with open(cache_path, "w", encoding="utf-8") as f:
+                    json.dump(data, f, indent=4)
+        except Exception:
+            pass
+            
+        return True
+
+    # -- factory helpers -----------------------------------------------------
+
+    @classmethod
+    def from_login(cls, email: str, password: str) -> "Credentials":
+        """Authenticate with QuillBot using email and password.
+
+        First attempts to load cached credentials from the user's cache dir.
+        If missing, expired, or invalid, performs a Firebase signInWithPassword.
+
+        Args:
+            email: QuillBot account email.
+            password: QuillBot account password.
+
+        Returns:
+            A Credentials instance with auto-refresh enabled.
+
+        Raises:
+            AuthenticationError: On invalid email/password.
+        """
+        cache_path = _get_cache_path()
+        try:
+            if os.path.exists(cache_path):
+                with open(cache_path, "r", encoding="utf-8") as f:
+                    data = json.load(f)
+                
+                # Use cache only if the email matches
+                if data.get("email") == email:
+                    creds = cls(
+                        useridtoken=data["useridtoken"],
+                        connect_sid=data.get("connect_sid"),
+                        is_premium=data.get("is_premium", False),
+                        _email=email,
+                        _password=password,
+                        _refresh_token=data.get("refresh_token"),
+                        _token_expiry=data.get("token_expiry", 0.0),
+                    )
+                    # Automatically refresh the cached token if it's expired
+                    creds.refresh_if_needed()
+                    return creds
+        except Exception:
+            pass  # Fallback to normal login
+
+        result = _firebase_sign_in(email, password)
+        useridtoken = result["idToken"]
+        local_id = result.get("localId", "")
+        account_details = _fetch_account_details(useridtoken, local_id, email)
+        
+        expiry = time.time() + int(result.get("expiresIn", 3600))
+        
+        # Save to cache
+        try:
+            with open(cache_path, "w", encoding="utf-8") as f:
+                json.dump({
+                    "email": email,
+                    "useridtoken": useridtoken,
+                    "connect_sid": account_details["connect_sid"],
+                    "is_premium": account_details["premium"],
+                    "refresh_token": result["refreshToken"],
+                    "token_expiry": expiry,
+                }, f, indent=4)
+        except Exception:
+            pass
+
+        return cls(
+            useridtoken=useridtoken,
+            connect_sid=account_details["connect_sid"],
+            is_premium=account_details["premium"],
+            _email=email,
+            _password=password,
+            _refresh_token=result["refreshToken"],
+            _token_expiry=expiry,
+        )
+
+    @classmethod
+    def from_env(
+        cls,
+        email_var: str = "QUILLBOT_EMAIL",
+        password_var: str = "QUILLBOT_PASSWORD",
+        token_var: str = "QUILLBOT_TOKEN",
+        sid_var: str = "QUILLBOT_SID",
+    ) -> "Credentials":
+        """Build credentials from environment variables.
+
+        If QUILLBOT_EMAIL and QUILLBOT_PASSWORD are set, performs a
+        Firebase login (preferred). Otherwise falls back to QUILLBOT_TOKEN.
+
+        Args:
+            email_var: Env var for the email address.
+            password_var: Env var for the password.
+            token_var: Fallback env var for a raw useridtoken.
+            sid_var: Env var for the connect.sid cookie.
+
+        Raises:
+            ValueError: If neither email/password nor token is available.
+        """
+        email = os.environ.get(email_var, "").strip()
+        password = os.environ.get(password_var, "").strip()
+
+        if email and password:
+            creds = cls.from_login(email, password)
+            sid = os.environ.get(sid_var, "").strip() or None
+            if sid:
+                creds.connect_sid = sid
+            return creds
+
+        token = os.environ.get(token_var, "").strip()
+        if not token:
+            raise ValueError(
+                f"Set {email_var!r} + {password_var!r} for auto-login, "
+                f"or set {token_var!r} with a raw useridtoken."
+            )
+        sid = os.environ.get(sid_var, "").strip() or None
+        return cls(useridtoken=token, connect_sid=sid)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, str]) -> "Credentials":
+        """Build credentials from a plain dictionary.
+
+        Accepts ``email`` + ``password`` (preferred) or ``useridtoken``.
+        """
+        email = data.get("email", "").strip()
+        password = data.get("password", "").strip()
+        if email and password:
+            return cls.from_login(email, password)
+
+        token = data.get("useridtoken", "").strip()
+        if not token:
+            raise ValueError(
+                "'email'+'password' or 'useridtoken' is required."
+            )
+        return cls(
+            useridtoken=token,
+            connect_sid=data.get("connect_sid"),
+        )