Merge origin/main into nicosuave/yardstick-parity

Author: nicosuave

.dockerignore

@@ -0,0 +1,26 @@
+.git
+.github
+.venv
+.mypy_cache
+.pytest_cache
+.ruff_cache
+__pycache__
+*.egg-info
+*.pyc
+
+# Rust/DuckDB extension builds (not needed for Python image)
+sidemantic-rs/
+sidemantic-duckdb/
+
+# Docs and examples not needed at runtime
+docs/
+examples/superset_demo/
+examples/rill_demo/
+examples/cube_demo/
+
+# Dev/test artifacts
+Dockerfile.test
+docker-compose.yml
+*.md
+!README.md
+.context/

.github/workflows/ci.yml

@@ -126,6 +126,8 @@ jobs:
 
       - name: Run cargo test
         run: cargo test
+        env:
+          RUST_MIN_STACK: 16777216
 
   duckdb-extension:
     name: DuckDB Extension

.github/workflows/docker.yml

@@ -0,0 +1,91 @@
+name: Docker
+
+on:
+  workflow_dispatch:
+  workflow_run:
+    workflows: ["Publish to PyPI"]
+    types: [completed]
+
+env:
+  IMAGE: sidequery/sidemantic
+
+jobs:
+  docker:
+    name: Docker build, test, and push
+    runs-on: ubuntu-latest
+    if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: main
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Extract version
+        id: version
+        run: |
+          VERSION=$(grep '^version = ' pyproject.toml | sed 's/version = "\(.*\)"/\1/')
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Version: $VERSION"
+
+      - name: Build image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          load: true
+          tags: ${{ env.IMAGE }}:test
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Start server (demo mode)
+        run: |
+          docker run -d --name sidemantic-test -p 5433:5433 ${{ env.IMAGE }}:test --demo
+          for i in $(seq 1 30); do
+            if docker logs sidemantic-test 2>&1 | grep -q "Listening on"; then
+              echo "Server ready"
+              break
+            fi
+            echo "Waiting for server... ($i/30)"
+            sleep 1
+          done
+
+      - name: Verify server logs
+        run: docker logs sidemantic-test 2>&1
+
+      - name: Install psql
+        run: sudo apt-get update && sudo apt-get install -y postgresql-client
+
+      - name: Test connection
+        run: PGPASSWORD=any psql -h localhost -p 5433 -U any -d sidemantic -c "SELECT 1 AS test"
+
+      - name: Test metric aggregation (products)
+        run: |
+          PGPASSWORD=any psql -h localhost -p 5433 -U any -d sidemantic -c \
+            "SELECT category, product_count, avg_price, total_catalog_value FROM semantic_layer.products GROUP BY category ORDER BY category"
+
+      - name: Test metric aggregation (customers)
+        run: |
+          PGPASSWORD=any psql -h localhost -p 5433 -U any -d sidemantic -c \
+            "SELECT region, customer_count FROM semantic_layer.customers GROUP BY region ORDER BY region"
+
+      - name: Stop server
+        if: always()
+        run: docker stop sidemantic-test || true
+
+      - name: Push to Docker Hub
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: |
+            ${{ env.IMAGE }}:latest
+            ${{ env.IMAGE }}:${{ steps.version.outputs.version }}
+          cache-from: type=gha

Dockerfile

@@ -0,0 +1,41 @@
+FROM python:3.12-slim AS builder
+
+# Install build deps for riffq (Rust/maturin) and other native extensions
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    cmake \
+    pkg-config \
+    libssl-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+WORKDIR /app
+
+COPY pyproject.toml README.md LICENSE ./
+COPY sidemantic/ sidemantic/
+COPY examples/ examples/
+
+RUN uv pip install --system --no-cache ".[serve,mcp,all-databases]"
+
+# --- Runtime stage (no build tools) ---
+FROM python:3.12-slim
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+# Copy installed packages from builder
+COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
+COPY --from=builder /usr/local/bin/sidemantic /usr/local/bin/sidemantic
+
+WORKDIR /app
+
+COPY docker-entrypoint.sh /docker-entrypoint.sh
+RUN chmod +x /docker-entrypoint.sh
+
+RUN mkdir -p /app/models
+WORKDIR /app/models
+
+EXPOSE 5433
+
+ENTRYPOINT ["/docker-entrypoint.sh"]
+# Mode is controlled by SIDEMANTIC_MODE env var (serve, mcp, both)

README.md

@@ -1,19 +1,15 @@
 # Sidemantic
 
