Consumer Guide

ConvEngine consumer integration is about wiring three things correctly:

• framework bootstrapping (@EnableConvEngine)
• LLM adapter (LlmClient)
• DB-driven behavior (ce_* control-plane rows)

10-Minute Starter

1

Enable framework

Use @EnableConvEngine on your Spring Boot entry point.

2

Provide LlmClient

Register a concrete LlmClient bean for intent/schema/derived flows.

3

Apply ce_* schema

Apply DDL and seed minimum rows in ce_intent, ce_intent_classifier, ce_response, ce_prompt_template.

4

Validate with audit trace

Run a real turn and validate with /api/v1/conversation/audit/{conversationId} and /api/v1/conversation/audit/{conversationId}/trace.

Dependency

Maven

pom.xml dependency

package: project build

XML

<dependency>
  <groupId>com.github.salilvnair</groupId>
  <artifactId>convengine</artifactId>
  <version>1.0.15</version>
</dependency>

Gradle

build.gradle.kts dependency

package: project build

KOTLIN

implementation("com.github.salilvnair:convengine:1.0.15")

Core Contracts

Consumer-side contracts

Contract	Why it matters	Where it plugs in
@EnableConvEngine	Bootstraps engine + pipeline + transport wiring	Spring Boot application class
LlmClient	Provides text/json generation backend	Consumer config bean
ce_* tables	Defines behavior as data, not hardcoded Java	Consumer database
EngineStepHook	Allows pre/post step intervention	Consumer extension bean
ResponseTransformer	Last-mile payload normalization	Consumer extension bean

Bootstrapping

Spring Boot entry point

package: com.zapper.demofile: src/main/java/com/acme/demo/DemoApplication.java

JAVA

@SpringBootApplication
@EnableConvEngine(stream = true)
public class DemoApplication {
  public static void main(String[] args) {
    SpringApplication.run(DemoApplication.class, args);
  }
}

LlmClient bean

package: com.zapper.demo.configfile: src/main/java/com/acme/demo/config/LlmConfig.java

JAVA

@Configuration
public class LlmConfig {
  @Bean
  public LlmClient llmClient(OpenAiClient openAiClient) {
    return new OpenAiLlmClient(openAiClient);
  }
}

Minimum Seed SQL

Minimum FAQ seed (consumer DB)

SQL

insert into ce_intent(intent_code, enabled)
values ('FAQ', true);

insert into ce_intent_classifier(intent_code, match_pattern, priority, enabled)
values ('FAQ', '(?i).*(office|location|address).*', 10, true);

insert into ce_response(intent_code, state_code, response_type, output_format, exact_text, enabled)
values ('FAQ', null, 'EXACT', 'TEXT', 'Yes. You can request relocation from the support portal.', true);

insert into ce_prompt_template(intent_code, state_code, response_type, system_prompt, user_prompt, enabled)
values (
'FAQ',
null,
'TEXT',
'You are a support assistant. Keep answers concise and clear.',
'User asked: {{user_input}}. Answer as FAQ in 1-2 lines.',
true
);

Intervention Points

EngineStepHook (typed step matching)

package: com.zapper.demo.hooksfile: src/main/java/com/acme/demo/hooks/SchemaHintHook.java

JAVA

@Component
public class SchemaHintHook implements EngineStepHook {
  @Override
  public boolean supports(EngineStep.Name stepName, EngineSession session) {
    return EngineStep.Name.SchemaExtractionStep == stepName
    && "DISCONNECT_ELECTRICITY".equalsIgnoreCase(session.getIntent());
  }

  @Override
  public void beforeStep(EngineStep.Name stepName, EngineSession session) {
    session.putInputParam("consumer_hint", "compact");
  }
}

ResponseTransformer (last-mile output shaping)

package: com.zapper.demo.transformfile: src/main/java/com/acme/demo/transform/ApiResponseTransformer.java

JAVA

@Component
public class ApiResponseTransformer implements ResponseTransformer {
  @Override
  public EngineResult transform(EngineResult result, EngineSession session) {
    // Example: add consumer-side envelope metadata
    return result.withMeta(Map.of("conversationId", session.getConversationId()));
  }
}

Rollout Plan

Recommended rollout path

Phase	Scope	Exit criteria
Phase A	EXACT responses + deterministic rules	No unresolved intent collisions in audit
Phase B	Schema extraction + clarification flow	Missing-field loop converges in <= 2 turns
Phase C	MCP + DERIVED output	Stable tool-call traces and bounded token usage

Do not skip audit validation

Treat ce_audit as mandatory observability. Promote behavior changes only after reviewing multi-turn traces for each key intent.