forgefile 0.1.0__tar.gz

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

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --python ${{ matrix.python-version }}
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+      - name: Type check
+        run: uv run mypy
+
+      - name: Test
+        run: uv run pytest

forgefile-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,51 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Verify the tag matches the packaged version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          version="$(grep -m1 '^version = ' pyproject.toml | cut -d'"' -f2)"
+          if [ "$tag" != "$version" ]; then
+            echo "Tag $tag does not match pyproject version $version" >&2
+            exit 1
+          fi
+
+      - name: Build
+        run: uv build
+
+      - name: Check metadata
+        run: uvx twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write        # required for trusted publishing; no token is stored
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

forgefile-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+# Environments
+.venv/
+.env
+
+# Tooling caches
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# Coverage
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# Interrupted downloads written by the client
+*.part
+
+# Editors and OS
+.DS_Store
+.idea/
+.vscode/

forgefile-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions
+follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Initial client for the [ForgeFile](https://forgefile.com) REST API, with the `system`,
+  `public`, `account`, `files` and `jobs` resource groups.
+- `HTTPTransport` protocol, so the HTTP layer can be replaced without touching the resources.
+- Typed exception hierarchy carrying the API's `error_code`, plus `retry_after` on
+  `RateLimitError`.
+- `files.wait()` to block until a job finishes, and `files.track()` to report progress while
+  it runs.
+- Runnable examples under `examples/`.
+
+### Fixed
+
+- `subscription_plans()` moved from `public` to `account`: the public route does not
+  exist on the API, the authenticated one does.

forgefile-0.1.0/LICENSE

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

forgefile-0.1.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.5
+Name: forgefile
+Version: 0.1.0
+Summary: Python client for the ForgeFile REST API — translate, transcribe, convert, OCR, summarize and rewrite files.
+Project-URL: Homepage, https://forgefile.com
+Project-URL: Documentation, https://forgefile.com/docs
+Project-URL: Source, https://github.com/ForgeFile/forgefile-python
+Project-URL: Issues, https://github.com/ForgeFile/forgefile-python/issues
+Project-URL: Changelog, https://github.com/ForgeFile/forgefile-python/blob/main/CHANGELOG.md
+Author-email: ForgeFile <support@forgefile.com>
+License: MIT
+License-File: LICENSE
+Keywords: api-client,file-conversion,forgefile,ocr,transcription,translation
+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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Description-Content-Type: text/markdown
+
+# forgefile-python
+
+Python client for the [ForgeFile](https://forgefile.com) REST API — translate, transcribe,
+convert, OCR, summarize and rewrite files.
+
+Requires Python 3.11+.
+
+## Install
+
+```bash
+pip install forgefile
+```
+
+## Quick start
+
+```python
+from forgefile import ForgeFile
+
+with ForgeFile("your-token") as api:
+    job = api.jobs.translate("contract.pdf", target_language="es")
+    api.files.wait(job.uuid)
+    api.files.download(job.uuid, "contract.es.pdf")
+```
+
+The token is read from `FORGEFILE_API_KEY` when the first argument is omitted.
+Public endpoints need no token at all:
+
+```python
+with ForgeFile() as api:
+    for language in api.public.languages():
+        print(language.code, language.name)
+```
+
+## Processing a file
+
+Every job endpoint uploads the file and starts the work in one call, returning a `FileJob`
+whose `uuid` identifies it from then on.
+
+```python
+api.jobs.translate("contract.pdf", target_language="de")  # source_language is optional
+api.jobs.transcribe("interview.mp3")
+api.jobs.convert("report.docx", to_format="pdf")
+api.jobs.ocr("receipt.jpg")
+api.jobs.summarize("paper.pdf")
+api.jobs.rewrite("draft.docx")
+api.jobs.compress("scan.pdf")
+```
+
+Uploads are capped at 10 MB by the API.
+
+### Waiting for the result
+
+`wait()` blocks until the job reaches a terminal state and raises `JobTimeoutError` if it
+does not. The job keeps running server-side, so calling again resumes waiting.
+
+```python
+finished = api.files.wait(job.uuid, timeout=900, interval=5)
+
+if finished.succeeded:
+    transcript = api.files.result(job.uuid)  # structured output
+    api.files.download(job.uuid, "interview.srt")
+```
+
+`track()` yields every observed state instead, for progress reporting:
+
+```python
+for state in api.files.track(job.uuid, interval=5):
+    print(state.status)
+```
+
+Branch on `job.is_finished` and `job.succeeded` rather than comparing status strings — a
+status this client does not recognise is never treated as finished, so a wait loop cannot
+end early on a state it has not seen.
+
+## Errors
+
+Every failure raises a subclass of `ForgeFileError` carrying the API's stable `error_code`,
+so you can branch on the code rather than on message text.
+
+```python
+from forgefile import RateLimitError, ValidationError
+
+try:
+    api.jobs.translate("contract.pdf", target_language="es")
+except ValidationError as exc:
+    print(exc.context)  # field errors
+except RateLimitError as exc:
+    print(f"retry in {exc.retry_after}s")
+```
+
+| Exception | Raised when |
+|---|---|
+| `AuthenticationError` | 401 — no token, or rejected |
+| `ForbiddenError` | 403 — token lacks the right |
+| `NotFoundError` | 404 |
+| `ValidationError` | 422 — field errors in `context` |
+| `RateLimitError` | 429 — `retry_after` in seconds |
+| `ServerError` | 5xx — safe to retry with backoff |
+| `TransportError` | no response at all: DNS, TLS, timeout |
+| `JobTimeoutError` | `wait()` gave up; the job still runs |
+
+The API allows 60 requests per minute.
+
+## Configuration
+
+| Argument | Environment variable | Default |
+|---|---|---|
+| `api_key` | `FORGEFILE_API_KEY` | none — public endpoints only |
+| `base_url` | `FORGEFILE_BASE_URL` | `https://forgefile.com/api/v1` |
+| `timeout` | — | 60 seconds |
+
+## Examples
+
+Runnable scripts in [`examples/`](examples):
+
+| File | Shows |
+|---|---|
+| `01_public_data.py` | reference data without a token |
+| `02_translate_document.py` | submit, wait, download |
+| `03_transcribe_with_progress.py` | streaming progress with `track()` |
+| `04_convert_a_folder.py` | batching — submit all, then collect |
+| `05_handling_errors.py` | every failure mode and its remedy |
+| `06_custom_transport.py` | replacing the HTTP layer |
+
+## Architecture
+
+| Module | Responsibility |
+|---|---|
+| `config` | where to connect and with what headers |
+| `envelope` | the API's `{success, message, data}` wrapper — the only place that knows it |
+| `errors` | turning a failed response into the right exception |
+| `transport` | HTTP, as a `Protocol` plus an httpx implementation |
+| `resources/` | one class per endpoint group: `system`, `public`, `account`, `files`, `jobs` |
+
+Resources depend on the `HTTPTransport` protocol, never on httpx, so the HTTP layer can be
+replaced with a recorded fixture, a proxy or a different library — see
+`examples/06_custom_transport.py`.
+
+Response models accept unknown fields, which stay reachable through `model_extra`. Only
+fields observed against the live API are typed explicitly; authenticated endpoints could not
+be inspected without a token while this client was written, so their payloads are permissive
+rather than guessed.
+
+The package ships a `py.typed` marker, so your type checker sees these signatures.
+
+## Development
+
+```bash
+git clone https://github.com/ForgeFile/forgefile-python
+cd forgefile-python
+uv sync
+
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run pytest
+```
+
+Tests make no network calls: the resource layer runs against a fake transport, the httpx
+layer against `respx`. CI runs these commands on Python 3.11, 3.12 and 3.13.
+
+## Links
+
+- [ForgeFile](https://forgefile.com) — the product
+- [API reference](https://forgefile.com/docs)
+- [Source and issues](https://github.com/ForgeFile/forgefile-python)
+- [ForgeFile on GitHub](https://github.com/ForgeFile)
+- Support — <support@forgefile.com>
+
+MIT licensed. See [LICENSE](LICENSE).

forgefile-0.1.0/README.md

@@ -0,0 +1,170 @@
+# forgefile-python
+
+Python client for the [ForgeFile](https://forgefile.com) REST API — translate, transcribe,
+convert, OCR, summarize and rewrite files.
+
+Requires Python 3.11+.
+
+## Install
+
+```bash
+pip install forgefile
+```
+
+## Quick start
+
+```python
+from forgefile import ForgeFile
+
+with ForgeFile("your-token") as api:
+    job = api.jobs.translate("contract.pdf", target_language="es")
+    api.files.wait(job.uuid)
+    api.files.download(job.uuid, "contract.es.pdf")
+```
+
+The token is read from `FORGEFILE_API_KEY` when the first argument is omitted.
+Public endpoints need no token at all:
+
+```python
+with ForgeFile() as api:
+    for language in api.public.languages():
+        print(language.code, language.name)
+```
+
+## Processing a file
+
+Every job endpoint uploads the file and starts the work in one call, returning a `FileJob`
+whose `uuid` identifies it from then on.
+
+```python
+api.jobs.translate("contract.pdf", target_language="de")  # source_language is optional
+api.jobs.transcribe("interview.mp3")
+api.jobs.convert("report.docx", to_format="pdf")
+api.jobs.ocr("receipt.jpg")
+api.jobs.summarize("paper.pdf")
+api.jobs.rewrite("draft.docx")
+api.jobs.compress("scan.pdf")
+```
+
+Uploads are capped at 10 MB by the API.
+
+### Waiting for the result
+
+`wait()` blocks until the job reaches a terminal state and raises `JobTimeoutError` if it
+does not. The job keeps running server-side, so calling again resumes waiting.
+
+```python
+finished = api.files.wait(job.uuid, timeout=900, interval=5)
+
+if finished.succeeded:
+    transcript = api.files.result(job.uuid)  # structured output
+    api.files.download(job.uuid, "interview.srt")
+```
+
+`track()` yields every observed state instead, for progress reporting:
+
+```python
+for state in api.files.track(job.uuid, interval=5):
+    print(state.status)
+```
+
+Branch on `job.is_finished` and `job.succeeded` rather than comparing status strings — a
+status this client does not recognise is never treated as finished, so a wait loop cannot
+end early on a state it has not seen.
+
+## Errors
+
+Every failure raises a subclass of `ForgeFileError` carrying the API's stable `error_code`,
+so you can branch on the code rather than on message text.
+
+```python
+from forgefile import RateLimitError, ValidationError
+
+try:
+    api.jobs.translate("contract.pdf", target_language="es")
+except ValidationError as exc:
+    print(exc.context)  # field errors
+except RateLimitError as exc:
+    print(f"retry in {exc.retry_after}s")
+```
+
+| Exception | Raised when |
+|---|---|
+| `AuthenticationError` | 401 — no token, or rejected |
+| `ForbiddenError` | 403 — token lacks the right |
+| `NotFoundError` | 404 |
+| `ValidationError` | 422 — field errors in `context` |
+| `RateLimitError` | 429 — `retry_after` in seconds |
+| `ServerError` | 5xx — safe to retry with backoff |
+| `TransportError` | no response at all: DNS, TLS, timeout |
+| `JobTimeoutError` | `wait()` gave up; the job still runs |
+
+The API allows 60 requests per minute.
+
+## Configuration
+
+| Argument | Environment variable | Default |
+|---|---|---|
+| `api_key` | `FORGEFILE_API_KEY` | none — public endpoints only |
+| `base_url` | `FORGEFILE_BASE_URL` | `https://forgefile.com/api/v1` |
+| `timeout` | — | 60 seconds |
+
+## Examples
+
+Runnable scripts in [`examples/`](examples):
+
+| File | Shows |
+|---|---|
+| `01_public_data.py` | reference data without a token |
+| `02_translate_document.py` | submit, wait, download |
+| `03_transcribe_with_progress.py` | streaming progress with `track()` |
+| `04_convert_a_folder.py` | batching — submit all, then collect |
+| `05_handling_errors.py` | every failure mode and its remedy |
+| `06_custom_transport.py` | replacing the HTTP layer |
+
+## Architecture
+
+| Module | Responsibility |
+|---|---|
+| `config` | where to connect and with what headers |
+| `envelope` | the API's `{success, message, data}` wrapper — the only place that knows it |
+| `errors` | turning a failed response into the right exception |
+| `transport` | HTTP, as a `Protocol` plus an httpx implementation |
+| `resources/` | one class per endpoint group: `system`, `public`, `account`, `files`, `jobs` |
+
+Resources depend on the `HTTPTransport` protocol, never on httpx, so the HTTP layer can be
+replaced with a recorded fixture, a proxy or a different library — see
+`examples/06_custom_transport.py`.
+
+Response models accept unknown fields, which stay reachable through `model_extra`. Only
+fields observed against the live API are typed explicitly; authenticated endpoints could not
+be inspected without a token while this client was written, so their payloads are permissive
+rather than guessed.
+
+The package ships a `py.typed` marker, so your type checker sees these signatures.
+
+## Development
+
+```bash
+git clone https://github.com/ForgeFile/forgefile-python
+cd forgefile-python
+uv sync
+
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run pytest
+```
+
+Tests make no network calls: the resource layer runs against a fake transport, the httpx
+layer against `respx`. CI runs these commands on Python 3.11, 3.12 and 3.13.
+
+## Links
+
+- [ForgeFile](https://forgefile.com) — the product
+- [API reference](https://forgefile.com/docs)
+- [Source and issues](https://github.com/ForgeFile/forgefile-python)
+- [ForgeFile on GitHub](https://github.com/ForgeFile)
+- Support — <support@forgefile.com>
+
+MIT licensed. See [LICENSE](LICENSE).

forgefile-0.1.0/examples/01_public_data.py

@@ -0,0 +1,24 @@
+"""Reference data — the endpoints that need no token.
+
+python examples/01_public_data.py
+"""
+
+from __future__ import annotations
+
+from forgefile import ForgeFile
+
+
+def main() -> None:
+    with ForgeFile() as api:
+        print("service:", api.system.health())
+
+        languages = api.public.languages()
+        print(f"\n{len(languages)} languages available, first ten:")
+        for language in languages[:10]:
+            print(f"  {language.code:<6} {language.name} ({language.native or '—'})")
+
+        print("\ncurrencies:", ", ".join(c.code or "?" for c in api.public.currencies()))
+
+
+if __name__ == "__main__":
+    main()

forgefile-0.1.0/examples/02_translate_document.py

@@ -0,0 +1,36 @@
+"""Translate a document and save the result next to the original.
+
+export FORGEFILE_API_KEY=...
+python examples/02_translate_document.py contract.pdf es
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from forgefile import ForgeFile
+
+
+def translate(source: Path, target_language: str) -> Path | None:
+    with ForgeFile() as api:
+        job = api.jobs.translate(source, target_language=target_language)
+        print(f"submitted {job.uuid}")
+
+        finished = api.files.wait(job.uuid)
+        if not finished.succeeded:
+            print(f"job ended as {finished.status}", file=sys.stderr)
+            return None
+
+        destination = source.with_suffix(f".{target_language}{source.suffix}")
+        return api.files.download(job.uuid, destination)
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 3:
+        print(__doc__, file=sys.stderr)
+        raise SystemExit(2)
+
+    result = translate(Path(sys.argv[1]), sys.argv[2])
+    print(f"saved {result}" if result else "translation failed")
+    raise SystemExit(0 if result else 1)

forgefile-0.1.0/examples/03_transcribe_with_progress.py

@@ -0,0 +1,41 @@
+"""Transcribe media and report progress as it happens.
+
+``track()`` yields every observed state instead of blocking silently, so a long
+job can drive a progress line.
+
+    export FORGEFILE_API_KEY=...
+    python examples/03_transcribe_with_progress.py interview.mp3
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from forgefile import ForgeFile
+
+
+def main(source: Path) -> int:
+    with ForgeFile() as api:
+        job = api.jobs.transcribe(source)
+
+        for state in api.files.track(job.uuid, interval=5):
+            print(f"\r{state.status or 'unknown':<16}", end="", flush=True)
+        print()
+
+        final = api.files.get(job.uuid)
+        if not final.succeeded:
+            print(f"job ended as {final.status}", file=sys.stderr)
+            return 1
+
+        transcript = api.files.result(job.uuid)
+        print(transcript)
+        api.files.download(job.uuid, source.with_suffix(".srt"))
+    return 0
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        print(__doc__, file=sys.stderr)
+        raise SystemExit(2)
+    raise SystemExit(main(Path(sys.argv[1])))

forgefile-0.1.0/examples/04_convert_a_folder.py

@@ -0,0 +1,59 @@
+"""Convert every file in a folder, submitting all jobs before waiting.
+
+Jobs run server-side, so start them all first and collect the results after —
+that turns N sequential waits into one.
+
+    export FORGEFILE_API_KEY=...
+    python examples/04_convert_a_folder.py ./invoices pdf
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from forgefile import FileJob, ForgeFile, ForgeFileError, JobTimeoutError
+
+
+def main(folder: Path, to_format: str) -> int:
+    sources = sorted(p for p in folder.iterdir() if p.is_file())
+    if not sources:
+        print(f"nothing to convert in {folder}", file=sys.stderr)
+        return 1
+
+    with ForgeFile() as api:
+        submitted: dict[str, Path] = {}
+        for source in sources:
+            try:
+                job: FileJob = api.jobs.convert(source, to_format=to_format)
+            except ForgeFileError as exc:
+                print(f"skipped {source.name}: {exc}", file=sys.stderr)
+                continue
+            submitted[job.uuid] = source
+            print(f"submitted {source.name} -> {job.uuid}")
+
+        failures = 0
+        for uuid, source in submitted.items():
+            destination = source.with_suffix(f".{to_format}")
+            try:
+                finished = api.files.wait(uuid, timeout=900)
+            except JobTimeoutError as exc:
+                print(f"timeout {source.name}: {exc}", file=sys.stderr)
+                failures += 1
+                continue
+
+            if finished.succeeded:
+                api.files.download(uuid, destination)
+                print(f"saved {destination.name}")
+            else:
+                print(f"failed {source.name}: {finished.status}", file=sys.stderr)
+                failures += 1
+
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 3:
+        print(__doc__, file=sys.stderr)
+        raise SystemExit(2)
+    raise SystemExit(main(Path(sys.argv[1]), sys.argv[2]))