apunkt/ktx
1
0
Fork 0
mirror of https://github.com/Kaelio/ktx.git synced 2026-07-04 10:52:13 +02:00
Code Issues Projects Releases Packages Wiki Activity

docs: standardize ktx naming

Browse source
This commit is contained in:
Andrey Avtomonov 2026-05-20 17:32:15 +02:00
parent 27afd6a3b0
commit 1f8c1089f6
41 changed files with 331 additions and 313 deletions
Download patch file Download diff file Expand all files Collapse all files

12
docs-site/content/docs/concepts/context-as-code.mdx
View file

@ -5,11 +5,11 @@ description: Treat analytics context like code - version it, review it, merge it
## The idea
dbt moved analytics transformations into git. KTX applies the same pattern to
dbt moved analytics transformations into git. **ktx** applies the same pattern to
analytics context: metric definitions, joins, business rules, wiki pages, and
ingest decisions become files that can be reviewed, merged, and audited.
| Before | With KTX |
| Before | With **ktx** |
|--------|----------|
| Context scattered across BI tools, chats, docs, and analyst memory | Context lives in YAML and Markdown |
| Agent changes are hard to inspect | Agent changes are git diffs |
@ -19,7 +19,7 @@ ingest decisions become files that can be reviewed, merged, and audited.
## Auto-ingestion
Most context already exists in dbt manifests, LookML, MetricFlow, Metabase,
Notion, warehouse metadata, and analyst notes. KTX reads those inputs through
Notion, warehouse metadata, and analyst notes. **ktx** reads those inputs through
connectors, then reconciles them into local files.
```text
@ -30,9 +30,9 @@ context sources -> connectors -> reconciliation agent -> YAML + Markdown diffs
|------|--------------|--------|
| **Extract** | Connectors read models, metrics, questions, schemas, and docs | Structured metadata |
| **Reconcile** | The agent compares incoming facts with existing context | Create, update, skip, or flag |
| **Write** | KTX saves changed semantic sources and wiki pages | Reviewable project files |
| **Write** | **ktx** saves changed semantic sources and wiki pages | Reviewable project files |
Reconciliation is the key difference from a sync. KTX preserves accepted local
Reconciliation is the key difference from a sync. **ktx** preserves accepted local
edits, fills gaps, and surfaces conflicts instead of blindly overwriting files.
## The git workflow
@ -103,7 +103,7 @@ they are part of your team's review workflow.
## Agent usage notes
Use this page when an agent needs to explain review workflows, ingestion diffs,
replayability, or why KTX writes YAML and Markdown instead of hiding context in
replayability, or why **ktx** writes YAML and Markdown instead of hiding context in
a hosted service.
| Agent task | Relevant section | Next page |

26
docs-site/content/docs/concepts/semantic-layer-internals.mdx
View file

@ -1,13 +1,13 @@
---
title: Semantic querying
description: How KTX compiles a short semantic query into safe, dialect-correct SQL using a reviewed join graph.
description: How ktx compiles a short semantic query into safe, dialect-correct SQL using a reviewed join graph.
---
import { SemanticLayerFlow } from "@/components/semantic-layer-flow";
KTX's semantic layer is a compiler that turns intent into SQL. The agent
**ktx**'s semantic layer is a compiler that turns intent into SQL. The agent
declares _what_ it wants - measures, dimensions, filters - in a small
semantic query. KTX figures out the _how_: which tables to join, what
semantic query. **ktx** figures out the _how_: which tables to join, what
grain to aggregate at, how to keep fan-out from inflating measures, and
what dialect the warehouse speaks.
@ -27,15 +27,15 @@ key links them, what grain to aggregate at, how to keep one fact from
inflating another, and what dialect the warehouse speaks. Plumbing on
top of intent, every query.
KTX's semantic layer separates those concerns:
**ktx**'s semantic layer separates those concerns:
- **You and KTX maintain the how.** Sources, joins, grain, measures, and
- **You and ktx maintain the how.** Sources, joins, grain, measures, and
segments live in reviewable YAML - the analytical contract the team
agrees on, version-controlled.
- **The agent declares the what.** It sends a semantic query and trusts
the compiler to produce safe SQL.
The agent stops reasoning about plumbing. It states intent. KTX turns
The agent stops reasoning about plumbing. It states intent. **ktx** turns
that into SQL the warehouse can run.
<SemanticLayerFlow />
@ -48,7 +48,7 @@ except `measures`, and column references are fully qualified
from.
Notice what's _not_ in the payload: no `FROM`, no `JOIN`, no `GROUP BY`,
no `WITH`. The agent states what it wants. KTX picks the join path, the
no `WITH`. The agent states what it wants. **ktx** picks the join path, the
grain, the SQL shape, and the dialect.
| Field | Purpose |
@ -71,7 +71,7 @@ A typical agent call looks like this:
}
```
That payload is enough for KTX to plan and compile. The agent never
That payload is enough for **ktx** to plan and compile. The agent never
authors a join, a CTE, or a dialect-specific cast.
## What the planner does
@ -161,7 +161,7 @@ measures:
## Building and maintaining the graph
KTX builds the graph from evidence and accepted edits, not from runtime
**ktx** builds the graph from evidence and accepted edits, not from runtime
inference. Each input contributes a different kind of authority.
| Evidence | What it contributes |
@ -293,7 +293,7 @@ shared dimension. A naive query joins them all together first, so each
row from one fact is multiplied by the matching rows from the other.
Measures duplicate, numbers go wrong, and the agent doesn't notice.
KTX's planner detects the shape by grouping measures by their owning
**ktx**'s planner detects the shape by grouping measures by their owning
source. If more than one source contributes raw measures, the generator
switches to aggregate locality: each fact is pre-aggregated at its own
grain inside a CTE, and the CTEs are joined back to the dimension at the
@ -311,7 +311,7 @@ analyst would have written by hand.
## Where the context comes from
The planner is only as good as the YAML it reads. KTX builds and
The planner is only as good as the YAML it reads. **ktx** builds and
maintains that YAML for you.
- `raw-sources/<connection>/` holds scan evidence from your warehouse:
@ -327,7 +327,7 @@ current as the warehouse changes.
## Agent usage notes
Point an agent at this page when it needs to explain why KTX asks for
Point an agent at this page when it needs to explain why **ktx** asks for
grain, why a query was rejected as unsafe, or why the compiled SQL looks
different from what the agent first proposed.
@ -335,6 +335,6 @@ different from what the agent first proposed.
|------------|------------------|-----------|
| Explain the semantic query shape | The semantic query contract | [ktx sl](/docs/cli-reference/ktx-sl) |
| Describe what the planner does between query and SQL | What the planner does | [ktx sl](/docs/cli-reference/ktx-sl) |
| Explain why KTX asks for grain and relationship types | The join graph | [Writing context](/docs/guides/writing-context) |
| Explain why **ktx** asks for grain and relationship types | The join graph | [Writing context](/docs/guides/writing-context) |
| Diagnose duplicated measures after a join | Fan-out and aggregate locality | [ktx sl](/docs/cli-reference/ktx-sl) |
| Describe how semantic context stays current | Building and maintaining the graph | [Context as code](/docs/concepts/context-as-code) |

