API Server

Author: nicosuave

Dockerfile

@@ -15,8 +15,12 @@ WORKDIR /app
 COPY pyproject.toml README.md LICENSE ./
 COPY sidemantic/ sidemantic/
 COPY examples/ examples/
+COPY scripts/ scripts/
 
-RUN uv pip install --system --no-cache ".[serve,mcp,all-databases]"
+RUN uv pip install --system --no-cache ".[serve,mcp,api,all-databases]"
+RUN mkdir -p /app/models
+RUN cp -R /app/examples/multi_format_demo/. /app/models/
+RUN python /app/scripts/build_demo_duckdb.py
 
 # --- Runtime stage (no build tools) ---
 FROM python:3.12-slim
@@ -33,9 +37,11 @@ COPY docker-entrypoint.sh /docker-entrypoint.sh
 RUN chmod +x /docker-entrypoint.sh
 
 RUN mkdir -p /app/models
+COPY --from=builder /app/models/ /app/models/
 WORKDIR /app/models
 
 EXPOSE 5433
+EXPOSE 4400
 
 ENTRYPOINT ["/docker-entrypoint.sh"]
-# Mode is controlled by SIDEMANTIC_MODE env var (serve, mcp, both)
+# Mode is controlled by SIDEMANTIC_MODE env var (serve, mcp, api, both)

README.md

@@ -23,6 +23,11 @@ Malloy support (uv):
 uv add "sidemantic[malloy]"
 ```
 
+HTTP API server (uv):
+```bash
+uv add "sidemantic[api]"
+```
+
 Notebook widget (uv):
 ```bash
 uv add "sidemantic[widget]" jupyterlab
@@ -129,6 +134,9 @@ sidemantic workbench models/ --db data.duckdb
 # PostgreSQL server (connect Tableau, DBeaver, etc.)
 sidemantic serve models/ --port 5433
 
+# HTTP API server (JSON or Arrow)
+sidemantic api-serve models/ --port 4400 --auth-token secret
+
 # Validate definitions
 sidemantic validate models/
 
