isitcredible 0.1.0__tar.gz

isitcredible-0.1.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: isitcredible
+Version: 0.1.0
+Summary: Python SDK for the isitcredible.com academic peer-review API
+Author: isitcredible.com
+License: MIT
+Project-URL: Homepage, https://isitcredible.com
+Project-URL: Documentation, https://isitcredible.com/docs/api
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Requires-Dist: requests>=2.28

isitcredible-0.1.0/README.md

@@ -0,0 +1,173 @@
+# isitcredible — Python SDK
+
+Python client for the [isitcredible.com](https://isitcredible.com) automated peer-review API.
+
+## Installation
+
+```bash
+pip install isitcredible
+```
+
+## Quick start
+
+```python
+from isitcredible import Client
+
+client = Client("iic_your_api_key")
+report = client.analyze("paper.pdf")
+report.save("review.pdf")
+```
+
+`analyze()` submits the document and polls until the report is ready, then returns a `Report` object. **Jobs take at least 20 minutes and may run longer** — the default timeout is 60 minutes.
+
+## API key
+
+Generate a key from your [account page](https://isitcredible.com/account). Keys start with `iic_` and require a verified email address.
+
+```python
+client = Client("iic_your_api_key")
+```
+
+You can also read the key from an environment variable:
+
+```python
+import os
+from isitcredible import Client
+
+client = Client(os.environ["IIC_API_KEY"])
+```
+
+## Report types
+
+| Mode | Price | Description |
+|------|-------|-------------|
+| `standard` | $5.00 | Full peer review: methodological critique, identified issues, directions for future research. |
+| `extended` | $7.00 | Everything in *standard*, plus an editorial response note and a proofreading pass. |
+
+```python
+report = client.analyze("paper.pdf", mode="extended")
+```
+
+## Saving the report
+
+```python
+report.save("review.pdf")          # PDF (default)
+report.save("review.txt", format="txt")  # plain text
+```
+
+Or get the raw bytes:
+
+```python
+pdf_bytes = report.download()
+```
+
+## Handling timeouts
+
+Because jobs are long-running, `analyze()` (and `wait()`) will raise `JobTimeoutError` if the job doesn't finish within the timeout. The job **keeps running on the server** — you can resume polling using the `job_id` attached to the exception:
+
+```python
+from isitcredible import Client, JobTimeoutError
+
+client = Client("iic_your_api_key")
+
+try:
+    report = client.analyze("paper.pdf", timeout=3600)  # 60 min
+except JobTimeoutError as e:
+    print(f"Timed out. Job is still running: {e.job_id}")
+    # Resume later:
+    report = client.wait(e.job_id, timeout=3600)
+    report.save("review.pdf")
+```
+
+If you lose track of a job ID, use `list_jobs()` to find it:
+
+```python
+jobs = client.list_jobs()
+# Each entry has 'uuid', 'status', 'title', 'mode', 'audit_date'
+```
+
+## Advanced: submit and poll separately
+
+Use `submit()` and `wait()` directly if you need to fire-and-forget or manage polling yourself:
+
+```python
+# Submit without blocking
+job = client.submit("paper.pdf", mode="standard")
+job_id = job["job_id"]
+print(f"Submitted: {job_id}")
+
+# ... do other things ...
+
+# Resume polling later
+report = client.wait(job_id, poll_interval=60, timeout=7200)
+report.save("review.pdf")
+```
+
+## Checking your balance
+
+```python
+balance = client.get_credits()
+print(f"${balance['balance_usd']:.2f} remaining")
+```
+
+## Webhooks
+
+Register a webhook to receive a POST when a job completes, instead of polling:
+
+```python
+# Register (secret is shown once — save it)
+hook = client.create_webhook("https://yourapp.com/webhook")
+print(hook["secret"])
+
+# Or pass a webhook URL per job
+client.submit("paper.pdf", webhook_url="https://yourapp.com/webhook")
+
+# Manage webhooks
+hooks = client.list_webhooks()
+client.delete_webhook(hooks[0]["id"])
+```
+
+## Full method reference
+
+| Method | Description |
+|--------|-------------|
+| `analyze(file_path, mode, note, webhook_url, poll_interval, timeout)` | Submit + poll + return `Report`. Blocks until complete. |
+| `submit(file_path, mode, note, webhook_url)` | Submit without waiting. Returns `dict` with `job_id`. |
+| `wait(job_id, poll_interval, timeout)` | Poll an existing job to completion. Returns `Report`. |
+| `get_job(job_id)` | Get current status and metadata for a job. |
+| `list_jobs()` | List your last 50 jobs. |
+| `get_credits()` | Get your current credit balance. |
+| `create_webhook(url, event)` | Register a webhook. Returns signing secret (shown once). |
+| `list_webhooks()` | List registered webhooks. |
+| `delete_webhook(id)` | Delete a webhook. |
+
+### Report object
+
+| Attribute | Description |
+|-----------|-------------|
+| `job_id` | Job UUID. |
+| `status` | `completed` or `published`. |
+| `mode` | `standard` or `extended`. |
+| `title` | Paper title (extracted from document). |
+| `authors` | Authors (extracted from document). |
+| `discipline` | Academic discipline (extracted from document). |
+| `report_url` | Direct URL to download the report. |
+| `.download(format)` | Return report as bytes (`"pdf"` or `"txt"`). |
+| `.save(path, format)` | Write report to a file. |
+
+## Errors
+
+| Exception | Description |
+|-----------|-------------|
+| `IsItCredibleError` | Base class. Has `.status_code` and `.detail`. |
+| `JobTimeoutError` | Polling timed out. Has `.job_id` — use it to resume with `wait()`. |
+
+HTTP errors map to `IsItCredibleError` with the relevant status code:
+
+| Code | Meaning |
+|------|---------|
+| `401` | Missing or invalid API key. |
+| `402` | Insufficient balance. |
+| `403` | Email not verified. |
+| `404` | Job not found. |
+| `400` | Invalid input (file too large, wrong format, etc.). |

isitcredible-0.1.0/isitcredible/__init__.py

@@ -0,0 +1,4 @@
+from .client import Client, IsItCredibleError, JobTimeoutError
+
+__all__ = ["Client", "IsItCredibleError", "JobTimeoutError"]
+__version__ = "0.1.0"

isitcredible-0.1.0/isitcredible/client.py

@@ -0,0 +1,259 @@
+"""
+isitcredible — Python SDK
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Usage:
+    from isitcredible import Client
+
+    client = Client("iic_your_api_key")
+    report = client.analyze("paper.pdf")
+    report.save("review.pdf")
+"""
+import os
+import time
+from pathlib import Path
+from typing import Optional, Union
+
+import requests
+
+
+API_BASE = "https://isitcredible.com/api/v1"
+
+
+class IsItCredibleError(Exception):
+    """Base exception for API errors."""
+    def __init__(self, message: str, status_code: int = None, detail: str = None):
+        self.status_code = status_code
+        self.detail = detail or message
+        super().__init__(message)
+
+
+class JobTimeoutError(IsItCredibleError):
+    """Raised when polling exceeds the timeout."""
+    pass
+
+
+class Report:
+    """Represents a completed analysis report."""
+
+    def __init__(self, job: dict, client: "Client"):
+        self.job_id: str = job["uuid"]
+        self.status: str = job["status"]
+        self.mode: str = job.get("mode", "standard")
+        self.title: str = job.get("title")
+        self.authors: str = job.get("authors")
+        self.discipline: str = job.get("discipline")
+        self.report_url: str = job.get("report_url")
+        self._client = client
+
+    def download(self, format: str = "pdf") -> bytes:
+        """Download the report as bytes."""
+        if not self.report_url:
+            raise IsItCredibleError("No report available (job may not be completed).")
+        resp = self._client._get(f"/jobs/{self.job_id}/report", params={"format": format},
+                                  stream=True)
+        return resp.content
+
+    def save(self, path: Union[str, Path], format: str = "pdf"):
+        """Download and save the report to a file."""
+        data = self.download(format=format)
+        Path(path).write_bytes(data)
+
+    def __repr__(self):
+        return f"<Report job_id={self.job_id!r} status={self.status!r} title={self.title!r}>"
+
+
+class Client:
+    """
+    isitcredible.com API client.
+
+    Args:
+        api_key: Your API key (starts with ``iic_``).
+        base_url: Override the API base URL (for testing).
+        timeout: HTTP request timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = None,
+        timeout: int = 30,
+    ):
+        if not api_key:
+            raise IsItCredibleError("API key is required.")
+        self._api_key = api_key
+        self._base_url = (base_url or API_BASE).rstrip("/")
+        self._timeout = timeout
+        self._session = requests.Session()
+        self._session.headers.update({
+            "Authorization": f"Bearer {api_key}",
+            "User-Agent": "isitcredible-python/0.1.0",
+        })
+
+    # -----------------------------------------------------------------
+    # Core high-level method
+    # -----------------------------------------------------------------
+
+    def analyze(
+        self,
+        file_path: Union[str, Path],
+        mode: str = "standard",
+        note: str = "",
+        webhook_url: str = "",
+        poll_interval: int = 15,
+        timeout: int = 3600,
+    ) -> Report:
+        """
+        Submit a document for analysis and wait for the result.
+
+        Args:
+            file_path: Path to the PDF, TXT, or MD file.
+            mode: ``"standard"`` or ``"extended"``.
+            note: Optional note for the reviewer.
+            webhook_url: Optional URL to receive a POST when the job completes.
+            poll_interval: Seconds between status checks (default 15).
+            timeout: Maximum seconds to wait (default 3600 = 60 min).
+
+        Returns:
+            A :class:`Report` object with the completed analysis.
+
+        Raises:
+            IsItCredibleError: On API errors.
+            JobTimeoutError: If the job doesn't finish within ``timeout``.
+            FileNotFoundError: If ``file_path`` doesn't exist.
+        """
+        job = self.submit(file_path, mode=mode, note=note, webhook_url=webhook_url)
+        job_id = job["job_id"]
+        return self.wait(job_id, poll_interval=poll_interval, timeout=timeout)
+
+    # -----------------------------------------------------------------
+    # Low-level methods (for advanced users / async pipelines)
+    # -----------------------------------------------------------------
+
+    def submit(
+        self,
+        file_path: Union[str, Path],
+        mode: str = "standard",
+        note: str = "",
+        webhook_url: str = "",
+    ) -> dict:
+        """
+        Submit a file for analysis without waiting.
+
+        Returns:
+            dict with ``job_id``, ``status``, ``mode``, ``message``.
+        """
+        file_path = Path(file_path)
+        if not file_path.exists():
+            raise FileNotFoundError(f"File not found: {file_path}")
+
+        with open(file_path, "rb") as f:
+            data = {"mode": mode, "user_note": note}
+            if webhook_url:
+                data["webhook_url"] = webhook_url
+            resp = self._post(
+                "/jobs",
+                files={"main_file": (file_path.name, f)},
+                data=data,
+            )
+        return resp.json()
+
+    def wait(self, job_id: str, poll_interval: int = 15, timeout: int = 3600) -> Report:
+        """
+        Poll a job until completion.
+
+        Args:
+            job_id: The job UUID returned by :meth:`submit`.
+            poll_interval: Seconds between polls.
+            timeout: Maximum wait time in seconds.
+
+        Returns:
+            A :class:`Report` object.
+        """
+        deadline = time.time() + timeout
+
+        while True:
+            job = self.get_job(job_id)
+            status = job.get("status", "")
+
+            if status in ("completed", "published"):
+                return Report(job, self)
+
+            if status == "failed":
+                raise IsItCredibleError(
+                    f"Job {job_id} failed.",
+                    detail=job.get("admin_notes", ""),
+                )
+
+            if time.time() > deadline:
+                err = JobTimeoutError(
+                    f"Job {job_id} did not complete within {timeout}s (status: {status})."
+                )
+                err.job_id = job_id
+                raise err
+
+            time.sleep(poll_interval)
+
+    def get_job(self, job_id: str) -> dict:
+        """Get status and metadata for a single job."""
+        return self._get(f"/jobs/{job_id}").json()
+
+    def list_jobs(self) -> list:
+        """List your recent jobs."""
+        return self._get("/jobs").json()
+
+    def get_credits(self) -> dict:
+        """Get your current credit balance."""
+        return self._get("/credits").json()
+
+    # -- Webhook management --
+
+    def create_webhook(self, url: str, event: str = "job.completed") -> dict:
+        """Register a default webhook URL. Returns the signing secret (save it!)."""
+        return self._post("/webhooks", data={"url": url, "event": event}).json()
+
+    def list_webhooks(self) -> list:
+        """List your registered webhooks."""
+        return self._get("/webhooks").json()
+
+    def delete_webhook(self, webhook_id: int) -> dict:
+        """Delete a webhook by ID."""
+        return self._delete(f"/webhooks/{webhook_id}").json()
+
+    # -----------------------------------------------------------------
+    # HTTP helpers
+    # -----------------------------------------------------------------
+
+    def _get(self, path: str, params: dict = None, stream: bool = False) -> requests.Response:
+        resp = self._session.get(
+            f"{self._base_url}{path}",
+            params=params,
+            timeout=self._timeout,
+            stream=stream,
+        )
+        self._check(resp)
+        return resp
+
+    def _post(self, path: str, **kwargs) -> requests.Response:
+        kwargs.setdefault("timeout", self._timeout)
+        resp = self._session.post(f"{self._base_url}{path}", **kwargs)
+        self._check(resp)
+        return resp
+
+    def _delete(self, path: str) -> requests.Response:
+        resp = self._session.delete(f"{self._base_url}{path}", timeout=self._timeout)
+        self._check(resp)
+        return resp
+
+    @staticmethod
+    def _check(resp: requests.Response):
+        if resp.status_code >= 400:
+            try:
+                detail = resp.json().get("detail", resp.text)
+            except Exception:
+                detail = resp.text
+            raise IsItCredibleError(
+                f"HTTP {resp.status_code}: {detail}",
+                status_code=resp.status_code,
+                detail=detail,
+            )

isitcredible-0.1.0/isitcredible.egg-info/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: isitcredible
+Version: 0.1.0
+Summary: Python SDK for the isitcredible.com academic peer-review API
+Author: isitcredible.com
+License: MIT
+Project-URL: Homepage, https://isitcredible.com
+Project-URL: Documentation, https://isitcredible.com/docs/api
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Requires-Dist: requests>=2.28

isitcredible-0.1.0/isitcredible.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+isitcredible/__init__.py
+isitcredible/client.py
+isitcredible.egg-info/PKG-INFO
+isitcredible.egg-info/SOURCES.txt
+isitcredible.egg-info/dependency_links.txt
+isitcredible.egg-info/requires.txt
+isitcredible.egg-info/top_level.txt

isitcredible-0.1.0/isitcredible.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

isitcredible-0.1.0/isitcredible.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.28

isitcredible-0.1.0/isitcredible.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+dist
+isitcredible

isitcredible-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "isitcredible"
+version = "0.1.0"
+description = "Python SDK for the isitcredible.com academic peer-review API"
+requires-python = ">=3.8"
+license = {text = "MIT"}
+authors = [{name = "isitcredible.com"}]
+dependencies = ["requests>=2.28"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering",
+    "Programming Language :: Python :: 3",
+]
+
+[project.urls]
+Homepage = "https://isitcredible.com"
+Documentation = "https://isitcredible.com/docs/api"
+
+[tool.setuptools.packages.find]
+where = ["."]

isitcredible-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+