# `LLMDB.History.Backfill`
[🔗](https://github.com/agentjido/llm_db/blob/main/lib/llm_db/history/backfill.ex#L1)

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.

# `check_result`

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

# `summary`

```elixir
@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
}
```

# `check`

> This function is deprecated. use mix llm_db.history.check; legacy backfill may be removed in v2027.0.0.

```elixir
@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`

> This function is deprecated. use the maintained mix llm_db.history.* workflows; legacy Backfill APIs may be removed in v2027.0.0.

```elixir
@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`

> 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.

```elixir
@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`

> 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.

```elixir
@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"`)

---

*Consult [api-reference.md](api-reference.md) for complete listing*