Skip to content

Public Python API

The supported package surface is imported from axm_smelt. Read contracts and report semantics before interpreting savings.

axm_smelt

axm-smelt - Deterministic token compaction for LLM inputs.

SmeltReport

Bases: BaseModel

Report produced by the smelt pipeline.

compacted instance-attribute
compacted_tokens instance-attribute
counter_backend = CounterBackend.TIKTOKEN class-attribute instance-attribute
format instance-attribute
original instance-attribute
original_tokens instance-attribute
savings_pct instance-attribute
strategies_applied instance-attribute
strategy_estimates = {} class-attribute instance-attribute

Format

Bases: Enum

Supported input formats.

CSV = 'csv' class-attribute instance-attribute
JSON = 'json' class-attribute instance-attribute
MARKDOWN = 'markdown' class-attribute instance-attribute
TEXT = 'text' class-attribute instance-attribute
TOML = 'toml' class-attribute instance-attribute
XML = 'xml' class-attribute instance-attribute
YAML = 'yaml' class-attribute instance-attribute

CounterBackend

Bases: StrEnum

Backend used to produce a token count.

Currently only :attr:TIKTOKEN exists; the enum is retained as the seam for a future HuggingFace/SentencePiece backend (Llama/Mistral/Gemma).

TIKTOKEN = _TIKTOKEN_VALUE class-attribute instance-attribute

smelt(text=None, strategies=None, preset=None, *, parsed=None)

Run the compaction pipeline and return a report.

Baseline for savings_pct: the pipeline's working text — the compact serialization the strategies actually operate on. On the text= path this is the provided raw string; on the parsed= path it is the compact dump json.dumps(parsed, separators=(",", ":")) (identical to report.original).

Reporting savings against the working text keeps savings_pct honest: it measures only what the strategies achieved, never the pretty-vs-compact gap of :func:resolve_input (which no strategy performed). A parsed= input on which no strategy applies therefore reports 0 — not a phantom reduction. This single honest baseline also seeds the keep-if-reduced guard, so a strategy whose output is heavier than the working text can never be accepted.

check(text=None, *, parsed=None)

Analyze text without transforming it.

The report carries two distinct savings figures:

  • strategy_estimates maps each registry strategy to the reduction it achieves in isolation, measured against the unmutated input. These estimates are independent and non-additive: summing them overstates the achievable gain, because strategies overlap (e.g. minify already removes whitespace that collapse_whitespace would also target).
  • savings_pct is the real cumulative gain — the reduction obtained by chaining the default strategy set (resolve_strategies(None, None), i.e. the safe preset, exactly what :func:smelt applies with no explicit strategies). It equals what a user would actually get from smelt(text).

original and compacted stay identical: check never transforms its input, it only measures.

count(text, model='o200k_base')

Return the token count for text.

Uses tiktoken with model encoding; a claude* or unknown model is routed to the o200k_base proxy.

Version

axm_smelt.__version__ is a string generated at build time, with a "0.0.0" import-failure fallback in a source checkout.