flaxflow 1.0.0__tar.gz

flaxflow-1.0.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/
+.pytest_cache/

flaxflow-1.0.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: flaxflow
+Version: 1.0.0
+Summary: Official Python SDK for the FlaxFlow Engine API — AI document processing.
+Project-URL: Homepage, https://www.flaxia.com.br
+Project-URL: Documentation, https://www.flaxia.com.br/engine-api
+Project-URL: Source, https://github.com/flaxflow/FlaxFlow.PortalAI.Backend
+Author: FlaxFlow
+License: MIT
+Keywords: ai,document,extraction,flaxflow,ocr,sdk
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2
+Provides-Extra: dev
+Requires-Dist: datamodel-code-generator>=0.25; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# flaxflow — Python SDK
+
+Official Python SDK for the **FlaxFlow Engine API** — AI-powered document processing
+(extraction, classification, webhooks).
+
+```bash
+pip install flaxflow
+```
+
+## Authentication
+
+The SDK authenticates with an **API key** (`sk_...`). Create one in the FlaxFlow app under
+**Settings → API keys**, then pass it to the client or set `FLAXFLOW_API_KEY`.
+
+```python
+from flaxflow import FlaxFlow
+
+fx = FlaxFlow(api_key="sk_...")  # or FlaxFlow() reading FLAXFLOW_API_KEY
+```
+
+## Quickstart
+
+```python
+from flaxflow import FlaxFlow
+
+fx = FlaxFlow(api_key="sk_...")
+
+# 1. Create a document class from a sample — the AI infers the fields to extract
+doc = fx.documents.create_from_sample("invoice-sample.pdf")
+
+# 2. Process a real document against that class
+job = fx.processing.process_document("invoice-001.pdf", document_id=str(doc.document_id))
+print(job.result)        # -> {"invoice_number": "123", "total_amount": "99.90", ...}
+
+# 3. Or extract with a free-form prompt, no document class needed
+job = fx.processing.process_with_prompt(
+    "invoice-001.pdf",
+    prompt="Extract invoice number, issue date and total amount",
+)
+print(job.result)
+```
+
+The file argument accepts a **path**, raw **bytes**, or any file-like object. For paths the
+`documentType` is inferred from the extension; otherwise pass `document_type=`.
+
+## Resources
+
+| Resource | Highlights |
+|----------|------------|
+| `fx.documents` | `create_from_sample`, `create_manual`, `update`, `list`, `delete` |
+| `fx.processing` | `process_document`, `process_with_prompt`, `process_many` |
+| `fx.jobs` | `list`, `get`, `get_batch`, `analytics`, `download_document` |
+| `fx.classifiers` | `create`, `list`, `get`, `update`, `set_models`, `delete` |
+| `fx.webhooks` | `create`, `list`, `update`, `delete`, `delivery_logs` |
+| `fx.api_keys` | `create`, `list`, `delete` |
+
+### Batch processing
+
+```python
+batch = fx.processing.process_many(
+    ["a.pdf", "b.pdf", "c.pdf"],
+    classifier_id="<classifier_id>",   # let the classifier pick the right class
+)
+print(batch.batch_id, len(batch.jobs))
+```
+
+### Webhooks
+
+```python
+hook = fx.webhooks.create("https://example.com/hooks/flaxflow",
+                          event_types=["job.completed", "job.failed"])
+print(hook.secret)   # HMAC-SHA256 signing secret — shown only once
+```
+
+## Error handling
+
+Every failure raises a subclass of `FlaxFlowError`:
+
+```python
+from flaxflow import FlaxFlow, AuthenticationError, NotFoundError, RateLimitError
+
+try:
+    fx.jobs.get("does-not-exist")
+except NotFoundError:
+    ...
+except RateLimitError as e:
+    print("slow down", e.status_code)
+except AuthenticationError:
+    print("check your API key")
+```
+
+## Configuration
+
+| Option | Default | Env var |
+|--------|---------|---------|
+| `api_key` | – (required) | `FLAXFLOW_API_KEY` |
+| `base_url` | `https://api.flaxia.com.br` | `FLAXFLOW_BASE_URL` |
+| `timeout` | `60` seconds | – |
+
+`FlaxFlow` is a context manager — use `with FlaxFlow(...) as fx:` to close the HTTP client
+automatically.
+
+## Types
+
+Response objects are [pydantic](https://docs.pydantic.dev) models generated from the API's
+OpenAPI spec, so you get full editor autocompletion and validation. Field names are
+`snake_case` in Python (the wire format stays `camelCase`).
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+bash scripts/generate.sh   # regenerate models from ../openapi.json
+pytest
+```
+
+## Publishing (maintainers)
+
+Configure o token PyPI no GitHub (uma vez):
+
+```bash
+bash scripts/configure-pypi.sh   # cole o token pypi-...
+```
+
+Push em `main` com mudanças nesta pasta publica automaticamente a versão em
+`pyproject.toml`. Antes de cada release, aumente `version` (ex.: `1.0.1`).
+
+The generated models live in `src/flaxflow/_generated/` and are produced from
+`sdks/openapi.json` (exported from the backend via `cargo run --bin export_openapi`).
+
+> Async support (`AsyncFlaxFlow`) is planned. The sync client is fully featured today.

flaxflow-1.0.0/README.md

@@ -0,0 +1,132 @@
+# flaxflow — Python SDK
+
+Official Python SDK for the **FlaxFlow Engine API** — AI-powered document processing
+(extraction, classification, webhooks).
+
+```bash
+pip install flaxflow
+```
+
+## Authentication
+
+The SDK authenticates with an **API key** (`sk_...`). Create one in the FlaxFlow app under
+**Settings → API keys**, then pass it to the client or set `FLAXFLOW_API_KEY`.
+
+```python
+from flaxflow import FlaxFlow
+
+fx = FlaxFlow(api_key="sk_...")  # or FlaxFlow() reading FLAXFLOW_API_KEY
+```
+
+## Quickstart
+
+```python
+from flaxflow import FlaxFlow
+
+fx = FlaxFlow(api_key="sk_...")
+
+# 1. Create a document class from a sample — the AI infers the fields to extract
+doc = fx.documents.create_from_sample("invoice-sample.pdf")
+
+# 2. Process a real document against that class
+job = fx.processing.process_document("invoice-001.pdf", document_id=str(doc.document_id))
+print(job.result)        # -> {"invoice_number": "123", "total_amount": "99.90", ...}
+
+# 3. Or extract with a free-form prompt, no document class needed
+job = fx.processing.process_with_prompt(
+    "invoice-001.pdf",
+    prompt="Extract invoice number, issue date and total amount",
+)
+print(job.result)
+```
+
+The file argument accepts a **path**, raw **bytes**, or any file-like object. For paths the
+`documentType` is inferred from the extension; otherwise pass `document_type=`.
+
+## Resources
+
+| Resource | Highlights |
+|----------|------------|
+| `fx.documents` | `create_from_sample`, `create_manual`, `update`, `list`, `delete` |
+| `fx.processing` | `process_document`, `process_with_prompt`, `process_many` |
+| `fx.jobs` | `list`, `get`, `get_batch`, `analytics`, `download_document` |
+| `fx.classifiers` | `create`, `list`, `get`, `update`, `set_models`, `delete` |
+| `fx.webhooks` | `create`, `list`, `update`, `delete`, `delivery_logs` |
+| `fx.api_keys` | `create`, `list`, `delete` |
+
+### Batch processing
+
+```python
+batch = fx.processing.process_many(
+    ["a.pdf", "b.pdf", "c.pdf"],
+    classifier_id="<classifier_id>",   # let the classifier pick the right class
+)
+print(batch.batch_id, len(batch.jobs))
+```
+
+### Webhooks
+
+```python
+hook = fx.webhooks.create("https://example.com/hooks/flaxflow",
+                          event_types=["job.completed", "job.failed"])
+print(hook.secret)   # HMAC-SHA256 signing secret — shown only once
+```
+
+## Error handling
+
+Every failure raises a subclass of `FlaxFlowError`:
+
+```python
+from flaxflow import FlaxFlow, AuthenticationError, NotFoundError, RateLimitError
+
+try:
+    fx.jobs.get("does-not-exist")
+except NotFoundError:
+    ...
+except RateLimitError as e:
+    print("slow down", e.status_code)
+except AuthenticationError:
+    print("check your API key")
+```
+
+## Configuration
+
+| Option | Default | Env var |
+|--------|---------|---------|
+| `api_key` | – (required) | `FLAXFLOW_API_KEY` |
+| `base_url` | `https://api.flaxia.com.br` | `FLAXFLOW_BASE_URL` |
+| `timeout` | `60` seconds | – |
+
+`FlaxFlow` is a context manager — use `with FlaxFlow(...) as fx:` to close the HTTP client
+automatically.
+
+## Types
+
+Response objects are [pydantic](https://docs.pydantic.dev) models generated from the API's
+OpenAPI spec, so you get full editor autocompletion and validation. Field names are
+`snake_case` in Python (the wire format stays `camelCase`).
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+bash scripts/generate.sh   # regenerate models from ../openapi.json
+pytest
+```
+
+## Publishing (maintainers)
+
+Configure o token PyPI no GitHub (uma vez):
+
+```bash
+bash scripts/configure-pypi.sh   # cole o token pypi-...
+```
+
+Push em `main` com mudanças nesta pasta publica automaticamente a versão em
+`pyproject.toml`. Antes de cada release, aumente `version` (ex.: `1.0.1`).
+
+The generated models live in `src/flaxflow/_generated/` and are produced from
+`sdks/openapi.json` (exported from the backend via `cargo run --bin export_openapi`).
+
+> Async support (`AsyncFlaxFlow`) is planned. The sync client is fully featured today.

flaxflow-1.0.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "flaxflow"
+version = "1.0.0"
+description = "Official Python SDK for the FlaxFlow Engine API — AI document processing."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "FlaxFlow" }]
+keywords = ["flaxflow", "document", "ai", "ocr", "extraction", "sdk"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+]
+dependencies = [
+    "httpx>=0.27,<1",
+    "pydantic>=2,<3",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "respx>=0.21",
+    "datamodel-code-generator>=0.25",
+]
+
+[project.urls]
+Homepage = "https://www.flaxia.com.br"
+Documentation = "https://www.flaxia.com.br/engine-api"
+Source = "https://github.com/flaxflow/FlaxFlow.PortalAI.Backend"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/flaxflow"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

flaxflow-1.0.0/scripts/configure-pypi.sh

@@ -0,0 +1,154 @@
+#!/usr/bin/env bash
+# Configura o secret PYPI_API_TOKEN no GitHub para publicação automática do SDK.
+#
+# Repo: flaxflow/FlaxFlow.PortalAI.Backend
+#
+# Uso:
+#   bash scripts/configure-pypi.sh                         # interativo
+#   bash scripts/configure-pypi.sh pypi-xxx              # token como argumento
+#   bash scripts/configure-pypi.sh pypi-xxx --repo owner/repo
+#   FLAXFLOW_GITHUB_REPO=owner/repo bash scripts/configure-pypi.sh
+#
+# Pré-requisitos: GitHub CLI (gh) autenticado — brew install gh && gh auth login
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SDK_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+DEFAULT_REPO="flaxflow/FlaxFlow.PortalAI.Backend"
+
+usage() {
+  sed -n '3,11p' "$0" | sed 's/^# \{0,1\}//'
+  exit "${1:-0}"
+}
+
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+  usage 0
+fi
+
+if ! command -v gh &>/dev/null; then
+  echo "Erro: GitHub CLI (gh) não encontrado."
+  echo "Instale com: brew install gh"
+  echo "Depois autentique: gh auth login"
+  exit 1
+fi
+
+if ! gh auth status &>/dev/null; then
+  echo "Erro: gh não está autenticado. Rode: gh auth login"
+  exit 1
+fi
+
+TOKEN=""
+REPO="${FLAXFLOW_GITHUB_REPO:-}"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --repo)
+      REPO="${2:?informe owner/repo após --repo}"
+      shift 2
+      ;;
+    -h|--help)
+      usage 0
+      ;;
+    *)
+      if [[ -z "$TOKEN" ]]; then
+        TOKEN="$1"
+      else
+        echo "Argumento desconhecido: $1"
+        usage 1
+      fi
+      shift
+      ;;
+  esac
+done
+
+if [[ -z "$TOKEN" ]]; then
+  echo "Cole o token PyPI (começa com pypi-) e pressione Enter:"
+  read -rs TOKEN
+  echo
+fi
+
+TOKEN="${TOKEN//$'\r'/}"
+TOKEN="${TOKEN//$'\n'/}"
+TOKEN="$(echo -n "$TOKEN" | xargs)"
+
+if [[ -z "$TOKEN" ]]; then
+  echo "Erro: token vazio."
+  exit 1
+fi
+
+if [[ ! "$TOKEN" =~ ^pypi- ]]; then
+  echo "Erro: token inválido — deve começar com pypi-"
+  exit 1
+fi
+
+repo_from_git_dir() {
+  local git_dir="$1"
+  if [[ ! -d "$git_dir" ]]; then
+    return 1
+  fi
+  (
+    cd "$git_dir"
+    gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null \
+      || git remote get-url origin 2>/dev/null | sed -E 's#.*github\.com[:/](.+)(\.git)?$#\1#' \
+      | sed -E 's#^git@[^:]+:##'
+  )
+}
+
+find_git_repo() {
+  local dir="$PWD"
+  while [[ "$dir" != "/" ]]; do
+    if [[ -d "$dir/.git" ]]; then
+      repo_from_git_dir "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+
+  # sdks dentro do Backend (FlaxFlow.PortalAI.Backend/sdks/python)
+  local inside_backend
+  inside_backend="$(cd "$SDK_ROOT/../.." && pwd)"
+  if repo_from_git_dir "$inside_backend" &>/dev/null; then
+    repo_from_git_dir "$inside_backend"
+    return 0
+  fi
+
+  # layout monorepo local: plataforma/sdks ao lado de FlaxFlow.PortalAI.Backend
+  local sibling_backend="$SDK_ROOT/../FlaxFlow.PortalAI.Backend"
+  if repo_from_git_dir "$sibling_backend" &>/dev/null; then
+    repo_from_git_dir "$sibling_backend"
+    return 0
+  fi
+
+  return 1
+}
+
+if [[ -z "$REPO" ]]; then
+  REPO="$(find_git_repo 2>/dev/null || true)"
+fi
+
+if [[ -z "$REPO" ]]; then
+  REPO="$DEFAULT_REPO"
+fi
+
+if ! gh repo view "$REPO" &>/dev/null; then
+  echo "Erro: repositório não encontrado ou sem acesso: $REPO"
+  echo "Informe manualmente: bash scripts/configure-pypi.sh --repo owner/repo"
+  exit 1
+fi
+
+echo "Configurando PYPI_API_TOKEN em $REPO ..."
+gh secret set PYPI_API_TOKEN --repo "$REPO" --body "$TOKEN"
+
+VERSION="$(grep '^version' "$SDK_ROOT/pyproject.toml" | head -1 | sed 's/.*"\(.*\)".*/\1/')"
+
+echo ""
+echo "Pronto. Secret PYPI_API_TOKEN configurado em $REPO."
+echo ""
+echo "Publicação automática (após push em main):"
+echo "  • Alterações em sdks/python/** disparam sdk-python-release.yml"
+echo "  • Versão atual do pacote: $VERSION"
+echo ""
+echo "Disparar manualmente:"
+echo "  gh workflow run sdk-python-release.yml --repo $REPO"
+echo ""
+echo "Antes de cada nova release, aumente version em sdks/python/pyproject.toml"

flaxflow-1.0.0/scripts/generate.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+#
+# Regenera os modelos pydantic a partir da spec OpenAPI (fonte de verdade).
+# A spec é exportada do backend com:  cargo run --bin export_openapi
+#
+# Uso:  bash scripts/generate.sh
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SPEC="${1:-$HERE/../openapi.json}"
+OUT="$HERE/src/flaxflow/_generated/models.py"
+
+if [ ! -f "$SPEC" ]; then
+  echo "OpenAPI spec not found at $SPEC" >&2
+  echo "Generate it first: cargo run --bin export_openapi && cp openapi.json sdks/openapi.json" >&2
+  exit 1
+fi
+
+datamodel-codegen \
+  --input "$SPEC" --input-file-type openapi \
+  --output "$OUT" \
+  --output-model-type pydantic_v2.BaseModel \
+  --use-standard-collections \
+  --target-python-version 3.10 \
+  --snake-case-field --use-field-description \
+  --collapse-root-models
+
+echo "Generated $OUT"

flaxflow-1.0.0/scripts/setup-github-repo.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# Cria o repositório GitHub para os SDKs (primeira vez) e prepara o push em main.
+#
+# Uso:
+#   bash scripts/setup-github-repo.sh
+#   bash scripts/setup-github-repo.sh --repo flaxflow/plataforma
+#   bash scripts/setup-github-repo.sh --repo roberto-fernandino/flaxflow-sdks
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SDK_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+MONOREPO_ROOT="$(cd "$SDK_ROOT/../.." && pwd)"
+DEFAULT_REPO="flaxflow/plataforma"
+
+REPO="${FLAXFLOW_GITHUB_REPO:-$DEFAULT_REPO}"
+PRIVATE="--private"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --repo)
+      REPO="${2:?informe owner/repo após --repo}"
+      shift 2
+      ;;
+    --public)
+      PRIVATE="--public"
+      shift
+      ;;
+    *)
+      echo "Uso: $0 [--repo owner/repo] [--public]"
+      exit 1
+      ;;
+  esac
+done
+
+if ! command -v gh &>/dev/null || ! gh auth status &>/dev/null; then
+  echo "Erro: instale e autentique o gh — brew install gh && gh auth login"
+  exit 1
+fi
+
+cd "$MONOREPO_ROOT"
+
+if [[ ! -f .gitignore ]]; then
+  cat > .gitignore <<'EOF'
+.DS_Store
+.cursor/
+.claude/
+.playwright-mcp/
+*.json
+
+# Apps com repositórios Git próprios (não fazem parte deste repo de SDKs)
+FlaxFlow.PortalAI.Backend/
+FlaxFlow.PortalAI.Frontend/
+videos/
+
+# Python / Node artefatos locais
+sdks/python/.venv/
+sdks/python/dist/
+sdks/python/build/
+sdks/python/.pytest_cache/
+sdks/typescript/node_modules/
+EOF
+fi
+
+if [[ ! -d .git ]]; then
+  echo "Inicializando git em $MONOREPO_ROOT ..."
+  git init -b main
+fi
+
+git add .gitignore sdks/ .github/ AGENTS.md CLAUDE.md 2>/dev/null || true
+git add -A sdks/ .github/ 2>/dev/null || true
+
+if git diff --cached --quiet; then
+  echo "Nada novo para commitar (já está tudo staged/commitado?)."
+else
+  git commit -m "$(cat <<'EOF'
+chore(sdks): preparar monorepo de SDKs com release automático no PyPI
+
+EOF
+)"
+fi
+
+if gh repo view "$REPO" &>/dev/null; then
+  echo "Repositório $REPO já existe."
+  if ! git remote get-url origin &>/dev/null; then
+    git remote add origin "https://github.com/$REPO.git"
+  fi
+  echo "Fazendo push para main ..."
+  git push -u origin main
+else
+  echo "Criando $REPO no GitHub e fazendo push ..."
+  gh repo create "$REPO" $PRIVATE --source=. --remote=origin --push
+fi
+
+echo ""
+echo "Repositório pronto: https://github.com/$REPO"
+echo ""
+echo "Próximo passo — configurar o token PyPI:"
+echo "  cd sdks/python && bash scripts/configure-pypi.sh"

flaxflow-1.0.0/src/flaxflow/__init__.py

@@ -0,0 +1,43 @@
+"""SDK oficial em Python para a FlaxFlow Engine API (processamento de documentos com IA).
+
+Quickstart:
+    >>> from flaxflow import FlaxFlow
+    >>> fx = FlaxFlow(api_key="sk_...")
+    >>> job = fx.processing.process_document("invoice.pdf", document_id="<doc_id>")
+    >>> print(job.result)
+"""
+
+from __future__ import annotations
+
+from ._files import SUPPORTED_DOCUMENT_TYPES
+from .client import FlaxFlow
+from .errors import (
+    APIConnectionError,
+    APIStatusError,
+    AuthenticationError,
+    ConflictError,
+    FlaxFlowError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    UnprocessableEntityError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "FlaxFlow",
+    "FlaxFlowError",
+    "APIConnectionError",
+    "APIStatusError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ConflictError",
+    "UnprocessableEntityError",
+    "RateLimitError",
+    "ServerError",
+    "SUPPORTED_DOCUMENT_TYPES",
+    "__version__",
+]