Metadata-Version: 2.4
Name: hex-sl-utils
Version: 0.1.0
Summary: Reusable models and utilities for Hex semantic-layer resources
License-Expression: Apache-2.0
License-File: LICENSE
License-File: VENDORED_LICENSES
Requires-Dist: eval-type-backport>=0.2.2 ; python_full_version < '3.10'
Requires-Dist: pydantic>=2.10
Requires-Dist: rapidyaml>=0.15.2,<0.16
Requires-Dist: typing-extensions>=4.12
Requires-Python: >=3.9
Project-URL: changelog, https://github.com/hex-inc/hex-sl-utils/blob/main/packages/hex-sl-utils/CHANGELOG.md
Project-URL: repository, https://github.com/hex-inc/hex-sl-utils
Description-Content-Type: text/markdown

# 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:

```bash
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:

```python
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:

```python
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:

```python
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:

```python
from hex_sl_utils.schema import resource_json_schema

schema = resource_json_schema()
```

Repository development instructions are in the workspace
[`CONTRIBUTING.md`](../../CONTRIBUTING.md).

Licensed under the [Apache License 2.0](../../LICENSE).
