Produce jobs and run durable handlers from Python.

Python SDK

Install the published getratchet package with pip install getratchet. Version 0.1.0 supports Python 3.10+ and uses the standard library. The HTTP quickstart and API reference are also available.

Produce a durable job

import { createRatchet } from '@getratchet/sdk';

const ratchet = createRatchet({
  baseUrl: 'https://getratchet.waelfz.com',
  apiKey: process.env.GETRATCHET_INGEST_KEY!,
});
await ratchet.startRun('Customer onboarding');
await ratchet.enqueue({ customerId: 'cus_2048' }, {
  name: 'send_welcome_email', version: '1', endpoint: 'Email service',
  idempotencyKey: 'welcome:cus_2048', timeoutMs: 30_000, maxAttempts: 5,
});
await ratchet.finishRun();

Use a project and environment scoped INGEST key. Store it in a server-side environment variable instead of source code.

Run a separate worker

import { createRatchet } from '@getratchet/sdk';

const worker = createRatchet({
  baseUrl: 'https://getratchet.waelfz.com',
  apiKey: process.env.GETRATCHET_WORKER_KEY!,
});
worker.registerTool({
  name: 'send_welcome_email', version: '1',
  handler: async (input: { customerId: string }, { idempotencyKey, signal }) =>
    sendWelcomeEmail(input, { idempotencyKey, signal }),
});
await worker.worker.start({ concurrency: 4, signal: shutdownSignal });

Use a separate WORKER key authorized for the exact name@version handler. Call worker.worker.stop() for graceful shutdown, and set downstream network timeouts. Python cannot forcibly stop a blocked handler thread. A crash after an external side effect but before its report can repeat that effect; use destination-side idempotency.

The client also supports replay_preview(step_id) before replay(step_id, reason=...), and after_step_id with after_status='FAILED' or 'SUCCEEDED' for dependencies. Enqueue branches before finish_run(). See durable worker operations for retry and replay safety.