Building an AI‑Native Service: A Minimal Viable Semantic Service Walkthrough

From Ontology to Semantic Service

Using a "customer health and churn‑risk" scenario, a minimal runnable Semantic Service is built to turn ontology assets into queryable, executable, and traceable business capabilities.

Four Key Engineering Questions

How to manage and publish continuously changing business rules.

Where to draw the boundary between precise deterministic calculation and large‑model inference.

How to unify semantic assets scattered across databases, documents, and existing systems.

How to enforce pre‑conditions, permissions, idempotency, approval, and audit controls on actions initiated by an Agent.

The system must answer a single request such as "Why is a customer high‑risk and what actions can be taken?" The response includes a fact snapshot, precise score, rule hits, permitted and restricted actions, and an evidence reference.

Mapping Ontology Elements to Runtime Capabilities

Fact : customer, contract, activity data.

Metric : deterministic metric definitions and calculations.

Logic : business rules and SOP retrieval & inference.

Action : action contracts, pre‑conditions, approvals, idempotency.

Evidence : audit trail for queries and actions.

Three‑Layer Implementation Strategy

Code layer : deterministic numeric calculations, data validation, action pre‑conditions, permission checks, idempotency – guarantees the same result for the same input and version.

Knowledge‑base layer : rules stored as structured Markdown, version‑controlled, searchable, with a gated publishing workflow.

LLM layer : consumes sanitized facts and published knowledge to match rules and generate explanations. The LLM can explain scores and rule matches but never overwrites code‑generated numbers or authorizes actions.

Overall Five‑Layer Architecture

Consumer → Capability‑contract layer → Semantic‑orchestration layer → Domain‑capability layer → Infrastructure layer.

Orchestration Flow

ObjectService resolves the identifier and collects authoritative facts.

MetricService invokes MetricComputer for deterministic metric calculation.

KnowledgeService retrieves relevant rules and SOP context.

LlmReasoningService assembles the prompt, calls the LLM, and validates rule hits and explanations.

LogicResult is assembled: metrics from code, rule hits and analysis from LLM.

ActionExecutor computes available actions under deterministic constraints.

EvidenceRecorder records the query evidence.

The unified SemanticContext is returned.

Domain Services Detail

ObjectService (Fact) : resolves a customer by ID, credit code, or name, merges customer, contract, and external metrics into a normalized Fact Map. Upstream services do not need to know the source system.

MetricService (Metric) : manages metric definitions and versions; MetricComputer registers calculators that operate on the Fact Map without accessing the database or LLM.

KnowledgeService (Logic) : manages rule documents, SOPs, versions, and indexes. Retrieval uses PostgreSQL full‑text search plus pgvector dual‑recall, fused with RRF ranking. Original documents are stored in object storage.

ActionExecutor (Action) : reads action contracts, validates pre‑conditions, approvals, cooldowns, performs idempotency checks, and invokes downstream services. LLM‑suggested actions are never authorized.

HybridRetrievalService and EvidenceRecorder are supporting components; the former serves Logic retrieval, the latter records the full query‑action chain.

Evidence Recording

EvidenceRecorder stores caller ID, fact snapshot, metric version, rule references, and action decisions, returning an evidence_ref. Query evidence and action logs are stored in separate tables for explanation/replay and audit/idempotency respectively.

Modular Monolith Deployment

The MVP is built as a modular monolith: orchestration and the four domain services run in the same Spring Boot 3.x process, communicating via module interfaces. Dependencies are one‑way (orchestration depends on domain interfaces; domains do not depend on each other). Modules can be split into independent services only when load, security isolation, or team boundaries demand.

Three‑Layer Collaboration Boundaries

Code layer guarantees deterministic values; LLM layer provides rule matches and textual analysis; hybrid mode combines both, with LLM operating in advisory‑only mode—its suggested actions are never executed.

Why Not Build a Full Rule Engine First

Rule engines excel when rule count is high, conditions are stable, and throughput/determinism are critical. In the MVP stage, rules are still being calibrated; a "document‑rule + retrieval + LLM" approach offers faster iteration and natural explanations, at the cost of higher latency and non‑deterministic matching. Once rules stabilize, migration to Drools, DMN, or a dedicated decision service is recommended.

Semantic Query Orchestration Code