35
docs-site/content/docs/concepts/the-context-layer.mdx
View file

@ -1,6 +1,6 @@
---
title: The Context Layer
description: What a context layer is, why agents need one, and the YAML and Markdown surfaces KTX writes to disk.
description: What a context layer is, why agents need one, and the YAML and Markdown surfaces ktx writes to disk.
---
import { GitIcon } from "@/components/git-icon";
@ -11,7 +11,7 @@ can't tell an agent on its own: which metrics are canonical, which joins are
safe, what your team means by "active customer", and where every definition
came from.
KTX builds that layer as plain files - YAML, Markdown, and JSON - that agents
**ktx** builds that layer as plain files - YAML, Markdown, and JSON - that agents
can search and humans can review. This page covers what's in it, why agents
need it, and how it compares to other semantic tooling.
@ -35,14 +35,14 @@ Schema is a starting point, not a contract. The context layer is the contract.
## The two pillars
A KTX project has two committed surfaces, each tuned for a different question.
A **ktx** project has two committed surfaces, each tuned for a different question.
Structured data lives where it can be compiled. Prose lives where it can be
searched. Wiki pages cross-reference semantic sources by name, so every metric
caveat stays anchored to the definition it explains.
<figure
className="not-prose my-10 overflow-hidden rounded-lg border border-fd-border bg-fd-card shadow-sm"
aria-label="The two committed pillars of a KTX context layer"
aria-label="The two committed pillars of a ktx context layer"
>
<div className="border-b border-fd-border bg-fd-muted/35 px-5 py-4">
<p className="text-[11px] font-semibold uppercase tracking-[0.08em] text-fd-primary">
@ -121,7 +121,8 @@ caveat stays anchored to the definition it explains.
<figcaption className="border-t border-fd-border bg-fd-muted/25 px-5 py-3 text-[11.5px] leading-5 text-fd-muted-foreground">
<span className="font-medium text-fd-foreground">{"Behind the scenes. "}</span>
{"KTX also keeps scan snapshots and a per-run event log locally so every committed change is traceable to its evidence. You don't read or edit these files yourself - see "}
<strong className="font-medium text-fd-foreground">{"ktx"}</strong>
{" also keeps scan snapshots and a per-run event log locally so every committed change is traceable to its evidence. You don't read or edit these files yourself - see "}
<a href="/docs/concepts/context-as-code" className="font-medium underline">{"Context as Code"}</a>
{" for how that audit trail flows into review."}
</figcaption>
@ -189,7 +190,7 @@ a graph agents traverse. An agent that finds this page while searching for
executable definition, then walks `refs` to related policies without rerunning
search.
The graph only helps if the edges stay live. KTX validates references when
The graph only helps if the edges stay live. **ktx** validates references when
wiki pages are written and prunes `sl_refs` during ingest when their target
sources are deleted or their measures are renamed - so a stale page can never
quietly route an agent to a definition that no longer exists.
@ -206,7 +207,7 @@ The split between the two pillars is sharp:
If a fact changes how the SQL runs, it goes in YAML. If a human needs it to
trust the answer, it goes in Markdown.
## How KTX compares
## How ktx compares
Two adjacent product categories cover parts of this problem - but each leaves
a different gap.
@ -224,13 +225,13 @@ hand-written, and the layer doesn't learn from the warehouse, BI tools, or
query history that surround it. The business context that explains *why* a
definition exists usually lives somewhere else.
KTX bundles both surfaces - wiki for business context, semantic layer for
**ktx** bundles both surfaces - wiki for business context, semantic layer for
queryable definitions - and keeps them current by reading the data stack and
reconciling new evidence with the reviewed files. You get the breadth of a
knowledge tool and the SQL safety of a semantic layer, without rewriting
models every time the warehouse changes.
| Capability | Company brain | Semantic layer | KTX |
| Capability | Company brain | Semantic layer | **ktx** |
|------------|---------------|----------------|-----|
| **Surface** | Indexed docs and chats | Modeling language or runtime | YAML and Markdown files |
| **Data-stack awareness** | None - treats data tools as text | High for declared metrics, none for the surrounding warehouse | Built in: scans schemas, dbt, BI tools, and query history |
@ -238,14 +239,14 @@ models every time the warehouse changes.
| **SQL safety** | None - generates plausible text | Compiled, dialect-correct | Compiled with join-graph and fan-out handling |
| **Agent edit loop** | Text-only | Tied to the modeling workflow | First-class: patch files, validate, review diffs |
If you already use MetricFlow, LookML, dbt, or BI tools, KTX can ingest that
If you already use MetricFlow, LookML, dbt, or BI tools, **ktx** can ingest that
context and turn it into agent-readable files. You don't need to replace your
serving layer to give agents a better working surface.
## A KTX project on disk
## A ktx project on disk
A KTX project is a directory of readable files. Semantic sources and wiki
pages are committed to git; everything else KTX needs at runtime stays local
A **ktx** project is a directory of readable files. Semantic sources and wiki
pages are committed to git; everything else **ktx** needs at runtime stays local
and out of the repo.
```text
@ -268,13 +269,13 @@ agents read the updated source of truth.
## Agent usage notes
Use this page when an agent needs to explain why KTX exists, why schema-only
database access isn't enough, or how KTX differs from traditional semantic
Use this page when an agent needs to explain why **ktx** exists, why schema-only
database access isn't enough, or how **ktx** differs from traditional semantic
layers.
| Agent task | Relevant section | Next page |
|------------|------------------|-----------|
| Explain why a data agent wrote a plausible but wrong query | Database access isn't enough | [Writing Context](/docs/guides/writing-context) |
| Decide whether a fact belongs in YAML or Markdown | Semantic sources / Wiki pages | [Writing Context](/docs/guides/writing-context) |
| Compare KTX to another semantic layer | How KTX compares | [Primary Sources](/docs/integrations/primary-sources) |
| Explain reviewability and source of truth | A KTX project on disk | [Context as Code](/docs/concepts/context-as-code) |
| Compare **ktx** to another semantic layer | How ktx compares | [Primary Sources](/docs/integrations/primary-sources) |
| Explain reviewability and source of truth | A ktx project on disk | [Context as Code](/docs/concepts/context-as-code) |