Skip to main content
v2

Consumer Configuration

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

It reflects the active v2 line through the later additions from 2.0.0 to 2.0.9, including scoped MCP planner behavior, richer audit controls, ce_verbose, and the current Semantic Query configuration surface.

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.mcp.* (planner/tool behavior, guardrails, HTTP defaults, Semantic Query)
  • 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
      PENDING_ACTION: CE_PENDING_ACTION
      OUTPUT_SCHEMA: CE_OUTPUT_SCHEMA
      POLICY: CE_POLICY
      PROMPT_TEMPLATE: CE_PROMPT_TEMPLATE
      RESPONSE: CE_RESPONSE
      RULE: CE_RULE
      VERBOSE: CE_VERBOSE


    # Feature flags for experimental features
    experimental:
      enabled: false

    # Flow tuning
    flow:
      query-rewrite:
        enabled: true
      conversation-history:
        max-turns: 20
      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

    mcp:
      tool-max-loops: 5
      tool-call-delay-ms: 0
      tool-call-delay-after-calls: 4
      tool-call-delay-after-ms: 2000
      planner-max-observation-chars: 4000
      guardrail:
        enabled: false
        fail-closed: false
        allowed-next-by-current-tool: {}
      http-api:
        defaults:
          connect-timeout-ms: 2000
          read-timeout-ms: 5000
          max-attempts: 2
          initial-backoff-ms: 200
          max-backoff-ms: 2000
          backoff-multiplier: 2.0
          circuit-breaker-enabled: true
          circuit-failure-threshold: 5
          circuit-open-ms: 30000
          retry-status-codes: [429, 502, 503, 504]
          retry-on-io-exception: true
      db:
        query:
          mode: semantic
        sql-guardrail-table: ""
        introspect-tables: []
        semantic:
          enabled: false
          tool-code: db.semantic.query
          # DB-driven semantic model (no file-path model source)
          default-limit: 100
          max-limit: 500
          sql-dialect: postgres
          timezone: system timezone
          max-join-hops: 6
          max-tables: 10
          retrieval:
            max-entities: 3
            max-tables: 6
            min-entity-score: 0.35
            min-table-score: 0.30
            synonym-weight: 0.40
            field-weight: 0.25
            id-pattern-weight: 0.20
            lexical-weight: 0.15
            vector-blend-weight: 0.30
          vector:
            enabled: false
            feedback-enabled: true
            table: ce_semantic_concept_embedding
            namespace-column: namespace
            target-type-column: target_type
            target-name-column: target_name
            embedding-column: embedding
            metadata-column: metadata_json
            max-results: 20
          clarification:
            enabled: true
            confidence-threshold: 0.80
            retrieval-weight: 0.60
            join-weight: 0.40
            min-top-entity-gap: 0.12
            max-entity-options: 2

    # 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: []
      include-intents: []
      exclude-intents: []
      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

PropertyDefaultDescription
resoluteREGEX_THEN_LLMIntent resolution strategy (REGEX_ONLY, REGEX_THEN_LLM, LLM_ONLY)
llm-threshold0.90Confidence threshold for LLM intent classification via DialogueAct

convengine.flow.query-rewrite

PropertyDefaultDescription
enabledtrueAutomatically derives a standalone query from conversation history for contextual downstream RAG tool injection.

convengine.flow.conversation-history

PropertyDefaultDescription
maxTurns10Maximum number of conversation turns to retain in history before summarization.

convengine.flow.interaction-policy

PropertyDefaultDescription
execute-pending-on-affirmtrueAutomatically run pending action if user says yes
reject-pending-on-negatetrueCancel pending action if user says no
fill-pending-slot-on-non-new-requesttrueAssign input to a waiting required parameter slot
require-resolved-intent-and-statetrueEnforce 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

PropertyDefaultDescription
enabledtrueTracks how long pending actions remain valid
ttl-turns3Number of conversational turns a pending action survives before eviction
ttl-minutes30Wall-clock time bounds for pending action survival

convengine.flow.guardrail

PropertyDefaultDescription
enabledtrueGeneral guardrail functionality
sanitize-inputtrueBasic textual sanitization
require-approval-for-sensitive-actionsfalseIf true, high-privilege tool execution demands explicit user affirmation
approval-gate-fail-closedfalseIf true, guardrail rejections fail closed rather than degrading gracefully
sensitive-patterns[]Regex signatures for proactive redaction

