datus-semantic-dosi

A Datus semantic adapter backed by Dosi, the native Rust OSI engine, with no MetricFlow dependency. It is a thin protocol translator: the OSI YAML is loaded, planned, compiled to dialect SQL, and executed entirely inside the Rust engine (via the dosi-engine pyo3 bindings); this package only maps the Datus semantic-adapter contract onto the engine's API and its structured errors onto SemanticValidationError.

service_type: dosi.

Install

The adapter declares the native engine as a normal dependency. One command installs both packages:

pip install datus-semantic-dosi

No separate dosi-engine installation is required.

For local source development, a release is not required. Install the native checkout first, then the adapter into the same environment:

uv pip install -e ../osi-engine/crates/dosi-py
uv pip install -e ./datus-semantic-dosi

Adjust the relative paths to the workspace root. The first command builds the Rust/PyO3 extension with maturin and keeps the Python package linked to the local checkout.

Configure

from datus_semantic_dosi.config import DosiConfig

DosiConfig(
    semantic_model_path="model.yaml",  # OSI model (.yaml/.yml/.json)
    db_config={"type": "sqlite", "uri": "orders.sqlite"},  # or duckdb
)

The adapter passes db_config to the Python engine entirely in memory. The Rust CLI and server retain connections-file discovery; the embedded Python surface does not read or write connection files.

SQLite is a storage connector rather than a SQL dialect: Dosi receives type: sqlite unchanged and executes DuckDB SQL against the file in read-only mode.

Authoring contract

datus_extension_authoring_spec_text() reads the dialect-neutral authoring contract from the active dosi-engine Python binding. The adapter keeps its vendored versioned specifications only as a compatibility fallback for older engine builds. datus_extension_authoring_spec_digest() exposes a stable prompt-cache key, while the datasource dialect remains a separate Agent input.

Use with Datus-agent

Install the adapter into the same virtualenv as datus-agent:

uv pip install datus-semantic-dosi

For local development before a registry release, install both checkouts with the editable commands above. Entry-point discovery requires an installed adapter distribution; PYTHONPATH alone is not sufficient.

Then wire it in agent.yml. The semantic_layer key must equal the service_type (dosi); Datus-agent fills db_config from the active datasource and semantic_models_path from subject/semantic_models/<datasource>/ automatically, so a model file dropped there needs no further config:

agent:
  services:
    datasources:
      mydb:
        type: duckdb
        uri: /abs/path/to/orders.db
    semantic_layer:
      dosi:                 # key MUST be the service_type
        # both optional; either overrides the auto-derived directory:
        # semantic_model_path: /abs/path/to/model.yaml   # explicit single file

Place OSI model files under <project>/subject/semantic_models/mydb/ (Datus's per-datasource convention). The adapter catalogs every top-level YAML/YML/JSON file, keeps one native engine per file, and routes each globally unique metric name to its owning model. Set semantic_model_path only when an authoring flow must pin the adapter to one explicit file. Launch with datus --datasource mydb; the ask_metrics node then drives list_metrics / query_metrics through this adapter.

Behavior notes

• attribute delegates to the native engine and returns the shared attribution contract with term_wise, mix_shift, factor_shapley, or a structured unsupported result.
• validate_semantic delegates to the engine's own validator (structure, references, metric compilation) — no separate ossie integration.
• get_dimensions(metric) projects the engine's metric-scoped dimension catalog unchanged: Dosi owns reachability, conformance, recommendation, and ordering. Every returned row is queryable; recommended=false is a discovery hint, not a permission check. The adapter uses compile-only planning only to add the supported grains for time dimensions.
• Ambiguous / unknown names surface as SemanticValidationException whose payload carries the engine's candidates; single-candidate fixes are turned into a concrete suggested_retry.
• Multiple model files are supported for discovery and single-model queries. Metric and semantic-model names must be unique within a datasource; one query cannot combine metrics owned by different files.
• Time granularity attaches only to time dimensions; supplying it with no time dimension raises a time_grain_required validation payload.
• Native time axis accepts metric_time plus time_granularity; a suffixed result column is an output/order key, not a query dimension.
• Window discovery exposes native structured-window metadata and rejects legacy grain_to_date, window_aggregation, period_over_period, and string window hints instead of silently executing the base aggregate.
• Engine instances and the metric routing catalog refresh when model files are added, removed, or changed.

Tests

Unit tests run against a fake binding (no native build needed): ci/run-unit-tests.sh datus-semantic-dosi. Integration tests (-m integration) need the real local or installed dosi-engine binding and the duckdb CLI used to seed the test fixture, and use the vendored tests/fixtures/orders/ copy.