quillbot 1.0.0

A comprehensive Python SDK for the QuillBot API.

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, translation, and summarizing capabilities into your applications, LLM agents, or command-line tools. It automatically handles token refreshing, payload formatting, and concurrent chunking of very large texts, fully mimicking the live web application.

Features

• Paraphrasing: Rewrite text using QuillBot's sophisticated paraphrasing engine. Supports all premium modes including the new AI Humanizer.
• Large Text Support: Send texts of any size (even thousands of words)! The SDK will automatically chunk the text by sentences and process them concurrently, merging the results back together seamlessly.
• Synonym Levels: Adjust the synonyms_level (0-3) to control the vocabulary replacement strength, identical to the website's Synonyms slider.
• Translation: Translate text into over 30 languages using the integrated translation 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. Extremely fast and lightweight.

Installation

This SDK requires Python 3.10+.

The package is available on PyPI. You can view the project at https://pypi.org/project/quillbot/.

To install the latest version, simply run:

pip install quillbot

Authentication

We highly recommend using email and password authentication. The SDK will automatically fetch, manage, and refresh the necessary JWT tokens in the background, keeping your session alive.

import os
from quillbot import QuillBot

email = os.getenv("QUILLBOT_EMAIL")
password = os.getenv("QUILLBOT_PASSWORD")

# Initialize the client (auto-authenticates and manages tokens)
bot = QuillBot(email=email, password=password)

print(f"Logged in successfully! Premium active: {bot.is_premium}")

You can optionally pass a static token directly if you prefer:

bot = QuillBot(useridtoken="your_static_jwt_token")

Quick Start

Paraphrasing and AI Humanizer

You can paraphrase text across multiple modes, such as ParaphraseMode.STANDARD, ParaphraseMode.FLUENCY, ParaphraseMode.FORMAL, or the new ParaphraseMode.HUMANIZER.

from quillbot.endpoints import ParaphraseMode

text = "The quick brown fox jumps over the lazy dog."

# Standard Paraphrasing with Synonyms Level 2
result = bot.paraphrase(text, mode=ParaphraseMode.STANDARD, synonyms_level=2)
print(f"Paraphrased: {result.text}")

# AI Humanizer
humanized_result = bot.paraphrase(text, mode=ParaphraseMode.HUMANIZER)
print(f"Humanized: {humanized_result.text}")

# Custom Modes
custom_result = bot.paraphrase(text, mode=ParaphraseMode.CUSTOM, custom_mode_name="Shakespearean")
print(f"Custom Output: {custom_result.text}")

# View the individual phrases that were rewritten
print(f"Phrases found: {result.phrases}")

Translation

You can supply the input_lang parameter to translate your output into one of the many supported languages.

from quillbot.endpoints import Language, ParaphraseMode

english_text = "Hello world! This SDK is amazing."

# Translate to French
result = bot.paraphrase(
    english_text, 
    mode=ParaphraseMode.STANDARD, 
    input_lang=Language.FRENCH
)

print(f"French Translation: {result.text}")

Interactive Editing (Synonym Suggestions)

By default, the SDK automatically fetches thesaurus data for the rewritten text. You can retrieve alternative synonyms for specific words or phrases.

if result.synonyms:
    first_word = result.phrases[0]
    suggestions = result.available_replacements(first_word)
    print(f"Suggestions for '{first_word}': {suggestions}")

Frozen Words

You can protect certain words or phrases from being altered.

frozen_result = bot.paraphrase(
    "Python is a great programming language.",
    frozen_words=["Python", "programming"]
)

Summarization

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.summary)

Model Context Protocol (MCP) Server

This SDK includes a fully featured MCP Server that allows AI assistants (like Claude Desktop, Cursor, and Google Antigravity) to directly use QuillBot's paraphrasing and synonym engines.

The server operates entirely over stdio and requires no manual installation of files.

Authentication for AI Clients

Because MCP servers run in the background, they need your QuillBot credentials. We provide a secure, one-time CLI login so you never have to pass your password to an AI agent or store it in plain text configuration files.

Simply open your terminal and run: uvx quillbot auth

(It will securely prompt for your email and password and save an encrypted/local session token).

Alternatively, you can provide QUILLBOT_EMAIL and QUILLBOT_PASSWORD as environment variables if you prefer stateless execution.

1. Claude Desktop

Add the following to your claude_desktop_config.json:

"mcpServers": {
  "quillbot": {
    "command": "uvx",
    "args": ["quillbot"]
  }
}

2. Cursor

In Cursor, navigate to Settings > Features > MCP and add a new server:

• Type: command
• Name: quillbot
• Command: uvx quillbot

3. Google Antigravity

To instantly connect the server to Google Antigravity, run:

agy mcp add quillbot "uvx quillbot"

4. Agent Instructions & Workflows (Prompts)

This server natively exposes a quillbot_workflow MCP Prompt. You do not need to download or configure any JSON files manually!

• In Claude Desktop, simply click the "Prompts" (paperclip/menu) icon and select the "Quillbot Workflow" prompt. Claude will automatically read the official agent instructions.
• In Cursor or Antigravity, you can ask the agent to "Fetch the quillbot_workflow prompt" to understand how to chain the macro tools together.

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_EMAIL and QUILLBOT_PASSWORD.
2. Run the tests:

pytest tests/test_unit.py -v -s

License

This project is licensed under the GNU General Public License v3.0 (GPLv3). See the LICENSE file for details.

Disclaimer

This is an unofficial SDK. Use responsibly and ensure you comply with QuillBot's Terms of Service.

Please support the development by donating.