convengine.flow.state-graph

PropertyDefaultDescription
enabledtrueTurn state transition validation on/off
soft-block-on-violationfalseAllow transition but mark warning if violating strict pathing
allowed-transitions{}Map defining hard-coded allowed path trajectories

convengine.flow.disambiguation

PropertyDefaultDescription
enabledtrueAllow engine to propose follow-ups when intent density intersects/collides
max-options5Clamp the number of disambiguation choices returned

convengine.flow.memory

PropertyDefaultDescription
enabledtrueEnables LLM-driven session summarization for long dialogues
summary-max-chars1200Maximum characters allowed in token context injection for memory
recent-turns-for-summary3Sliding window of interaction chunks prior to memory compression
2.0.9 routing note

ce_prompt_template.interaction_mode and interaction_contract are table-driven, but the surrounding convengine.flow.* settings determine whether the routing features around CorrectionStep, schema collection, and pending-action handling are active and how strict they behave.

Breakdown: Audit Configuration​

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

convengine.audit

PropertyDefaultDescription
enabledtrueRoot toggle for the audit framework
persist-metatrueAttach engine metadata to the payload (intent, state, emittedAt)
cache-inspectorfalseTakes full snapshots of the memory session tree on every cache step
levelALLLogging verbosity threshold (ALL, STANDARD, ERROR_ONLY, NONE)
include-stages[]Whitelist specific stages
exclude-stages[]Blacklist specific stages
include-intents[]Whitelist specific intents. If set, only matching intents emit audit events.
exclude-intents[]Blacklist specific intents. Matching intents emit no audit events at all.

convengine.audit.dispatch

PropertyDefaultDescription
async-enabledfalseMoves transport fan-out off the main request thread when true
worker-threads2Number of async audit dispatcher threads
queue-capacity2000Maximum queued events
rejection-policyCALLER_RUNSBackpressure handling when capacity exceeded (CALLER_RUNS, DROP_NEWEST, DROP_OLDEST, ABORT)
keep-alive-seconds60Metrics keep-alive window

convengine.audit.persistence

PropertyDefaultDescription
modeIMMEDIATEWrite style. IMMEDIATE writes row by row. DEFERRED_BULK buffers events and writes batch inserts (safer under load).
jdbc-batch-size200Row chunking factor for DB connection drivers
max-buffered-events5000Maximum heap objects maintained for bulk emission
flush-stagesENGINE_KNOWN_FAILURE, ENGINE_UNKNOWN_FAILUREImmediate force-flush triggers
final-step-namesPipelineEndGuardStepTrigger to signify request termination to commit remainder logs
flush-on-stop-outcometrueFlush early if a stage explicitly terminates the pipeline

convengine.audit.rate-limit

PropertyDefaultDescription
enabledfalseProtects DB from noisy event generation loop conditions
max-events200Cap on volume
window-ms1000Time interval (sliding)
per-conversationtrueBucket per conversation UUID
per-stagetrueBucket per discrete execution component logic
max-tracked-buckets20000Upper memory footprint limit for Token Bucket store

Breakdown: MCP Configuration​

convengine.mcp.* is much broader in the current v2 line than the older docs implied. It now covers next-tool guardrails, framework-managed HTTP behavior, and Semantic Query.

convengine.mcp.orchestration

PropertyDefaultDescription
tool-max-loops5Hard cap on iterative tool executions to prevent runaway LLM loops.
planner-max-observation-chars4000Truncates tool output observation characters.
tool-call-delay-after-calls4Triggers artificial delay after rapid successive tool invokes.
tool-call-delay-after-ms2000Duration of the artificial rate-limiting delay.

convengine.mcp.guardrail

PropertyDefaultDescription
enabledfalseTurns the MCP next-tool guardrail on or off.
fail-closedfalseIf true, missing allowed-next rules can block planner proposals.
allowed-next-by-current-tool{}Whitelists legal next tools by current tool code.

convengine.mcp.http-api.defaults

