convilyn

Official Python client for the Convilyn API — convert files, run AI workflows, and ship in five lines of Python or a single shell command.

pip install convilyn
export CONVILYN_API_KEY=ck_...
convilyn convert report.docx --to pdf

from convilyn import Convilyn

client = Convilyn()  # reads CONVILYN_API_KEY from env
file = client.files.upload("report.docx")
job = client.convert.create_and_wait(file=file, target_format="pdf")
client.convert.download_to(job, to="report.pdf")

What you get

• Offline conversion — no API key — convilyn.local converts PDF, Word, PowerPoint, Excel, CSV, XML and plain text to Markdown entirely on your machine. No connection, no account, no quota. Install one extra per format you read (convilyn[pdf], convilyn[docx], …); plain text and CSV need none. convilyn local doctor reports what this machine can do and how to extend it. See QUICKSTART §1b.

• Python SDK — Convilyn (sync) and AsyncConvilyn (async) with resource-style accessors: client.files, client.convert, client.goals (agentic / AI workflows with HITL slot filling), client.workflows (community marketplace), client.user_workflows (manage the workflows you authored), client.builder (chat-Builder sessions), and client.account (billing tier + cost-preview).

  Goal progress is polling-only in v1. Follow a run with client.goals.wait(...) / retrieve(...) (or convilyn goals status from the shell). The WebSocket gateway does not accept consumer ck_ keys yet, so goals.events() streaming raises with guidance pointing back at polling until that lands.

• CLI — five sub-command groups installed with the package:

  • convilyn convert <file> --to <format> — upload, convert, download
  • convilyn doctor — environment + connectivity diagnostics
  • convilyn api <METHOD> <PATH> — gh-style escape hatch for any API endpoint
  • convilyn goals {start,status,events,fill-slot,confirm,cancel,retry} — drive AI workflows from the shell (NDJSON streaming, HITL, pinned exit codes)
  • convilyn account {plan,quota} — pre-flight your billing tier and workflow cost before running

• Free to install, metered to use — pip install convilyn is free. API calls draw on your monthly quota (a generous free tier is available; Pro lifts the cap). The SDK raises typed PlanRequiredError / QuotaExceededError (both subclass APIError) when an action exceeds your tier — see QUICKSTART §8.

• Resilient by default — retry on 5xx / 429 / 408 with exponential backoff + jitter, Idempotency-Key auto-stamped on mutating verbs, Retry-After honoured.

• AI-agent friendly — every command supports --json for machine-readable output, --dry-run for safe previews, and pinned exit codes (0 / 1 / 2 / 3 / 130) so agent loops can branch on the result without parsing free-text.

Companion package — building your own workflows

convilyn is the consumer SDK (you call the API). If you want to build a tool server or author a workflow spec for the Convilyn platform, install the author SDK:

pip install convilyn-author          # separate package
convilyn-author init my-server

The two packages are intentionally separate so consumers don't pay the uvicorn / FastAPI dependency cost. See convilyn-author for its source and docs.

Next

• QUICKSTART.md — 5-minute new-user guide (covers convert, goals, workflows, and account / quota chapters)
• STABILITY.md — what the public API is and the SemVer / deprecation promise behind it
• CHANGELOG.md — version history
• examples/ — runnable Python + shell scripts
• AGENT.md — guidance for AI coding agents contributing to this SDK

Licence

Apache-2.0. See LICENSE.