SemanticContext query(String identifier, Mode mode, Caller caller) {
    // 1. Resolve object and collect authoritative facts
    Customer customer = objectService.resolve(identifier);
    FactMap fact = objectService.collectFacts(customer);
    // 2. Deterministic metric calculation
    MetricResult metric = mode == Mode.LLM ? MetricResult.empty()
        : metricService.compute("customer_health_score", fact);
    // 3. Retrieve business knowledge and perform semantic reasoning
    ReasoningResult reasoning = mode == Mode.COMPUTE ? ReasoningResult.empty()
        : llmReasoning.reason(fact, metric,
            knowledgeService.retrieve("customer_health_assessment", fact, metric));
    // 4. Assemble LogicResult
    LogicResult logic = LogicResult.builder()
        .metrics(metric)
        .riskLevel(reasoning.riskLevel())
        .ruleHits(reasoning.ruleHits())
        .analysisSummary(reasoning.summary())
        .build();
    // 5. Compute available actions under deterministic constraints
    AvailableActions actions = mode == Mode.LLM
        ? AvailableActions.advisoryOnly()
        : actionExecutor.computeAvailable(customer.id(), fact, metric, caller);
    // 6. Persist query evidence
    Evidence evidence = evidenceRecorder.recordQuery(
        customer, fact, metric, reasoning, actions, caller);
    // 7. Return unified semantic context
    return SemanticContext.builder()
        .customer(customer).fact(fact).logic(logic)
        .actions(actions).evidenceRef(evidence.ref()).build();
}

Core Data Model (Key Tables)

sem_customer / sem_customer_contract

: unified customer and contract relationships. sem_action_contract / sem_action_log: action contracts and execution logs. sem_knowledge_base / sem_knowledge_document: knowledge base and document versioning. sem_document_chunk: text slices, keyword projections, and vectors. sem_metric_definition: metric catalog, business description, and calculator version mapping. sem_query_evidence: query input snapshot, asset versions, and decision results.

Each table has a clear authority: raw customer data from source systems, metric definitions from sem_metric_definition, and rules from published knowledge versions. Slices, keyword indexes, and vectors are reproducible projections and cannot modify the original definitions.

Exposed Tools

The MVP provides two stable tools: queryCustomerContext: fetches the semantic context for a customer. executeAction: performs a controlled action after all constraints are checked.

The MCP layer discovers tools, enforces schema constraints, and propagates caller identity; business rules and action constraints remain within the Semantic Service.

Technology Stack and Rationale

Language & Framework : Spring Boot 3.x – enterprise‑grade, mature ecosystem for transactions, integration, and long‑term maintenance.

Main Database : PostgreSQL – structured facts, JSONB, transactions, and audit in a single store.

Vector Retrieval : pgvector – co‑located with the main DB, reducing component count.

Keyword Retrieval : PostgreSQL pg_trgm / tsvector + GIN – handles Chinese phrases, business IDs, and proprietary terms within the same instance.

File Storage : PostgreSQL or existing S3/MinIO – reuses enterprise object storage, no new component.

LLM Integration : Spring AI + OpenAI‑compatible interface – unified chat and embedding client.

Agent Protocol : Spring AI MCP Server – exposes domain capabilities as tools.

Recommended Roll‑out Order

Define contracts: Fact Map, SemanticContext, error codes, and evidence fields.

Establish the deterministic path: integrate ObjectService and MetricService without LLM.

Implement knowledge governance: document versioning, ingestion, retrieval evaluation, and publishing gate.

Introduce hybrid reasoning: let the LLM match retrieved rules, generate explanations, and test degradation strategies.

Open actions gradually: first return permitted actions, then enable low‑risk writes with approval, idempotency, and audit.

Each step can be independently accepted. After the first three steps the system can reliably answer "what happened, what is the metric, and why"; the last two steps add explanation and controlled execution.

Evolution Path

Metadata & lineage: OpenMetadata, DataHub.

Rule engine: Drools, DMN (once rules stabilize).

Search engine: Elasticsearch / OpenSearch for advanced ranking.

Vector DB: Milvus, Qdrant for large‑scale approximate search.

Workflow engine: Temporal for long‑running transactions.

Knowledge extraction: ontology extraction, knowledge graphs, RAG pipelines.

Component replacement should be driven by metrics, not pre‑emptive decisions. Stable contracts ( SemanticContext, domain service contracts, action contracts, and evidence_ref) remain unchanged across evolutions.

Conclusion

Ontology captures semantic assets; Semantic Service turns them into callable, traceable business capabilities. Facts come from trusted data sources, metrics from deterministic code, logic from governed rules, actions from server‑side contracts, and evidence guarantees end‑to‑end traceability. LLMs contribute only to rule understanding, semantic matching, and result explanation—they never become the final authority for facts, metrics, or permissions. Maintaining a stable SemanticContext, domain contracts, action contracts, and evidence chain enables the system to evolve from an MVP monolith to a robust, production‑grade business infrastructure.