PropertyDefaultDescription
connect-timeout-ms2000Connect timeout for framework-managed HTTP tools.
read-timeout-ms5000Read timeout for framework-managed HTTP tools.
max-attempts2Automatic retry attempts for HTTP tools.
initial-backoff-ms200Starting backoff duration.
max-backoff-ms2000Maximum backoff cap.
backoff-multiplier2.0Exponential backoff progression factor.
circuit-breaker-enabledtrueEnables the in-memory circuit-breaker path.
circuit-failure-threshold5Failure threshold before opening the breaker.
circuit-open-ms30000Window used for breaker evaluation.
retry-status-codes[429, 502, 503, 504]Specific HTTP status codes that trigger a retry attempt.
retry-on-io-exceptiontrueTriggers a retry on network drops or connection timeouts.

convengine.mcp.db.semantic

PropertyDefaultDescription
enabledfalseEnables semantic tool chain (`db.semantic.interpret -> db.semantic.query -> postgres.query`).
tool-codedb.semantic.queryPrimary tool code used by semantic query stage.
semantic model sourceDB tables (`ce_semantic_*`)Semantic model is assembled from DB tables; no YAML file path required.
default-limit / max-limit100 / 500Default and max row limits for semantic queries.
sql-dialectpostgresDialect hint used during SQL generation.
timezonesystem timezoneDefault timezone used for time parsing.
max-join-hops / max-tables6 / 10Safety limits for SQL generation breadth.
`postgres.query` interceptor SPI

postgres.query execution now supports consumer-overridable interceptor beans (PostgresQueryInterceptor) that run before SQL guardrail + execution.
Framework default interceptor (DefaultPostgresQueryInterceptor, lowest precedence) auto-corrects invalid epoch conversion on timestamp/date columns (for example to_timestamp(ts_col/1000.0) when ts_col is already timestamp/date).
There is no config key for this SPI; override by providing your own interceptor bean with higher @Order.

PostgresQueryInterceptor consumer example
JAVA
@Component
@Order(10) // higher priority than framework fallback
public class TenantSqlInterceptor implements PostgresQueryInterceptor {

    @Override
    public boolean supports(CeMcpTool tool, EngineSession session, Map<String, Object> args) {
        return tool != null && "postgres.query".equalsIgnoreCase(tool.getToolCode());
    }

    @Override
    public String intercept(String sql, CeMcpTool tool, EngineSession session, Map<String, Object> args) {
        // Example: enforce fully-qualified schema or org SQL conventions
        if (sql == null) return null;
        return sql.replace(" FROM zp_", " FROM v2.zp_")
        .replace(" JOIN zp_", " JOIN v2.zp_");
    }
}

convengine.mcp.db.semantic.retrieval / vector / clarification

PropertyDefaultDescription
retrieval.max-entities / max-tables3 / 6Candidate cap for entity and table retrieval.
retrieval scoring weightssynonym/field/id-pattern/lexical/vector-blendControls retrieval ranking blend.
vector.enabledfalseEnable vector-assisted retrieval.
vector.feedback-enabledtrueAllow USER_QUERY feedback embeddings to boost retrieval.
vector.table / columnsce_semantic_concept_embedding + overridesEmbedding source table and column mapping.
clarification.enabledtrueEnable clarification follow-up loop.
clarification.confidence-threshold0.80Threshold below which clarification is asked.
clarification.min-top-entity-gap0.12If top entity scores are too close, clarification is asked.
clarification.max-entity-options2Maximum options shown in clarification question.

Breakdown: Transport Configuration​

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

convengine.transport.sse

PropertyDefaultDescription
enabledtrueRoot toggle for Server Sent Events protocol
emitter-timeout-ms1800000Maximum lifespan of an SSE connection (30 minutes default)

convengine.transport.stomp.broker

PropertyDefaultDescription
modeSIMPLESIMPLE operates an in-memory broker. RELAY interfaces with external STOMP brokers (e.g., RabbitMQ).
relay-destination-prefixes/topic, /queuePath segments bound to external relay dispatch
relay-hostlocalhostAddress of standard STOMP capable broker
relay-port61613Network port
system-heartbeat-send-interval-ms10000Broker heartbeat outgoing frequency
system-heartbeat-receive-interval-ms10000Broker heartbeat tolerance incoming frequency
Stream enablement note

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