aimeta

aimeta is a q module that defines an extended metadata model for kdb+ tables and functions, and a compiler that populates the model from qdoc-style annotations in .q source. The model is served over HTTP (/meta) and qIPC (.aimeta.get*) for operators and AI coding agents to consume.

Why

• An extended metadata model for kdb+ tables and functions. Captures column descriptions, semantic types, foreign-reference edges, working call examples, parameter and return docs, and inline sample data — the semantic detail an operator or agent needs to write correct queries that native meta and tables[] don't carry.
• Annotations populate the model. qdoc-style tags in .q source compile to a canonical meta.json — one annotation pass yields both a developer-readable source and a machine wire format. The compiler validates against 13 rules at build time, and the output is byte-deterministic, so the JSON is safe to commit as a build artifact.
• Self-describing over HTTP and qIPC, with graceful fallback. Operators and AI coding agents probe a host to read the model. The bundled kx-meta CLI walks from rich annotated metadata down to bare introspection, so it works against unannotated processes too. Compile runs at startup; if it fails or the source isn't annotated, init[] falls back through existing meta.json → basic introspection → empty document. The host stays up; consumers get the metadata that is available.

Quickstart

/ host.q
aimeta: use `kx.aimeta;

/ @kind data
/ @name trade
/ @desc Trade tape — every fill, raw, append-only.
/ @col time {timestamp} Wall-clock fill time.
/ @col sym {symbol} Instrument symbol. @attr:g
/ @col price {float} Fill price in instrument's quote currency.
/ @col size {int} Fill size in shares.
trade: ([] time:`timestamp$(); sym:`symbol$(); price:`float$(); size:`int$())
@[`trade;`sym;`g#];

/ @kind function
/ @name .gw.vwap
/ @desc Volume-weighted average price for the given symbols.
/ @param syms {symbol[]} Symbols to compute VWAP for.
/ @uses trade
/ @returns {table} sym-keyed VWAP.
/ @example .gw.vwap[`AAPL`MSFT]
.gw.vwap: {[syms] select vwap:size wavg price by sym from trade where sym in syms}

\p 5013
aimeta.init[];                          / compiles annotations + serves /meta

curl localhost:5013/meta
scripts/kx-meta.sh discover localhost:5013

Documentation

• docs/install.md — installation, host wiring, kx-meta CLI, Claude Code skills
• docs/reference.md — per-symbol API reference and HTTP surface
• docs/agent-guide.md — metadata guide for agents authoring or consuming meta.json
• SPEC.md — annotation standard, runtime model, meta.json schema

Hacking on the module itself? See CONTRIBUTING.md and CLAUDE.md.

Status

Pre-1.0. Public surface is stable and versioned by schemaVersion.

Related

• KxSystems/ax — open-source qdoc parser used by the compiler

License

Apache-2.0. See LICENSE.