core.history.recorder

Single point for writing interactions to all history stores.

Single point for writing interactions to all history stores.

class HistoryRecorder(context, permanent_history, ordered_history, memory=None, memory_persist=False, memory_persist_path=None)[source]

Bases: object

Records interactions to all 5 history stores in a single operation.

Owns the raw history and clean_history lists and coordinates writes to PermanentHistory, OrderedPromptHistory, and ResponseContext. Optionally embeds each recorded Q+A pair into a Memory instance on a fire-and-forget background thread.

Callers invoke record() instead of manually writing to 5 separate stores.

Parameters:

  • context (ResponseContext) – The ResponseContext for prompt_attr_history recording.

  • permanent_history (PermanentHistory) – The PermanentHistory for chronological turns.

  • ordered_history (OrderedPromptHistory) – The OrderedPromptHistory for named interactions.

  • memory (Memory | None) – Optional Memory instance. When provided, each successful record() call submits an embedding task to a dedicated single-worker thread pool. Failed embeds are logged at WARNING and dropped; they never propagate to the caller.

  • memory_persist (bool) – If True, persist the memory store to Parquet after each successful embed. Requires memory_persist_path to be set.

  • memory_persist_path (str | None) – Fully-qualified file path for the Parquet persistence file. Ignored when memory_persist is False or memory is None. Typically computed by FFAI.__init__() as f"{config.memory.persist_dir}/{config.memory.collection_name}.parquet".

record(prompt, response, model, prompt_name=None, history=None, status='success', resolved_prompt=None, usage=None, metadata=None)[source]

Record an interaction to all 5 history stores.

When a Memory instance is configured and status == "success", the Q+A pair is embedded on a fire-and-forget background thread. Metadata is derived from prompt_name when not explicitly passed.

Parameters:

  • prompt (str) – The resolved prompt text.

  • response (Any) – The cleaned response.

  • model (str) – Model identifier used.

  • prompt_name (str | None) – Logical name for the prompt.

  • history (list[str] | None) – List of prompt names this call depends on.

  • status (str) – Execution status (“success”, “skipped”, “failed”). Only "success" triggers embedding.

  • resolved_prompt (str | None) – The fully interpolated prompt sent to the model.

  • usage (Any) – Token usage from the API call.

  • metadata (dict[str, Any] | None) – Optional caller metadata. When None, derived from prompt_name as {"prompt_name": prompt_name} (or {} if prompt_name is also None).

Return type:

None

shutdown()[source]

Shut down the background embed thread pool.

Safe to call multiple times. Called by FFAI.close() on teardown. Pending submitted tasks are not awaited (wait=False); they may complete or be abandoned at interpreter exit.

Return type:

None

Classes

class HistoryRecorder(context, permanent_history, ordered_history, memory=None, memory_persist=False, memory_persist_path=None)[source]

Bases: object

Records interactions to all 5 history stores in a single operation.

Owns the raw history and clean_history lists and coordinates writes to PermanentHistory, OrderedPromptHistory, and ResponseContext. Optionally embeds each recorded Q+A pair into a Memory instance on a fire-and-forget background thread.

Callers invoke record() instead of manually writing to 5 separate stores.

Parameters:

  • context (ResponseContext) – The ResponseContext for prompt_attr_history recording.

  • permanent_history (PermanentHistory) – The PermanentHistory for chronological turns.

  • ordered_history (OrderedPromptHistory) – The OrderedPromptHistory for named interactions.

  • memory (Memory | None) – Optional Memory instance. When provided, each successful record() call submits an embedding task to a dedicated single-worker thread pool. Failed embeds are logged at WARNING and dropped; they never propagate to the caller.

  • memory_persist (bool) – If True, persist the memory store to Parquet after each successful embed. Requires memory_persist_path to be set.

  • memory_persist_path (str | None) – Fully-qualified file path for the Parquet persistence file. Ignored when memory_persist is False or memory is None. Typically computed by FFAI.__init__() as f"{config.memory.persist_dir}/{config.memory.collection_name}.parquet".

record(prompt, response, model, prompt_name=None, history=None, status='success', resolved_prompt=None, usage=None, metadata=None)[source]

Record an interaction to all 5 history stores.

When a Memory instance is configured and status == "success", the Q+A pair is embedded on a fire-and-forget background thread. Metadata is derived from prompt_name when not explicitly passed.

Parameters:

  • prompt (str) – The resolved prompt text.

  • response (Any) – The cleaned response.

  • model (str) – Model identifier used.

  • prompt_name (str | None) – Logical name for the prompt.

  • history (list[str] | None) – List of prompt names this call depends on.

  • status (str) – Execution status (“success”, “skipped”, “failed”). Only "success" triggers embedding.

  • resolved_prompt (str | None) – The fully interpolated prompt sent to the model.

  • usage (Any) – Token usage from the API call.

  • metadata (dict[str, Any] | None) – Optional caller metadata. When None, derived from prompt_name as {"prompt_name": prompt_name} (or {} if prompt_name is also None).

Return type:

None

shutdown()[source]

Shut down the background embed thread pool.

Safe to call multiple times. Called by FFAI.close() on teardown. Pending submitted tasks are not awaited (wait=False); they may complete or be abandoned at interpreter exit.

Return type:

None