falaw.base#

Core types: ToolSpec and ModelRecord.

These dataclasses are the single source of truth from which every external surface (Claude skill, MCP server, HTTP service, UI) is derived.

Module Attributes

TABLE_VERSION_CHARS

Hex characters of the digest data_table_version() returns.

Functions

data_table_version(path)

Short content digest naming the version of a committed data table.

Classes

`CostEstimate`(*, kind, amount[, currency, ...])	Quantitative cost of one fal call against this model.
`ModelRecord`(*, id, category[, description, ...])	One entry in the fal model catalog.
`ToolSpec`(*, name, description, func[, ...])	Single source of truth for a tool exposed by falaw.

class falaw.base.CostEstimate(*, kind, amount, currency='USD', notes='', source='approximate')[source]#

Bases: object

Quantitative cost of one fal call against this model.

kind#: How the price scales. per_call is the simplest: constant per invocation regardless of size. per_second applies to video / TTS where output length matters. per_image covers batch image gen. per_megapixel covers high-res image generation. per_token covers LLM-style endpoints.

amount#: USD (or currency) per unit defined by kind.

currency#: ISO 4217 code. "USD" is the only supported value today; the field exists so we can extend without a schema migration.

notes#: Free-form caveats — “rounded up to next second”, etc.

source#: How the estimate was obtained — "docs", "empirical", "approximate". Lets us flag stale or unverified entries in audits.

class falaw.base.ModelRecord(*, id, category, description='', aliases=(), quality_tier='', cost_hint='', cost_estimate=None, docs_url='', max_clip_seconds=None, single_character_recommended=False, supported_resolutions=(), default_negative_prompt='', max_prompt_chars=None, size_param='image_size', param_specs=<factory>)[source]#

Bases: object

One entry in the fal model catalog.

default_negative_prompt: str#: Quality/realism negatives worth appending by default (e.g. to avoid the plastic-skin look). Empty when none.

max_clip_seconds: float | None#: Practical max length of a single generated clip, in seconds (e.g. ~10 for Seedance). Drives the “this shot is too long, split it” warning.

max_prompt_chars: int | None#: Hard cap on prompt length, from the model’s OpenAPI schema. Calls over it fail at fal with an HTTP 422 after queueing; falaw raises first.

param_specs: Mapping[str, Mapping[str, Any]]#: Discoverable per-model parameters that matter for choosing well, as {name: {"enum": [...], "default": ...}} — e.g. Recraft’s style, whose photoreal default silently overrides a woodcut prompt. See falaw.model_params().

single_character_recommended: bool#: True when the model handles a single character per shot far better than multiple interacting ones — drives the “two characters, consider shot/reverse-shot” warning.

size_param: str#

"image_size" (fal’s named presets, the default) or "aspect_ratio" (+ resolution).

Type:: Which argument carries the output size

supported_resolutions: tuple[str, ...]#: Resolutions the model offers, cheap→expensive (e.g. (“720p”, “1080p”)).

falaw.base.TABLE_VERSION_CHARS = 12#: Hex characters of the digest data_table_version() returns.

class falaw.base.ToolSpec(*, name, description, func, input_schema=<factory>, output_schema=<factory>, tags=(), examples=(), version='0.0.1')[source]#

Bases: object

Single source of truth for a tool exposed by falaw.

A ToolSpec is what the registry stores. Bridges read it to produce Claude-skill instructions, MCP tool descriptors, HTTP endpoints, etc.

falaw.base.data_table_version(path)[source]#

Short content digest naming the version of a committed data table.

The one definition for every table falaw ships (models.json, llm_rates.json), so a falaw.CostBasis stamped by one is comparable with a basis stamped by another.

Deliberately the bytes, not a declared version field: 0.0.46 moved every premium LLM row’s price tenfold without touching one, and that drift is exactly what a persisted quote must be able to detect. A digest cannot forget to be bumped.

Return type:: str