Chapter 14: Context Graph, Ontology, and Semantic Layer

The Context Graph, Ontology Service, and Semantic Layer form the knowledge infrastructure of the MATIH platform, providing the semantic understanding that enables intelligent data discovery, agent reasoning capture, and business-aware query generation. This chapter covers three interconnected services: the Context Graph within the AI Service for knowledge graph construction and agent thinking traces, the Ontology Service for entity relationship management, and the Semantic Layer for business metric definitions powered by WrenAI.

What You Will Learn

By the end of this chapter, you will understand:

The Context Graph architecture including Dgraph-backed knowledge storage, agent thinking trace capture, and integration with the agent orchestrators
The Ontology Service built on Python/FastAPI for entity relationship management, GraphQL schema modeling, and semantic query support
The Semantic Layer built on Java/Spring Boot with WrenAI integration for business metric definitions, dimensions, facts, and semantic SQL generation
Knowledge graph construction from agent reasoning traces, entity extraction, and relationship discovery
Embedding generation including structural, trajectory, node2vec, similarity, and thinking embeddings
The Agent Thinking Service for capturing and querying agent reasoning patterns with tenant-scoped embeddings

Chapter Structure

Section	Description	Audience
Context Graph Architecture	Dgraph storage, tenant isolation, thinking models, and API surface	Knowledge engineers, backend developers
Ontology Service	Entity relationships, GraphQL schema, semantic queries	Data architects, knowledge engineers
Semantic Layer	WrenAI integration, business metrics, dimensions, facts	Data analysts, business analysts
Knowledge Graph Construction	Graph building from agent traces, entity extraction, sync	AI/ML engineers, knowledge engineers
Embedding Generation	Structural, trajectory, node2vec, similarity, model providers	AI/ML engineers
Agent Thinking Service	Thinking trace capture, reasoning analysis, pattern detection	AI/ML engineers
API Reference	Complete API documentation for all three services	All developers

Services Overview

The knowledge infrastructure comprises three services:

+---------------------------------------------------+
|                AI Service (Port 8000)              |
|                                                    |
|  +--------------------------------------------+   |
|  |           Context Graph Module              |   |
|  |                                              |  |
|  |  +------------------+  +------------------+  |  |
|  |  | Agent Thinking   |  | Orchestrator     |  |  |
|  |  | Service          |  | Hooks            |  |  |
|  |  +--------+---------+  +--------+---------+  |  |
|  |           |                      |            |  |
|  |  +--------v---------+  +--------v---------+  |  |
|  |  | Dgraph Context   |  | Metrics Bridge   |  |  |
|  |  | Store             |  |                  |  |  |
|  |  +--------+---------+  +--------+---------+  |  |
|  |           |                      |            |  |
|  |  +--------v----------------------v---------+  |  |
|  |  |         Embedding Services               |  |  |
|  |  | (structural, trajectory, thinking)       |  |  |
|  |  +------------------------------------------+  |  |
|  +--------------------------------------------+   |
+---------------------------------------------------+
         |                    |
         v                    v
+----------------+   +-------------------+
| Dgraph         |   | Qdrant / Pinecone |
| (Graph DB)     |   | (Vector Store)    |
+----------------+   +-------------------+

+---------------------------------------------------+
|          Ontology Service (Port 8101)              |
|  Entity relationships, GraphQL schema,             |
|  semantic queries                                  |
+---------------------------------------------------+
         |
         v
+----------------+
| Dgraph         |
| (Shared)       |
+----------------+

+---------------------------------------------------+
|          Semantic Layer (Port 8086)                |
|  WrenAI integration, business metrics,             |
|  dimensions, facts                                 |
+---------------------------------------------------+

Key Numbers

Service	Technology	Port	Storage
Context Graph	Python (within AI Service)	8000	Dgraph, Qdrant/Pinecone
Ontology Service	Python/FastAPI	8101	Dgraph
Semantic Layer	Java/Spring Boot	8086	PostgreSQL, WrenAI

Key Source Files

Context Graph (within AI Service)

Path	Purpose
`context_graph/services/agent_thinking_service.py`	`AgentThinkingCaptureService` for trace lifecycle
`context_graph/services/agent_trace_service.py`	Trace persistence and retrieval
`context_graph/storage/dgraph_context_store.py`	`DgraphContextStore` with tenant-isolated queries
`context_graph/embeddings/thinking_embeddings.py`	`ThinkingEmbeddingService` for trace embeddings
`context_graph/embeddings/structural.py`	`StructuralEmbedder` using Node2Vec
`context_graph/embeddings/trajectory.py`	Trajectory embeddings
`context_graph/embeddings/node2vec.py`	Node2Vec implementation
`context_graph/embeddings/similarity.py`	Similarity computation
`context_graph/embeddings/model_providers.py`	Embedding model abstraction
`context_graph/integration/orchestrator_hooks.py`	`ContextGraphOrchestratorHooks`
`context_graph/integration/metrics_bridge.py`	`MetricsBridge` for observability linkage
`context_graph/integration/kafka_producer.py`	Kafka event streaming
`context_graph/integration/kafka_consumer.py`	Kafka event consumption
`context_graph/security/authorization.py`	Graph access authorization
`context_graph/security/permissions.py`	Permission management
`context_graph/config/tenant_config.py`	Per-tenant configuration
`context_graph/causal/`	Causal chain analysis
`context_graph/simulation/`	Graph simulation

Ontology Service

Path	Purpose
`ontology-service/src/api/routes/`	API route definitions
`ontology-service/src/api/graphql/`	GraphQL schema and resolvers
`ontology-service/src/models/object_type.py`	Entity type definitions
`ontology-service/src/models/enums.py`	Enumeration types
`ontology-service/src/models/semantic/`	Semantic model definitions
`ontology-service/src/storage/`	Storage backends
`ontology-service/src/schema_mapping/`	Schema mapping
`ontology-service/src/templates/`	Ontology templates

Semantic Layer

Path	Purpose
`semantic-layer/src/`	Java/Spring Boot source
WrenAI integration	Business metric definitions

Integration Points

Source	Target	Protocol	Purpose
AI Service Orchestrator	Context Graph	In-process	Thinking trace capture
Context Graph	Dgraph	HTTP/GraphQL	Knowledge graph persistence
Context Graph	Qdrant/Pinecone	gRPC/HTTP	Embedding storage and search
Context Graph	Kafka	Kafka	Event streaming
Ontology Service	Dgraph	HTTP/GraphQL	Entity relationship storage
Semantic Layer	PostgreSQL	JDBC	Metric definitions
Semantic Layer	WrenAI	HTTP	Semantic SQL generation
AI Service	Ontology Service	HTTP	Entity resolution
AI Service	Semantic Layer	HTTP	Metric definitions for SQL

Serving Context Graph Architecture