https://github.com/kxsystems/aimeta
[WIP] kdb-x module for metadata and AI metadata discovery
https://github.com/kxsystems/aimeta
Last synced: 14 days ago
JSON representation
[WIP] kdb-x module for metadata and AI metadata discovery
- Host: GitHub
- URL: https://github.com/kxsystems/aimeta
- Owner: KxSystems
- License: apache-2.0
- Created: 2026-05-20T14:36:04.000Z (24 days ago)
- Default Branch: main
- Last Pushed: 2026-05-22T16:51:18.000Z (22 days ago)
- Last Synced: 2026-05-25T12:05:30.433Z (19 days ago)
- Language: q
- Size: 151 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# 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
```q
/ 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
```
```bash
curl localhost:5013/meta
scripts/kx-meta.sh discover localhost:5013
```
## Documentation
- [docs/install.md](docs/install.md) — installation, host wiring, `kx-meta` CLI, Claude Code skills
- [docs/reference.md](docs/reference.md) — per-symbol API reference and HTTP surface
- [docs/agent-guide.md](docs/agent-guide.md) — metadata guide for agents authoring or consuming `meta.json`
- [SPEC.md](SPEC.md) — annotation standard, runtime model, `meta.json` schema
Hacking on the module itself? See [CONTRIBUTING.md](CONTRIBUTING.md) and [CLAUDE.md](CLAUDE.md).
## Status
Pre-1.0. Public surface is stable and versioned by `schemaVersion`.
## Related
- [KxSystems/ax](https://github.com/KxSystems/ax) — open-source qdoc parser used by the compiler
## License
Apache-2.0. See [LICENSE](LICENSE).