orionbelt-semantic-layer

OrionBelt Semantic Layer provides an API-first engine that translates declarative YAML semantic models into optimized SQL across multiple dialects (Postgres, Snowflake, ClickHouse, Dremio, and Databricks). The MCP server exposes the same REST API that powers the web UI and client integrations, allowing you to load models, validate them, generate SQL, and visualize diagrams through sessions. You can run the API backend behind any orchestrator or schedule tasks to compile models on demand, enabling consistent, governance-friendly analytics workloads across your data stack.

To use it, start the API server via the MCP client. Once running, you interact with endpoints such as creating sessions, loading models into sessions, validating schemas, and requesting compiled SQL for a target dialect. The system supports per-session model stores, diagram generation (ER diagrams via API and Gradio UI), and dialect-aware validation to ensure syntax correctness before executing queries. The MCP layer simply delegates HTTP requests to the REST API, so you can deploy the server in a lightweight environment or inside a larger workflow platform (e.g., Prefect, Airflow, or a CI/CD pipeline).

Key capabilities include: model loading and validation, SQL compilation across dialects (Postgres, Snowflake, ClickHouse, Dremio, Databricks), ER diagram generation, and REST endpoints for session management. This makes OrionBelt straightforward to integrate into applications, AI assistants, or automation scripts that need semantic-model-driven analytics without embedding SQL logic directly in your codebase.

Prerequisites:

• Python 3.12+ (as required by the project)
• uv package manager (installable via your environment as shown below)

Installation steps:

1. Clone the repository: git clone https://github.com/ralfbecher/orionbelt-semantic-layer.git cd orionbelt-semantic-layer
2. Install and bootstrap using UV (the MCP approach used by this project):
   • Ensure uv is installed in your environment. If you don’t have it yet: python -m pip install uv
   • Synchronize/install dependencies and prepare the project for running the API: uv sync
3. Run the API server via MCP (as shown in the Quick Start): uv run orionbelt-api

Notes:

• The project is Python-based and ships a REST API. The MCP entry point delegates to this API via HTTP.
• If you’re using a containerized environment, you can adapt the uv commands to your orchestration system and expose port 8000 as the API endpoint.

Tips and common considerations:

• The API runs by default on http://127.0.0.1:8000/docs for Swagger and /redoc for API docs once started.
• Use per-session model stores to isolate models between different users or workflows.
• When deploying in production, consider securing the API with authentication and IP allowlists, and run behind a reverse proxy with TLS.
• If you modify YAML models, enable validation to catch schema errors early; the system reports line/column positions for easier debugging.
• The MCP layer can be used to integrate OrionBelt into automation tooling (e.g., Prefect Horizon) by spawning the API as a separate service and issuing HTTP requests to manage sessions and models.
• For multi-dialect SQL generation, ensure your target dialect is supported and pass the dialect name to the compile endpoint to receive dialect-specific SQL.