API reference

Cached, budget-capped calls to Meta’s Muse Spark.

exception BudgetError

The request would exceed the authorized cap.

class Client(cap_usd, workdir, model='muse-spark-1.3-contributor', rates=None, transport=None, key=None, ledger=None)

Structured Muse Spark completions under a hard spending cap.

Parameters:

• cap_usd (float)

• workdir (str | Path)

• model (str)

• rates (dict[str, float] | None)

• transport (Callable[[dict, str], tuple[int, str]] | None)

• key (str | None)

• ledger (str | Path | None)

property key

The API key, looked up on first use.

exposure()

Reserved or reported cost of every call recorded in the ledger.

payload(messages, schema, name, max_completion_tokens, reasoning_effort)

The chat-completions request body for a structured answer.

complete(messages, schema, name='result', max_completion_tokens=8000, reasoning_effort='low', key_extra=None, with_call=False)

The parsed, schema-valid JSON answer to messages; cached by request.

key_extra is folded into the cache key and recorded, but not sent: use it for deliberate repeats of an identical request (a replicate, an explicit retry). With with_call=True the call’s folder is returned too, so a caller can keep its own derived files beside the request.

folder_for(messages, schema, name='result', max_completion_tokens=8000, reasoning_effort='low', key_extra=None)

Where complete with these arguments keeps its call, sent or not.

abandon(call_id)

Set aside a call with no response, keeping its reserve in the ledger.

spend()

Provider-reported cost of completed calls, and current exposure.

exception ResponseError

The provider’s response is incomplete, malformed or off-contract.

exception UnknownOutcomeError

The call was sent but no response arrived; it may have been charged.

listed_rates(model, key)

USD per million tokens for input, cached input and output, as listed.

usage_cost(usage, rates, cached=True)

USD for a usage record; cached=False ignores the cache discount.