flexorch-mcp 0.1.0__tar.gz

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

@@ -0,0 +1,32 @@
+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
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v
+
+      - name: Type check
+        run: mypy src/

flexorch_mcp-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+.env
+*.env
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+htmlcov/
+.coverage

flexorch_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to `flexorch-mcp` are documented here.
+
+---
+
+## [0.1.0] — 2026-06-24
+
+### Added
+- `process_document` tool — download from URL and process via FlexOrch pipeline (PDF, DOCX, TXT, XLSX, HTML, XML, EML, JPG, PNG, TIFF); 50 MB limit
+- `get_job_status` tool — poll job status until completed or failed; handles data_process and dataset_build job types
+- `get_extraction_result` tool — retrieve all extracted records directly from execution response; up to 100 records inline, `has_more` hint for larger sets
+- `build_dataset` tool — build a structured dataset from a completed execution
+- `search_documents` tool — full-text and semantic search across indexed datasets; supports auto/structured/semantic/hybrid modes (semantic/hybrid requires Pro+)
+- `export_dataset` tool — export datasets as inline text content; supported formats: JSONL, CSV, JSON, MD, XML, RAG (LangChain/LlamaIndex chunks)
+- `flexorch-mcp --check` CLI command for API key validation and connection verification
+- Structured error messages for all FlexOrch API error codes (QUOTA_EXCEEDED, RATE_LIMIT_EXCEEDED, INVALID_API_KEY, etc.)
+- Claude Desktop and Cursor configuration examples

