flexorch-sdk 0.1.0__py3-none-any.whl

flexorch_sdk/__init__.py

@@ -0,0 +1,63 @@
+"""
+flexorch-sdk — Python SDK for the FlexOrch API.
+
+    from flexorch_sdk import FlexOrchClient
+
+    client = FlexOrchClient("fx_your_key_here")
+
+    # Process a document and wait for the result
+    job = client.process("contract.pdf", locale="tr").wait()
+    print(job.quality_grade)   # "A"
+
+    # Download the dataset as JSONL
+    dataset = job.dataset()
+    dataset.export("jsonl", path="output.jsonl")
+
+    # Or use the context manager
+    with FlexOrchClient("fx_...") as client:
+        jobs = client.process_many(["a.pdf", "b.pdf"])
+        for job in jobs:
+            job.wait()
+"""
+
+from .client import FlexOrchClient
+from .models.job import Job
+from .models.dataset import Dataset
+from .models.connector import Connector, ConnectorTestResult
+from .models.search import SearchResult
+from .resources.usage import UsageSnapshot
+from .resources.webhooks import Webhook
+from .errors import (
+    FlexOrchError,
+    AuthError,
+    QuotaError,
+    RateLimitError,
+    NotFoundError,
+    ValidationError,
+    ServerError,
+    JobFailedError,
+    TimeoutError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "FlexOrchClient",
+    "Job",
+    "Dataset",
+    "Connector",
+    "ConnectorTestResult",
+    "SearchResult",
+    "UsageSnapshot",
+    "Webhook",
+    "FlexOrchError",
+    "AuthError",
+    "QuotaError",
+    "RateLimitError",
+    "NotFoundError",
+    "ValidationError",
+    "ServerError",
+    "JobFailedError",
+    "TimeoutError",
+    "__version__",
+]