-SQL-first semantic layer for consistent metrics across your data stack. Compatible with many other semantic model formats.
+The universal metrics layer for consistent metrics across your data stack. Compatible with 15+ semantic model formats.
 
-- **Formats:** Sidemantic, Cube, MetricFlow (dbt), LookML, Hex, Rill, Superset, Omni, BSL, GoodData LDM, Snowflake Cortex, Malloy, OSI, AtScale SML, ThoughtSpot TML
-- **Databases:** DuckDB, MotherDuck, PostgreSQL, BigQuery, Snowflake, ClickHouse, Databricks, Spark SQL
+- **Supported Formats:** Sidemantic (YAML, Python or SQL), Cube, dbt MetricFlow, LookML, Hex, Rill, Superset, Omni, BSL, GoodData LDM, Snowflake Cortex, Malloy, OSI, AtScale SML, ThoughtSpot TML
+- **Databases:** DuckDB, MotherDuck, PostgreSQL, BigQuery, Snowflake, ClickHouse, Databricks, Spark SQL (also via ADBC)
 
-[Documentation](https://sidemantic.com) | [GitHub](https://github.com/sidequery/sidemantic) | [Discord](https://discord.com/invite/7MZ4UgSVvF) | [Demo](https://sidemantic.com/demo) (50+ MB download)
+[Documentation](https://sidemantic.com) | [GitHub](https://github.com/sidequery/sidemantic) | [Docker Hub](https://hub.docker.com/repository/docker/sidequery/sidemantic) | [Discord](https://discord.com/invite/7MZ4UgSVvF) | [Demo](https://sidemantic.com/demo) (50+ MB data download, runs in your browser with Pyodide + DuckDB)
 
 ![Jupyter Widget Preview](preview.png)
 
-## Should I use Sidemantic
-
-Sidemantic is a very ambitious and young semantic layer project. You may encounter rough patches, especially with the more exotic features like converting between semantic model formats.
-
-Issue reports are much appreciated if you try out Sidemantic and hit a snag 🫡
+The installer downloads the skill to `~/.agents/skills/sidemantic-modeler` and symlinks it into `~/.claude/skills/`.
 
 ## Quickstart
 
@@ -252,6 +248,44 @@ load_from_directory(layer, "my_models/")  # Auto-detects formats
 | Databricks | ✅ | `uv add sidemantic[databricks]` |
 | Spark SQL | ✅ | `uv add sidemantic[spark]` |
 
+## Docker
+
+The published image is [`sidequery/sidemantic`](https://hub.docker.com/r/sidequery/sidemantic) on Docker Hub. Mount your models directory as a volume at `/app/models`:
+
+```bash
+docker run -p 5433:5433 -v ./models:/app/models sidequery/sidemantic
+```
+
+Demo mode (built-in sample data, no volume needed):
+
+```bash
+docker run -p 5433:5433 sidequery/sidemantic --demo
+```
+
+See [`examples/docker/`](examples/docker/) for MCP mode, env vars, building from source, and integration test services.
+
+## Agent Skill
+
+Sidemantic ships an [agent skill](skills/sidemantic-modeler/) that teaches Claude Code, Codex, and other `SKILL.md`-compatible agents to build, validate, and query semantic models.
+
+**One-liner install (no clone required):**
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/sidequery/sidemantic/main/skills/install.sh | bash
+```
+
+**npx / bunx:**
+
+```bash
+npx skills add https://github.com/sidequery/sidemantic --skill sidemantic-modeler
+# or
+bunx skills add https://github.com/sidequery/sidemantic --skill sidemantic-modeler
+```
+
+## How mature is Sidemantic?
+
+Sidemantic is an ambitious but young semantic layer project. You could encounter rough patches, especially with the more exotic features like converting between semantic model formats or serving semantic layers via the included Postgres protocol server.
+
 ## Testing
 
 ```bash

docker-entrypoint.sh

@@ -0,0 +1,52 @@
+#!/bin/sh
+set -e
+
+# SIDEMANTIC_MODE: "serve" (default), "mcp", or "both"
+MODE="${SIDEMANTIC_MODE:-serve}"
+
+# Build arg arrays for each command.
+# serve accepts: --connection, --db, --host, --port, --username, --password
+# mcp-serve accepts: --db only
+
+# Serve args
+SERVE_ARGS="--host 0.0.0.0"
+if [ -n "$SIDEMANTIC_CONNECTION" ]; then
+    SERVE_ARGS="$SERVE_ARGS --connection \"$SIDEMANTIC_CONNECTION\""
+fi
+if [ -n "$SIDEMANTIC_DB" ]; then
+    SERVE_ARGS="$SERVE_ARGS --db \"$SIDEMANTIC_DB\""
+fi
+if [ -n "$SIDEMANTIC_USERNAME" ]; then
+    SERVE_ARGS="$SERVE_ARGS --username \"$SIDEMANTIC_USERNAME\""
+fi
+if [ -n "$SIDEMANTIC_PASSWORD" ]; then
+    SERVE_ARGS="$SERVE_ARGS --password \"$SIDEMANTIC_PASSWORD\""
+fi
+if [ -n "$SIDEMANTIC_PORT" ]; then
+    SERVE_ARGS="$SERVE_ARGS --port \"$SIDEMANTIC_PORT\""
+fi
+
+# MCP args (only --db is supported)
+MCP_ARGS=""
+if [ -n "$SIDEMANTIC_DB" ]; then
+    MCP_ARGS="$MCP_ARGS --db \"$SIDEMANTIC_DB\""
+fi
+
+case "$MODE" in
+    serve)
+        eval exec sidemantic serve $SERVE_ARGS "$@"
+        ;;
+    mcp)
+        eval exec sidemantic mcp-serve $MCP_ARGS "$@"
+        ;;
+    both)
+        eval sidemantic serve $SERVE_ARGS &
+        SERVE_PID=$!
+        trap "kill $SERVE_PID 2>/dev/null" EXIT
+        eval exec sidemantic mcp-serve $MCP_ARGS "$@"
+        ;;
+    *)
+        echo "Unknown SIDEMANTIC_MODE: $MODE (use serve, mcp, or both)" >&2
+        exit 1
+        ;;
+esac

