quillbot 0.1.0__py3-none-any.whl

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/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"),
+        )

quillbot/client.py

@@ -0,0 +1,286 @@
+"""Public API for the QuillBot SDK.
+
+Usage::
+
+    from quillbot import QuillBot
+
+    bot = QuillBot(useridtoken="...")
+    result = bot.paraphrase("The quick brown fox jumps over the lazy dog.")
+    print(result.paraphrased_text)
+    print(result.synonyms)
+
+The ``QuillBot`` class is the only object most users need to import.
+Internally it delegates to the HTTP client and endpoint wrappers.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from quillbot.auth import Credentials
+from quillbot.http import HttpClient
+from quillbot import endpoints
+from quillbot.models import ParaphraseResult, SummarizeResult, SynonymMap
+
+
+class QuillBot:
+    """Lightweight client that exposes QuillBot's capabilities over HTTP.
+
+    This class owns an authenticated HTTP session and provides methods that
+    mirror QuillBot's features: paraphrasing, synonym retrieval, and
+    summarisation.
+
+    It does *not* contain any decision-making logic.  The caller decides
+    which word to replace, which suggestion to pick, and how many
+    iterations to run.
+
+    Construction patterns::
+
+        # Recommended: email + password (auto-refreshes tokens)
+        bot = QuillBot(email="user@example.com", password="secret")
+
+        # Legacy: raw token (you manage expiry)
+        bot = QuillBot(useridtoken="eyJ...")
+
+    Args:
+        email: QuillBot account email (used with ``password``).
+        password: QuillBot account password (used with ``email``).
+        useridtoken: Raw Firebase JWT (alternative to email/password).
+        connect_sid: Express ``connect.sid`` session cookie (optional).
+        timeout: HTTP request timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        useridtoken: str | None = None,
+        *,
+        email: str | None = None,
+        password: str | None = None,
+        connect_sid: str | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        if email and password:
+            self._creds = Credentials.from_login(email, password)
+        elif useridtoken:
+            self._creds = Credentials(
+                useridtoken=useridtoken, connect_sid=connect_sid,
+            )
+        else:
+            raise ValueError(
+                "Provide either email + password, or a useridtoken."
+            )
+        if connect_sid:
+            self._creds.connect_sid = connect_sid
+        self._timeout = timeout
+        self._http = HttpClient(self._creds, timeout=timeout)
+
+    def _ensure_fresh_token(self) -> None:
+        """Refresh the Firebase token if expired and rebuild the HTTP client."""
+        if self._creds.refresh_if_needed():
+            self._http.close()
+            self._http = HttpClient(self._creds, timeout=self._timeout)
+
+    # -- lifecycle -----------------------------------------------------------
+
+    def close(self) -> None:
+        """Release the underlying HTTP connection pool."""
+        self._http.close()
+
+    @property
+    def is_premium(self) -> bool:
+        """Return True if the authenticated account has Premium status."""
+        return self._creds.is_premium
+
+    def __enter__(self) -> "QuillBot":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    # -- paraphrasing --------------------------------------------------------
+
+    def paraphrase(
+        self,
+        text: str,
+        *,
+        mode: int = 99,
+        strength: int = 9,
+        frozen_words: list[str] | None = None,
+        fetch_synonyms: bool = True,
+    ) -> ParaphraseResult:
+        """Paraphrase *text* and optionally pre-fetch synonyms.
+
+        Args:
+            text: The sentence or paragraph to rewrite.
+            mode: QuillBot mode id (99=Custom, 0=Standard, etc.).
+            strength: Rewriting aggressiveness (0-10).
+            frozen_words: Words that must not be changed.
+            fetch_synonyms: When ``True`` (default), automatically call the
+                thesaurus endpoint to populate ``result.synonyms``.
+
+        Returns:
+            A :class:`ParaphraseResult` containing the rewritten text,
+            alternative candidates, and (if requested) a pre-fetched
+            synonym map.
+        """
+        self._ensure_fresh_token()
+        raw = endpoints.single_paraphrase(
+            self._http,
+            text,
+            mode=mode,
+            strength=strength,
+            frozen_words=frozen_words,
+        )
+
+        # Extract the primary paraphrase and alternatives from the response.
+        paraphrased_text, alternatives, phrases = self._parse_paraphrase(raw)
+
+        # Optionally fetch bulk synonyms for the paraphrased output.
+        synonyms: SynonymMap = {}
+        if fetch_synonyms and phrases:
+            synonyms = self._fetch_thesaurus(paraphrased_text, phrases, mode=mode)
+
+        return ParaphraseResult(
+            original_text=text,
+            paraphrased_text=paraphrased_text,
+            alternatives=alternatives,
+            synonyms=synonyms,
+            phrases=phrases,
+            raw=raw,
+        )
+
+    # -- synonyms ------------------------------------------------------------
+
+    def get_synonyms(
+        self,
+        text: str,
+        phrases: list[str],
+        *,
+        mode: int = 99,
+    ) -> SynonymMap:
+        """Fetch context-aware synonyms for a sentence.
+
+        This mirrors the ``paraphrase-phrase`` endpoint that the QuillBot
+        frontend calls when a user clicks a word.
+
+        Args:
+            text: The full sentence.
+            phrases: The chunked phrases (as returned in
+                :attr:`ParaphraseResult.phrases`).
+            mode: Paraphrase mode id.
+
+        Returns:
+            A :data:`SynonymMap` mapping each phrase to its suggestions.
+        """
+        self._ensure_fresh_token()
+        raw = endpoints.paraphrase_phrase(
+            self._http, text, phrases, mode=mode
+        )
+        suggestions: dict[str, list[str]] = (
+            raw.get("data", {}).get("suggestions", {})
+        )
+        return suggestions
+
+    # -- summarisation -------------------------------------------------------
+
+    def summarize(
+        self,
+        text: str,
+        *,
+        summary_type: str = "abs",
+        ratio: float = 0.2,
+        length: str = "short",
+    ) -> SummarizeResult:
+        """Summarize *text*.
+
+        Args:
+            text: The text to condense.
+            summary_type: ``"abs"`` (abstractive) or ``"key"`` (extractive).
+            ratio: Target compression ratio (0.0-1.0).
+            length: Desired length hint (``"short"``, ``"concise"``, ``"long"``).
+
+        Returns:
+            A :class:`SummarizeResult` containing the summary.
+        """
+        self._ensure_fresh_token()
+        raw = endpoints.summarize(
+            self._http,
+            text,
+            summary_type=summary_type,
+            ratio=ratio,
+            length=length,
+        )
+        summary = raw.get("data", {}).get("summary", "")
+        return SummarizeResult(
+            original_text=text,
+            summary=summary,
+            summary_type=summary_type,
+            raw=raw,
+        )
+
+    # -- internal helpers ----------------------------------------------------
+
+    @staticmethod
+    def _parse_paraphrase(
+        raw: dict[str, Any],
+    ) -> tuple[str, list[str], list[str]]:
+        """Extract text, alternatives, and phrases from the raw response.
+
+        The response structure from ``/single-paraphrase`` nests the
+        paraphrased sentences inside ``data[].paras_<N>[].alt`` where
+        ``<N>`` varies by mode (e.g. ``paras_100`` for mode 99).
+
+        Returns:
+            A tuple of (primary_text, alternative_texts, phrase_tokens).
+        """
+        data_list = raw.get("data", [])
+        if not data_list:
+            return "", [], []
+
+        first_entry = data_list[0] if isinstance(data_list, list) else data_list
+
+        # Find the paras_* key dynamically (paras_10, paras_100, etc.)
+        paras: list[dict[str, Any]] = []
+        for key, value in first_entry.items():
+            if key.startswith("paras_") and isinstance(value, list):
+                paras = value
+                break
+
+        primary = paras[0].get("alt", "") if paras else ""
+        alternatives = [p.get("alt", "") for p in paras[1:]]
+
+        # QuillBot also returns segmentation data we can use as phrases.
+        segments = first_entry.get("segments", {})
+        phrases_data = segments.get("phrases", [])
+        phrases = [p.get("phrase", "") for p in phrases_data] if phrases_data else []
+
+        # If no segments in the response, split the primary text on whitespace
+        # as a fallback so the thesaurus endpoint still works.
+        if not phrases and primary:
+            phrases = primary.split()
+
+        return primary, alternatives, phrases
+
+    def _fetch_thesaurus(
+        self,
+        text: str,
+        phrases: list[str],
+        *,
+        mode: int = 99,
+    ) -> SynonymMap:
+        """Call the bulk thesaurus endpoint and merge the result."""
+        raw = endpoints.paraphrase_thesaurus(
+            self._http,
+            phrases=phrases,
+            mode=mode,
+        )
+        # The response nests suggestions differently than paraphrase-phrase.
+        # It returns per-sentence data; we merge all of them.
+        synonyms: SynonymMap = {}
+        data = raw.get("data", {})
+        if isinstance(data, list):
+            for entry in data:
+                synonyms.update(entry.get("suggestions", {}))
+        elif isinstance(data, dict):
+            synonyms.update(data.get("suggestions", {}))
+        return synonyms

