miniml/.eval/dossier.md

A minimal, embeddable semantic data modeling language for generating SQL queries from YAML model definitions. Inspired by LookML.

# DOSSIER: MiniML (dtempx/miniml)

## What it is
MiniML is a minimal, embeddable semantic-layer library in TypeScript that compiles YAML model definitions (dimensions, measures, joins, date logic) into SQL for BigQuery and Snowflake. Explicit positioning: the safety/vocabulary layer for AI-powered conversational analytics ("chat with your data" / text-to-SQL) — instead of letting an LLM write arbitrary SQL, the LLM picks from a model-defined vocabulary and MiniML generates the SQL. Inspired by LookML. Published on npm as `miniml` v1.0.17, MIT licensed, author Dave Templin (dtempx). Repo: https://github.com/dtempx/miniml

## Who it's for
Developers embedding analytics into AI agents/apps who want a lightweight, zero-infrastructure alternative to heavyweight semantic layers (Cube, dbt MetricFlow, Looker, Snowflake Cortex Analyst). The author works at Wayvia and appears to dogfood it there (Snowflake-based conversational analytics) — likely production use by its own author. [MEASURED from repo/context; dogfooding is inference]

## Tech stack & dependencies
TypeScript (ESNext, ES modules), Node. Runtime deps: `yaml`, `nunjucks` (Jinja templating for model info), `node-sql-parser` (AST-based SQL injection validation), `he`, `word-wrap`, `cli-options`. Dev: mocha/chai. CLI binary (`miniml`) + programmatic API (`loadModel`, `renderQuery`). License: MIT, clean. Copyright 2025 Dave Templin.

## Vital signs [MEASURED]
- **Age/cadence**: First commit 2025-06-09. 25 commits total. Active Jun–Aug 2025 (17 commits), then **~9-month dormancy**, revived Jun–Jul 2026 (8 commits, mostly README/docs/keywords — i.e., recent effort is marketing, not features).
- **Size**: ~1,040 LOC of source TS in `lib/` + ~880 LOC of tests. Small, readable.
- **Tests**: 68 mocha tests, all passing in ~111ms. Heavily weighted toward SQL-injection/validation logic (`validation.test.ts` is the only test file). Query-generation correctness itself is lightly tested.
- **Docs**: Unusually complete 925-line README with quickstart, API reference, security model, honest fan-out warning, and an `alternatives.md` comparing dbt MetricFlow, Cube, Looker, Snowflake Cortex, Databricks.
- **Community**: No visible stars/forks/issues data in local clone; agents should check GitHub/npm downloads. No CONTRIBUTING.md, no CI config visible, no GitHub Actions.
- **Known defects**: TASKS.md openly lists 10 unresolved issues, several serious (date_granularity bugs, `date_from == date_to` returns no rows, non-TIMESTAMP date fields generate failing SQL, order_by on expression fields breaks).

## Completion estimate
Core pipeline works end-to-end (model → validated query → SQL, two dialects). Honest state: a working v1.x for its author's own use case, but the TASKS.md bug list, single test file, two-dialect limit, and absence of CI/CONTRIBUTING put a *generalized* production-grade v1.0 for strangers at roughly 60–70% complete; 2–4 focused engineering-months to close.

## Author's apparent intent
README keywords ("mcp", "model context protocol", "conversational-analytics", "text-to-sql") and the recent doc-heavy revival suggest the author is repositioning MiniML for the AI-agent wave and wants adoption, not just personal tooling. No MCP server actually exists in the repo yet — it's keyword aspiration. [MEASURED: keywords exist, no MCP code exists]

## Search phrases a stranger would use
1. "lightweight semantic layer for text-to-SQL"
2. "LookML alternative open source YAML"
3. "safe SQL generation for LLM agents"
4. "embeddable metrics layer node.js"
5. "MCP server semantic layer Snowflake BigQuery"

## Finding #1 caveats for all agents
The name "miniml" collides with MiniML the classic ML-language teaching dialect (typed lambda calculus) — searchability is a real question. npm package name is claimed; GitHub discoverability unverified.