Clients

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

Convilyn (sync)

from convilyn import Convilyn
 
client = Convilyn(api_key=my_key)  # 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

Resource accessors

client.files       # Files — upload / register
client.convert     # Convert — hosted document conversion jobs
client.goals       # Goals — goal workflows (multi-step)
client.workflows   # Workflows — community marketplace (search / fork / publish / like)
client.account     # Account — billing tier + cost-preview / quota queries

goals.start (and goals.run) accept an optional llm_config_id to run the job on one of your stored BYO-LLM provider configs (created in the console); omit it to use your account default. It is honoured only when BYO-LLM is enabled for your account — otherwise the run uses the platform provider. (Wire name: llmConfigId; the same option is available on AsyncConvilyn.)

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 (incl. `goals.events(...)` WS streaming — async only)
client.workflows   # AsyncWorkflows
client.account     # AsyncAccount

goals.events(job_spec_id) is the one method that's async-only — it returns an AsyncIterator[GoalEvent] over the WebSocket stream. The sync Convilyn does NOT expose it because bridging a WebSocket through asyncio.run per call is ergonomically wrong; switch to AsyncConvilyn when you need streaming.

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.