FFAI

Declarative context handling API wrapper for AI clients.

This module provides the FFAI class which wraps AI client implementations and adds declarative context management, history tracking, and DataFrame export capabilities.

Declarative context handling API wrapper for AI clients.

This module provides the FFAI class which wraps AI client implementations and adds declarative context management, history tracking, and DataFrame export capabilities.

class FFAI(client, persist_dir=None, persist_name=None, auto_persist=False, shared_prompt_attr_history=None, history_lock=None, rag=None, memory_enabled=None, memory_embeddings=None, memory_persist=None, memory=None)[source]

Bases: object

Declarative context handling wrapper for AI clients.

This class wraps an AI client implementation and exposes three namespaced managers:

  • workflow — execution orchestration (generate, DAG, workflows)

  • history — interaction queries, DataFrame export, persistence

  • rag — retrieval-augmented generation (query, index, search)

client

The underlying AI client instance.

workflow

WorkflowEngine for execution orchestration.

history

HistoryManager for history queries and export. history.memory exposes the Memory instance when memory is enabled (else None). history.search() performs semantic recall.

rag

RAG instance, or None if not configured.

persist_dir

Directory for history persistence files.

persist_name

Filename stem for persisted files.

auto_persist

Whether histories auto-persist after each call.

Parameters:

  • client (FFAIClientBase) – AI client to wrap.

  • persist_dir (str | None) – Directory for history persistence files.

  • persist_name (str | None) – Filename stem for persisted files.

  • auto_persist (bool) – Whether to auto-persist histories after each call.

  • shared_prompt_attr_history (list[dict[str, Any]] | None) – Optional shared prompt-attr list.

  • history_lock (threading.Lock | None) – Optional thread lock for history access.

  • rag (RAG | None) – Optional pre-constructed RAG instance.

  • memory_enabled (bool | None) – Override config.memory.enabled. None falls through to config (default False).

  • memory_embeddings (str | None) – Override config.memory.embedding_model. None falls through to config; triggers the resolution ladder if config is also None.

  • memory_persist (bool | None) – Override config.memory.persist. None falls through to config (default False).

  • memory (Memory | None)

property rag: RAG | None

RAG instance for retrieval-augmented generation.

Setting this property automatically wires the current client as the RAG’s default generate_fn via ClientAdapter.

set_client(client)[source]

Switch to a different AI client.

Parameters:

client (FFAIClientBase)

Return type:

None

get_system_instructions()[source]

Return the system instructions configured on the client, or None.

Return type:

str | None

clear_conversation()[source]

Clear conversation in client but retain history.

Return type:

None

get_client_conversation_history()[source]

Get the raw conversation history from the underlying client.

Return type:

list[dict[str, str]]

set_client_conversation_history(history)[source]

Set the raw conversation history in the underlying client.

Parameters:

history (list[dict[str, str]])

Return type:

bool

add_client_message(role, content, **kwargs)[source]

Add a single message to the client’s conversation history.

Parameters:
Return type:

bool

close()[source]

Release background resources.

Shuts down the memory embed thread pool if one is running. Safe to call multiple times. Call this at process teardown to avoid leaking daemon threads (e.g., in long-running services).

Return type:

None

extract_json_field(data, path)[source]

Extract a value from JSON using dot notation path.

Supports: - Simple fields: “field_name” - Nested objects: “object.field” - Array indices: “array.0” - Combined: “object.array.0.field”

Parameters:

  • data (Any) – Parsed JSON data (dict or list)

  • path (str) – Dot-separated path to extract

Returns:

Extracted value as string, or empty string if not found

Return type:

str

interpolate_prompt(prompt, history, strict=False)[source]

Replace {{prompt_name.response}} patterns with actual content.

Parameters:

  • prompt (str) – Template containing {{}} patterns

  • history (dict[str, str]) – Dict mapping prompt_name to response text

  • strict (bool) – If True, raise ValueError on unknown references instead of silently replacing with empty string.

Returns:

Tuple of (resolved_prompt, set_of_interpolated_prompt_names)

Return type:

tuple[str, set[str]]

Classes

class FFAI(client, persist_dir=None, persist_name=None, auto_persist=False, shared_prompt_attr_history=None, history_lock=None, rag=None, memory_enabled=None, memory_embeddings=None, memory_persist=None, memory=None)[source]

Bases: object

Declarative context handling wrapper for AI clients.

This class wraps an AI client implementation and exposes three namespaced managers:

  • workflow — execution orchestration (generate, DAG, workflows)

  • history — interaction queries, DataFrame export, persistence

  • rag — retrieval-augmented generation (query, index, search)

client

The underlying AI client instance.

workflow

WorkflowEngine for execution orchestration.

history

HistoryManager for history queries and export. history.memory exposes the Memory instance when memory is enabled (else None). history.search() performs semantic recall.

rag

RAG instance, or None if not configured.

persist_dir

Directory for history persistence files.

persist_name

Filename stem for persisted files.

auto_persist

Whether histories auto-persist after each call.

Parameters:

  • client (FFAIClientBase) – AI client to wrap.

  • persist_dir (str | None) – Directory for history persistence files.

  • persist_name (str | None) – Filename stem for persisted files.

  • auto_persist (bool) – Whether to auto-persist histories after each call.

  • shared_prompt_attr_history (list[dict[str, Any]] | None) – Optional shared prompt-attr list.

  • history_lock (threading.Lock | None) – Optional thread lock for history access.

  • rag (RAG | None) – Optional pre-constructed RAG instance.

  • memory_enabled (bool | None) – Override config.memory.enabled. None falls through to config (default False).

  • memory_embeddings (str | None) – Override config.memory.embedding_model. None falls through to config; triggers the resolution ladder if config is also None.

  • memory_persist (bool | None) – Override config.memory.persist. None falls through to config (default False).

  • memory (Memory | None)

property rag: RAG | None

RAG instance for retrieval-augmented generation.

Setting this property automatically wires the current client as the RAG’s default generate_fn via ClientAdapter.

set_client(client)[source]

Switch to a different AI client.

Parameters:

client (FFAIClientBase)

Return type:

None

get_system_instructions()[source]

Return the system instructions configured on the client, or None.

Return type:

str | None

clear_conversation()[source]

Clear conversation in client but retain history.

Return type:

None

get_client_conversation_history()[source]

Get the raw conversation history from the underlying client.

Return type:

list[dict[str, str]]

set_client_conversation_history(history)[source]

Set the raw conversation history in the underlying client.

Parameters:

history (list[dict[str, str]])

Return type:

bool

add_client_message(role, content, **kwargs)[source]

Add a single message to the client’s conversation history.

Parameters:
Return type:

bool

close()[source]

Release background resources.

Shuts down the memory embed thread pool if one is running. Safe to call multiple times. Call this at process teardown to avoid leaking daemon threads (e.g., in long-running services).

Return type:

None