examples/docker/README.md

@@ -0,0 +1,94 @@
+# Docker
+
+The published image is [`sidequery/sidemantic`](https://hub.docker.com/repository/docker/sidequery/sidemantic) on Docker Hub. It includes all database drivers, the PostgreSQL wire-protocol server, and the MCP server.
+
+## Mounting your models
+
+The container looks for model files (YAML, SQL, etc.) in `/app/models`. Use a volume mount (`-v`) to point it at your local models directory:
+
+```bash
+# If your models are in ~/my-project/models/
+docker run -p 5433:5433 -v ~/my-project/models:/app/models sidequery/sidemantic
+
+# Or from the current directory
+docker run -p 5433:5433 -v $(pwd)/models:/app/models sidequery/sidemantic
+```
+
+The `-v local/path:/app/models` flag maps a folder on your machine into the container. Any `.yml`, `.sql`, or other semantic model files in that folder will be auto-detected and loaded.
+
+## PostgreSQL server (default)
+
+Mount your models directory and expose port 5433:
+
+```bash
+docker run -p 5433:5433 -v ./models:/app/models sidequery/sidemantic
+```
+
+Connect with any PostgreSQL client:
+
+```bash
+psql -h localhost -p 5433 -U any -d sidemantic
+```
+
+With a backend database connection:
+
+```bash
+docker run -p 5433:5433 \
+  -v ./models:/app/models \
+  -e SIDEMANTIC_CONNECTION="postgres://user:pass@host:5432/db" \
+  sidequery/sidemantic
+```
+
+## MCP server
+
+```bash
+docker run -v ./models:/app/models -e SIDEMANTIC_MODE=mcp sidequery/sidemantic
+```
+
+## Both servers simultaneously
+
+Runs the PG server in the background and MCP on stdio:
+
+```bash
+docker run -p 5433:5433 -v ./models:/app/models -e SIDEMANTIC_MODE=both sidequery/sidemantic
+```
+
+## Demo mode
+
+```bash
+docker run -p 5433:5433 sidequery/sidemantic --demo
+```
+
+## Baking models into the image
+
+```dockerfile
+FROM sidequery/sidemantic
+COPY my_models/ /app/models/
+```
+
+## Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `SIDEMANTIC_MODE` | `serve` (default), `mcp`, or `both` |
+| `SIDEMANTIC_CONNECTION` | Database connection string |
+| `SIDEMANTIC_DB` | Path to DuckDB file (inside container) |
+| `SIDEMANTIC_USERNAME` | PG server auth username |
+| `SIDEMANTIC_PASSWORD` | PG server auth password |
+| `SIDEMANTIC_PORT` | PG server port (default 5433) |
+
+## Building from source
+
+From the repo root:
+
+```bash
+docker build -t sidemantic .
+```
+
+## Integration test services (docker-compose)
+
+The `docker-compose.yml` in this directory spins up Postgres, BigQuery emulator, Spark, and ClickHouse for local integration testing:
+
+```bash
+docker compose -f examples/docker/docker-compose.yml up
+```