Consumer Configuration

This guide covers the core tunable properties available for ConvEngine consumers. Properties are managed via Spring Boot @ConfigurationProperties and can be set in your application.yml or application.properties.

Core namespaces

ConvEngine introduces several configuration namespaces:

convengine.flow.* (runtime behavior tuning)
convengine.audit.* (event and tracking controls)
convengine.transport.* (SSE/STOMP delivery settings)
convengine.tables.* (dynamic table mapping overrides)
convengine.experimental.* (forward-looking toggles)

Complete `application.yml` Reference

Below is a complete reference of the default configuration options exposed by ConvEngine.

Complete application.yml reference

YAML

convengine:
  # Dynamic table mapping for CE_* entities (same as V1)
  tables:
    AUDIT: CE_AUDIT
    CONFIG: CE_CONFIG
    CONTAINER_CONFIG: CE_CONTAINER_CONFIG
    CONVERSATION: CE_CONVERSATION
    INTENT: CE_INTENT
    INTENT_CLASSIFIER: CE_INTENT_CLASSIFIER
    LLM_CALL_LOG: CE_LLM_CALL_LOG
    MCP_DB_TOOL: CE_MCP_DB_TOOL
    MCP_PLANNER: CE_MCP_PLANNER
    MCP_TOOL: CE_MCP_TOOL
    OUTPUT_SCHEMA: CE_OUTPUT_SCHEMA
    POLICY: CE_POLICY
    PROMPT_TEMPLATE: CE_PROMPT_TEMPLATE
    RESPONSE: CE_RESPONSE
    RULE: CE_RULE


  # Feature flags for experimental features
  experimental:
    enabled: false

  # Flow tuning
  flow:
    query-rewrite:
      enabled: true
    conversation-history:
      max-turns: 10
    dialogue-act:
      resolute: REGEX_THEN_LLM # REGEX_ONLY | REGEX_THEN_LLM | LLM_ONLY
      llm-threshold: 0.90
    interaction-policy:
      execute-pending-on-affirm: true
      reject-pending-on-negate: true
      fill-pending-slot-on-non-new-request: true
      require-resolved-intent-and-state: true
      matrix:
        "PENDING_ACTION:AFFIRM": EXECUTE_PENDING_ACTION
        "PENDING_ACTION:NEGATE": REJECT_PENDING_ACTION
        "PENDING_SLOT:EDIT": FILL_PENDING_SLOT
        "PENDING_SLOT:QUESTION": FILL_PENDING_SLOT
        "PENDING_SLOT:NEGATE": FILL_PENDING_SLOT
        "PENDING_SLOT:AFFIRM": FILL_PENDING_SLOT
    action-lifecycle:
      enabled: true
      ttl-turns: 3
      ttl-minutes: 30
    tool-orchestration:
      enabled: true
    guardrail:
      enabled: true
      sanitize-input: true
      require-approval-for-sensitive-actions: false
      approval-gate-fail-closed: false
      sensitive-patterns: []
    state-graph:
      enabled: true
      soft-block-on-violation: false
      allowed-transitions: {}
    disambiguation:
      enabled: true
      max-options: 5
    memory:
      enabled: true
      summary-max-chars: 1200
      recent-turns-for-summary: 3

  # Transport mechanisms
  transport:
    sse:
      enabled: true
      emitter-timeout-ms: 1800000
    stomp:
      enabled: false
      endpoint: /ws-convengine
      app-destination-prefix: /app
      topic-prefix: /topic
      audit-destination-base: /topic/convengine/audit
      allowed-origin-pattern: "*"
      sock-js: true
      broker:
        mode: SIMPLE   # SIMPLE | RELAY
        relay-destination-prefixes: /topic,/queue
        relay-host: localhost
        relay-port: 61613
        client-login: ""
        client-passcode: ""
        system-login: ""
        system-passcode: ""
        virtual-host: ""
        system-heartbeat-send-interval-ms: 10000
        system-heartbeat-receive-interval-ms: 10000

  # Auditing controls
  audit:
    enabled: true
    persist-meta: true
    cache-inspector: false
    level: ALL          # ALL | STANDARD | ERROR_ONLY | NONE
    include-stages: []
    exclude-stages: []
    persistence:
      mode: IMMEDIATE   # IMMEDIATE | DEFERRED_BULK
      jdbc-batch-size: 200
      max-buffered-events: 5000
      flush-stages: ENGINE_KNOWN_FAILURE,ENGINE_UNKNOWN_FAILURE
      final-step-names: PipelineEndGuardStep
      flush-on-stop-outcome: true
    dispatch:
      async-enabled: false
      worker-threads: 2
      queue-capacity: 2000
      rejection-policy: CALLER_RUNS  # CALLER_RUNS | DROP_NEWEST | DROP_OLDEST | ABORT
      keep-alive-seconds: 60
    rate-limit:
      enabled: false
      max-events: 200
      window-ms: 1000
      per-conversation: true
      per-stage: true
      max-tracked-buckets: 20000

Breakdown: Flow Configuration

The convengine.flow.* properties control the nuanced routing behavior without requiring consumer-side hardcoded Java branching for common dialogue/action patterns.

convengine.flow.dialogue-act

Property	Default	Description
resolute	REGEX_THEN_LLM	Intent resolution strategy (REGEX_ONLY, REGEX_THEN_LLM, LLM_ONLY)
llm-threshold	0.90	Confidence threshold for LLM intent classification via DialogueAct

