LLMDB.History.Backfill (LLM DB v2026.7.3)

Copy Markdown View Source

Backfills model history by diffing committed provider snapshots across git history.

This module is intentionally git-driven and infrastructure-free: it reads priv/llm_db/providers/*.json from commit history and writes append-only NDJSON event files under a local history directory.

This legacy Git-to-NDJSON path is deprecated and remains available only for compatibility. For the maintained snapshot workflow, seed historical data once with mix llm_db.history.migrate_git --publish, then use mix llm_db.history.rebuild --publish for subsequent rebuilds.

These compatibility functions may be removed no earlier than v2027.0.0, after at least one minor release deprecation window.

Summary

Types

check_result()
summary()

Functions

check(opts \\ []) deprecated

Checks whether generated history is current with git history.

diff_models(previous_models, current_models) deprecated

Diffs two model maps and returns deterministic model events.

run(opts \\ []) deprecated

Runs a full history backfill from git.

sync(opts \\ []) deprecated

Incrementally syncs history output from the last generated commit to :to (default HEAD).

Types

check_result()

@type check_result() ::
  :history_unavailable
  | :up_to_date
  | {:outdated, %{new_commits: non_neg_integer(), latest_commit: String.t()}}

summary()

@type summary() :: %{
  commits_scanned: non_neg_integer(),
  commits_processed: non_neg_integer(),
  snapshots_written: non_neg_integer(),
  events_written: non_neg_integer(),
  output_dir: String.t(),
  from_commit: String.t() | nil,
  to_commit: String.t() | nil
}

Functions

check(opts \\ [])

This function is deprecated. use mix llm_db.history.check; legacy backfill may be removed in v2027.0.0. 
@spec check(keyword()) :: {:ok, check_result()} | {:error, term()}

Checks whether generated history is current with git history.

Returns :history_unavailable when meta.json is missing, :up_to_date when no metadata commits are pending, or {:outdated, ...} when new commits exist.

diff_models(previous_models, current_models)

This function is deprecated. use the maintained mix llm_db.history.* workflows; legacy Backfill APIs may be removed in v2027.0.0. 
@spec diff_models(%{optional(String.t()) => map()}, %{optional(String.t()) => map()}) ::
  [map()]

Diffs two model maps and returns deterministic model events.

Expects maps keyed by "provider:model_id" with normalized model payload values.

run(opts \\ [])

This function is deprecated. use mix llm_db.history.migrate_git --publish for the one-time migration; legacy backfill may be removed in v2027.0.0. 
@spec run(keyword()) :: {:ok, summary()} | {:error, term()}

Runs a full history backfill from git.

Options

  • :from - Optional start commit (inclusive)
  • :to - Optional end commit/reference (default: "HEAD")
  • :output_dir - Output directory (default: "priv/llm_db/history")
  • :force - Remove previously generated history files first (default: false)

sync(opts \\ [])

This function is deprecated. use mix llm_db.snapshot.publish and mix llm_db.history.rebuild --publish; legacy backfill may be removed in v2027.0.0. 
@spec sync(keyword()) :: {:ok, summary()} | {:error, term()}

Incrementally syncs history output from the last generated commit to :to (default HEAD).

If no history output exists yet, this performs a full backfill into the output directory.

Options

  • :to - Optional end commit/reference (default: "HEAD")
  • :output_dir - Output directory (default: "priv/llm_db/history")