flexorch-sdk 0.1.0__tar.gz

flexorch_sdk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install
+        run: pip install -e ".[dev]"
+
+      - name: Test
+        run: python -m pytest tests/ -q --tb=short

flexorch_sdk-0.1.0/.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Type checkers
+.mypy_cache/
+.pyright/
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Secrets
+.env
+.env.*
+!.env.example
+.pypirc

flexorch_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versioning follows [Semantic Versioning](https://semver.org/).
+
+---
+
+## [0.1.0] — 2026-05-24
+
+Initial release.
+
+### Added
+
+**Core**
+- `FlexOrchClient` — main entry point; reads `FLEXORCH_API_KEY` env var automatically
+- `Transport` — httpx-based HTTP layer with automatic retry (3×, exponential backoff) on `429` and `5xx`
+- Context manager support (`with FlexOrchClient() as client: ...`)
+
+**Processing**
+- `client.process(file_path, locale, pipeline_config)` — upload a document and start the pipeline
+- `client.process_many(file_paths, locale)` — sequential batch processing
+- `client.process_from_s3(connector_id, keys, locale)` — import directly from an S3 connector
+
+**Jobs**
+- `Job.wait(timeout, poll_interval)` — blocking poll until `completed` or `failed`
+- `Job.dataset()` — fetch the linked dataset once the job is done
+- `client.jobs.get(job_id)` / `client.jobs.list(page, page_size)`
+
+**Datasets**
+- `Dataset.export(format, path)` — download in `json`, `jsonl`, `csv`, `parquet`, `md`, `xml`, `xlsx`, or `rag`
+- `Dataset.export_to_s3(connector_id, format, prefix)` — push directly to S3
+- `Dataset.index()` / `Dataset.index_status()` — semantic indexing (Pro+)
+- `client.datasets.get(dataset_id)` / `client.datasets.list()`
+
+**Semantic search**
+- `client.search(query, top_k, filters)` — cosine similarity search across indexed datasets (Pro+)
+
+**Connectors**
+- `client.connectors.create(name, type, config)` — register an S3 connector
+- `client.connectors.list()` / `get(id)` / `delete(id)` / `test(id)`
+
+**Usage & Webhooks**
+- `client.usage.current()` — credits used/remaining, plan, reset date
+- `client.webhooks.register(url, events)` / `list()` / `delete(id)`
+
+**Errors**
+- `FlexOrchError`, `AuthError`, `QuotaError`, `RateLimitError`, `NotFoundError`,
+  `ValidationError`, `ServerError`, `JobFailedError`, `TimeoutError`

flexorch_sdk-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Contributing
+
+Thank you for your interest in contributing to flexorch-sdk.
+
+## Setup
+
+```bash
+git clone https://github.com/flexorch/flexorch-sdk
+cd flexorch-sdk
+pip install -e ".[dev]"
+```
+
+## Running tests
+
+```bash
+pytest
+```
+
+Tests use [respx](https://lundberg.github.io/respx/) to mock httpx — no network calls or API key required.
+
+## Code style
+
+- Line length: 100 characters (`ruff` configured in `pyproject.toml`)
+- Type hints required on all public functions
+- No `any` in public interfaces — use explicit types
+
+```bash
+pip install ruff
+ruff check src/ tests/
+```
+
+## Submitting changes
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feat/your-feature`
+3. Add tests for new behaviour
+4. Open a pull request against `main`
+
+## Reporting issues
+
+Open an issue at [github.com/flexorch/flexorch-sdk/issues](https://github.com/flexorch/flexorch-sdk/issues).
+
+For security issues, email [privacy@flexorch.com](mailto:privacy@flexorch.com) instead of opening a public issue.

flexorch_sdk-0.1.0/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.

flexorch_sdk-0.1.0/PKG-INFO

@@ -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)