Convilyn docs

Clients

The two entry-point classes — pick the one that matches your runtime.

Convilyn (sync)

from convilyn import Convilyn

client = Convilyn(api_key="cvl_...")  # or read from CONVILYN_API_KEY env

A blocking, synchronous client suitable for scripts and shells. Wraps AsyncConvilyn internally — calling a sync method blocks the current thread on the async implementation.

Constructor parameters

| Name | Type | Default | Notes | |---|---|---|---| | api_key | str \| None | None | Reads CONVILYN_API_KEY env var if unset | | base_url | str \| None | None | Reads CONVILYN_BASE_URL env var; defaults to https://api.convilyn.com | | ws_url | str \| None | None | WebSocket URL for goal-lane event streams. Optional for non-goals workflows. | | timeout | float | 30.0 | Default HTTP timeout in seconds | | retry_policy | RetryPolicy \| None | ExponentialBackoffRetry(...) | Pass a custom retry policy, or NoRetry() to disable |

Resource accessors

client.files       # Files — upload / register
client.convert     # Convert — turbo-lane document conversion jobs
client.goals       # Goals — goal-lane (multi-step) workflow jobs

Context manager support

with Convilyn() as client:
    file = client.files.upload("doc.pdf")
    # ... HTTP connections closed on exit

Methods

  • close() — release the underlying HTTP client. Use the context manager form when possible.

AsyncConvilyn (async)

from convilyn import AsyncConvilyn

async with AsyncConvilyn() as client:  # reads CONVILYN_API_KEY from env
    file = await client.files.upload("doc.pdf")

The native async variant. Every resource method has an async counterpart with the same signature as the sync version.

Constructor parameters

Same as Convilyn above.

Resource accessors

client.files       # AsyncFiles
client.convert     # AsyncConvert
client.goals       # AsyncGoals

Async context manager

async with AsyncConvilyn() as client:
    file = await client.files.upload("doc.pdf")
    # ... connections closed on exit

Methods

  • aclose() — async cleanup of the underlying HTTP client.

Choosing between them

  • Use Convilyn for scripts, REPL sessions, one-shot CLI usage.
  • Use AsyncConvilyn when you're already inside an event loop (FastAPI, Starlette, an async worker, etc.). It avoids the overhead of synchronously bridging through asyncio.run.

Both share the same retry policy, transport configuration, and error types — switching between them is mechanical.