AI-VideoAssistant/engine/docs/backend_integration.md

Backend Integration and History Bridge

This engine uses adapter-based backend integration so core runtime logic can run with or without an external backend service.

Runtime Modes

Configure with environment variables:

• BACKEND_MODE=auto|http|disabled
• BACKEND_URL
• BACKEND_TIMEOUT_SEC
• HISTORY_ENABLED=true|false

Mode behavior:

• auto: use HTTP backend adapter only when BACKEND_URL is set.
• http: force HTTP backend adapter (falls back to null adapter when URL is missing).
• disabled: force null adapter and run engine-only.

Architecture

• Ports: core/ports/backend.py
• Adapters: app/backend_adapters.py
• Compatibility wrappers: app/backend_client.py

Session and DuplexPipeline receive backend capabilities via injected adapter methods instead of hard-coding backend client imports.

Async History Writes

Session history persistence is handled by core/history_bridge.py.

Design:

• transcript writes are queued with put_nowait (non-blocking turn path)
• background worker drains queue
• failed writes retry with exponential backoff
• finalize waits briefly for queue drain before sending call finalize
• finalize is idempotent

Related settings:

• HISTORY_QUEUE_MAX_SIZE
• HISTORY_RETRY_MAX_ATTEMPTS
• HISTORY_RETRY_BACKOFF_SEC
• HISTORY_FINALIZE_DRAIN_TIMEOUT_SEC