Ariadne

Governed metrics for AI agents. Ariadne gives agents a reviewed source of truth for business metrics: definitions are compiled and queried by Ariadne, while business policies and caveats travel with the answer.

Raw text-to-SQL asks an agent to guess tables, joins, filters, and definitions. Ariadne separates those responsibilities into two layers:

• Semantic Layer (OSI): reviewed metric definitions, compiled to SQL and executed read-only by Ariadne.
• Context Layer (OKF): business policies, source caveats, and terminology that explain how to interpret a result.

Ariadne is a Python package with embedded DuckDB. Use it locally through the CLI, connect an agent through optional MCP, or add the separately distributed Ariadne Agent. A human remains responsible for source approval and for admitting the exact reviewed Git revision. Ariadne is not a BI dashboard or a high-concurrency metrics API.

Documentation

The documentation follows Diátaxis:

• Tutorial: create a project and reach a first governed query.
• How-to guides: complete specific tasks such as Git-backed authoring, private Docker MCP setup, or reading multiple S3 storages.
• Reference: look up CLI commands, data-source configuration, and migration mappings.
• Explanation: understand Ariadne's layers, governance gates, and authority boundaries.

The documentation index lists all guides and references for Ariadne 0.3.0.

Source development

Work on Ariadne itself happens from the package checkout, not inside a data project:

uv venv --python 3.14 .venv
uv pip install --python .venv/bin/python -e .
source .venv/bin/activate
# Optional MCP example (after creating and admitting a project; requires .[mcp]):
uv pip install --python .venv/bin/python -e '.[mcp]'
examples/retail-demo/mcp_client.py --project /path/to/admitted/retail-project

For a candidate-wheel check, run uv build, install dist/ariadne_data-*.whl into a fresh virtual environment, and follow the getting-started tutorial with the installed console scripts rather than the editable install.