@@ -154,6 +162,11 @@ uvx sidemantic workbench --demo
 uvx sidemantic serve --demo --port 5433
 ```
 
+**HTTP API server** (JSON or Arrow):
+```bash
+uvx --from "sidemantic[api]" sidemantic api-serve --demo --port 4400 --auth-token secret
+```
+
 **Colab notebooks:**
 
 [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/sidequery/sidemantic/blob/main/examples/notebooks/sidemantic_sql_duckdb_demo.ipynb) SQL + DuckDB
@@ -219,6 +232,7 @@ See `examples/` for more.
 - Segments and metric-level filters
 - Jinja2 templating for dynamic SQL
 - PostgreSQL wire protocol server for BI tools
+- HTTP API with JSON and Arrow IPC responses
 
 ## Multi-Format Support
 
@@ -264,6 +278,54 @@ 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.
 
+For Cloudflare Worker + Container deployment, see [`examples/cloudflare_containers/`](examples/cloudflare_containers/).
+
+## HTTP API
+
+Start the API server:
+
+```bash
+sidemantic api-serve models/ --db data.duckdb --port 4400 --auth-token secret
+```
+
+Compile a structured semantic query:
+
+```bash
+curl -s http://localhost:4400/compile \
+  -H "Authorization: Bearer secret" \
+  -H "Content-Type: application/json" \
+  -d '{"dimensions":["orders.status"],"metrics":["orders.total_amount"]}'
+```
+
+Run a structured query as JSON:
+
+```bash
+curl -s http://localhost:4400/query \
+  -H "Authorization: Bearer secret" \
+  -H "Content-Type: application/json" \
+  -d '{"dimensions":["orders.status"],"metrics":["orders.total_amount","orders.order_count"]}'
+```
+
+Run a structured query as Arrow IPC:
+
+```bash
+curl -s http://localhost:4400/query \
+  -H "Authorization: Bearer secret" \
+  -H "Accept: application/vnd.apache.arrow.stream" \
+  -H "Content-Type: application/json" \
+  -d '{"metrics":["orders.order_count"]}' \
+  > result.arrow
+```
+
+Execute rewritten SQL over HTTP:
+
+```bash
+curl -s http://localhost:4400/sql \
+  -H "Authorization: Bearer secret" \
+  -H "Content-Type: application/json" \
+  -d '{"query":"SELECT status, total_amount FROM orders ORDER BY status"}'
+```
+
 ## 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.

docker-entrypoint.sh

@@ -1,8 +1,12 @@
 #!/bin/sh
 set -e
 
-# SIDEMANTIC_MODE: "serve" (default), "mcp", or "both"
+# SIDEMANTIC_MODE: "serve" (default), "mcp", "api", or "both"
 MODE="${SIDEMANTIC_MODE:-serve}"
+DEMO_ARGS=""
+if [ -n "$SIDEMANTIC_DEMO" ]; then
+    DEMO_ARGS="--demo"
+fi
 
 # Build arg arrays for each command.
 # serve accepts: --connection, --db, --host, --port, --username, --password
@@ -32,21 +36,50 @@ if [ -n "$SIDEMANTIC_DB" ]; then
     MCP_ARGS="$MCP_ARGS --db \"$SIDEMANTIC_DB\""
 fi
 
+# HTTP API args
+API_ARGS="--host 0.0.0.0"
+if [ -n "$SIDEMANTIC_CONNECTION" ]; then
+    API_ARGS="$API_ARGS --connection \"$SIDEMANTIC_CONNECTION\""
+fi
+if [ -n "$SIDEMANTIC_DB" ]; then
+    API_ARGS="$API_ARGS --db \"$SIDEMANTIC_DB\""
+fi
+if [ -n "$SIDEMANTIC_API_TOKEN" ]; then
+    API_ARGS="$API_ARGS --auth-token \"$SIDEMANTIC_API_TOKEN\""
+fi
+if [ -n "$SIDEMANTIC_API_PORT" ]; then
+    API_ARGS="$API_ARGS --port \"$SIDEMANTIC_API_PORT\""
+fi
+if [ -n "$SIDEMANTIC_MAX_REQUEST_BODY_BYTES" ]; then
+    API_ARGS="$API_ARGS --max-request-body-bytes \"$SIDEMANTIC_MAX_REQUEST_BODY_BYTES\""
+fi
+if [ -n "$SIDEMANTIC_CORS_ORIGINS" ]; then
+    OLD_IFS="$IFS"
+    IFS=','
+    for ORIGIN in $SIDEMANTIC_CORS_ORIGINS; do
+        API_ARGS="$API_ARGS --cors-origin \"$ORIGIN\""
+    done
+    IFS="$OLD_IFS"
+fi
+
 case "$MODE" in
     serve)
-        eval exec sidemantic serve $SERVE_ARGS "$@"
+        eval exec sidemantic serve $SERVE_ARGS $DEMO_ARGS "$@"
         ;;
     mcp)
-        eval exec sidemantic mcp-serve $MCP_ARGS "$@"
+        eval exec sidemantic mcp-serve $MCP_ARGS $DEMO_ARGS "$@"
+        ;;
+    api)
+        eval exec sidemantic api-serve $API_ARGS $DEMO_ARGS "$@"
         ;;
     both)
-        eval sidemantic serve $SERVE_ARGS &
+        eval sidemantic serve $SERVE_ARGS $DEMO_ARGS &
         SERVE_PID=$!
         trap "kill $SERVE_PID 2>/dev/null" EXIT
-        eval exec sidemantic mcp-serve $MCP_ARGS "$@"
+        eval exec sidemantic mcp-serve $MCP_ARGS $DEMO_ARGS "$@"
         ;;
     *)
-        echo "Unknown SIDEMANTIC_MODE: $MODE (use serve, mcp, or both)" >&2
+        echo "Unknown SIDEMANTIC_MODE: $MODE (use serve, mcp, api, or both)" >&2
         exit 1
         ;;
 esac

examples/cloudflare_containers/.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+.wrangler/

examples/cloudflare_containers/Dockerfile

@@ -0,0 +1,10 @@
+FROM sidequery/sidemantic:latest
+
+ENV SIDEMANTIC_MODE=api
+ENV SIDEMANTIC_API_PORT=4400
+
+WORKDIR /app/models
+
+# Demo mode makes the example deployable without bundling local models.
+# For a real deployment, replace this with baked-in models and remove --demo.
+CMD ["--demo"]

examples/cloudflare_containers/README.md

@@ -0,0 +1,94 @@
+# Cloudflare Containers
+
+This example runs the Sidemantic HTTP API behind a Cloudflare Worker that proxies requests into Cloudflare Containers.
+
+## Deployment shape
+
+- HTTPS terminates at the Worker.
+- The Worker starts a Sidemantic container and forwards requests to port `4400`.
+- The container runs `SIDEMANTIC_MODE=api`.
+- The example image bakes demo models and a seeded `demo.duckdb` into `/app/models`.
+
+For a real deployment, the clean shape is:
+
+- bake your semantic models into the container image
+- point Sidemantic at an external database with `SIDEMANTIC_CONNECTION`
+- keep DuckDB files out of the container unless they are disposable, because Cloudflare container disks reset on stop
+
+## Files
+
+- `wrangler.jsonc`: Cloudflare Worker and container binding config
+- `src/index.ts`: Worker entrypoint and container proxy
+- `Dockerfile`: Sidemantic container image used by Cloudflare
+
+## Prereqs
+
+- Bun
+- Docker
+- A Cloudflare account with Containers enabled
+- Wrangler auth: `bunx wrangler whoami`
+
+## Deploy the demo
+
+```bash
+cd examples/cloudflare_containers
+bun install
+bunx wrangler secret put SIDEMANTIC_API_TOKEN
+bun run deploy
+```
+
+After deploy, query the worker URL:
+
+```bash
+curl -s https://YOUR-WORKER.workers.dev/query \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"metrics":["customers.customer_count"]}'
+```
+
+Arrow still works through the Worker:
+
+```bash
+curl -s https://YOUR-WORKER.workers.dev/query \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Accept: application/vnd.apache.arrow.stream" \
+  -H "Content-Type: application/json" \
+  -d '{"metrics":["customers.customer_count"]}' \
+  > result.arrow
+```
+
+## Switching from demo to real models
+
+Edit `Dockerfile` to bake in your models:
+
+```dockerfile
+FROM sidequery/sidemantic:latest
+
+ENV SIDEMANTIC_MODE=api
+ENV SIDEMANTIC_API_PORT=4400
+
+COPY models/ /app/models/
+WORKDIR /app/models
+```
+
+Then remove `SIDEMANTIC_DB` from the default container env in [src/index.ts](/Users/nico/Code/sidemantic/examples/cloudflare_containers/src/index.ts).
+
+Then set your warehouse connection:
+
+```bash
+bunx wrangler secret put SIDEMANTIC_CONNECTION
+```
+
+The Worker passes `SIDEMANTIC_CONNECTION`, `SIDEMANTIC_API_TOKEN`, and `SIDEMANTIC_CORS_ORIGINS` into the container at startup.
+
+## Auth
+
+The container already supports bearer-token auth via `SIDEMANTIC_API_TOKEN`.
+
+If you want proper edge auth, put the deployed hostname behind Cloudflare Access and use service tokens or your IdP there. Keep the app bearer token as a second gate if you want defense in depth.
+
+## Notes
+
+- Cloudflare Containers is beta.
+- Cold starts are materially slower than plain Workers.
+- The Worker is required. The container is not exposed directly on the public Internet.