mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-28 08:49:38 +02:00
docs: rewrite context-as-code as reviewing-context guide (#201)
* docs: rewrite context-as-code as reviewing-context guide Move the page from Concepts to Guides and rebuild around an interactive review-loop diagram. Extract pan/zoom + fit-view controls into a shared FlowCanvas wrapper and adopt it across all three docs diagrams. * test: point examples-docs assertion at reviewing-context Update the doc smoke test that read context-as-code.mdx to read the new guides/reviewing-context.mdx path. The `ktx ingest --all --no-input` assertion still holds; the rename was the only break.
This commit is contained in:
Andrey Avtomonov
GitHub
parent
5211a0317e
commit
4d4296f397
14 changed files with 1062 additions and 288 deletions
|
|
@ -1,114 +0,0 @@
|
|||
---
|
||||
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
|
||||
connectors, then reconciles them into local files.
|
||||
|
||||
```text
|
||||
context sources -> connectors -> reconciliation agent -> YAML + Markdown diffs
|
||||
```
|
||||
|
||||
| Step | What happens | Output |
|
||||
|------|--------------|--------|
|
||||
| **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 |
|
||||
|
||||
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 connector 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) |
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
{
|
||||
"title": "Concepts",
|
||||
"defaultOpen": true,
|
||||
"pages": ["the-context-layer", "semantic-layer-internals", "wiki-retrieval", "context-as-code"]
|
||||
"pages": ["the-context-layer", "semantic-layer-internals", "wiki-retrieval"]
|
||||
}
|
||||
|
|
|
|||
|
|
@ -337,4 +337,4 @@ different from what the agent first proposed.
|
|||
| 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) |
|
||||
| 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) |
|
||||
| Describe how semantic context stays current | Building and maintaining the graph | [Reviewing Context](/docs/guides/reviewing-context) |
|
||||
|
|
|
|||
|
|
@ -123,7 +123,7 @@ caveat stays anchored to the definition it explains.
|
|||
<span className="font-medium text-fd-foreground">{"Behind the scenes. "}</span>
|
||||
<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>
|
||||
<a href="/docs/guides/reviewing-context" className="font-medium underline">{"Reviewing Context"}</a>
|
||||
{" for how that audit trail flows into review."}
|
||||
</figcaption>
|
||||
</figure>
|
||||
|
|
@ -282,4 +282,4 @@ layers.
|
|||
| 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) |
|
||||
| Explain reviewability and source of truth | A ktx project on disk | [Reviewing Context](/docs/guides/reviewing-context) |
|
||||
|
|
|
|||
|
|
@ -277,4 +277,4 @@ stays in step with the semantic layer.
|
|||
| Decide whether to add a `refs` or `sl_refs` entry | The page graph | [Writing Context](/docs/guides/writing-context) |
|
||||
| Repair a wiki write rejected for missing references | Keeping the graph live | [Writing Context](/docs/guides/writing-context) |
|
||||
| Describe how historic SQL becomes a wiki page | Where the pages come from | [Building Context](/docs/guides/building-context) |
|
||||
| Explain raw-source provenance comments | Where the pages come from | [Context as Code](/docs/concepts/context-as-code) |
|
||||
| Explain raw-source provenance comments | Where the pages come from | [Reviewing Context](/docs/guides/reviewing-context) |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue