boreholeai 0.1.0__tar.gz

boreholeai-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.env

boreholeai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BoreholeAI
+
+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.

boreholeai-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: boreholeai
+Version: 0.1.0
+Summary: Python SDK for the BoreholeAI API — digitise borehole logs programmatically
+Project-URL: Homepage, https://boreholeai.com
+Project-URL: Documentation, https://boreholeai.com/docs
+Project-URL: Repository, https://github.com/boreholeai/boreholeai-python
+Author-email: BoreholeAI <support@boreholeai.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,borehole,boreholeai,digitisation,geotechnical
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.24
+Description-Content-Type: text/markdown
+
+# BoreholeAI Python SDK
+
+Python SDK for the [BoreholeAI](https://boreholeai.com) API. Digitise borehole logs programmatically — upload PDFs or images, get structured ground profiles, test data, and annotated PDFs.
+
+## Installation
+
+```bash
+pip install boreholeai
+```
+
+## Quick Start
+
+```python
+from boreholeai import BoreholeAI
+
+client = BoreholeAI(api_key="bhai_your_api_key_here")
+
+# Process a single borehole log
+result = client.process_documents("BH01.pdf", output_dir="./results")
+
+print(f"Pages processed: {result.num_pages}")
+for f in result.files:
+    print(f"  {f.filename}")
+```
+
+## Folder Processing
+
+Pass a directory path to process multiple files together. Results are merged into a single ground profile Excel, test data Excel, and AGS file, with one annotated PDF per input file.
+
+```python
+result = client.process_documents("./borehole_logs/", output_dir="./results")
+
+# Output:
+#   Borehole_ground_profile.xlsx   (merged from all input files)
+#   Borehole_test_data.xlsx        (merged from all input files)
+#   Borehole_ags4.ags              (merged from all input files)
+#   BH01_annotated.pdf             (one per input file)
+#   BH02_annotated.pdf
+#   BH03_annotated.pdf
+```
+
+## Supported File Types
+
+- PDF (`.pdf`)
+- PNG (`.png`)
+- JPEG (`.jpg`, `.jpeg`)
+- TIFF (`.tif`, `.tiff`)
+- WebP (`.webp`)
+
+## API Key
+
+Get your API key from the [BoreholeAI dashboard](https://boreholeai.com/app/settings/api-keys).
+
+```python
+# Pass directly
+client = BoreholeAI(api_key="bhai_xxx")
+
+# Or use for local development / testing
+client = BoreholeAI(api_key="bhai_xxx", base_url="http://localhost:8000")
+```
+
+## Error Handling
+
+```python
+from boreholeai import BoreholeAI, InsufficientCreditsError, AuthenticationError
+
+client = BoreholeAI(api_key="bhai_xxx")
+
+try:
+    result = client.process_documents("borehole.pdf")
+except AuthenticationError:
+    print("Invalid API key")
+except InsufficientCreditsError:
+    print("Not enough credits — buy more at boreholeai.com")
+```
+
+## Response
+
+`process_documents()` returns a `JobResult`:
+
+```python
+@dataclass
+class JobResult:
+    job_id: str              # Unique job identifier
+    status: str              # "completed"
+    num_pages: int           # Total pages processed
+    credits_used: int        # Credits consumed
+    files: list[FileResult]  # Downloaded result files
+
+@dataclass
+class FileResult:
+    filename: str            # e.g. "Borehole_ground_profile.xlsx"
+    path: Path               # Local path where file was saved
+```
+
+## License
+
+MIT

boreholeai-0.1.0/README.md

@@ -0,0 +1,98 @@
+# BoreholeAI Python SDK
+
+Python SDK for the [BoreholeAI](https://boreholeai.com) API. Digitise borehole logs programmatically — upload PDFs or images, get structured ground profiles, test data, and annotated PDFs.
+
+## Installation
+
+```bash
+pip install boreholeai
+```
+
+## Quick Start
+
+```python
+from boreholeai import BoreholeAI
+
+client = BoreholeAI(api_key="bhai_your_api_key_here")
+
+# Process a single borehole log
+result = client.process_documents("BH01.pdf", output_dir="./results")
+
+print(f"Pages processed: {result.num_pages}")
+for f in result.files:
+    print(f"  {f.filename}")
+```
+
+## Folder Processing
+
+Pass a directory path to process multiple files together. Results are merged into a single ground profile Excel, test data Excel, and AGS file, with one annotated PDF per input file.
+
+```python
+result = client.process_documents("./borehole_logs/", output_dir="./results")
+
+# Output:
+#   Borehole_ground_profile.xlsx   (merged from all input files)
+#   Borehole_test_data.xlsx        (merged from all input files)
+#   Borehole_ags4.ags              (merged from all input files)
+#   BH01_annotated.pdf             (one per input file)
+#   BH02_annotated.pdf
+#   BH03_annotated.pdf
+```
+
+## Supported File Types
+
+- PDF (`.pdf`)
+- PNG (`.png`)
+- JPEG (`.jpg`, `.jpeg`)
+- TIFF (`.tif`, `.tiff`)
+- WebP (`.webp`)
+
+## API Key
+
+Get your API key from the [BoreholeAI dashboard](https://boreholeai.com/app/settings/api-keys).
+
+```python
+# Pass directly
+client = BoreholeAI(api_key="bhai_xxx")
+
+# Or use for local development / testing
+client = BoreholeAI(api_key="bhai_xxx", base_url="http://localhost:8000")
+```
+
+## Error Handling
+
+```python
+from boreholeai import BoreholeAI, InsufficientCreditsError, AuthenticationError
+
+client = BoreholeAI(api_key="bhai_xxx")
+
+try:
+    result = client.process_documents("borehole.pdf")
+except AuthenticationError:
+    print("Invalid API key")
+except InsufficientCreditsError:
+    print("Not enough credits — buy more at boreholeai.com")
+```
+
+## Response
+
+`process_documents()` returns a `JobResult`:
+
+```python
+@dataclass
+class JobResult:
+    job_id: str              # Unique job identifier
+    status: str              # "completed"
+    num_pages: int           # Total pages processed
+    credits_used: int        # Credits consumed
+    files: list[FileResult]  # Downloaded result files
+
+@dataclass
+class FileResult:
+    filename: str            # e.g. "Borehole_ground_profile.xlsx"
+    path: Path               # Local path where file was saved
+```
+
+## License
+
+MIT

boreholeai-0.1.0/examples/basic_usage.py

@@ -0,0 +1,25 @@
+"""Basic usage example for the BoreholeAI Python SDK."""
+
+from boreholeai import BoreholeAI
+
+# Initialize client with your API key
+client = BoreholeAI(api_key="bhai_your_api_key_here")
+
+# Process a single PDF
+result = client.process_documents("path/to/borehole.pdf", output_dir="./results")
+
+print(f"Job ID: {result.job_id}")
+print(f"Pages processed: {result.num_pages}")
+print(f"Credits used: {result.credits_used}")
+print(f"Output files:")
+for f in result.files:
+    print(f"  {f.filename} → {f.path}")
+
+
+# Process a folder of PDFs and images (merged output)
+result = client.process_documents("path/to/logs/", output_dir="./results")
+
+print(f"\nBatch job ID: {result.job_id}")
+print(f"Total pages: {result.num_pages}")
+for f in result.files:
+    print(f"  {f.filename} → {f.path}")

boreholeai-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "boreholeai"
+version = "0.1.0"
+description = "Python SDK for the BoreholeAI API — digitise borehole logs programmatically"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "BoreholeAI", email = "support@boreholeai.com" }]
+keywords = ["boreholeai", "geotechnical", "borehole", "digitisation", "api"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "httpx>=0.24,<1",
+]
+
+[project.urls]
+Homepage = "https://boreholeai.com"
+Documentation = "https://boreholeai.com/docs"
+Repository = "https://github.com/boreholeai/boreholeai-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/boreholeai"]

boreholeai-0.1.0/src/boreholeai/__init__.py

@@ -0,0 +1,26 @@
+"""BoreholeAI Python SDK — digitise borehole logs programmatically."""
+
+from boreholeai._types import FileResult, JobResult
+from boreholeai._version import __version__
+from boreholeai.client import BoreholeAI
+from boreholeai.exceptions import (
+    AuthenticationError,
+    BoreholeAIError,
+    InsufficientCreditsError,
+    JobFailedError,
+    RateLimitError,
+    ServerError,
+)
+
+__all__ = [
+    "BoreholeAI",
+    "__version__",
+    "AuthenticationError",
+    "BoreholeAIError",
+    "FileResult",
+    "InsufficientCreditsError",
+    "JobFailedError",
+    "JobResult",
+    "RateLimitError",
+    "ServerError",
+]

boreholeai-0.1.0/src/boreholeai/_api.py

@@ -0,0 +1,86 @@
+"""Low-level HTTP calls to the BoreholeAI worker API."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from boreholeai.exceptions import (
+    AuthenticationError,
+    BoreholeAIError,
+    InsufficientCreditsError,
+    RateLimitError,
+    ServerError,
+)
+
+DEFAULT_BASE_URL = "https://boreholeai-worker-7b5nhwzhwq-uc.a.run.app"
+DEFAULT_TIMEOUT = 120.0
+
+
+class APIClient:
+    """Thin wrapper around httpx for authenticated requests to the worker."""
+
+    def __init__(self, api_key: str, base_url: str, timeout: float):
+        self._client = httpx.Client(
+            base_url=base_url,
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=timeout,
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def create_job(self, file_paths: list[Path]) -> dict[str, Any]:
+        """POST /v1/jobs — upload files and create a job.
+
+        Returns {"job_id": ..., "num_pages": ..., "credits_remaining": ...}.
+        """
+        files = [
+            ("files", (p.name, p.read_bytes()))
+            for p in file_paths
+        ]
+        resp = self._client.post("/v1/jobs", files=files)
+        _raise_for_status(resp)
+        return resp.json()
+
+    def get_job(self, job_id: str) -> dict[str, Any]:
+        """GET /v1/jobs/{id} — poll job status."""
+        resp = self._client.get(f"/v1/jobs/{job_id}")
+        _raise_for_status(resp)
+        return resp.json()
+
+    def get_results(self, job_id: str) -> dict[str, Any]:
+        """GET /v1/jobs/{id}/results — signed download URLs."""
+        resp = self._client.get(f"/v1/jobs/{job_id}/results")
+        _raise_for_status(resp)
+        return resp.json()
+
+    def download_file(self, url: str) -> bytes:
+        """Download a file from a signed URL."""
+        resp = httpx.get(url, timeout=self._client.timeout)
+        resp.raise_for_status()
+        return resp.content
+
+
+def _raise_for_status(resp: httpx.Response) -> None:
+    """Convert HTTP errors to SDK exceptions."""
+    if resp.is_success:
+        return
+
+    detail = ""
+    try:
+        detail = resp.json().get("detail", "")
+    except Exception:
+        detail = resp.text
+
+    if resp.status_code == 401:
+        raise AuthenticationError(detail or "Invalid API key", 401)
+    if resp.status_code == 402:
+        raise InsufficientCreditsError(detail or "Insufficient credits", 402)
+    if resp.status_code == 429:
+        raise RateLimitError(detail or "Rate limited", 429)
+    if resp.status_code >= 500:
+        raise ServerError(detail or "Server error", resp.status_code)
+    raise BoreholeAIError(detail or f"HTTP {resp.status_code}", resp.status_code)

boreholeai-0.1.0/src/boreholeai/_files.py

@@ -0,0 +1,47 @@
+"""File scanning and validation utilities."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+SUPPORTED_EXTENSIONS = {".pdf", ".png", ".jpg", ".jpeg", ".tif", ".tiff", ".webp"}
+
+
+def collect_files(input_path: str | Path) -> list[Path]:
+    """Collect valid files from a path (single file or directory).
+
+    Returns a sorted list of Paths with supported extensions.
+    Raises FileNotFoundError if the path doesn't exist.
+    Raises ValueError if no supported files are found.
+    """
+    path = Path(input_path).resolve()
+
+    if not path.exists():
+        raise FileNotFoundError(f"Path not found: {path}")
+
+    if path.is_file():
+        _validate_extension(path)
+        return [path]
+
+    if path.is_dir():
+        files = sorted(
+            f for f in path.iterdir()
+            if f.is_file() and f.suffix.lower() in SUPPORTED_EXTENSIONS
+        )
+        if not files:
+            raise ValueError(
+                f"No supported files found in {path}. "
+                f"Accepted: {', '.join(sorted(SUPPORTED_EXTENSIONS))}"
+            )
+        return files
+
+    raise ValueError(f"Path is neither a file nor a directory: {path}")
+
+
+def _validate_extension(path: Path) -> None:
+    """Raise ValueError if the file extension is not supported."""
+    if path.suffix.lower() not in SUPPORTED_EXTENSIONS:
+        raise ValueError(
+            f"Unsupported file type: {path.suffix}. "
+            f"Accepted: {', '.join(sorted(SUPPORTED_EXTENSIONS))}"
+        )

boreholeai-0.1.0/src/boreholeai/_types.py

@@ -0,0 +1,25 @@
+"""Response types for the BoreholeAI SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class FileResult:
+    """A single downloaded result file."""
+
+    filename: str
+    path: Path
+
+
+@dataclass
+class JobResult:
+    """Result of processing a single job (one or more input files)."""
+
+    job_id: str
+    status: str
+    num_pages: int
+    credits_used: int
+    files: list[FileResult] = field(default_factory=list)

boreholeai-0.1.0/src/boreholeai/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

boreholeai-0.1.0/src/boreholeai/client.py

@@ -0,0 +1,164 @@
+"""BoreholeAI Python SDK client."""
+
+from __future__ import annotations
+
+import sys
+import time
+from pathlib import Path
+
+from boreholeai._api import APIClient, DEFAULT_BASE_URL, DEFAULT_TIMEOUT
+from boreholeai._files import collect_files
+from boreholeai._types import FileResult, JobResult
+from boreholeai.exceptions import JobFailedError
+
+# Polling configuration
+_POLL_INITIAL_INTERVAL = 2.0   # seconds
+_POLL_MAX_INTERVAL = 10.0      # seconds
+_POLL_BACKOFF_FACTOR = 1.5
+
+# Default output directory
+_DEFAULT_OUTPUT_DIR = "./boreholeai_output"
+
+
+class BoreholeAI:
+    """Client for the BoreholeAI API.
+
+    Usage::
+
+        from boreholeai import BoreholeAI
+
+        client = BoreholeAI(api_key="bhai_xxx")
+
+        # Single file
+        results = client.process_documents("borehole.pdf")
+
+        # Folder — all PDFs + images processed together, merged output
+        results = client.process_documents("./logs/", output_dir="./results")
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ):
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._api = APIClient(api_key=api_key, base_url=base_url, timeout=timeout)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._api.close()
+
+    def __enter__(self) -> BoreholeAI:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def process_documents(
+        self,
+        input_path: str | Path,
+        *,
+        output_dir: str | Path = _DEFAULT_OUTPUT_DIR,
+    ) -> JobResult:
+        """Upload files, process them, and download results.
+
+        Args:
+            input_path: Path to a single file or a directory of files.
+                Supported formats: PDF, PNG, JPG, JPEG, TIF, TIFF, WebP.
+            output_dir: Directory to save result files. Created if it doesn't exist.
+
+        Returns:
+            JobResult with job metadata and list of downloaded files.
+
+        Raises:
+            FileNotFoundError: If input_path doesn't exist.
+            ValueError: If no supported files found.
+            AuthenticationError: If API key is invalid.
+            InsufficientCreditsError: If not enough credits.
+            JobFailedError: If processing fails on the server.
+        """
+        files = collect_files(input_path)
+        out = Path(output_dir).resolve()
+        out.mkdir(parents=True, exist_ok=True)
+
+        # Upload
+        total_files = len(files)
+        _print_status(f"Uploading {total_files} file(s)...")
+        job_data = self._api.create_job(files)
+        job_id = job_data["job_id"]
+        num_pages = job_data["num_pages"]
+        _print_status(
+            f"Job {job_id[:8]}... created — "
+            f"{num_pages} page(s), {total_files} file(s)"
+        )
+
+        # Poll
+        result = self._poll_until_done(job_id)
+
+        # Download results
+        downloaded = self._download_results(job_id, out)
+
+        return JobResult(
+            job_id=job_id,
+            status=result["status"],
+            num_pages=num_pages,
+            credits_used=num_pages,
+            files=downloaded,
+        )
+
+    def _poll_until_done(self, job_id: str) -> dict:
+        """Poll GET /v1/jobs/{id} until status is completed or failed."""
+        interval = _POLL_INITIAL_INTERVAL
+
+        while True:
+            data = self._api.get_job(job_id)
+            status = data["status"]
+
+            if status == "completed":
+                _print_status("Processing complete!")
+                return data
+
+            if status == "failed":
+                error = data.get("error_message", "Unknown error")
+                raise JobFailedError(f"Job {job_id} failed: {error}")
+
+            # Show progress if available
+            progress = data.get("progress") or {}
+            pages_done = progress.get("pages_done", 0)
+            pages_total = progress.get("pages_total", "?")
+            _print_status(
+                f"Processing... {pages_done}/{pages_total} pages "
+                f"[{status}]"
+            )
+
+            time.sleep(interval)
+            interval = min(interval * _POLL_BACKOFF_FACTOR, _POLL_MAX_INTERVAL)
+
+    def _download_results(self, job_id: str, output_dir: Path) -> list[FileResult]:
+        """Download all result files to output_dir."""
+        results_data = self._api.get_results(job_id)
+        downloaded: list[FileResult] = []
+
+        for file_info in results_data.get("files", []):
+            filename = file_info["filename"]
+            url = file_info["url"]
+
+            _print_status(f"Downloading {filename}...")
+            content = self._api.download_file(url)
+
+            dest = output_dir / filename
+            dest.write_bytes(content)
+            downloaded.append(FileResult(filename=filename, path=dest))
+
+        _print_status(
+            f"Downloaded {len(downloaded)} file(s) to {output_dir}"
+        )
+        return downloaded
+
+
+def _print_status(message: str) -> None:
+    """Print a status message to stderr (doesn't interfere with stdout piping)."""
+    print(f"  {message}", file=sys.stderr, flush=True)

boreholeai-0.1.0/src/boreholeai/exceptions.py

@@ -0,0 +1,29 @@
+"""BoreholeAI SDK exceptions."""
+
+
+class BoreholeAIError(Exception):
+    """Base exception for all SDK errors."""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class AuthenticationError(BoreholeAIError):
+    """Invalid or missing API key (401)."""
+
+
+class InsufficientCreditsError(BoreholeAIError):
+    """Not enough credits to process the request (402)."""
+
+
+class RateLimitError(BoreholeAIError):
+    """Too many requests (429)."""
+
+
+class ServerError(BoreholeAIError):
+    """Worker returned 5xx."""
+
+
+class JobFailedError(BoreholeAIError):
+    """Job processing failed on the server."""