quillbot/endpoints.py

@@ -0,0 +1,212 @@
+"""Raw endpoint wrappers for QuillBot's HTTP API.
+
+Each function maps 1-to-1 to a QuillBot API endpoint.  They accept an
+``HttpClient``, build the correct payload, call the endpoint, and return
+the raw JSON dict.  No response parsing happens here -- that is the job
+of ``client.py`` which converts raw dicts into typed ``models``.
+
+Keeping endpoint wrappers separate makes it easy to add new endpoints
+later without touching the public API or response parsing.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from quillbot.http import HttpClient
+
+
+# ---------------------------------------------------------------------------
+# Paraphraser
+# ---------------------------------------------------------------------------
+
+_PARAPHRASER_HEADERS = {
+    "platform-type": "webapp",
+    "qb-product": "PARAPHRASER",
+    "qb-dialect": "en-us",
+    "referer": "https://quillbot.com/paraphrasing-tool",
+}
+
+
+def single_paraphrase(
+    client: HttpClient,
+    text: str,
+    *,
+    mode: int = 99,
+    strength: int = 9,
+    frozen_words: list[str] | None = None,
+    dialect: str = "US",
+    input_lang: str = "en",
+) -> dict[str, Any]:
+    """Call ``POST /api/paraphraser/single-paraphrase/{mode}``.
+
+    Args:
+        client: Authenticated HTTP client.
+        text: The sentence to paraphrase.
+        mode: Paraphrase mode id (99 = Custom, 0 = Standard, etc.).
+        strength: Rewriting aggressiveness. Valid values:
+            0, 2, 6, 7, 8, 9, 10, 12, 13, 15, 16, 99, 100, 101, 201, 202, 203.
+        frozen_words: Words to leave unchanged.
+        dialect: Target English dialect (``"US"`` or ``"UK"``).
+        input_lang: Source language code.
+
+    Returns:
+        Raw JSON response dict.
+    """
+    payload: dict[str, Any] = {
+        "text": text,
+        "strength": strength,
+        "autoflip": False,
+        "wikify": False,
+        "fthresh": -1,
+        "inputLang": input_lang,
+        "quoteIndex": -1,
+        "frozenWords": frozen_words or [],
+        "nBeams": 4,
+        "freezeQuotes": True,
+        "preferActive": False,
+        "dialect": dialect,
+        "promptVersion": "v2",
+        "multilingualModelVersion": "v2",
+    }
+    return client.post_json(
+        f"/api/paraphraser/single-paraphrase/{mode}",
+        payload,
+        extra_headers=_PARAPHRASER_HEADERS,
+    )
+
+
+def paraphrase_thesaurus(
+    client: HttpClient,
+    phrases: list[str],
+    *,
+    mode: int = 99,
+) -> dict[str, Any]:
+    """Call ``POST /api/paraphraser/paraphrase-thesaurus``.
+
+    Fetches bulk synonyms for the phrases in the paraphrased output.
+
+    Args:
+        client: Authenticated HTTP client.
+        phrases: List of phrase strings.
+        mode: Paraphrase mode id.
+
+    Returns:
+        Raw JSON response dict.
+    """
+    payload: dict[str, Any] = {
+        "phrases": phrases,
+        "mode": mode,
+    }
+    return client.post_json(
+        "/api/paraphraser/paraphrase-thesaurus",
+        payload,
+        extra_headers=_PARAPHRASER_HEADERS,
+    )
+
+
+def paraphrase_phrase(
+    client: HttpClient,
+    text: str,
+    phrases: list[str],
+    *,
+    mode: int = 99,
+    w1: float = 0.6,
+    w2: float = 0.4,
+) -> dict[str, Any]:
+    """Call ``POST /api/utils/paraphrase-phrase``.
+
+    Fetches context-aware synonyms for a specific sentence.
+
+    Args:
+        client: Authenticated HTTP client.
+        text: The full sentence containing the word.
+        phrases: The chunked phrases of the sentence.
+        mode: Paraphrase mode id.
+        w1: Weight parameter (controls suggestion style).
+        w2: Weight parameter (controls suggestion style).
+
+    Returns:
+        Raw JSON response dict.
+    """
+    payload: dict[str, Any] = {
+        "phrases": phrases,
+        "text": text,
+        "w1": w1,
+        "w2": w2,
+        "mode": mode,
+    }
+    return client.post_json(
+        "/api/utils/paraphrase-phrase",
+        payload,
+        extra_headers=_PARAPHRASER_HEADERS,
+    )
+
+
+def chunker(
+    client: HttpClient,
+    text: str,
+) -> dict[str, Any]:
+    """Call ``POST /api/paraphraser/chunker``.
+
+    Splits a sentence into the phrase tokens that QuillBot uses for
+    synonym lookups and rendering.
+
+    Args:
+        client: Authenticated HTTP client.
+        text: The sentence to tokenize.
+
+    Returns:
+        Raw JSON response dict containing ``data.segments.phrases``.
+    """
+    payload: dict[str, Any] = {"text": text}
+    return client.post_json(
+        "/api/paraphraser/chunker",
+        payload,
+        extra_headers=_PARAPHRASER_HEADERS,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Summarizer
+# ---------------------------------------------------------------------------
+
+_SUMMARIZER_HEADERS = {
+    "platform-type": "webapp",
+    "qb-product": "SUMMARIZER",
+    "referer": "https://quillbot.com/summarize",
+}
+
+
+def summarize(
+    client: HttpClient,
+    text: str,
+    *,
+    summary_type: str = "abs",
+    ratio: float = 0.2,
+    length: str = "short",
+) -> dict[str, Any]:
+    """Call ``POST /api/summarizer/summarize-para/{summary_type}``.
+
+    Args:
+        client: Authenticated HTTP client.
+        text: The text to summarize.
+        summary_type: Algorithm -- ``"abs"`` (abstractive) or ``"key"``
+            (key-sentences / extractive).
+        ratio: Target compression ratio (0.0-1.0).
+        length: Desired length hint (``"short"``, ``"concise"``, ``"long"``).
+
+    Returns:
+        Raw JSON response dict.
+    """
+    payload: dict[str, Any] = {
+        "para": text,
+        "type": summary_type,
+        "ratio": ratio,
+        "length": length,
+    }
+    return client.post_json(
+        f"/api/summarizer/summarize-para/{summary_type}",
+        payload,
+        extra_headers=_SUMMARIZER_HEADERS,
+    )

quillbot/exceptions.py

@@ -0,0 +1,42 @@
+"""Custom exceptions for the QuillBot SDK.
+
+Every exception inherits from QuillBotError so callers can catch broadly
+or narrowly as they prefer.
+"""
+
+
+class QuillBotError(Exception):
+    """Base exception for all QuillBot SDK errors."""
+
+
+class AuthenticationError(QuillBotError):
+    """Raised when the useridtoken is missing, expired, or rejected (HTTP 401/408)."""
+
+
+class RateLimitError(QuillBotError):
+    """Raised when QuillBot returns rate-limit headers or HTTP 429.
+
+    Attributes:
+        retry_after: Seconds to wait before retrying, if the server provided
+                     a Retry-After header.
+    """
+
+    def __init__(self, message: str, retry_after: int | None = None) -> None:
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class APIError(QuillBotError):
+    """Raised for any unexpected HTTP error from the QuillBot backend.
+
+    Attributes:
+        status_code: The HTTP status code returned.
+        body: The raw response body, if available.
+    """
+
+    def __init__(
+        self, message: str, status_code: int, body: str | None = None
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body

quillbot/http.py

@@ -0,0 +1,132 @@
+"""Low-level HTTP transport for the QuillBot SDK.
+
+Wraps ``httpx.Client`` with the exact headers, cookies, and error handling
+that QuillBot's Node.js backend expects.  Every request is routed through
+``post_json`` which handles authentication headers, response parsing, and
+error translation into SDK exceptions.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from quillbot.auth import Credentials
+from quillbot.exceptions import APIError, AuthenticationError, RateLimitError
+
+# The base URL shared by all QuillBot API endpoints.
+BASE_URL = "https://quillbot.com"
+
+# Default headers that every request must carry.
+_DEFAULT_HEADERS: dict[str, str] = {
+    "user-agent": (
+        "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
+        "(KHTML, like Gecko) Chrome/150.0.0.0 Safari/537.36"
+    ),
+    "accept": "application/json, text/plain, */*",
+    "content-type": "application/json",
+    "origin": BASE_URL,
+    "webapp-version": "44.1.0",
+}
+
+
+class HttpClient:
+    """Thin wrapper around ``httpx.Client`` tuned for QuillBot.
+
+    This class is an internal implementation detail.  Users interact with
+    the public ``QuillBot`` class in ``client.py``.
+    """
+
+    def __init__(self, credentials: Credentials, timeout: float = 30.0) -> None:
+        cookies: dict[str, str] = {
+            "useridtoken": credentials.useridtoken,
+        }
+        if credentials.connect_sid:
+            cookies["connect.sid"] = credentials.connect_sid
+
+        headers = {
+            **_DEFAULT_HEADERS,
+            "useridtoken": credentials.useridtoken,
+        }
+
+        self._client = httpx.Client(
+            base_url=BASE_URL,
+            headers=headers,
+            cookies=cookies,
+            timeout=timeout,
+            follow_redirects=True,
+        )
+
+    # -- public interface ----------------------------------------------------
+
+    def post_json(
+        self,
+        path: str,
+        payload: dict[str, Any],
+        *,
+        extra_headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """Send a JSON POST and return the parsed response body.
+
+        Args:
+            path: API path relative to BASE_URL (e.g. ``/api/paraphraser/...``).
+            payload: JSON-serialisable request body.
+            extra_headers: Per-request header overrides.
+
+        Returns:
+            The parsed JSON response as a dict.
+
+        Raises:
+            AuthenticationError: On 401 or 408 (SESSION_FAILED).
+            RateLimitError: On 429 or when ``x-ratelimit-limit`` is exceeded.
+            APIError: On any other non-2xx response.
+        """
+        headers = extra_headers or {}
+        response = self._client.post(path, json=payload, headers=headers)
+        return self._handle_response(response)
+
+    def close(self) -> None:
+        """Release the underlying connection pool."""
+        self._client.close()
+
+    # -- context manager -----------------------------------------------------
+
+    def __enter__(self) -> "HttpClient":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    # -- internal ------------------------------------------------------------
+
+    @staticmethod
+    def _handle_response(response: httpx.Response) -> dict[str, Any]:
+        """Translate HTTP status codes into SDK exceptions."""
+        status = response.status_code
+
+        if 200 <= status < 300:
+            return response.json()
+
+        body = response.text
+
+        if status in (401, 408):
+            raise AuthenticationError(
+                f"Authentication failed (HTTP {status}). "
+                "Your useridtoken may be expired. "
+                f"Response: {body[:200]}"
+            )
+
+        if status == 429:
+            retry_after_raw = response.headers.get("retry-after")
+            retry_after = int(retry_after_raw) if retry_after_raw else None
+            raise RateLimitError(
+                f"Rate limited (HTTP 429). Retry after {retry_after}s.",
+                retry_after=retry_after,
+            )
+
+        raise APIError(
+            f"QuillBot API error (HTTP {status}): {body[:300]}",
+            status_code=status,
+            body=body,
+        )

quillbot/models.py

@@ -0,0 +1,79 @@
+"""Data models for QuillBot API responses.
+
+These are simple, immutable containers that stay close to what QuillBot
+returns.  They carry the data and provide thin helper methods -- no
+decision-making logic.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+# ---------------------------------------------------------------------------
+# Synonym helpers
+# ---------------------------------------------------------------------------
+
+SynonymMap = dict[str, list[str]]
+"""Mapping of word/phrase to its list of synonym suggestions.
+
+Example::
+
+    {"agile": ["fast", "quick", "nimble"], "fox": ["hound", "feline"]}
+"""
+
+
+# ---------------------------------------------------------------------------
+# Paraphrase
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class ParaphraseResult:
+    """Result returned by :meth:`QuillBot.paraphrase`.
+
+    Attributes:
+        original_text: The text that was submitted.
+        paraphrased_text: The rewritten text returned by QuillBot.
+        alternatives: Other paraphrase candidates (may be empty).
+        synonyms: Pre-fetched synonym map for words in the paraphrased text.
+            Populated automatically from the ``paraphrase-thesaurus`` bulk
+            endpoint so callers can inspect available replacements without
+            making another network call.
+        phrases: The chunked phrases that QuillBot uses internally.
+        raw: The full raw JSON response from ``/single-paraphrase``, kept
+            for debugging and forward-compatibility.
+    """
+
+    original_text: str
+    paraphrased_text: str
+    alternatives: list[str] = field(default_factory=list)
+    synonyms: SynonymMap = field(default_factory=dict)
+    phrases: list[str] = field(default_factory=list)
+    raw: dict = field(default_factory=dict, repr=False)
+
+    def available_replacements(self, word: str) -> list[str]:
+        """Return the synonym list for *word*, or an empty list."""
+        return self.synonyms.get(word, [])
+
+
+# ---------------------------------------------------------------------------
+# Summarize
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class SummarizeResult:
+    """Result returned by :meth:`QuillBot.summarize`.
+
+    Attributes:
+        original_text: The text that was submitted.
+        summary: The condensed text returned by QuillBot.
+        summary_type: The summarisation algorithm used (e.g. ``"abs"``).
+        raw: The full raw JSON response.
+    """
+
+    original_text: str
+    summary: str
+    summary_type: str = "abs"
+    raw: dict = field(default_factory=dict, repr=False)

quillbot/server.py

@@ -0,0 +1,61 @@
+import os
+from mcp.server.fastmcp import FastMCP
+from quillbot import QuillBot
+
+# Create an MCP server instance
+mcp = FastMCP("QuillBot")
+
+_bot = None
+
+def get_bot() -> QuillBot:
+    """Lazily initialize the QuillBot client."""
+    global _bot
+    if _bot is None:
+        email = os.environ.get("QUILLBOT_EMAIL")
+        password = os.environ.get("QUILLBOT_PASSWORD")
+        if not email or not password:
+            raise RuntimeError(
+                "Please set QUILLBOT_EMAIL and QUILLBOT_PASSWORD environment variables."
+            )
+        _bot = QuillBot(email, password)
+    return _bot
+
+@mcp.tool()
+def paraphrase(text: str, mode: int = 0, strength: int = 2) -> str:
+    """
+    Paraphrase text using QuillBot.
+
+    Args:
+        text: The text to paraphrase.
+        mode: The paraphrasing mode (0=Standard, 1=Fluency, 6=Shorten, 9=Formal). Default is 0.
+        strength: The aggressiveness of the paraphrasing (0-10). Default is 2.
+    """
+    bot = get_bot()
+    try:
+        # Note: Free accounts may only have access to mode=0 (Standard) and mode=1 (Fluency).
+        result = bot.paraphrase(text, mode=mode, strength=strength)
+        return result.paraphrased_text
+    except Exception as e:
+        return f"Error paraphrasing text: {e}"
+
+@mcp.tool()
+def summarize(text: str) -> str:
+    """
+    Summarize text using QuillBot.
+
+    Args:
+        text: The long text or paragraph to summarize.
+    """
+    bot = get_bot()
+    try:
+        result = bot.summarize(text)
+        return result.summary_text
+    except Exception as e:
+        return f"Error summarizing text: {e}"
+
+def main():
+    """Entry point for the MCP server."""
+    mcp.run()
+
+if __name__ == "__main__":
+    main()

quillbot-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+quillbot/__init__.py,sha256=99xyCjavsyEeI6oM5syK8BtfJ1nXlH-AL4VLT5359aU,463
+quillbot/auth.py,sha256=HMExcrWSJLWrvZeGNRsEljjwdgEFeqVtaLCrhykpaXA,13093
+quillbot/client.py,sha256=Fjn2XwkCV3DPPXRsrKl8ufBDpgS8G07EihZz4iU5Ogo,9546
+quillbot/endpoints.py,sha256=bc_YmsIAuqUj0x5RZtGVZN3L64mUd6mTnY-bCXkIN68,5735
+quillbot/exceptions.py,sha256=Tz_A0o-eG6k1vLqTccPBfKjiZCBSGgTtIJHs-xdSSgE,1206
+quillbot/http.py,sha256=ukWj9iHJwa97-EQY_qc1ikYOGd-IdmUOdYsfKN8GJIc,4182
+quillbot/models.py,sha256=qL4H5snsoUnWHArCA30NrVUx3TwPboXyNowPZ17HsbU,2717
+quillbot/server.py,sha256=cKx5EKp2AytwGGOoyQCdAXQza7sHrj2qCj6Pdf8t7-0,1705
+quillbot-0.1.0.dist-info/METADATA,sha256=9zQFcPdN0QKDLVvqToYfwGXQV_kuBADo7TVC7TnMCCk,4222
+quillbot-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+quillbot-0.1.0.dist-info/entry_points.txt,sha256=5ahPNfafJk9-Om436P9Isp2R5OaHWhrT0hJipSv0Oug,54
+quillbot-0.1.0.dist-info/top_level.txt,sha256=Knc40gaC5aNg8yGglQfhQpXXopNkq5XFQoBG42eoneE,9
+quillbot-0.1.0.dist-info/RECORD,,

quillbot-0.1.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
+

quillbot-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+quillbot-mcp = quillbot.server:main

quillbot-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+quillbot