convengine.flow.query-rewrite

Property	Default	Description
enabled	true	Automatically derives a standalone query from conversation history for contextual downstream RAG tool injection.

convengine.flow.conversation-history

Property	Default	Description
maxTurns	10	Maximum number of conversation turns to retain in history before summarization.

convengine.flow.interaction-policy

Property	Default	Description
execute-pending-on-affirm	true	Automatically run pending action if user says yes
reject-pending-on-negate	true	Cancel pending action if user says no
fill-pending-slot-on-non-new-request	true	Assign input to a waiting required parameter slot
require-resolved-intent-and-state	true	Enforce strict intent tracking
matrix	{...}	Configures the fallback resolution engine for dialogue act intent mapping to standard actions (e.g. PENDING_ACTION:AFFIRM -> EXECUTE_PENDING_ACTION)

convengine.flow.action-lifecycle

Property	Default	Description
enabled	true	Tracks how long pending actions remain valid
ttl-turns	3	Number of conversational turns a pending action survives before eviction
ttl-minutes	30	Wall-clock time bounds for pending action survival

convengine.flow.guardrail

Property	Default	Description
enabled	true	General guardrail functionality
sanitize-input	true	Basic textual sanitization
require-approval-for-sensitive-actions	false	If true, high-privilege tool execution demands explicit user affirmation
approval-gate-fail-closed	false	If true, guardrail rejections fail closed rather than degrading gracefully
sensitive-patterns	[]	Regex signatures for proactive redaction

convengine.flow.state-graph

Property	Default	Description
enabled	true	Turn state transition validation on/off
soft-block-on-violation	false	Allow transition but mark warning if violating strict pathing
allowed-transitions	{}	Map defining hard-coded allowed path trajectories

convengine.flow.disambiguation

Property	Default	Description
enabled	true	Allow engine to propose follow-ups when intent density intersects/collides
max-options	5	Clamp the number of disambiguation choices returned

convengine.flow.memory

Property	Default	Description
enabled	true	Enables LLM-driven session summarization for long dialogues
summary-max-chars	1200	Maximum characters allowed in token context injection for memory
recent-turns-for-summary	3	Sliding window of interaction chunks prior to memory compression

Breakdown: Audit Configuration

convengine.audit.* dictates how the system records telemetry and metric payloads down to the individual pipeline stage logic.

convengine.audit

Property	Default	Description
enabled	true	Root toggle for the audit framework
persist-meta	true	Attach engine metadata to the payload (intent, state, emittedAt)
cache-inspector	false	Takes full snapshots of the memory session tree on every cache step
level	ALL	Logging verbosity threshold (ALL, STANDARD, ERROR_ONLY, NONE)
include-stages	[]	Whitelist specific stages
exclude-stages	[]	Blacklist specific stages

convengine.audit.dispatch

Property	Default	Description
async-enabled	false	Moves transport fan-out off the main request thread when true
worker-threads	2	Number of async audit dispatcher threads
queue-capacity	2000	Maximum queued events
rejection-policy	CALLER_RUNS	Backpressure handling when capacity exceeded (CALLER_RUNS, DROP_NEWEST, DROP_OLDEST, ABORT)
keep-alive-seconds	60	Metrics keep-alive window

convengine.audit.persistence

Property	Default	Description
mode	IMMEDIATE	Write style. IMMEDIATE writes row by row. DEFERRED_BULK buffers events and writes batch inserts (safer under load).
jdbc-batch-size	200	Row chunking factor for DB connection drivers
max-buffered-events	5000	Maximum heap objects maintained for bulk emission
flush-stages	ENGINE_KNOWN_FAILURE, ENGINE_UNKNOWN_FAILURE	Immediate force-flush triggers
final-step-names	PipelineEndGuardStep	Trigger to signify request termination to commit remainder logs
flush-on-stop-outcome	true	Flush early if a stage explicitly terminates the pipeline

convengine.audit.rate-limit

Property	Default	Description
enabled	false	Protects DB from noisy event generation loop conditions
max-events	200	Cap on volume
window-ms	1000	Time interval (sliding)
per-conversation	true	Bucket per conversation UUID
per-stage	true	Bucket per discrete execution component logic
max-tracked-buckets	20000	Upper memory footprint limit for Token Bucket store

Breakdown: Transport Configuration

convengine.transport.* applies to interactive async communication paths like Server Sent Events (SSE) or WebSockets via STOMP.

convengine.transport.stomp.broker

Property	Default	Description
mode	SIMPLE	SIMPLE operates an in-memory broker. RELAY interfaces with external STOMP brokers (e.g., RabbitMQ).
relay-destination-prefixes	/topic, /queue	Path segments bound to external relay dispatch
relay-host	localhost	Address of standard STOMP capable broker
relay-port	61613	Network port
system-heartbeat-send-interval-ms	10000	Broker heartbeat outgoing frequency
system-heartbeat-receive-interval-ms	10000	Broker heartbeat tolerance incoming frequency

Stream enablement note

Some transport handlers may also be gated by @EnableConvEngine(stream = true) in your main application class.

Runtime DB Behavior (Deep Dive Links)

ce_verbose: Verbose and Conversation Runtime
ce_conversation: Verbose and Conversation Runtime
session reset/continuity behavior: Session, Reset, Continuity

Core namespaces​

Complete application.yml Reference​

Breakdown: Flow Configuration​