Configuration

Construct a worker with keyword arguments:

from zeridion_flare.worker import FlareWorker

worker = FlareWorker(
    api_key=None,            # falls back to FLARE_API_KEY
    base_url=None,           # override for local dev / staging
    concurrency=10,          # max jobs in flight at once
    poll_interval_s=2.0,     # idle wait between polls when there's no work
    default_timeout_s=1800,  # per-job timeout when a job carries none
    default_max_attempts=3,  # advertised attempt ceiling default
    shutdown_grace_s=30.0,   # how long to wait for in-flight jobs at shutdown
)

Options

Keyword	Default	Description
api_key	FLARE_API_KEY env var	API key. Pass directly or via the environment.
base_url	the SDK default	Point at a different environment. As with the client, the default already includes the /flare/v1 path — an override must too.
queues	the queues your jobs declare	Override which queues to poll. By default the worker polls the union of the queues its registered jobs use.
concurrency	10	Maximum jobs running simultaneously. The advertised free-slot count is clamped to the server-accepted range, so you can set this freely.
poll_interval_s	2.0	Idle delay between poll cycles when there is no work or no free slots.
default_timeout_s	1800	Fallback per-job timeout (seconds) when a job carries none.
default_max_attempts	3	Default advertised attempt ceiling for registered jobs.
shutdown_grace_s	30.0	Upper bound on the drain wait for in-flight jobs at shutdown.

Choosing concurrency

The worker runs jobs on a thread pool. Python releases the GIL during I/O, so I/O-bound handlers (HTTP calls, database queries) scale well with higher concurrency. CPU-bound handlers contend for the GIL — keep concurrency low and push heavy compute into separate processes.

Lifecycle

# Blocking — installs SIGTERM / SIGINT handlers and drains on signal.
worker.run()

# Or control it yourself (e.g. inside a larger app):
worker.start()   # non-blocking; begins polling
...
worker.stop()    # stops polling, drains in-flight jobs, releases resources

• run() must be called from the main thread, because it installs signal handlers. It blocks until a SIGTERM / SIGINT (Ctrl-C) arrives, then drains and returns an exit code.
• start() / stop() are for embedding the worker in another application that owns its own shutdown. Both are idempotent.

Graceful shutdown

On shutdown the worker:

1. stops polling for new jobs,
2. lets in-flight jobs run to completion (bounded by shutdown_grace_s),
3. closes its HTTP connection and exits.

A job that is still running when the grace window expires is left for the server to reclaim and redeliver — another reason handlers must be idempotent.

See also

• Worker overview
• Job context