perplexity-webui-scraper 0.3.4__tar.gz → 0.3.5__tar.gz

{perplexity_webui_scraper-0.3.4 → perplexity_webui_scraper-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: perplexity-webui-scraper
-Version: 0.3.4
+Version: 0.3.5
 Summary: Python scraper to extract AI responses from Perplexity's web interface.
 Keywords: perplexity,ai,scraper,webui,api,client
 Author: henrique-coder
@@ -20,14 +20,18 @@ Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Dist: curl-cffi>=0.14.0
+Requires-Dist: loguru>=0.7.3
 Requires-Dist: orjson>=3.11.5
 Requires-Dist: pydantic>=2.12.5
-Requires-Python: >=3.10
+Requires-Dist: tenacity>=9.1.2
+Requires-Dist: fastmcp>=2.14.1 ; extra == 'mcp'
+Requires-Python: >=3.10, <3.15
 Project-URL: Changelog, https://github.com/henrique-coder/perplexity-webui-scraper/releases
 Project-URL: Documentation, https://github.com/henrique-coder/perplexity-webui-scraper#readme
 Project-URL: Homepage, https://github.com/henrique-coder/perplexity-webui-scraper
 Project-URL: Issues, https://github.com/henrique-coder/perplexity-webui-scraper/issues
 Project-URL: Repository, https://github.com/henrique-coder/perplexity-webui-scraper.git
+Provides-Extra: mcp
 Description-Content-Type: text/markdown
 
 <div align="center">
@@ -47,7 +51,8 @@ Python scraper to extract AI responses from [Perplexity's](https://www.perplexit
 ## Installation
 
 ```bash
-uv pip install perplexity-webui-scraper
+uv pip install perplexity-webui-scraper  # from PyPI (stable)
+uv pip install git+https://github.com/henrique-coder/perplexity-webui-scraper.git@dev  # from GitHub (development)
 ```
 
 ## Requirements
@@ -197,18 +202,103 @@ conversation.ask("Latest AI research", files=["paper.pdf"])
 | `timezone`        | `None`        | Timezone           |
 | `coordinates`     | `None`        | Location (lat/lng) |
 
-## CLI Tools
+## Exceptions
 
-### Session Token Generator
+The library provides specific exception types for better error handling:
+
+| Exception                          | Description                                                  |
+| ---------------------------------- | ------------------------------------------------------------ |
+| `PerplexityError`                  | Base exception for all library errors                        |
+| `AuthenticationError`              | Session token is invalid or expired (HTTP 403)               |
+| `RateLimitError`                   | Rate limit exceeded (HTTP 429)                               |
+| `FileUploadError`                  | File upload failed                                           |
+| `FileValidationError`              | File validation failed (size, type, etc.)                    |
+| `ResearchClarifyingQuestionsError` | Research mode is asking clarifying questions (not supported) |
+| `ResponseParsingError`             | API response could not be parsed                             |
+| `StreamingError`                   | Error during streaming response                              |
+
+### Handling Research Mode Clarifying Questions
+
+When using Research mode (`Models.RESEARCH`), the API may ask clarifying questions before providing an answer. Since programmatic interaction is not supported, the library raises a `ResearchClarifyingQuestionsError` with the questions:
+
+```python
+from perplexity_webui_scraper import (
+    Perplexity,
+    ResearchClarifyingQuestionsError,
+)
+
+try:
+    conversation.ask("Research this topic", model=Models.RESEARCH)
+except ResearchClarifyingQuestionsError as error:
+    print("The AI needs clarification:")
+    for question in error.questions:
+        print(f"  - {question}")
+    # Consider rephrasing your query to be more specific
+```
+
+## MCP Server (Model Context Protocol)
+
+The library includes an MCP server that allows AI assistants (like Claude) to search using Perplexity AI directly.
+
+### Installation
 
 ```bash
-get-perplexity-session-token
+uv pip install perplexity-webui-scraper[mcp]
+```
+
+### Running the Server
+
+```bash
+# Set your session token
+export PERPLEXITY_SESSION_TOKEN="your_token_here"  # For Linux/Mac
+set PERPLEXITY_SESSION_TOKEN="your_token_here"  # For Windows
+
+# Run with FastMCP
+uv run fastmcp run src/perplexity_webui_scraper/mcp/server.py
+
+# Or test with the dev inspector
+uv run fastmcp dev src/perplexity_webui_scraper/mcp/server.py
+```
+
+### Claude Desktop Configuration
+
+Add to `~/.config/claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "perplexity": {
+      "command": "uv",
+      "args": [
+        "run",
+        "fastmcp",
+        "run",
+        "path/to/perplexity_webui_scraper/mcp/server.py"
+      ],
+      "env": {
+        "PERPLEXITY_SESSION_TOKEN": "your_token_here"
+      }
+    }
+  }
+}
 ```
 
-Interactive tool to automatically obtain your Perplexity session token via email authentication. The token can be automatically saved to your `.env` file for immediate use.
+### Available Tool
+
+| Tool             | Description                                                                 |
+| ---------------- | --------------------------------------------------------------------------- |
+| `perplexity_ask` | Ask questions and get AI-generated answers with real-time data from the web |
+
+**Parameters:**
+
+| Parameter      | Type  | Default  | Description                                                   |
+| -------------- | ----- | -------- | ------------------------------------------------------------- |
+| `query`        | `str` | -        | Question to ask (required)                                    |
+| `model`        | `str` | `"best"` | AI model (`best`, `research`, `gpt52`, `claude_sonnet`, etc.) |
+| `source_focus` | `str` | `"web"`  | Source type (`web`, `academic`, `social`, `finance`, `all`)   |
 
 ## Disclaimer
 
-This is an **unofficial** library. It uses internal APIs that may change without notice. Use at your own risk. Not for production use.
+This is an **unofficial** library. It uses internal APIs that may change without notice. Use at your own risk.
 
 By using this library, you agree to Perplexity AI's Terms of Service.

{perplexity_webui_scraper-0.3.4 → perplexity_webui_scraper-0.3.5}/README.md

@@ -15,7 +15,8 @@ Python scraper to extract AI responses from [Perplexity's](https://www.perplexit
 ## Installation
 
 ```bash
-uv pip install perplexity-webui-scraper
+uv pip install perplexity-webui-scraper  # from PyPI (stable)
+uv pip install git+https://github.com/henrique-coder/perplexity-webui-scraper.git@dev  # from GitHub (development)
 ```
 
 ## Requirements
@@ -165,18 +166,103 @@ conversation.ask("Latest AI research", files=["paper.pdf"])
 | `timezone`        | `None`        | Timezone           |
 | `coordinates`     | `None`        | Location (lat/lng) |
 
-## CLI Tools
+## Exceptions
 
-### Session Token Generator
+The library provides specific exception types for better error handling:
+
+| Exception                          | Description                                                  |
+| ---------------------------------- | ------------------------------------------------------------ |
+| `PerplexityError`                  | Base exception for all library errors                        |
+| `AuthenticationError`              | Session token is invalid or expired (HTTP 403)               |
+| `RateLimitError`                   | Rate limit exceeded (HTTP 429)                               |
+| `FileUploadError`                  | File upload failed                                           |
+| `FileValidationError`              | File validation failed (size, type, etc.)                    |
+| `ResearchClarifyingQuestionsError` | Research mode is asking clarifying questions (not supported) |
+| `ResponseParsingError`             | API response could not be parsed                             |
+| `StreamingError`                   | Error during streaming response                              |
+
+### Handling Research Mode Clarifying Questions
+
+When using Research mode (`Models.RESEARCH`), the API may ask clarifying questions before providing an answer. Since programmatic interaction is not supported, the library raises a `ResearchClarifyingQuestionsError` with the questions:
+
+```python
+from perplexity_webui_scraper import (
+    Perplexity,
+    ResearchClarifyingQuestionsError,
+)
+
+try:
+    conversation.ask("Research this topic", model=Models.RESEARCH)
+except ResearchClarifyingQuestionsError as error:
+    print("The AI needs clarification:")
+    for question in error.questions:
+        print(f"  - {question}")
+    # Consider rephrasing your query to be more specific
+```
+
+## MCP Server (Model Context Protocol)
+
+The library includes an MCP server that allows AI assistants (like Claude) to search using Perplexity AI directly.
+
+### Installation
 
 ```bash
-get-perplexity-session-token
+uv pip install perplexity-webui-scraper[mcp]
+```
+
+### Running the Server
+
+```bash
+# Set your session token
+export PERPLEXITY_SESSION_TOKEN="your_token_here"  # For Linux/Mac
+set PERPLEXITY_SESSION_TOKEN="your_token_here"  # For Windows
+
+# Run with FastMCP
+uv run fastmcp run src/perplexity_webui_scraper/mcp/server.py
+
+# Or test with the dev inspector
+uv run fastmcp dev src/perplexity_webui_scraper/mcp/server.py
+```
+
+### Claude Desktop Configuration
+
+Add to `~/.config/claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "perplexity": {
+      "command": "uv",
+      "args": [
+        "run",
+        "fastmcp",
+        "run",
+        "path/to/perplexity_webui_scraper/mcp/server.py"
+      ],
+      "env": {
+        "PERPLEXITY_SESSION_TOKEN": "your_token_here"
+      }
+    }
+  }
+}
 ```
 
-Interactive tool to automatically obtain your Perplexity session token via email authentication. The token can be automatically saved to your `.env` file for immediate use.
+### Available Tool
+
+| Tool             | Description                                                                 |
+| ---------------- | --------------------------------------------------------------------------- |
+| `perplexity_ask` | Ask questions and get AI-generated answers with real-time data from the web |
+
+**Parameters:**
+
+| Parameter      | Type  | Default  | Description                                                   |
+| -------------- | ----- | -------- | ------------------------------------------------------------- |
+| `query`        | `str` | -        | Question to ask (required)                                    |
+| `model`        | `str` | `"best"` | AI model (`best`, `research`, `gpt52`, `claude_sonnet`, etc.) |
+| `source_focus` | `str` | `"web"`  | Source type (`web`, `academic`, `social`, `finance`, `all`)   |
 
 ## Disclaimer
 
-This is an **unofficial** library. It uses internal APIs that may change without notice. Use at your own risk. Not for production use.
+This is an **unofficial** library. It uses internal APIs that may change without notice. Use at your own risk.
 
 By using this library, you agree to Perplexity AI's Terms of Service.

{perplexity_webui_scraper-0.3.4 → perplexity_webui_scraper-0.3.5}/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "perplexity-webui-scraper"
-version = "0.3.4"
+version = "0.3.5"
 description = "Python scraper to extract AI responses from Perplexity's web interface."
 authors = [{ name = "henrique-coder", email = "henriquemoreira10fk@gmail.com" }]
 license = "MIT"
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.10,<3.15"
 keywords = ["perplexity", "ai", "scraper", "webui", "api", "client"]
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -24,8 +24,10 @@ classifiers = [
 ]
 dependencies = [
     "curl-cffi>=0.14.0",
+    "loguru>=0.7.3",
     "orjson>=3.11.5",
     "pydantic>=2.12.5",
+    "tenacity>=9.1.2",
 ]
 
 [dependency-groups]
@@ -43,6 +45,11 @@ tests = [
     "pytest>=9.0.2",
 ]
 
+[project.optional-dependencies]
+mcp = [
+    "fastmcp>=2.14.1",
+]
+
 [project.urls]
 Homepage = "https://github.com/henrique-coder/perplexity-webui-scraper"
 Documentation = "https://github.com/henrique-coder/perplexity-webui-scraper#readme"
@@ -103,6 +110,7 @@ skip-magic-trailing-comma = false   # Preserve trailing commas as formatting hin
 
 [project.scripts]
 get-perplexity-session-token = "perplexity_webui_scraper.cli.get_perplexity_session_token:get_token"
+perplexity-webui-scraper-mcp = "perplexity_webui_scraper.mcp:run_server"
 
 [build-system]
 requires = ["uv_build"]

{perplexity_webui_scraper-0.3.4 → perplexity_webui_scraper-0.3.5}/src/perplexity_webui_scraper/__init__.py

@@ -4,33 +4,22 @@ from importlib import metadata
 
 from .config import ClientConfig, ConversationConfig
 from .core import Conversation, Perplexity
-from .enums import CitationMode, SearchFocus, SourceFocus, TimeRange
-from .exceptions import (
-    AuthenticationError,
-    FileUploadError,
-    FileValidationError,
-    PerplexityError,
-    RateLimitError,
-)
+from .enums import CitationMode, LogLevel, SearchFocus, SourceFocus, TimeRange
 from .models import Model, Models
 from .types import Coordinates, Response, SearchResultItem
 
 
 __version__: str = metadata.version("perplexity-webui-scraper")
 __all__: list[str] = [
-    "AuthenticationError",
     "CitationMode",
     "ClientConfig",
     "Conversation",
     "ConversationConfig",
     "Coordinates",
-    "FileUploadError",
-    "FileValidationError",
+    "LogLevel",
     "Model",
     "Models",
     "Perplexity",
-    "PerplexityError",
-    "RateLimitError",
     "Response",
     "SearchFocus",
     "SearchResultItem",

perplexity_webui_scraper-0.3.5/src/perplexity_webui_scraper/config.py

@@ -0,0 +1,61 @@
+"""Configuration classes."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from .enums import CitationMode, LogLevel, SearchFocus, SourceFocus, TimeRange
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from .models import Model
+    from .types import Coordinates
+
+
+@dataclass(slots=True)
+class ConversationConfig:
+    """Default settings for a conversation. Can be overridden per message."""
+
+    model: Model | None = None
+    citation_mode: CitationMode = CitationMode.CLEAN
+    save_to_library: bool = False
+    search_focus: SearchFocus = SearchFocus.WEB
+    source_focus: SourceFocus | list[SourceFocus] = SourceFocus.WEB
+    time_range: TimeRange = TimeRange.ALL
+    language: str = "en-US"
+    timezone: str | None = None
+    coordinates: Coordinates | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ClientConfig:
+    """
+    HTTP client settings.
+
+    Attributes:
+        timeout: Request timeout in seconds.
+        impersonate: Browser to impersonate (e.g., "chrome", "edge", "safari").
+        max_retries: Maximum retry attempts for failed requests.
+        retry_base_delay: Initial delay in seconds before first retry.
+        retry_max_delay: Maximum delay between retries.
+        retry_jitter: Random jitter factor (0-1) to add to delays.
+        requests_per_second: Rate limit for requests (0 to disable).
+        rotate_fingerprint: Whether to rotate browser fingerprint on retries.
+        logging_level: Logging verbosity level. Default is DISABLED.
+        log_file: Optional file path for persistent logging. If set, logs go to file only.
+                  If None, logs go to console. All logs are appended.
+    """
+
+    timeout: int = 3600
+    impersonate: str = "chrome"
+    max_retries: int = 3
+    retry_base_delay: float = 1.0
+    retry_max_delay: float = 60.0
+    retry_jitter: float = 0.5
+    requests_per_second: float = 0.5
+    rotate_fingerprint: bool = True
+    logging_level: LogLevel = LogLevel.DISABLED
+    log_file: str | Path | None = None