flexorch_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 flexorch
+
+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_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: flexorch-mcp
+Version: 0.1.0
+Summary: MCP server for FlexOrch — SDK for machines
+Project-URL: Homepage, https://flexorch.com
+Project-URL: Documentation, https://docs.flexorch.com
+Project-URL: Repository, https://github.com/flexorch/flexorch-mcp
+Project-URL: Changelog, https://github.com/flexorch/flexorch-mcp/blob/main/CHANGELOG.md
+Author-email: Flexorch Technology <founder@flexorch.com>
+License: MIT License
+        
+        Copyright (c) 2026 flexorch
+        
+        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.
+License-File: LICENSE
+Keywords: agents,document-processing,flexorch,llm,mcp,pii
+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
+Requires-Dist: mcp<2.0,>=1.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# flexorch-mcp
+
+**MCP server for FlexOrch — SDK for machines.**
+
+Connect Claude and other MCP-compatible agents to the [FlexOrch](https://flexorch.com) document intelligence pipeline. Process documents, extract structured data, detect PII, and export LLM-ready datasets — all through natural language tool calls.
+
+---
+
+## What this is
+
+`flexorch-mcp` is a thin proxy that exposes the FlexOrch API as MCP tools. All processing happens on FlexOrch's managed infrastructure. A FlexOrch account and API key are required.
+
+**For humans writing code:** use [flexorch-sdk](https://github.com/flexorch/flexorch-sdk) (Python) or [flexorch-sdk-js](https://github.com/flexorch/flexorch-sdk-js) (TypeScript).  
+**For agents:** use this package.
+
+---
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `process_document` | Upload and process a document (PDF, DOCX, TXT, XLSX, HTML, XML, EML, JPG, PNG, TIFF) |
+| `get_job_status` | Poll a processing job until completed or failed |
+| `get_extraction_result` | Get structured extracted fields from a completed job |
+| `build_dataset` | Build a structured dataset from a completed execution |
+| `search_documents` | Semantic search across indexed datasets (Pro+) |
+| `export_dataset` | Export a dataset as JSONL, CSV, JSON, XML, MD, or RAG (LangChain/LlamaIndex chunks) |
+
+---
+
+## Installation
+
+```bash
+pip install flexorch-mcp
+```
+
+Requires Python 3.10+.
+
+---
+
+## Configuration
+
+### Claude Desktop
+
+Add to `~/.claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "flexorch": {
+      "command": "flexorch-mcp",
+      "env": {
+        "FLEXORCH_API_KEY": "dfx_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to your Cursor MCP config:
+
+```json
+{
+  "flexorch": {
+    "command": "flexorch-mcp",
+    "env": {
+      "FLEXORCH_API_KEY": "dfx_your_key_here"
+    }
+  }
+}
+```
+
+Get your API key from [app.flexorch.com/settings](https://app.flexorch.com/settings).
+
+---
+
+## Verify connection
+
+```bash
+flexorch-mcp --check
+# → FlexOrch API key: dfx_xxx*** ✓
+# → Connection: OK (api.flexorch.com)
+# → Plan: Starter (1,200 credits/mo)
+# → Tools: 6 registered
+```
+
+---
+
+## Example agent workflow
+
+```
+User: "Process this invoice and export it as JSONL for fine-tuning."
+
+Agent:
+  1. process_document(file_url="https://...")   → job_id: 1234
+  2. get_job_status(1234)                        → completed, execution_id: 567
+  3. get_extraction_result(567)                  → vendor, total, date, PII masked
+  4. build_dataset(execution_id=567)             → job_id: 1235
+  5. get_job_status(1235)                        → completed, dataset_id: 89
+  6. export_dataset(89, format="jsonl")          → inline JSONL content
+```
+
+---
+
+## Plan limits
+
+All FlexOrch plan limits apply to MCP tool calls. Credits are consumed per document processed.
+
+| Plan | Credits/mo | Semantic search |
+|------|-----------|----------------|
+| Trial | 1,200 (30 days) | — |
+| Starter | 1,200 | — |
+| Pro | 6,000 | ✓ |
+| Enterprise | Custom | ✓ |
+
+---
+
+## Security
+
+- API key is read from the `FLEXORCH_API_KEY` environment variable — never passed as a tool argument
+- No data is stored or cached by this server — stateless proxy
+- PII masking is applied by FlexOrch's pipeline before results are returned
+- All communication with `api.flexorch.com` uses HTTPS
+
+---
+
+## Related
+
+- [flexorch-audit](https://github.com/flexorch/flexorch-audit) — Standalone PII detection and document quality scoring (no account required)
+- [flexorch-sdk](https://github.com/flexorch/flexorch-sdk) — Python SDK for developers
+- [flexorch-sdk-js](https://github.com/flexorch/flexorch-sdk-js) — TypeScript SDK for developers
+- [docs.flexorch.com](https://docs.flexorch.com) — Full documentation
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

flexorch_mcp-0.1.0/README.md

@@ -0,0 +1,140 @@
+# flexorch-mcp
+
+**MCP server for FlexOrch — SDK for machines.**
+
+Connect Claude and other MCP-compatible agents to the [FlexOrch](https://flexorch.com) document intelligence pipeline. Process documents, extract structured data, detect PII, and export LLM-ready datasets — all through natural language tool calls.
+
+---
+
+## What this is
+
+`flexorch-mcp` is a thin proxy that exposes the FlexOrch API as MCP tools. All processing happens on FlexOrch's managed infrastructure. A FlexOrch account and API key are required.
+
+**For humans writing code:** use [flexorch-sdk](https://github.com/flexorch/flexorch-sdk) (Python) or [flexorch-sdk-js](https://github.com/flexorch/flexorch-sdk-js) (TypeScript).  
+**For agents:** use this package.
+
+---
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `process_document` | Upload and process a document (PDF, DOCX, TXT, XLSX, HTML, XML, EML, JPG, PNG, TIFF) |
+| `get_job_status` | Poll a processing job until completed or failed |
+| `get_extraction_result` | Get structured extracted fields from a completed job |
+| `build_dataset` | Build a structured dataset from a completed execution |
+| `search_documents` | Semantic search across indexed datasets (Pro+) |
+| `export_dataset` | Export a dataset as JSONL, CSV, JSON, XML, MD, or RAG (LangChain/LlamaIndex chunks) |
+
+---
+
+## Installation
+
+```bash
+pip install flexorch-mcp
+```
+
+Requires Python 3.10+.
+
+---
+
+## Configuration
+
+### Claude Desktop
+
+Add to `~/.claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "flexorch": {
+      "command": "flexorch-mcp",
+      "env": {
+        "FLEXORCH_API_KEY": "dfx_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to your Cursor MCP config:
+
+```json
+{
+  "flexorch": {
+    "command": "flexorch-mcp",
+    "env": {
+      "FLEXORCH_API_KEY": "dfx_your_key_here"
+    }
+  }
+}
+```
+
+Get your API key from [app.flexorch.com/settings](https://app.flexorch.com/settings).
+
+---
+
+## Verify connection
+
+```bash
+flexorch-mcp --check
+# → FlexOrch API key: dfx_xxx*** ✓
+# → Connection: OK (api.flexorch.com)
+# → Plan: Starter (1,200 credits/mo)
+# → Tools: 6 registered
+```
+
+---
+
+## Example agent workflow
+
+```
+User: "Process this invoice and export it as JSONL for fine-tuning."
+
+Agent:
+  1. process_document(file_url="https://...")   → job_id: 1234
+  2. get_job_status(1234)                        → completed, execution_id: 567
+  3. get_extraction_result(567)                  → vendor, total, date, PII masked
+  4. build_dataset(execution_id=567)             → job_id: 1235
+  5. get_job_status(1235)                        → completed, dataset_id: 89
+  6. export_dataset(89, format="jsonl")          → inline JSONL content
+```
+
+---
+
+## Plan limits
+
+All FlexOrch plan limits apply to MCP tool calls. Credits are consumed per document processed.
+
+| Plan | Credits/mo | Semantic search |
+|------|-----------|----------------|
+| Trial | 1,200 (30 days) | — |
+| Starter | 1,200 | — |
+| Pro | 6,000 | ✓ |
+| Enterprise | Custom | ✓ |
+
+---
+
+## Security
+
+- API key is read from the `FLEXORCH_API_KEY` environment variable — never passed as a tool argument
+- No data is stored or cached by this server — stateless proxy
+- PII masking is applied by FlexOrch's pipeline before results are returned
+- All communication with `api.flexorch.com` uses HTTPS
+
+---
+
+## Related
+
+- [flexorch-audit](https://github.com/flexorch/flexorch-audit) — Standalone PII detection and document quality scoring (no account required)
+- [flexorch-sdk](https://github.com/flexorch/flexorch-sdk) — Python SDK for developers
+- [flexorch-sdk-js](https://github.com/flexorch/flexorch-sdk-js) — TypeScript SDK for developers
+- [docs.flexorch.com](https://docs.flexorch.com) — Full documentation
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

flexorch_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "flexorch-mcp"
+version = "0.1.0"
+description = "MCP server for FlexOrch — SDK for machines"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "Flexorch Technology", email = "founder@flexorch.com" }]
+keywords = ["mcp", "flexorch", "document-processing", "pii", "llm", "agents"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "mcp>=1.0,<2.0",
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "respx>=0.21",
+    "mypy>=1.10",
+]
+
+[project.scripts]
+flexorch-mcp = "flexorch_mcp.server:main"
+
+[project.urls]
+Homepage = "https://flexorch.com"
+Documentation = "https://docs.flexorch.com"
+Repository = "https://github.com/flexorch/flexorch-mcp"
+Changelog = "https://github.com/flexorch/flexorch-mcp/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/flexorch_mcp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.mypy]
+python_version = "3.10"
+strict = true

flexorch_mcp-0.1.0/src/flexorch_mcp/__init__.py

@@ -0,0 +1,2 @@
+__version__ = "0.1.0"
+__all__ = ["__version__"]

flexorch_mcp-0.1.0/src/flexorch_mcp/client.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+from urllib.parse import urlparse
+from typing import Any
+
+import httpx
+
+from .errors import FlexOrchAPIError, DownloadError, FileTooLargeError, map_api_error  # noqa: F401
+
+_BASE_URL = "https://api.flexorch.com/v1"
+_MAX_DOWNLOAD_BYTES = 50 * 1024 * 1024  # 50 MB
+_CHUNK_SIZE = 65536
+
+
+def _mask_key(key: str) -> str:
+    """Return dfx_xxx*** masked form for logs — never expose the full key."""
+    if len(key) <= 7:
+        return "***"
+    return key[:7] + "***"
+
+
+class FlexOrchMCPClient:
+    """Async HTTP client for FlexOrch API calls within the MCP server.
+
+    Keeps two httpx.AsyncClient instances:
+    - _api: for FlexOrch API requests (carries X-API-KEY header)
+    - _downloader: for external file_url downloads (no auth header)
+    """
+
+    def __init__(self, api_key: str, base_url: str = _BASE_URL) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._api = httpx.AsyncClient(
+            headers={
+                "X-API-KEY": api_key,
+                "User-Agent": "flexorch-mcp/0.1.0",
+            },
+            timeout=httpx.Timeout(30.0, connect=5.0),
+            max_redirects=3,
+            verify=True,
+        )
+        self._downloader = httpx.AsyncClient(
+            timeout=httpx.Timeout(30.0, connect=5.0),
+            max_redirects=3,
+            verify=True,
+            follow_redirects=True,
+        )
+
+    # ------------------------------------------------------------------
+    # Core request helpers
+    # ------------------------------------------------------------------
+
+    def _url(self, path: str) -> str:
+        return f"{self._base_url}/{path.lstrip('/')}"
+
+    def _raise_for_response(self, response: httpx.Response) -> None:
+        if not response.is_error:
+            return
+        retry_after: int | None = None
+        error_code = ""
+        try:
+            body = response.json()
+            error_code = body.get("error", {}).get("code", "")
+        except Exception:
+            pass
+        if response.status_code == 429:
+            retry_after = int(response.headers.get("Retry-After", 60))
+        raise FlexOrchAPIError(
+            map_api_error(error_code, retry_after=retry_after),
+            status_code=response.status_code,
+            error_code=error_code,
+            retry_after=retry_after,
+        )
+
+    def _parse(self, response: httpx.Response) -> Any:
+        self._raise_for_response(response)
+        if response.status_code == 204 or not response.content:
+            return None
+        return response.json()
+
+    async def get(self, path: str, **kwargs: Any) -> Any:
+        response = await self._api.get(self._url(path), **kwargs)
+        return self._parse(response)
+
+    async def post(self, path: str, **kwargs: Any) -> Any:
+        response = await self._api.post(self._url(path), **kwargs)
+        return self._parse(response)
+
+    async def get_raw(self, path: str, **kwargs: Any) -> tuple[bytes, str, str]:
+        """Fetch binary/text response without JSON parsing.
+
+        Returns (content_bytes, content_type, filename).
+        Raises FlexOrchAPIError on HTTP errors.
+        """
+        response = await self._api.get(self._url(path), **kwargs)
+        self._raise_for_response(response)
+        content_type = response.headers.get("content-type", "application/octet-stream")
+        cd = response.headers.get("content-disposition", "")
+        filename = ""
+        if 'filename="' in cd:
+            filename = cd.split('filename="')[1].split('"')[0]
+        elif "filename=" in cd:
+            filename = cd.split("filename=")[1].split(";")[0].strip()
+        return response.content, content_type, filename
+
+    # ------------------------------------------------------------------
+    # File download
+    # ------------------------------------------------------------------
+
+    async def download_file(self, url: str) -> tuple[bytes, str]:
+        """Download a file from an external URL and return (bytes, filename).
+
+        Validates scheme (http/https only) and enforces 50 MB size limit.
+        """
+        parsed = urlparse(url)
+        if parsed.scheme not in ("http", "https"):
+            raise ValueError(
+                f"Invalid URL scheme '{parsed.scheme}'. "
+                "Only http and https URLs are supported."
+            )
+
+        chunks: list[bytes] = []
+        total = 0
+
+        async with self._downloader.stream("GET", url) as response:
+            if response.is_error:
+                raise DownloadError(
+                    "Could not download file from provided URL. "
+                    "Check that the URL is publicly accessible."
+                )
+            content_length = int(response.headers.get("content-length", 0))
+            if content_length > _MAX_DOWNLOAD_BYTES:
+                raise FileTooLargeError("File exceeds size limit. Max 50 MB.")
+
+            async for chunk in response.aiter_bytes(_CHUNK_SIZE):
+                total += len(chunk)
+                if total > _MAX_DOWNLOAD_BYTES:
+                    raise FileTooLargeError("File exceeds size limit. Max 50 MB.")
+                chunks.append(chunk)
+
+        content = b"".join(chunks)
+        filename = (parsed.path.rstrip("/").split("/")[-1]) or "document"
+        return content, filename
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def aclose(self) -> None:
+        await self._api.aclose()
+        await self._downloader.aclose()
+
+    async def __aenter__(self) -> FlexOrchMCPClient:
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.aclose()
+
+    def masked_key(self) -> str:
+        return _mask_key(self._api_key)

flexorch_mcp-0.1.0/src/flexorch_mcp/errors.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+FLEXORCH_ERRORS: dict[str, str] = {
+    "QUOTA_EXCEEDED": (
+        "Credit quota exceeded. Upgrade your FlexOrch plan at app.flexorch.com/settings"
+    ),
+    "TRIAL_EXPIRED": "Trial period ended. Activate a plan to continue.",
+    "RATE_LIMIT_EXCEEDED": "Rate limit reached. Retry in {retry_after} seconds.",
+    "UNSUPPORTED_FILE": (
+        "Unsupported file type. Supported: PDF, DOCX, TXT, XLSX, HTML, XML, EML, JPG, PNG, TIFF"
+    ),
+    "PLAN_UPGRADE_REQUIRED": (
+        "This feature requires a Pro plan or above. Upgrade at app.flexorch.com/settings"
+    ),
+    "INVALID_API_KEY": (
+        "Invalid API key. Check your FLEXORCH_API_KEY environment variable."
+    ),
+    "FILE_TOO_LARGE": "File exceeds size limit. Max 50 MB.",
+    "NOT_FOUND": "Resource not found. Check the provided ID.",
+}
+
+_DEFAULT_ERROR = "An error occurred. Visit app.flexorch.com for support."
+
+
+def map_api_error(code: str, retry_after: int | None = None) -> str:
+    template = FLEXORCH_ERRORS.get(code, _DEFAULT_ERROR)
+    if code == "RATE_LIMIT_EXCEEDED" and retry_after is not None:
+        return template.format(retry_after=retry_after)
+    return template
+
+
+class FlexOrchAPIError(Exception):
+    def __init__(
+        self,
+        message: str,
+        status_code: int = 0,
+        error_code: str = "",
+        retry_after: int | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.error_code = error_code
+        self.retry_after = retry_after
+
+
+class DownloadError(Exception):
+    pass
+
+
+class FileTooLargeError(Exception):
+    pass