mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-07 07:55:13 +02:00
b318671d31
* docs: shorten concept pages * docs: shorten semantic internals page * docs: restore semantic internals diagrams * docs: align semantic internals intro * docs: rename semantic internals page * docs: polish safe sql comparison
114 lines
4.5 KiB
Text
114 lines
4.5 KiB
Text
---
|
|
title: Context as Code
|
|
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
|
|
analytics context: metric definitions, joins, business rules, wiki pages, and
|
|
ingest decisions become files that can be reviewed, merged, and audited.
|
|
|
|
| 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 |
|
|
| Imports overwrite local judgment | Ingest reconciles with existing files |
|
|
| History depends on tool logs | History lives in commits and transcripts |
|
|
|
|
## Auto-ingestion
|
|
|
|
Most context already exists in dbt manifests, LookML, MetricFlow, Metabase,
|
|
Notion, warehouse metadata, and analyst notes. KTX reads those inputs through
|
|
adapters, then reconciles them into local files.
|
|
|
|
```text
|
|
source tools -> adapters -> reconciliation agent -> YAML + Markdown diffs
|
|
```
|
|
|
|
| Step | What happens | Output |
|
|
|------|--------------|--------|
|
|
| **Extract** | Adapters 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 |
|
|
|
|
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
|
|
|
|
Run ingestion on a branch, review the changed YAML and Markdown, then merge the
|
|
accepted context the same way you merge dbt or application code.
|
|
|
|
```text
|
|
dbt / BI / docs / warehouse
|
|
|
|
|
v
|
|
ktx ingest --all
|
|
|
|
|
v
|
|
branch: ingest/nightly
|
|
|
|
|
v
|
|
semantic diff in PR
|
|
|
|
|
v
|
|
approve and merge
|
|
|
|
|
v
|
|
agents read updated files
|
|
```
|
|
|
|
Typical review checklist:
|
|
|
|
- new sources match the warehouse and source-tool evidence;
|
|
- joins have the right relationship direction;
|
|
- generated measures match business definitions;
|
|
- wiki pages capture caveats without duplicating YAML;
|
|
- `.ktx/` runtime state stays out of git unless your team intentionally reviews
|
|
a report or transcript.
|
|
|
|
Teams often run ingestion on demand during setup, then schedule
|
|
`ktx ingest --all --no-input` on an ingest branch once the source is stable.
|
|
|
|
## Feedback loops
|
|
|
|
Context improves when human corrections and agent signals flow back into the
|
|
same reviewed files.
|
|
|
|
| Signal | Example | Where it lands |
|
|
|--------|---------|----------------|
|
|
| Analyst correction | A measure excludes test accounts | `semantic-layer/**/*.yaml` |
|
|
| Business clarification | ARR changed definition this quarter | `wiki/**/*.md` |
|
|
| Agent query issue | A filter returns no rows unexpectedly | Wiki caveat or tighter source filter |
|
|
| Join problem | A path duplicates order-level measures | Relationship metadata or grain fix |
|
|
|
|
Accepted corrections become input to the next ingest run. That makes the
|
|
context layer converge toward the team's current source of truth.
|
|
|
|
## Deterministic replay
|
|
|
|
Every ingestion session records the adapter inputs, tool calls, LLM responses,
|
|
write decisions, and reasoning behind each change.
|
|
|
|
| Use case | What replay gives you |
|
|
|----------|-----------------------|
|
|
| **Debugging** | Trace a bad source, join, or measure back to the input that produced it |
|
|
| **Trust** | Show where a definition came from and who reviewed the resulting diff |
|
|
| **Reproducibility** | Compare old and new ingest behavior after config or model changes |
|
|
|
|
Commit the YAML and Markdown changes. Commit reports or transcripts only when
|
|
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
|
|
a hosted service.
|
|
|
|
| Agent task | Relevant section | Next page |
|
|
|------------|------------------|-----------|
|
|
| Explain how generated context should be reviewed | The git workflow | [Building Context](/docs/guides/building-context) |
|
|
| Diagnose why ingestion changed a semantic source | Auto-ingestion / Deterministic replay | [ktx ingest](/docs/cli-reference/ktx-ingest) |
|
|
| Explain how context improves over time | Feedback loops | [Building Context](/docs/guides/building-context) |
|
|
| Tell a user what to commit | The git workflow | [Writing Context](/docs/guides/writing-context) |
|