# semantic-engine

> Guidelines and reference documentation for the Semantic Engine (SMQ to SQL, SQL to SMQ, Parser, Composer, Model Manager).

- Author: sttking
- Repository: sttking/educate_page
- Version: 20260130165115
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/sttking/educate_page
- Web: https://mule.run/skillshub/@@sttking/educate_page~semantic-engine:20260130165115

---

---
name: semantic-engine
description: Guidelines and reference documentation for the Semantic Engine (SMQ to SQL, SQL to SMQ, Parser, Composer, Model Manager).
---

# Semantic Engine Development Skill

Use this skill when reading, modifying, or debugging the Semantic Engine code (located in `service/semantic` or `service/query`).
This includes SMQ (Semantic Model Query) parsing, composition (SMQ to SQL), and reverse transformation (SQL to SMQ).

## Critical Rules

### 1. Vendor Setup for SQLGlot
**Important**: When using `sqlglot` in this project, you **MUST** import `vendor_setup` at the very top of the file, before any other imports.
This ensures the custom vendored version of `sqlglot` is loaded correctly.

```python
import vendor_setup  # MUST be the first import
from sqlglot import exp
...
```

### 2. Server Management
After making changes, restart the server to test:

```bash
./stop.sh && ./run.sh
```

Run semantic tests against the running server:

```bash
./test/semantic/smq2sql_test.sh
```

## Module Documentation

The following documents provide detailed architectural and implementation rules for specific components:

- **[SMQ to SQL Pipeline](semantic-smq2sql.md)**: Overall implementation reference for converting SMQ to SQL.
- **[SMQ Parser](semantic-parser.md)**: Rules for parsing SMQ JSON into internal objects.
- **[Semantic Composer](semantic-composer.md)**: Detailed 14-step pipeline for composing SQL from SMQ objects.
- **[Semantic Model Manager](semantic-model-manager.md)**: Managing semantic models and their relationships.
- **[SQL to SMQ](query-sql-to-smq.md)**: Reverse engineering SQL back into SMQ format.

## Implementation Guidelines

- Follow the 14-step pipeline in `Semantic Composer` when modifying SQL generation logic.
- Ensure all physical table references are abstracted through the Semantic Manifest.
- Use `sqlglot` for all SQL parsing and generation tasks.