hex-sl-utils

Typed models and loaders for Hex semantic-layer resources.

This package is in its initial development phase and is not yet published. Its APIs may change until the first stable release.

Features

• Pydantic models for semantic-layer projects, models, views, dimensions, measures, and relations.
• Project loading from YAML files with structured validation problems.
• Support for multiple SQL dialects.
• Generated JSON Schema and TypeScript declarations.

Installation

Once the package is published, install it with:

uv add hex-sl-utils

# or
python -m pip install hex-sl-utils

Python 3.9 or newer is required.

Usage

Load all .yml and .yaml resources beneath a project directory:

from hex_sl_utils.spec.load import load_project

loaded = load_project(
    project_dir="path/to/project",
    project_name="My project",
    dialect_name="duckdb",
)

for problem in loaded.problems:
    print(problem.to_str())

for model in loaded.project.models:
    print(model.id)

Converters and other callers that already hold file contents in memory can use the equivalent load_project_files entry point:

from hex_sl_utils.spec.load import load_project_files

loaded = load_project_files(
    files={"orders.yml": "id: orders\nbase_sql_table: analytics.orders\n"},
    project_name="My project",
    dialect_name="duckdb",
)

Models are also available directly from hex_sl_utils.spec.types for validation and generation:

from hex_sl_utils.spec.types import Model

model = Model.model_validate(
    {
        "id": "orders",
        "base_sql_table": "analytics.orders",
    }
)

The generated schema artifacts are included in the distribution and can be read without relying on a checkout path:

from hex_sl_utils.schema import resource_json_schema

schema = resource_json_schema()

Repository development instructions are in the workspace CONTRIBUTING.md.

Licensed under the Apache License 2.0.