Skip to content

Foveance 0.5.0 — the codec release

Choose a tag to compare

View all tags
@Aimaghsoodi Aimaghsoodi released this 16 Jul 07:49
· 3 commits to main since this release
v0.5.0
57d4d27

The first release since 0.2.0, and it ships everything from the 0.3 and 0.4 lines as well. Those two
versions were developed and are documented in full below, but were never published: 0.3.0 predates
its own vault handle-leak fix, and both predate the codec work that supersedes them. Rather than
put superseded builds on PyPI permanently, 0.5.0 folds them in. If you are coming from 0.2.0 you get
the 0.3 interactive-compression work, the 0.4 lossless codec, and the 0.5 codec-everywhere work in
one step.

Added

  • Shared-prefix template pass (RedundancyCodec(template=True), compress(..., template=True)):
    factors the prefix shared by a run of near-identical lines out once
    ([fov:tpl 20 "src/service/module_"] + the suffixes), recovering the intra-line redundancy that
    line-level dedup structurally cannot see. Exactly invertible via the new
    foveance.expand_templates(), never inflates, and takes the head-to-head from 75.4% to 82.4%
    saved — past LLMLingua-2 matched (79.8%) while remaining lossless with 100% of facts preserved.
    Opt-in by design: it measured 0.90 vs 0.95 mean accuracy at 14% fewer tokens on the five-model
    benchmark (one task in twenty, within noise, but not measurably free), and the default must stay
    safe to enable unconditionally.
  • RULER public benchmark arm (bench/fetch_ruler.py, bench/codec_ruler.py): 480 real examples
    across all task families at 4k/8k/16k. Serves as a negative control — RULER plants distinct
    needles, so the codec correctly saves ~0% on qa/niah_multikey and never inflates, while
    removing 91.4% on the one family that genuinely repeats. All 480 round-trip exactly.
  • .foveance.toml now also carries the codec and agentic_codec switches, so the codec can be
    turned on once per machine/project instead of per invocation.

Fixed

  • foveance --version / -V now print the version. Previously only the foveance version
    subcommand worked and the flags silently printed help and exited 0, which reads like a broken
    install. Regression-tested.
  • The test suite no longer hard-fails without the optional ML extras. Four tests imported numpy
    (via foveance.learned) without a guard, so pip install "foveance[dev]" && pytest reported
    four ModuleNotFoundError failures on an otherwise healthy install. They now
    pytest.importorskip("numpy") and skip cleanly, matching how the integration tests already
    handle optional dependencies.

Changed (packaging)

  • The source distribution no longer ships assets/ (README images are served from GitHub by
    absolute URL) or the manuscript's vector PDFs, halving it from 4.4 MB to 2.2 MB. The benchmark
    figures (bench/plots/*.png) and every results CSV are still included — they are the evidence
    behind the README's numbers. The installed wheel is unchanged at ~82 KB.
  • Lossless codec on the agentic (tool-use) paths (foveance proxy --agentic-codec /
    FOVEANCE_AGENTIC_CODEC=1): on tool-using requests the codec now runs across the old tool
    payloads in place, collapsing cross-message repeats (re-listed dirs, retried stack traces,
    boilerplate) to legible pointers with the first occurrence kept verbatim — instead of lossily
    digesting each payload. Only free-text payload strings are rewritten; message count/order, roles,
    tool_use↔tool_result ids, cache_control blocks, and the last agentic_protect_last turns
    stay byte-identical, so the provider still validates the request and the prompt cache is never
    invalidated. Wired through all three dialects (Anthropic Messages, OpenAI Chat, OpenAI Responses)
    and covered by a full tool-pairing safety matrix. agentic_codec surfaced in /admin/stats.
  • New agent adapters: foveance wrap/env now know Cursor, Windsurf, Roo Code, Zed, and the
    Gemini CLI (15 total), each with an honest note on GUI-vs-env configuration.
  • Lossless codec in the proxy (foveance proxy --codec / FOVEANCE_CODEC=1): the 0.4
    cross-item redundancy codec now runs on the assembled plain-chat context, reference-encoding
    repeated line-runs across items losslessly (the first occurrence stays verbatim, so no fact
    is dropped). Off by default; a codec_saved_tokens counter reports the additional lossless
    saving. Zero accuracy risk, so it is safe to layer on top of any budget/policy.

Changed

  • Codec default min_run=1 (was 2): because every reference is already gated by the token
    guard, dereferencing a single repeated line only when the pointer is strictly cheaper is
    cost-optimal — measured 76.1% vs 75.6% saved on the redundancy suite, never inflates, losslessness
    unchanged. Applied to compress/compress_anthropic/proxy.
  • Vault storage codec now picks the strongest installed backend — Brotli (~50×) or Zstandard
    (~44×)     when available, falling back to stdlib zlib — via a self-describing 3-byte header.
    Backward-compatible: legacy headerless-zlib blobs still decode.
  • foveance.compress_anthropic(system, messages) — the Anthropic-shaped lossless codec
    one-liner, returning (new_system, new_messages, report) with the system string participating
    in the cross-message dedup.
  • Entropy-coded vault storage (ItemVault(compress=True), default on): stored full texts are
    now zlib-compressed (the transport-codec storage saving — up to ~50–100× on redundant content),
    realising the paper's storage-side result. Reads transparently handle both compressed and legacy
    plaintext rows, so existing vaults keep working (a blob column is migrated in automatically).
Assets 4
Loading