Skip to main content
v2

Data Model

ConvEngine relies entirely on configuration over code. State, relationships, and execution boundaries are encoded in the schema.

Control-plane tables​

  • ce_config
  • ce_container_config
  • ce_intent
  • ce_intent_classifier
  • ce_output_schema
  • ce_prompt_template
  • ce_response
  • ce_rule
  • ce_policy
  • ce_mcp_tool
  • ce_mcp_db_tool
  • ce_mcp_planner
  • ce_pending_action
  • ce_verbose

Runtime tables​

  • ce_conversation
  • ce_audit
  • ce_conversation_history
  • ce_llm_call_log

ce_conversation_history​

Introduced to store chronological multi-turn array states strictly decoupled from internal ce_audit tracking.

Key columns:

  • history_id
  • conversation_id
  • user_input
  • assistant_output
  • created_at
  • modified_at

ce_pending_action​

Introduced for confirm-before-run logic and unambiguous multi-action resolution.

Purpose:

  • declarative catalog for executable pending actions by intent/state/action key

Key columns:

  • pending_action_id
  • intent_code
  • state_code
  • action_key
  • bean_name
  • method_names
  • priority
  • enabled
  • description
  • created_at

Lookup index:

  • (enabled, action_key, intent_code, state_code, priority)

Important:

  • runtime status (OPEN/IN_PROGRESS/EXECUTED/REJECTED/EXPIRED) is not stored in this table
  • runtime status is stored in context.pending_action_runtime

ce_verbose​

Introduced in 2.0.8 for deterministic runtime progress/error messages emitted by the Java pipeline. In 2.0.9, the same resolver path can also be triggered from consumer code through ConvEngineVerboseAdapter.

Purpose:

  • declarative message mapping by runtime context (intent/state/step/determinant/rule/tool)

Key columns:

  • verbose_id
  • intent_code
  • state_code
  • step_match (EXACT|REGEX|JSON_PATH)
  • step_value
  • determinant
  • rule_id (optional)
  • tool_code (optional)
  • message
  • error_message
  • priority
  • enabled
  • created_at

Lookup index:

  • (enabled, intent_code, state_code, determinant, step_match, step_value, rule_id, tool_code, priority)

ce_prompt_template​

ce_prompt_template is used for both schema extraction prompts and derived response generation.

Key columns:

  • template_id
  • intent_code
  • state_code
  • response_type
  • system_prompt
  • user_prompt
  • temperature
  • interaction_mode
  • interaction_contract
  • enabled
  • created_at

Runtime notes:

  • prompts are rendered through the shared ThymeleafTemplateRenderer
  • legacy {{...}} placeholders still work, but Thymeleaf expressions are the native path
  • common runtime vars include user_input, resolved_user_input, standalone_query, intent, state, context, and inputParams
  • see Thymeleaf and SpEL for expression examples across prompts and ce_verbose

interaction_mode is the coarse semantic contract for the turn. Supported values:

  • NORMAL
  • IDLE
  • COLLECT
  • CONFIRM
  • PROCESSING
  • FINAL
  • ERROR
  • DISAMBIGUATE
  • FOLLOW_UP
  • PENDING_ACTION
  • REVIEW

interaction_contract is extensible JSON text for concrete capabilities and expectations. Recommended shape:

{"allows":["affirm","edit","retry","reset"],"expects":["structured_input"]}

Current conventions:

  • allows: turn capabilities such as affirm, edit, retry, reset
  • expects: input expectations such as structured_input

Design note:

  • prefer extending interaction_contract arrays for new capabilities instead of adding new columns
  • use interaction_mode for broad semantics and interaction_contract for fine-grained runtime behavior

Rule phase compatibility​

ce_rule.phase includes phases:

  • POST_DIALOGUE_ACT
  • PRE_RESPONSE_RESOLUTION
  • POST_AGENT_INTENT
  • POST_SCHEMA_EXTRACTION
  • PRE_AGENT_MCP
  • POST_AGENT_MCP
  • POST_TOOL_EXECUTION

Rule action compatibility​

ce_rule.action includes:

  • SET_INTENT
  • SET_STATE
  • SET_DIALOGUE_ACT
  • SET_JSON
  • GET_CONTEXT
  • GET_SCHEMA_JSON
  • GET_SESSION
  • SET_TASK
  • SET_INPUT_PARAM

SET_INPUT_PARAM is the lightweight runtime-flag action. Use it for values like:

  • awaiting_confirmation=true
  • confirmation_key=LOAN_APPLICATION_CONFIRM
  • skip_schema_extraction=true
  • routing_decision=PROCEED_CONFIRMED

SET_DIALOGUE_ACT is the lightweight post-classification override action. Use it when a POST_DIALOGUE_ACT rule should replace the final dialogue_act with a more appropriate normalized value (for example promoting a guarded NEW_REQUEST back to EDIT).

Tool-group compatibility​

ce_mcp_tool.tool_group normalizes to:

  • DB
  • HTTP_API
  • WORKFLOW_ACTION
  • DOCUMENT_RETRIEVAL
  • CALCULATOR_TRANSFORM
  • NOTIFICATION
  • FILES

MCP tool scope columns​

ce_mcp_tool also supports optional scope columns:

  • intent_code (nullable)
  • state_code (nullable)

Behavior:

  • if both are NULL, the tool is globally eligible
  • if set, tool eligibility is constrained to matching runtime session.intent and session.state
  • non-matching scoped tools are skipped from MCP planning/execution

MCP planner scope columns​

ce_mcp_planner supports scoped planner prompts:

  • intent_code (nullable)
  • state_code (nullable)
  • system_prompt
  • user_prompt
  • enabled

Behavior:

  • exact intent/state row wins
  • intent-only row is next
  • global default row (NULL/NULL) is fallback
  • if not found, planner uses legacy ce_config prompts