API Reference

API Reference

Everything below is importable from distribatch (import distribatch as dib). Anything else is internal and may change without notice.

Jobs

dib.GenerateJob(model, prompt, system=None, output_schema=None, sampling=Sampling(), engine="auto", engine_options={})

LLM generation. See GenerateJob.

dib.EmbedJob(model, text, dimensions=None, normalize=False, engine="auto", engine_options={})

Text embeddings. See EmbedJob.

dib.TranscribeJob(model, audio_col, language=None, prompt=None, timestamps=False, translate=False, engine="auto", engine_options={})

Speech to text. See TranscribeJob.

dib.BaseJob

Common base class (pydantic model, frozen). Shared fields:

field	type	default
model	model spec or URI string	required
engine	"auto", "openai", "vllm", "transformers", "faster_whisper", "fake"	"auto"
engine_options	dict	{} (see Engines)

Methods:

• run(data, *, backend="local", output_col="output", batch_size=32, workers=None, partitions=None, dedupe=False, checkpoint=None, id_col=None, retry_failed=True, checkpoint_every=None) runs the job and returns the data with output columns. See Running Jobs.
• preview(data, n=5, *, output_col="output") runs the first n rows locally.
• fingerprint() -> str returns the identity of what the job computes (used by checkpoints).
• task: class attribute, "generate", "embed" or "transcribe".

Extension hooks (implemented by the job classes): required_columns(), build_request(row_id, record, capabilities), finish(output), output_type().

dib.Sampling(temperature=0.0, max_tokens=512, top_p=None, stop=None, seed=None)

Generation parameters. See GenerateJob.

Models: dib.models

function	returns
uc(name, *, version=None, alias=None, stage_dir=None)	UCModel
path(path, *, copy_to_local=False)	PathModel
openai(model, *, base_url=None, api_key_env=None)	OpenAIModel
databricks(endpoint, *, api_key_env=None)	OpenAIModel with base_url="databricks"
fake(*, response=None, fail_marker=None, crash_marker=None, exit_marker=None, delay_ms=0.0, structured_output=True)	FakeModel
parse(uri)	the spec for a URI string

Spec classes: UCModel, PathModel, OpenAIModel, FakeModel (frozen pydantic models), and ModelSpec (their union). See Model Sources.

Statistics

dib.summarize(output, output_col="output") -> RunStats

Statistics of a run() result (list, pandas or Spark). See Statistics and Costs.

dib.RunStats

Fields: rows, succeeded, failed, reused, retries, prompt_tokens, completion_tokens, audio_seconds, latency_ms_p50, latency_ms_p95, errors.

• success_rate (property).
• cost(*, input_per_million=0.0, output_per_million=0.0, per_audio_minute=0.0).
• to_dict().
• log_to_mlflow(job=None, prefix="distribatch.").

Exceptions

class	base	raised / reported
DistribatchError	Exception	base of all below
ConfigError	DistribatchError	raised: invalid configuration, before work starts
MissingDependencyError	DistribatchError, ImportError	raised: an extra is missing (.module, .extra)
InvalidInputError	DistribatchError	row error: unusable input
PromptRenderError	InvalidInputError	row error: template could not be filled
SchemaValidationError	DistribatchError	row error: output doesn't match output_schema
OutputTypeError	DistribatchError	row error (Spark): value doesn't fit the column type
EngineError	DistribatchError	row error: engine failure
WorkerCrashedError	DistribatchError	row error (multiprocessing): worker process died

Row errors appear as "<ClassName>: <message>" in the <out>_error column. See Output Contract.

Version

dib.__version__