Datasource-independent query & dataframe layer

Docs · Getting started · Publishing · Contributing · Brand

OpenPlait is a standalone, application-neutral interoperability layer for analytics and observability. It defines one portable query IR, normalized dataframes, transformations, dashboards, and alerts — without replacing PromQL, TraceQL, LogQL, SQL, or other native languages.

Host applications own credentials, authorization, and UI. Adapters compile and execute bounded requests, then return OpenPlait frames any product can consume.

git clone git@github.com:openlit/openplait.git
cd openplait

SSH	git@github.com:openlit/openplait.git
HTTPS	https://github.com/openlit/openplait.git
API	openplait.io/v1alpha1
npm	@openplait/* · 0.1.0-alpha.0
PyPI	openplait · 0.1.0a0

---

Repository layout

Path	Role
typescript/	npm workspaces — @openplait/* reference implementation
python/	Poetry package — openplait on PyPI (alpha)
docs/	Documentation site
brand/	Logo mark, wordmark, and concept art
examples/	Portable query / dashboard examples
specifications/	Spec notes + schema pointers

Language	Status	Install
TypeScript / Node	Implemented (@openplait/*)	npm install @openplait/core @openplait/runtime …
Python	Scaffold (openplait)	pip install openplait (alpha)

---

Why OpenPlait

• One query model across ClickHouse, Tempo, Loki, Prometheus/Mimir, Jaeger, and custom backends
• Honest capabilities — unsupported joins/ops fail explicitly before execution
• Secret-safe — connection config stays server-side; query resources only carry datasource refs
• Normalized frames — host UIs, alerts, and dashboards share one result shape
• Agent-ready — Cursor Agent Skills help wire OpenPlait into any codebase

---

TypeScript packages

Workspace root: typescript/. See typescript/README.md.

Package	Role
@openplait/core	Query IR, schemas, validation, serialization
@openplait/adapter-sdk	DatasourceAdapter contract and HTTP helpers
@openplait/adapter-clickhouse	ClickHouse / OTel datasets
@openplait/adapter-tempo	Grafana Tempo / TraceQL
@openplait/adapter-loki	Grafana Loki / LogQL
@openplait/adapter-prometheus	Prometheus / Mimir / PromQL
@openplait/adapter-jaeger	Jaeger Query HTTP API
@openplait/runtime	Registry, planning, multi-query, alert intents
@openplait/perses	Perses import/export bindings

Quick start

cd typescript
npm install
npm run check

npm install @openplait/core @openplait/adapter-sdk \
  @openplait/runtime @openplait/adapter-clickhouse

import { ClickHouseAdapter } from "@openplait/adapter-clickhouse";
import { DatasourceRegistry, OpenPlaitRuntime } from "@openplait/runtime";
import { OPENPLAIT_API_VERSION, type SemanticQuery } from "@openplait/core";

const config = {
  url: process.env.CLICKHOUSE_URL!,
  username: process.env.CLICKHOUSE_USER,
  password: process.env.CLICKHOUSE_PASSWORD,
  database: "observability",
};

const registry = new DatasourceRegistry().register({
  name: "primary",
  kind: "ClickHouseDatasource",
  scope: "workspace",
  config,
  adapter: new ClickHouseAdapter(config),
});

const runtime = new OpenPlaitRuntime(registry, { defaultTimeoutMs: 30_000 });

Guides: TypeScript · Getting started.

---

Python

Package root: python/. See python/README.md and the Python guide.

cd python
poetry install
poetry run pytest

---

Agent skills

Cursor skills under .cursor/skills/:

Skill	Use when
integrate-openplait	Install + registry + runtime + queries
create-openplait-adapter	Custom DatasourceAdapter
openplait-clickhouse / tempo / loki / prometheus / jaeger	Wire a shipped adapter

---

Development

# TypeScript
cd typescript && npm install && npm run check && npm run build

# Python
cd python && poetry install && poetry run pytest

# Docs site (from repo root)
npm run docs:dev

See CONTRIBUTING.md and plan.md.

---

Release workflow

Tag-driven publishes for npm and PyPI:

Ecosystem	Sources	Tag	Workflow
npm @openplait/*	typescript/	ts-*.*.*	npm-release.yml
PyPI openplait	python/	py-*.*.*	pypi-release.yml

Details: PUBLISHING.md.

# npm alpha
cd typescript
VERSION=$(node -p "require('./packages/core/package.json').version")
git tag "ts-${VERSION}" && git push origin "ts-${VERSION}"

# PyPI alpha
cd python
VERSION=$(poetry version -s)
git tag "py-${VERSION}" && git push origin "py-${VERSION}"

---

Brand

Asset	Path
Wordmark	brand/openplait-wordmark.svg
Mark	brand/openplait-mark.svg
Concept	brand/openplait-logo-concept.png

Usage guidance: Brand docs.

Project status

OpenPlait is pre-release. The v1alpha1 API may evolve. See GOVERNANCE.md and SECURITY.md.

License

Apache-2.0