gigai-tools 0.1.0__tar.gz

gigai_tools-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gigai Kripa Services
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gigai_tools-0.1.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: gigai-tools
+Version: 0.1.0
+Summary: Client for the GigAI Tools API - run PDF, image, SVG and QR tools from Python. Free plan, no dependencies.
+Author-email: Gigai Kripa Services <hello@gigaikripaservices.com>
+License: MIT
+Project-URL: Homepage, https://gigai.tools/developers
+Project-URL: Documentation, https://gigai.tools/developers
+Keywords: pdf,merge,split,image,convert,resize,compress,qr,svg,api
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# gigai-tools
+
+Python client for the [GigAI Tools API](https://gigai.tools/developers). Run PDF, image, SVG and QR tools from code. The free plan gives 1,000 tasks a month with no card.
+
+No dependencies. Python 3.9+.
+
+## Install
+
+```
+pip install gigai-tools
+```
+
+## Get a key
+
+Create an account at [gigai.tools/developers](https://gigai.tools/developers) and make an API key in the dashboard. Set it as `GIGAI_API_KEY` or pass `api_key=`.
+
+## One call
+
+```python
+from gigai_tools import Client
+
+client = Client()
+
+# Merge two PDFs
+client.run("merge-pdf", files=["a.pdf", "b.pdf"], output="merged.pdf")
+
+# Compress an image to fit under 200 KB
+client.run("compress-image", files=["photo.jpg"], options={"target_kb": 200}, output="small.jpg")
+
+# Generate a QR code (no input file - the text is the payload)
+client.run("generate-qr", options={"text": "https://example.com"}, output="qr.png")
+```
+
+`run()` imports your files, runs the tool, exports the result and downloads it. Files can also be `https://` URLs and the server fetches them.
+
+## Tools
+
+```python
+for tool in client.tools():
+    print(tool["slug"], "-", tool["description"])
+```
+
+Live engines: merge-pdf, split-pdf, rotate-pdf, pdf-to-text, convert-image, resize-image, compress-image, optimize-svg, markdown-to-html, generate-qr. The catalog only lists tools the API can actually run.
+
+## Job graphs
+
+Chain tools in one job. Each task names its inputs and the server runs them in dependency order:
+
+```python
+job = client.create_job({
+    "in":  {"operation": "import/url", "url": "https://example.com/report.pdf"},
+    "rot": {"operation": "rotate-pdf", "input": ["in"], "angle": 90},
+    "txt": {"operation": "pdf-to-text", "input": ["rot"]},
+    "out": {"operation": "export/url", "input": ["txt"]},
+}, retention_s=600)
+
+job = client.wait(job["id"])
+export = next(t for t in job["tasks"] if t["name"] == "out")
+client.download(export["result"]["files"][0]["url"], "report.txt")
+```
+
+`Idempotency-Key` makes retries safe: pass `idempotency_key=` and the same key returns the same job instead of running the work twice.
+
+## Errors
+
+Every failure raises `GigaiError` with a machine-readable `code` (`invalid_option`, `file_too_large`, `quota_exceeded`, `target_unreachable`, ...), the human message, and the offending parameter when there is one.
+
+## Privacy
+
+File contents are never logged. Results are deleted after the retention you choose (default 1 hour, `retention_s=0` means one download or 60 seconds) and deletion is verified. The web tools at [gigai.tools](https://gigai.tools) never need an account - accounts exist only for this API.

gigai_tools-0.1.0/README.md

@@ -0,0 +1,70 @@
+# gigai-tools
+
+Python client for the [GigAI Tools API](https://gigai.tools/developers). Run PDF, image, SVG and QR tools from code. The free plan gives 1,000 tasks a month with no card.
+
+No dependencies. Python 3.9+.
+
+## Install
+
+```
+pip install gigai-tools
+```
+
+## Get a key
+
+Create an account at [gigai.tools/developers](https://gigai.tools/developers) and make an API key in the dashboard. Set it as `GIGAI_API_KEY` or pass `api_key=`.
+
+## One call
+
+```python
+from gigai_tools import Client
+
+client = Client()
+
+# Merge two PDFs
+client.run("merge-pdf", files=["a.pdf", "b.pdf"], output="merged.pdf")
+
+# Compress an image to fit under 200 KB
+client.run("compress-image", files=["photo.jpg"], options={"target_kb": 200}, output="small.jpg")
+
+# Generate a QR code (no input file - the text is the payload)
+client.run("generate-qr", options={"text": "https://example.com"}, output="qr.png")
+```
+
+`run()` imports your files, runs the tool, exports the result and downloads it. Files can also be `https://` URLs and the server fetches them.
+
+## Tools
+
+```python
+for tool in client.tools():
+    print(tool["slug"], "-", tool["description"])
+```
+
+Live engines: merge-pdf, split-pdf, rotate-pdf, pdf-to-text, convert-image, resize-image, compress-image, optimize-svg, markdown-to-html, generate-qr. The catalog only lists tools the API can actually run.
+
+## Job graphs
+
+Chain tools in one job. Each task names its inputs and the server runs them in dependency order:
+
+```python
+job = client.create_job({
+    "in":  {"operation": "import/url", "url": "https://example.com/report.pdf"},
+    "rot": {"operation": "rotate-pdf", "input": ["in"], "angle": 90},
+    "txt": {"operation": "pdf-to-text", "input": ["rot"]},
+    "out": {"operation": "export/url", "input": ["txt"]},
+}, retention_s=600)
+
+job = client.wait(job["id"])
+export = next(t for t in job["tasks"] if t["name"] == "out")
+client.download(export["result"]["files"][0]["url"], "report.txt")
+```
+
+`Idempotency-Key` makes retries safe: pass `idempotency_key=` and the same key returns the same job instead of running the work twice.
+
+## Errors
+
+Every failure raises `GigaiError` with a machine-readable `code` (`invalid_option`, `file_too_large`, `quota_exceeded`, `target_unreachable`, ...), the human message, and the offending parameter when there is one.
+
+## Privacy
+
+File contents are never logged. Results are deleted after the retention you choose (default 1 hour, `retention_s=0` means one download or 60 seconds) and deletion is verified. The web tools at [gigai.tools](https://gigai.tools) never need an account - accounts exist only for this API.

gigai_tools-0.1.0/gigai_tools/__init__.py

@@ -0,0 +1,3 @@
+from .client import Client, GigaiError, __version__
+
+__all__ = ["Client", "GigaiError", "__version__"]

gigai_tools-0.1.0/gigai_tools/client.py

@@ -0,0 +1,219 @@
+"""GigAI Tools API client. Stdlib only - no dependencies to install or audit.
+
+    from gigai_tools import Client
+
+    client = Client()  # reads GIGAI_API_KEY
+    paths = client.run("merge-pdf", files=["a.pdf", "b.pdf"], output="merged.pdf")
+
+The low-level surface (create_job, wait, download) mirrors the HTTP API
+one to one. run() is the convenience wrapper: import -> tool -> export ->
+download in a single call.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Optional, Union
+
+__version__ = "0.1.0"
+
+DEFAULT_BASE = "https://api.gigai.tools/v1"
+FINAL_STATES = ("finished", "error", "cancelled")
+
+
+class GigaiError(Exception):
+    """An error answer from the API, with its machine-readable code."""
+
+    def __init__(self, status: int, code: str, message: str, param: Optional[str] = None):
+        super().__init__(f"{code}: {message}")
+        self.status = status
+        self.code = code
+        self.message = message
+        self.param = param
+
+
+class Client:
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None,
+                 timeout: float = 120.0):
+        self.api_key = api_key or os.environ.get("GIGAI_API_KEY", "")
+        self.base_url = (base_url or os.environ.get("GIGAI_API_BASE", DEFAULT_BASE)).rstrip("/")
+        self.timeout = timeout
+        if not self.api_key:
+            raise GigaiError(0, "no_api_key",
+                             "No API key. Pass api_key= or set GIGAI_API_KEY. "
+                             "Keys come from https://gigai.tools/developers/dashboard")
+
+    # ------------------------------------------------------------------ http
+
+    def _request(self, method: str, path: str, body: Any = None,
+                 headers: Optional[dict] = None) -> Any:
+        req = urllib.request.Request(
+            self.base_url + path,
+            data=json.dumps(body).encode() if body is not None else None,
+            method=method,
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": f"gigai-tools-python/{__version__}",
+                **(headers or {}),
+            },
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return json.loads(resp.read() or b"{}")
+        except urllib.error.HTTPError as exc:
+            raise self._as_error(exc) from None
+        except urllib.error.URLError as exc:
+            raise GigaiError(0, "network_error", f"Could not reach {self.base_url}: {exc.reason}") from None
+
+    @staticmethod
+    def _as_error(exc: urllib.error.HTTPError) -> GigaiError:
+        try:
+            payload = json.loads(exc.read())
+            err = payload.get("detail", payload).get("error", {})
+            return GigaiError(exc.code, err.get("code", "http_error"),
+                              err.get("message", str(exc)), err.get("param"))
+        except Exception:
+            return GigaiError(exc.code, "http_error", f"HTTP {exc.code}")
+
+    # ----------------------------------------------------------------- tools
+
+    def tools(self) -> list:
+        return self._request("GET", "/tools")["tools"]
+
+    def tool(self, slug: str) -> dict:
+        return self._request("GET", f"/tools/{slug}")
+
+    # ------------------------------------------------------------------ jobs
+
+    def create_job(self, tasks: dict, tag: Optional[str] = None,
+                   retention_s: Optional[int] = None,
+                   idempotency_key: Optional[str] = None) -> dict:
+        body: dict[str, Any] = {"tasks": tasks}
+        if tag is not None:
+            body["tag"] = tag
+        if retention_s is not None:
+            body["retention_s"] = retention_s
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        return self._request("POST", "/jobs", body, headers)
+
+    def job(self, job_id: str) -> dict:
+        return self._request("GET", f"/jobs/{job_id}")
+
+    def jobs(self, status: Optional[str] = None, limit: int = 20) -> list:
+        qs = f"?limit={limit}" + (f"&status={status}" if status else "")
+        return self._request("GET", f"/jobs{qs}")["jobs"]
+
+    def wait(self, job_id: str, timeout: float = 600.0) -> dict:
+        """Block until the job settles (finished, error or cancelled)."""
+        deadline = time.time() + timeout
+        while True:
+            job = self._request("GET", f"/jobs/{job_id}/wait")
+            if job["status"] in FINAL_STATES:
+                return job
+            if time.time() > deadline:
+                raise GigaiError(0, "wait_timeout",
+                                 f"Job {job_id} still {job['status']} after {timeout}s.")
+
+    def cancel(self, job_id: str) -> dict:
+        """Cancel outstanding work and delete the job's files immediately."""
+        return self._request("DELETE", f"/jobs/{job_id}")
+
+    # ----------------------------------------------------------------- files
+
+    def file(self, file_id: str) -> dict:
+        return self._request("GET", f"/files/{file_id}")
+
+    def delete_file(self, file_id: str) -> dict:
+        return self._request("DELETE", f"/files/{file_id}")
+
+    def _localize(self, url: str) -> str:
+        """Point a signed URL at this client's base host. The signature covers
+        the file id and expiry, not the host, so the base can differ (tunnel,
+        staging, or the api. host before the server config catches up)."""
+        if url.startswith(self.base_url):
+            return url
+        idx = url.find("/v1/")
+        return self.base_url + url[idx + 3:] if idx >= 0 else url
+
+    def download(self, url: str, path: str) -> str:
+        """Save a signed result URL to a local file."""
+        req = urllib.request.Request(self._localize(url),
+                                     headers={"User-Agent": f"gigai-tools-python/{__version__}"})
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp, open(path, "wb") as out:
+                while chunk := resp.read(1 << 16):
+                    out.write(chunk)
+        except urllib.error.HTTPError as exc:
+            raise self._as_error(exc) from None
+        return path
+
+    # -------------------------------------------------------------- webhooks
+
+    def webhooks(self) -> list:
+        return self._request("GET", "/webhooks")["webhooks"]
+
+    def create_webhook(self, url: str, events: Optional[list] = None) -> dict:
+        body: dict[str, Any] = {"url": url}
+        if events:
+            body["events"] = events
+        return self._request("POST", "/webhooks", body)
+
+    def delete_webhook(self, webhook_id: str) -> dict:
+        return self._request("DELETE", f"/webhooks/{webhook_id}")
+
+    # --------------------------------------------------------------- one-call
+
+    def run(self, operation: str, files: Union[str, list, None] = None,
+            options: Optional[dict] = None, output: Optional[str] = None,
+            retention_s: Optional[int] = None, timeout: float = 600.0) -> list:
+        """Run one tool start to finish. Returns the list of saved file paths.
+
+        files: local paths, or http(s) URLs to import server-side. Omit for
+        tools that take no input (generate-qr).
+        output: a file path (single result) or a directory. Default: the
+        current directory, using the API's result filenames.
+        """
+        if isinstance(files, str):
+            files = [files]
+        tasks: dict[str, Any] = {}
+        names = []
+        for i, f in enumerate(files or []):
+            name = f"in{i}"
+            names.append(name)
+            if f.startswith(("http://", "https://")):
+                tasks[name] = {"operation": "import/url", "url": f}
+            else:
+                with open(f, "rb") as fh:
+                    data = fh.read()
+                tasks[name] = {"operation": "import/base64",
+                               "file": base64.b64encode(data).decode(),
+                               "filename": os.path.basename(f)}
+        tasks["work"] = {"operation": operation, **(options or {})}
+        if names:
+            tasks["work"]["input"] = names
+        tasks["out"] = {"operation": "export/url", "input": ["work"]}
+
+        job = self.create_job(tasks, retention_s=retention_s)
+        job = self.wait(job["id"], timeout=timeout)
+        if job["status"] != "finished":
+            failed = next((t for t in job["tasks"] if t.get("error")), None)
+            err = (failed or {}).get("error", {})
+            raise GigaiError(0, err.get("code", "job_" + job["status"]),
+                             err.get("message", f"The job ended {job['status']}."))
+
+        export = next(t for t in job["tasks"] if t["name"] == "out")
+        saved = []
+        results = export["result"]["files"]
+        for r in results:
+            if output and len(results) == 1 and not os.path.isdir(output):
+                path = output
+            else:
+                path = os.path.join(output or ".", r["filename"])
+            saved.append(self.download(r["url"], path))
+        return saved

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

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: gigai-tools
+Version: 0.1.0
+Summary: Client for the GigAI Tools API - run PDF, image, SVG and QR tools from Python. Free plan, no dependencies.
+Author-email: Gigai Kripa Services <hello@gigaikripaservices.com>
+License: MIT
+Project-URL: Homepage, https://gigai.tools/developers
+Project-URL: Documentation, https://gigai.tools/developers
+Keywords: pdf,merge,split,image,convert,resize,compress,qr,svg,api
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# gigai-tools
+
+Python client for the [GigAI Tools API](https://gigai.tools/developers). Run PDF, image, SVG and QR tools from code. The free plan gives 1,000 tasks a month with no card.
+
+No dependencies. Python 3.9+.
+
+## Install
+
+```
+pip install gigai-tools
+```
+
+## Get a key
+
+Create an account at [gigai.tools/developers](https://gigai.tools/developers) and make an API key in the dashboard. Set it as `GIGAI_API_KEY` or pass `api_key=`.
+
+## One call
+
+```python
+from gigai_tools import Client
+
+client = Client()
+
+# Merge two PDFs
+client.run("merge-pdf", files=["a.pdf", "b.pdf"], output="merged.pdf")
+
+# Compress an image to fit under 200 KB
+client.run("compress-image", files=["photo.jpg"], options={"target_kb": 200}, output="small.jpg")
+
+# Generate a QR code (no input file - the text is the payload)
+client.run("generate-qr", options={"text": "https://example.com"}, output="qr.png")
+```
+
+`run()` imports your files, runs the tool, exports the result and downloads it. Files can also be `https://` URLs and the server fetches them.
+
+## Tools
+
+```python
+for tool in client.tools():
+    print(tool["slug"], "-", tool["description"])
+```
+
+Live engines: merge-pdf, split-pdf, rotate-pdf, pdf-to-text, convert-image, resize-image, compress-image, optimize-svg, markdown-to-html, generate-qr. The catalog only lists tools the API can actually run.
+
+## Job graphs
+
+Chain tools in one job. Each task names its inputs and the server runs them in dependency order:
+
+```python
+job = client.create_job({
+    "in":  {"operation": "import/url", "url": "https://example.com/report.pdf"},
+    "rot": {"operation": "rotate-pdf", "input": ["in"], "angle": 90},
+    "txt": {"operation": "pdf-to-text", "input": ["rot"]},
+    "out": {"operation": "export/url", "input": ["txt"]},
+}, retention_s=600)
+
+job = client.wait(job["id"])
+export = next(t for t in job["tasks"] if t["name"] == "out")
+client.download(export["result"]["files"][0]["url"], "report.txt")
+```
+
+`Idempotency-Key` makes retries safe: pass `idempotency_key=` and the same key returns the same job instead of running the work twice.
+
+## Errors
+
+Every failure raises `GigaiError` with a machine-readable `code` (`invalid_option`, `file_too_large`, `quota_exceeded`, `target_unreachable`, ...), the human message, and the offending parameter when there is one.
+
+## Privacy
+
+File contents are never logged. Results are deleted after the retention you choose (default 1 hour, `retention_s=0` means one download or 60 seconds) and deletion is verified. The web tools at [gigai.tools](https://gigai.tools) never need an account - accounts exist only for this API.

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

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

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1 @@
+gigai_tools

gigai_tools-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gigai-tools"
+version = "0.1.0"
+description = "Client for the GigAI Tools API - run PDF, image, SVG and QR tools from Python. Free plan, no dependencies."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "Gigai Kripa Services", email = "hello@gigaikripaservices.com" }]
+keywords = ["pdf", "merge", "split", "image", "convert", "resize", "compress", "qr", "svg", "api"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+Homepage = "https://gigai.tools/developers"
+Documentation = "https://gigai.tools/developers"
+
+[tool.setuptools]
+packages = ["gigai_tools"]

gigai_tools-0.1.0/setup.cfg

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