flexorch_sdk/_transport.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import httpx
+
+from .errors import (
+    AuthError,
+    FlexOrchError,
+    NotFoundError,
+    QuotaError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+_DEFAULT_BASE_URL = "https://api.flexorch.com/v1"
+_DEFAULT_TIMEOUT = 30.0
+_DEFAULT_MAX_RETRIES = 3
+_RETRY_STATUSES = {429, 500, 502, 503, 504}
+
+
+def _parse_error(response: httpx.Response) -> FlexOrchError:
+    status = response.status_code
+    try:
+        body = response.json()
+        error_block = body.get("error", {})
+        code = error_block.get("code", "")
+        message = error_block.get("message", response.text)
+    except Exception:
+        code = ""
+        message = response.text or f"HTTP {status}"
+
+    if status == 401:
+        return AuthError(message, status_code=status, error_code=code)
+    if status in (402,):
+        return QuotaError(message, status_code=status, error_code=code)
+    if status == 404:
+        return NotFoundError(message, status_code=status, error_code=code)
+    if status == 422:
+        return ValidationError(message, status_code=status, error_code=code)
+    if status == 429:
+        retry_after = int(response.headers.get("Retry-After", 60))
+        return RateLimitError(message, retry_after=retry_after)
+    if status >= 500:
+        return ServerError(message, status_code=status, error_code=code)
+    return FlexOrchError(message, status_code=status, error_code=code)
+
+
+class Transport:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = _DEFAULT_TIMEOUT,
+        max_retries: int = _DEFAULT_MAX_RETRIES,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+        self._client = httpx.Client(
+            headers={
+                "X-API-KEY": api_key,
+                "User-Agent": "flexorch-sdk-python/0.1.0",
+            },
+            timeout=timeout,
+        )
+
+    def _url(self, path: str) -> str:
+        return f"{self._base_url}/{path.lstrip('/')}"
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        url = self._url(path)
+        last_exc: Exception | None = None
+
+        for attempt in range(self._max_retries):
+            try:
+                response = self._client.request(method, url, **kwargs)
+            except httpx.TimeoutException as exc:
+                last_exc = exc
+                if attempt < self._max_retries - 1:
+                    time.sleep(2 ** attempt)
+                continue
+
+            if response.status_code in _RETRY_STATUSES and attempt < self._max_retries - 1:
+                wait = int(response.headers.get("Retry-After", 2 ** attempt))
+                time.sleep(wait)
+                continue
+
+            if response.is_error:
+                raise _parse_error(response)
+
+            if response.status_code == 204 or not response.content:
+                return None
+            return response.json()
+
+        raise FlexOrchError(f"Request failed after {self._max_retries} attempts: {last_exc}")
+
+    def get(self, path: str, **kwargs: Any) -> Any:
+        return self._request("GET", path, **kwargs)
+
+    def get_bytes(self, path: str, **kwargs: Any) -> bytes:
+        """GET that returns raw response bytes (for file download endpoints)."""
+        url = self._url(path)
+        response = self._client.request("GET", url, **kwargs)
+        if response.is_error:
+            raise _parse_error(response)
+        return response.content
+
+    def post(self, path: str, **kwargs: Any) -> Any:
+        return self._request("POST", path, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> Any:
+        return self._request("DELETE", path, **kwargs)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> Transport:
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()

flexorch_sdk/client.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from ._transport import Transport
+from .models.job import Job
+from .models.search import SearchResult
+from .resources.jobs import JobsResource
+from .resources.datasets import DatasetsResource
+from .resources.usage import UsageResource
+from .resources.webhooks import WebhooksResource
+from .resources.connectors import ConnectorsResource
+
+_DEFAULT_BASE_URL = "https://api.flexorch.com/v1"
+
+
+class FlexOrchClient:
+    """Main entry point for the FlexOrch API.
+
+    Args:
+        api_key:     Your FlexOrch API key (fx_...).
+                     Defaults to FLEXORCH_API_KEY environment variable.
+        base_url:    Override the API base URL (useful for testing).
+        timeout:     HTTP timeout in seconds. Default: 30.
+        max_retries: Maximum retry attempts for transient errors. Default: 3.
+
+    Example::
+
+        from flexorch_sdk import FlexOrchClient
+
+        client = FlexOrchClient("fx_your_key_here")
+        dataset = client.process("contract.pdf", locale="tr").wait().dataset()
+        dataset.export("jsonl", path="output.jsonl")
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+    ) -> None:
+        resolved_key = api_key or os.environ.get("FLEXORCH_API_KEY", "")
+        if not resolved_key:
+            raise ValueError(
+                "No API key provided. Pass api_key= or set the FLEXORCH_API_KEY environment variable."
+            )
+
+        self._transport = Transport(
+            api_key=resolved_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+
+        self.jobs = JobsResource(self._transport)
+        self.datasets = DatasetsResource(self._transport)
+        self.usage = UsageResource(self._transport)
+        self.webhooks = WebhooksResource(self._transport)
+        self.connectors = ConnectorsResource(self._transport)
+
+    def process(
+        self,
+        file_path: str | Path,
+        *,
+        locale: str = "und",
+        pipeline_config: dict[str, Any] | None = None,
+    ) -> Job:
+        """Upload a document and start the processing pipeline.
+
+        Args:
+            file_path:       Path to the file (PDF, DOCX, TXT, XLSX, …).
+            locale:          Language hint for PII detection.
+                             "und" = all detectors (default), "tr", "de", "en", etc.
+            pipeline_config: Optional pipeline overrides passed to the API.
+
+        Returns:
+            A :class:`Job` object. Call ``.wait()`` to block until processing completes.
+        """
+        path = Path(file_path)
+        if not path.exists():
+            raise FileNotFoundError(f"File not found: {path}")
+
+        form: dict[str, Any] = {"locale": locale}
+        if pipeline_config:
+            import json
+            form["pipeline_config"] = json.dumps(pipeline_config)
+
+        with path.open("rb") as fh:
+            data = self._transport.post(
+                "/data-process/async",
+                files={"file": (path.name, fh, "application/octet-stream")},
+                data=form,
+            )
+
+        return Job._from_dict(data, self._transport)
+
+    def process_many(
+        self,
+        file_paths: list[str | Path],
+        *,
+        locale: str = "und",
+    ) -> list[Job]:
+        """Upload and start processing for multiple files sequentially.
+
+        Returns:
+            List of :class:`Job` objects in the same order as *file_paths*.
+        """
+        return [self.process(p, locale=locale) for p in file_paths]
+
+    def process_from_s3(
+        self,
+        connector_id: str,
+        keys: list[str],
+        *,
+        locale: str = "und",
+        pipeline_config: dict[str, Any] | None = None,
+    ) -> list[Job]:
+        """Start processing for files already stored in an S3 connector.
+
+        Args:
+            connector_id: ID of an active S3 connector.
+            keys:         List of S3 object keys to process.
+            locale:       Language hint for PII detection.
+            pipeline_config: Optional pipeline overrides.
+
+        Returns:
+            List of :class:`Job` objects, one per key.
+        """
+        import json as _json
+
+        jobs = []
+        for key in keys:
+            source = {"connector_id": connector_id, "keys": [key]}
+            form: dict[str, Any] = {
+                "locale": locale,
+                "source": _json.dumps(source),
+            }
+            if pipeline_config:
+                form["pipeline_config"] = _json.dumps(pipeline_config)
+            data = self._transport.post("/data-process/async", data=form)
+            jobs.append(Job._from_dict(data, self._transport))
+        return jobs
+
+    def search(
+        self,
+        query: str,
+        *,
+        top_k: int = 10,
+        filters: dict[str, Any] | None = None,
+    ) -> list[SearchResult]:
+        """Semantic search across all indexed datasets (Pro+ plan required).
+
+        Args:
+            query:   Natural language search query.
+            top_k:   Number of results to return (1–50). Default: 10.
+            filters: Optional filter dict. Supported keys:
+                     ``document_type``, ``language``, ``pii_masked``, ``quality_grade``.
+
+        Returns:
+            List of :class:`SearchResult` sorted by descending cosine score.
+        """
+        body: dict[str, Any] = {"query": query, "top_k": top_k}
+        if filters:
+            body["filters"] = filters
+        data = self._transport.post("/search", json=body) or {}
+        items = data.get("results", [])
+        return [SearchResult._from_dict(item) for item in items]
+
+    def close(self) -> None:
+        """Release the underlying HTTP connection pool."""
+        self._transport.close()
+
+    def __enter__(self) -> FlexOrchClient:
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"FlexOrchClient(base_url={self._transport._base_url!r})"

flexorch_sdk/errors.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+
+class FlexOrchError(Exception):
+    """Base exception for all FlexOrch SDK errors."""
+
+    def __init__(self, message: str, status_code: int = 0, error_code: str = "") -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.error_code = error_code
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.args[0]!r}, status={self.status_code}, code={self.error_code!r})"
+
+
+class AuthError(FlexOrchError):
+    """Invalid or missing API key (401)."""
+
+
+class QuotaError(FlexOrchError):
+    """Credit quota exceeded or trial expired (402 / 429)."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int = 402,
+        error_code: str = "",
+        remaining_credits: int = 0,
+        reset_at: str = "",
+    ) -> None:
+        super().__init__(message, status_code, error_code)
+        self.remaining_credits = remaining_credits
+        self.reset_at = reset_at
+
+
+class RateLimitError(FlexOrchError):
+    """Too many requests — slow down (429 with rate-limit context)."""
+
+    def __init__(
+        self,
+        message: str,
+        retry_after: int = 60,
+    ) -> None:
+        super().__init__(message, status_code=429, error_code="RATE_LIMIT_EXCEEDED")
+        self.retry_after = retry_after
+
+
+class NotFoundError(FlexOrchError):
+    """Requested resource does not exist (404)."""
+
+
+class ValidationError(FlexOrchError):
+    """Request payload failed validation (422)."""
+
+
+class ServerError(FlexOrchError):
+    """Unexpected server-side error (5xx)."""
+
+
+class JobFailedError(FlexOrchError):
+    """Job completed with status=failed — pipeline could not process the document."""
+
+    def __init__(self, job_id: str, reason: str = "") -> None:
+        super().__init__(f"Job {job_id!r} failed: {reason or 'unknown reason'}")
+        self.job_id = job_id
+        self.failure_reason = reason
+
+
+class TimeoutError(FlexOrchError):  # noqa: A001
+    """job.wait() exceeded the requested timeout without completing."""
+
+    def __init__(self, job_id: str, timeout: int) -> None:
+        super().__init__(f"Job {job_id!r} did not complete within {timeout}s")
+        self.job_id = job_id
+        self.timeout = timeout

flexorch_sdk/models/__init__.py

@@ -0,0 +1,6 @@
+from .job import Job
+from .dataset import Dataset
+from .connector import Connector, ConnectorTestResult
+from .search import SearchResult
+
+__all__ = ["Job", "Dataset", "Connector", "ConnectorTestResult", "SearchResult"]

flexorch_sdk/models/connector.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Connector:
+    id: str
+    name: str
+    type: str
+    active: bool
+    last_tested_at: str | None = None
+    last_used_at: str | None = None
+    created_at: str = ""
+
+    @classmethod
+    def _from_dict(cls, data: dict) -> Connector:
+        return cls(
+            id=data.get("id", ""),
+            name=data.get("name", ""),
+            type=data.get("type", ""),
+            active=data.get("active", True),
+            last_tested_at=data.get("last_tested_at"),
+            last_used_at=data.get("last_used_at"),
+            created_at=data.get("created_at", ""),
+        )
+
+    def __repr__(self) -> str:
+        return f"Connector(id={self.id!r}, name={self.name!r}, type={self.type!r}, active={self.active})"
+
+
+@dataclass
+class ConnectorTestResult:
+    success: bool
+    latency_ms: int | None = None
+    message: str = ""
+
+    @classmethod
+    def _from_dict(cls, data: dict) -> ConnectorTestResult:
+        return cls(
+            success=data.get("success", False),
+            latency_ms=data.get("latency_ms"),
+            message=data.get("message", ""),
+        )

flexorch_sdk/models/dataset.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .._transport import Transport
+
+_SUPPORTED_FORMATS = {"json", "jsonl", "csv", "parquet", "md", "xml", "xlsx", "rag"}
+
+_INDEX_STATUSES = {"not_indexed", "indexing", "ready", "failed"}
+
+
+@dataclass
+class Dataset:
+    id: str
+    name: str
+    slug: str
+    status: str
+    row_count: int = 0
+    created_at: str = ""
+    available_formats: list[str] = field(default_factory=list)
+    _transport: Any = field(default=None, repr=False)
+
+    @classmethod
+    def _from_dict(cls, data: dict, transport: Transport) -> Dataset:
+        fmt_summary = data.get("format_summary", {})
+        formats = list(fmt_summary.get("files", {}).keys()) if isinstance(fmt_summary, dict) else []
+        return cls(
+            id=data.get("id", ""),
+            name=data.get("name", ""),
+            slug=data.get("slug", ""),
+            status=data.get("status", ""),
+            row_count=data.get("row_count", 0),
+            created_at=data.get("created_at", ""),
+            available_formats=formats,
+            _transport=transport,
+        )
+
+    def export(self, format: str, path: str | Path | None = None) -> bytes:
+        """Download dataset in the requested format.
+
+        Args:
+            format: One of json, jsonl, csv, parquet, md, xml, xlsx, rag.
+            path:   If given, write bytes to this file and return them.
+                    If None, return raw bytes without writing.
+
+        Returns:
+            Raw file content as bytes.
+        """
+        if format not in _SUPPORTED_FORMATS:
+            raise ValueError(f"Unsupported format {format!r}. Choose from: {sorted(_SUPPORTED_FORMATS)}")
+
+        raw = self._transport.get_bytes(
+            f"/datasets/{self.id}/export",
+            params={"format": format},
+        )
+
+        if path is not None:
+            Path(path).write_bytes(raw)
+
+        return raw
+
+    def export_to_s3(
+        self,
+        connector_id: str,
+        format: str,
+        prefix: str = "",
+    ) -> dict[str, Any]:
+        """Push an exported file directly to an S3 connector.
+
+        Args:
+            connector_id: ID of an active S3 connector.
+            format:       Export format (same set as :meth:`export`).
+            prefix:       Optional S3 key prefix (e.g. "exports/datasets/").
+
+        Returns:
+            Dict with ``s3_key`` and ``size_bytes``.
+        """
+        if format not in _SUPPORTED_FORMATS:
+            raise ValueError(f"Unsupported format {format!r}. Choose from: {sorted(_SUPPORTED_FORMATS)}")
+        return self._transport.post(
+            f"/datasets/{self.id}/export-s3",
+            json={"format": format, "connector_id": connector_id, "prefix": prefix},
+        )
+
+    def index(self) -> dict[str, Any]:
+        """Trigger semantic indexing for this dataset (Pro+ plan required).
+
+        Returns:
+            Dict with ``status`` and ``message``.
+        """
+        return self._transport.post(f"/datasets/{self.id}/index") or {}
+
+    def index_status(self) -> dict[str, Any]:
+        """Return the current semantic index status.
+
+        Returns:
+            Dict with ``status`` (not_indexed | indexing | ready | failed),
+            ``chunks_indexed``, and ``total_chunks``.
+        """
+        return self._transport.get(f"/datasets/{self.id}/index/status") or {}
+
+    def __repr__(self) -> str:
+        return f"Dataset(id={self.id!r}, name={self.name!r}, rows={self.row_count}, status={self.status!r})"

flexorch_sdk/models/job.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from ..errors import JobFailedError, TimeoutError
+
+if TYPE_CHECKING:
+    from .dataset import Dataset
+    from .._transport import Transport
+
+_TERMINAL_STATUSES = {"completed", "failed"}
+_DEFAULT_POLL_INTERVAL = 2
+_DEFAULT_TIMEOUT = 300
+
+
+@dataclass
+class Job:
+    id: str
+    status: str
+    quality_grade: str | None = None
+    quality_score: float | None = None
+    document_id: str | None = None
+    has_dataset: bool = False
+    failure_reason: str | None = None
+    created_at: str = ""
+    completed_at: str | None = None
+    _transport: Any = field(default=None, repr=False)
+
+    @classmethod
+    def _from_dict(cls, data: dict, transport: Transport) -> Job:
+        return cls(
+            id=data.get("job_id") or data.get("id", ""),
+            status=data.get("status", ""),
+            quality_grade=data.get("quality", {}).get("grade") if isinstance(data.get("quality"), dict) else data.get("quality_grade"),
+            quality_score=data.get("quality", {}).get("score") if isinstance(data.get("quality"), dict) else data.get("quality_score"),
+            document_id=data.get("document_id"),
+            has_dataset=bool(data.get("has_dataset", False)),
+            failure_reason=data.get("failure_reason"),
+            created_at=data.get("created_at", ""),
+            completed_at=data.get("completed_at"),
+            _transport=transport,
+        )
+
+    def wait(
+        self,
+        timeout: int = _DEFAULT_TIMEOUT,
+        poll_interval: int = _DEFAULT_POLL_INTERVAL,
+    ) -> Job:
+        """Poll until the job reaches a terminal status or timeout is exceeded."""
+        if self.status in _TERMINAL_STATUSES:
+            return self
+
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            data = self._transport.get(f"/jobs/{self.id}")
+            updated = Job._from_dict(data, self._transport)
+            self.__dict__.update(updated.__dict__)
+
+            if self.status in _TERMINAL_STATUSES:
+                break
+            time.sleep(poll_interval)
+        else:
+            raise TimeoutError(self.id, timeout)
+
+        if self.status == "failed":
+            raise JobFailedError(self.id, self.failure_reason or "")
+
+        return self
+
+    def dataset(self) -> Dataset | None:
+        """Return the dataset built from this job, if one exists."""
+        from .dataset import Dataset
+
+        if not self.has_dataset:
+            return None
+        data = self._transport.get("/datasets", params={"job_id": self.id})
+        items = data.get("items", data) if isinstance(data, dict) else data
+        if not items:
+            return None
+        return Dataset._from_dict(items[0], self._transport)
+
+    def __repr__(self) -> str:
+        return f"Job(id={self.id!r}, status={self.status!r}, grade={self.quality_grade!r})"

flexorch_sdk/models/search.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class SearchResult:
+    chunk_id: str
+    text: str
+    score: float
+    dataset_id: str
+    chunk_index: int
+    token_count: int
+    metadata: dict = field(default_factory=dict)
+
+    @classmethod
+    def _from_dict(cls, data: dict) -> SearchResult:
+        return cls(
+            chunk_id=data.get("chunk_id", ""),
+            text=data.get("text", ""),
+            score=data.get("score", 0.0),
+            dataset_id=data.get("dataset_id", ""),
+            chunk_index=data.get("chunk_index", 0),
+            token_count=data.get("token_count", 0),
+            metadata=data.get("metadata", {}),
+        )
+
+    def __repr__(self) -> str:
+        return f"SearchResult(score={self.score:.3f}, dataset_id={self.dataset_id!r}, chunk_index={self.chunk_index})"

flexorch_sdk/resources/__init__.py

@@ -0,0 +1,13 @@
+from .jobs import JobsResource
+from .datasets import DatasetsResource
+from .usage import UsageResource, UsageSnapshot
+from .webhooks import WebhooksResource, Webhook
+
+__all__ = [
+    "JobsResource",
+    "DatasetsResource",
+    "UsageResource",
+    "UsageSnapshot",
+    "WebhooksResource",
+    "Webhook",
+]

flexorch_sdk/resources/connectors.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from typing import Any, TYPE_CHECKING
+
+from ..models.connector import Connector, ConnectorTestResult
+
+if TYPE_CHECKING:
+    from .._transport import Transport
+
+_VALID_TYPES = {"s3", "gcs", "azure_blob"}
+
+
+class ConnectorsResource:
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def create(self, name: str, type: str, config: dict[str, Any]) -> Connector:
+        """Register a new storage connector.
+
+        Args:
+            name:   Display name (e.g. "Production S3").
+            type:   Connector type — "s3", "gcs", or "azure_blob".
+            config: Provider-specific credentials dict.
+                    S3 example: {"bucket": "...", "region": "...",
+                                 "access_key_id": "...", "secret_access_key": "..."}
+        """
+        if type not in _VALID_TYPES:
+            raise ValueError(f"Unknown connector type {type!r}. Valid: {sorted(_VALID_TYPES)}")
+        data = self._t.post("/connectors", json={"name": name, "type": type, "config": config})
+        return Connector._from_dict(data)
+
+    def list(self) -> list[Connector]:
+        """Return all connectors for the current tenant."""
+        data = self._t.get("/connectors")
+        items = data.get("items", data) if isinstance(data, dict) else data
+        return [Connector._from_dict(item) for item in items]
+
+    def get(self, connector_id: str) -> Connector:
+        """Fetch a single connector by ID."""
+        data = self._t.get(f"/connectors/{connector_id}")
+        return Connector._from_dict(data)
+
+    def delete(self, connector_id: str) -> None:
+        """Delete a connector (sets active=False on the backend)."""
+        self._t.delete(f"/connectors/{connector_id}")
+
+    def test(self, connector_id: str) -> ConnectorTestResult:
+        """Run a connectivity test for a connector.
+
+        Returns:
+            :class:`ConnectorTestResult` with ``success``, ``latency_ms``, and ``message``.
+        """
+        data = self._t.post(f"/connectors/{connector_id}/test")
+        return ConnectorTestResult._from_dict(data or {})

flexorch_sdk/resources/datasets.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..models.dataset import Dataset
+
+if TYPE_CHECKING:
+    from .._transport import Transport
+
+
+class DatasetsResource:
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def get(self, dataset_id: str) -> Dataset:
+        """Fetch a single dataset by ID."""
+        data = self._t.get(f"/datasets/{dataset_id}")
+        return Dataset._from_dict(data, self._t)
+
+    def list(self, page: int = 1, page_size: int = 20) -> list[Dataset]:
+        """List datasets for the current tenant, newest first."""
+        data = self._t.get("/datasets", params={"page": page, "page_size": page_size})
+        items = data.get("items", data) if isinstance(data, dict) else data
+        return [Dataset._from_dict(item, self._t) for item in items]

flexorch_sdk/resources/jobs.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..models.job import Job
+
+if TYPE_CHECKING:
+    from .._transport import Transport
+
+
+class JobsResource:
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def get(self, job_id: str) -> Job:
+        """Fetch a single job by ID."""
+        data = self._t.get(f"/jobs/{job_id}")
+        return Job._from_dict(data, self._t)
+
+    def list(self, page: int = 1, page_size: int = 20) -> list[Job]:
+        """List jobs for the current tenant, newest first."""
+        data = self._t.get("/jobs", params={"page": page, "page_size": page_size})
+        items = data.get("items", data) if isinstance(data, dict) else data
+        return [Job._from_dict(item, self._t) for item in items]

flexorch_sdk/resources/usage.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .._transport import Transport
+
+
+@dataclass
+class UsageSnapshot:
+    plan: str
+    credits_used: int
+    credits_limit: int
+    credits_remaining: int
+    reset_at: str
+    period_start: str
+    period_end: str
+
+    @classmethod
+    def _from_dict(cls, data: dict) -> UsageSnapshot:
+        return cls(
+            plan=data.get("plan", ""),
+            credits_used=data.get("credits_used", 0),
+            credits_limit=data.get("credits_limit", 0),
+            credits_remaining=data.get("credits_remaining", 0),
+            reset_at=data.get("reset_at", ""),
+            period_start=data.get("period_start", ""),
+            period_end=data.get("period_end", ""),
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"UsageSnapshot(plan={self.plan!r}, "
+            f"used={self.credits_used}/{self.credits_limit}, "
+            f"remaining={self.credits_remaining})"
+        )
+
+
+class UsageResource:
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def current(self) -> UsageSnapshot:
+        """Return the current billing period usage and credit balance."""
+        data = self._t.get("/usage/current")
+        return UsageSnapshot._from_dict(data)

flexorch_sdk/resources/webhooks.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .._transport import Transport
+
+_VALID_EVENTS = {"dataset.ready", "job.completed", "job.failed"}
+
+
+@dataclass
+class Webhook:
+    id: str
+    url: str
+    events: list[str]
+    active: bool
+    created_at: str
+
+    @classmethod
+    def _from_dict(cls, data: dict) -> Webhook:
+        return cls(
+            id=data.get("id", ""),
+            url=data.get("url", ""),
+            events=data.get("events", []),
+            active=data.get("active", True),
+            created_at=data.get("created_at", ""),
+        )
+
+    def __repr__(self) -> str:
+        return f"Webhook(id={self.id!r}, url={self.url!r}, events={self.events})"
+
+
+class WebhooksResource:
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def register(self, url: str, events: list[str]) -> Webhook:
+        """Register a new webhook endpoint.
+
+        Args:
+            url:    HTTPS URL that will receive POST requests.
+            events: List of event types, e.g. ["dataset.ready"].
+        """
+        invalid = set(events) - _VALID_EVENTS
+        if invalid:
+            raise ValueError(f"Unknown event types: {invalid}. Valid: {_VALID_EVENTS}")
+        data = self._t.post("/webhooks", json={"url": url, "events": events})
+        return Webhook._from_dict(data)
+
+    def list(self) -> list[Webhook]:
+        """Return all registered webhooks for the current tenant."""
+        data = self._t.get("/webhooks")
+        items = data.get("items", data) if isinstance(data, dict) else data
+        return [Webhook._from_dict(item) for item in items]
+
+    def delete(self, webhook_id: str) -> None:
+        """Delete a webhook by ID."""
+        self._t.delete(f"/webhooks/{webhook_id}")

flexorch_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,344 @@
+Metadata-Version: 2.4
+Name: flexorch-sdk
+Version: 0.1.0
+Summary: Python SDK for the FlexOrch API — process documents, build LLM-ready datasets
+Project-URL: Homepage, https://flexorch.com
+Project-URL: Repository, https://github.com/flexorch/flexorch-sdk
+Project-URL: Issues, https://github.com/flexorch/flexorch-sdk/issues
+Project-URL: Changelog, https://github.com/flexorch/flexorch-sdk/blob/main/CHANGELOG.md
+License: MIT
+License-File: LICENSE
+Keywords: dataset,document,flexorch,llm,pipeline
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# flexorch-sdk
+
+[![PyPI](https://img.shields.io/pypi/v/flexorch-sdk)](https://pypi.org/project/flexorch-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/flexorch-sdk)](https://pypi.org/project/flexorch-sdk/)
+[![CI](https://github.com/flexorch/flexorch-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/flexorch/flexorch-sdk/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Python SDK for the [FlexOrch](https://flexorch.com) API.
+
+FlexOrch turns unstructured documents (PDF, DOCX, invoices, emails…) into clean, structured, LLM-ready datasets — with automatic PII detection and masking, quality scoring, and multiple export formats.
+
+---
+
+## Install
+
+```bash
+pip install flexorch-sdk
+```
+
+Requires Python 3.10+. The only dependency is [`httpx`](https://www.python-httpx.org/).
+
+---
+
+## Quick start
+
+```python
+from flexorch_sdk import FlexOrchClient
+
+client = FlexOrchClient("fx_your_key_here")
+
+# Upload a document and wait for the pipeline to finish
+job = client.process("contract.pdf", locale="tr").wait()
+
+print(job.quality_grade)   # "A"
+print(job.quality_score)   # 0.91
+
+# Download the resulting dataset
+dataset = job.dataset()
+dataset.export("jsonl", path="output.jsonl")
+```
+
+---
+
+## Auth
+
+Pass your API key directly or set the `FLEXORCH_API_KEY` environment variable:
+
+```bash
+export FLEXORCH_API_KEY=fx_...
+```
+
+```python
+from flexorch_sdk import FlexOrchClient
+
+client = FlexOrchClient()   # reads FLEXORCH_API_KEY automatically
+```
+
+Get your API key from [app.flexorch.com](https://app.flexorch.com) → Settings.
+
+---
+
+## Supported input formats
+
+| Category | Formats |
+|---|---|
+| Documents | PDF (text + scanned), DOCX, TXT |
+| Spreadsheets | XLSX |
+| Email | EML, MSG |
+| E-invoices | XML/UBL (Peppol, GİB TR), FatturaPA (IT), XRechnung (DE), ZUGFeRD/Factur-X |
+| Images | JPG, PNG, TIFF (OCR) |
+| Web | HTML, HTM |
+
+---
+
+## Export formats
+
+`json` · `jsonl` · `csv` · `parquet` · `md` · `xml` · `xlsx` · `rag`
+
+```python
+dataset.export("jsonl", path="output.jsonl")   # write to file
+raw = dataset.export("parquet")                # return bytes
+```
+
+The `rag` format produces LlamaIndex/LangChain-compatible chunks with metadata.
+
+---
+
+## Processing
+
+### Single file
+
+```python
+job = client.process("invoice.pdf", locale="de").wait()
+```
+
+`locale` is an [IETF language tag](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry)
+used to activate the right PII detectors (`tr`, `de`, `en`, `fr`, `it`, `nl`, `es`, `pl`, `und` = all).
+
+### Batch
+
+```python
+jobs = client.process_many(["a.pdf", "b.pdf", "c.pdf"], locale="und")
+for job in jobs:
+    job.wait()
+    print(job.quality_grade, job.quality_score)
+```
+
+### From S3
+
+```python
+# Register a connector once; store conn.id for reuse
+conn = client.connectors.create(
+    "Production S3", "s3",
+    {
+        "bucket": "my-bucket",
+        "region": "eu-central-1",
+        "access_key_id": "AKIA...",
+        "secret_access_key": "...",
+    },
+)
+
+# Verify connectivity
+result = client.connectors.test(conn.id)
+print(result.success, result.latency_ms)   # True, 38
+
+# Process files from S3
+jobs = client.process_from_s3(conn.id, ["invoices/inv-001.pdf", "invoices/inv-002.pdf"])
+for job in jobs:
+    job.wait()
+```
+
+---
+
+## Job polling
+
+`Job.wait()` blocks until the pipeline completes or times out.
+
+```python
+job = client.process("large-report.pdf").wait(
+    timeout=600,       # seconds before TimeoutError (default: 300)
+    poll_interval=5,   # polling interval in seconds (default: 2)
+)
+
+print(job.status)        # "completed"
+print(job.quality_grade) # "A" | "B" | "C" | "D"
+print(job.quality_score) # 0.0 – 1.0
+print(job.has_dataset)   # True
+```
+
+---
+
+## Dataset operations
+
+```python
+ds = job.dataset()          # fetch dataset linked to this job
+ds = client.datasets.get("dataset-id")
+
+print(ds.name)              # "contract-2024-q1"
+print(ds.row_count)         # 142
+print(ds.available_formats) # ["json", "jsonl", "csv", "parquet"]
+
+# Download locally
+ds.export("jsonl", path="output.jsonl")
+
+# Push directly to S3
+push = ds.export_to_s3(conn.id, "jsonl", prefix="processed/datasets/")
+print(push["s3_key"])       # "processed/datasets/contract-2024-q1.jsonl"
+print(push["size_bytes"])   # 84320
+
+# Semantic indexing (Pro+)
+ds.index()
+status = ds.index_status()  # {"status": "ready", "chunks_indexed": 48}
+```
+
+---
+
+## Semantic search (Pro+)
+
+```python
+results = client.search(
+    "payment terms net 30",
+    top_k=10,
+    filters={
+        "document_type": "invoice",
+        "language": "de",
+        "quality_grade": "A",
+        "pii_masked": True,
+    },
+)
+
+for r in results:
+    print(f"{r.score:.3f}  [{r.dataset_id}]  {r.text[:120]}")
+```
+
+---
+
+## Resources
+
+```python
+# Jobs
+jobs = client.jobs.list(page=1, page_size=20)
+job  = client.jobs.get("job-id")
+
+# Datasets
+datasets = client.datasets.list()
+ds       = client.datasets.get("dataset-id")
+
+# Usage
+usage = client.usage.current()
+print(f"{usage.credits_used} / {usage.credits_limit} credits used")
+print(f"Plan: {usage.plan}  —  resets {usage.reset_at}")
+
+# Webhooks
+client.webhooks.register("https://your-server.com/hook", events=["dataset.ready"])
+client.webhooks.list()
+client.webhooks.delete("webhook-id")
+
+# Connectors
+client.connectors.create("name", "s3", {...})
+client.connectors.list()
+client.connectors.get("connector-id")
+client.connectors.test("connector-id")
+client.connectors.delete("connector-id")
+```
+
+---
+
+## Error handling
+
+```python
+from flexorch_sdk import (
+    FlexOrchClient,
+    AuthError,       # 401 — invalid or missing API key
+    QuotaError,      # 402 — credit limit reached or trial expired
+    RateLimitError,  # 429 — too many requests; has .retry_after (seconds)
+    NotFoundError,   # 404
+    ValidationError, # 422 — bad request parameters
+    ServerError,     # 5xx
+    JobFailedError,  # pipeline failed; has .job_id and .failure_reason
+    TimeoutError,    # Job.wait() exceeded timeout; has .job_id
+)
+
+try:
+    job = client.process("doc.pdf").wait(timeout=120)
+except AuthError:
+    print("Invalid API key — check FLEXORCH_API_KEY")
+except QuotaError as e:
+    print(f"Out of credits — reset at {e.reset_at}")
+except JobFailedError as e:
+    print(f"Pipeline failed for job {e.job_id}: {e.failure_reason}")
+except TimeoutError as e:
+    print(f"Job {e.job_id} still running after timeout — poll manually")
+```
+
+The SDK automatically retries `429` and `5xx` responses with exponential backoff (up to 3 attempts by default).
+
+---
+
+## Configuration
+
+```python
+client = FlexOrchClient(
+    api_key="fx_...",
+    base_url="https://api.flexorch.com/v1",  # override for self-hosted
+    timeout=60.0,       # HTTP timeout per request in seconds
+    max_retries=5,      # retry attempts for transient errors
+)
+```
+
+### Context manager
+
+```python
+with FlexOrchClient() as client:
+    job = client.process("report.pdf").wait()
+    job.dataset().export("jsonl", path="report.jsonl")
+# HTTP connection pool released automatically
+```
+
+---
+
+## Examples
+
+See [`examples/`](examples/) for runnable scripts:
+
+| File | Description |
+|---|---|
+| [`basic_process.py`](examples/basic_process.py) | Process a single document and export as JSONL |
+| [`batch_process.py`](examples/batch_process.py) | Process multiple files with error handling |
+| [`s3_import.py`](examples/s3_import.py) | Import from S3, process, export results back to S3 |
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/flexorch/flexorch-sdk
+cd flexorch-sdk
+pip install -e ".[dev]"
+pytest
+```
+
+Tests use [respx](https://lundberg.github.io/respx/) to mock httpx — no network calls, no API key needed.
+
+---
+
+## Links
+
+- [Platform](https://app.flexorch.com)
+- [API reference](https://flexorch.com/developers)
+- [flexorch-audit](https://github.com/flexorch/flexorch-audit) — open-source PII detection library
+
+---
+
+## License
+
+[MIT](LICENSE)

flexorch_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+flexorch_sdk/__init__.py,sha256=oiRvyQxyjA1VPwRIMNS-SPbh9y_uyA0wOFxnRj4u9ig,1457
+flexorch_sdk/_transport.py,sha256=Ajrqd4ow8ukmel9Mof62pfHWZpXqCJmFiTrnBAQXyx4,3936
+flexorch_sdk/client.py,sha256=cZ2Qli5A9reDtcbgMTpt5pehWtZpQEOBteG5jJax5sM,6115
+flexorch_sdk/errors.py,sha256=HYc4mUlAruIAR5neKznUwnHrVFP28LGJFs6l18JOVLs,2244
+flexorch_sdk/models/__init__.py,sha256=7_raZnMhl4kK8-SiAPzyDS4Y5w_zY05twsqwflPiR8Q,219
+flexorch_sdk/models/connector.py,sha256=BE2yJiMPla3snTabx2HuTzdFrdxqSsv2Shhlw7JSu2I,1199
+flexorch_sdk/models/dataset.py,sha256=8NZxLk3dpO1PskL6cRFram5I8B7aGkI148GmJgg7CYs,3572
+flexorch_sdk/models/job.py,sha256=Xy4kycl-RKFNGidzvyKjXZ18ZgSYE5VvrafrZUmEbtw,2939
+flexorch_sdk/models/search.py,sha256=TuX9LvZYSknP9zglhenbr0OOlnXKDpBG4_rNkG_rEUQ,852
+flexorch_sdk/resources/__init__.py,sha256=6ZadAypDV1PXH7eBWX19-Gn0aB51qt3l4jT8zTzZogc,306
+flexorch_sdk/resources/connectors.py,sha256=Hzqswqe5G0s6fYctrXfgyKKoQk7qLmvhNPvtA9dAdt8,2118
+flexorch_sdk/resources/datasets.py,sha256=R7Rivws-I0daVGsudmiCtWrmrvkKZcrbYBU163QWEoo,840
+flexorch_sdk/resources/jobs.py,sha256=GKFQmwX-BhM-FanpXcjMY_NNaotwpRI1uPr4qogAzH8,788
+flexorch_sdk/resources/usage.py,sha256=2tZcRE76G5VUXc33_3K8Ypb7oKRNFvc62aM4mS_2bEY,1343
+flexorch_sdk/resources/webhooks.py,sha256=sjwJUTNn82TR9aforoMj1zg_0pYplA4Bmu-V2r7Ti_0,1823
+flexorch_sdk-0.1.0.dist-info/METADATA,sha256=5pH1dBSVgZkm2RR1wGjecLeDI8WVETgt1NAVMG0LMow,9114
+flexorch_sdk-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+flexorch_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=8c-X4OCfQIme81CSEakvgKLVka5i6gpYaHihSWGcaRI,1076
+flexorch_sdk-0.1.0.dist-info/RECORD,,

flexorch_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

flexorch_sdk-0.1.0.dist-info/licenses/LICENSE

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