diff --git a/docs-site/components/product-mechanics.tsx b/docs-site/components/product-mechanics.tsx index 7f551450..1c10e9aa 100644 --- a/docs-site/components/product-mechanics.tsx +++ b/docs-site/components/product-mechanics.tsx @@ -1,31 +1,48 @@ import type { ReactNode } from "react"; +type SourceInput = { + name: string; + sources: string[]; + detail: string; + signal: string; + accent: string; +}; + const sourceInputs = [ { - name: "Warehouse schema", + name: "Database structure", + sources: [ + "Postgres", + "Snowflake", + "BigQuery", + "and many others", + ], detail: "tables, columns, types, constraints, row counts", signal: "grounds definitions in live database structure", accent: "border-fd-primary", }, { - name: "Metabase and query history", + name: "BI and usage evidence", + sources: ["Metabase", "Looker"], detail: "historic SQL, questions, dashboards, usage patterns", signal: "extracts joins, filters, grain, and trusted examples", accent: "border-orange-500", }, { - name: "dbt, MetricFlow, LookML", + name: "Semantic modeling", + sources: ["dbt", "MetricFlow", "LookML"], detail: "models, metrics, dimensions, explores, joins", signal: "maps existing modeling logic into semantic entities", accent: "border-amber-500", }, { name: "Company documentation", - detail: "Notion pages, policies, caveats, analyst notes", + sources: ["Notion"], + detail: "Notion pages, policies, caveats", signal: "links business language back to semantic references", accent: "border-slate-500 dark:border-cyan-200", }, -]; +] satisfies SourceInput[]; const ingestSteps = [ { @@ -99,20 +116,16 @@ export function ProductMechanics() { aria-labelledby="mechanics-title" >
-

- Product mechanics -

- A semantic compiler for analytics agents + How KTX works

- KTX builds typed semantic files, links wiki context back to those - entities, validates the model against database evidence, then compiles - agent requests into executable SQL. + KTX reads source evidence, writes local context files, and gives + agents semantic search, validation, SQL, and provenance.

@@ -133,41 +146,44 @@ function IngestionDiagram() { -
-
+
+
Inputs KTX reads -
+
{sourceInputs.map((source) => (
-

- {source.name} -

-

- {source.detail} -

-

- {source.signal} -

+
+

+ {source.name} +

+

+ {source.detail} +

+

+ {source.signal} +

+
+
))}
-
- KTX builds the model -
-
+
+ KTX transforms evidence +
+

- Ingest pipeline + KTX builds the model

-
    +
      {ingestSteps.map((step, index) => (
-
- {artifacts.map((artifact) => ( - - ))} +
+

+ Outputs KTX writes +

+
+ {artifacts.map((artifact) => ( + + ))} +
@@ -201,8 +222,8 @@ function RuntimeDiagram() {
@@ -374,7 +395,7 @@ function PipelineStep({ @@ -393,6 +414,42 @@ function ColumnLabel({ children }: { children: ReactNode }) { ); } +function SourceList({ + sources, +}: { + sources: string[]; +}) { + return ( +
+

+ Sources +

+
+ {sources.map((source) => + source === "and many others" ? ( + + {source} + + ) : ( + + {source} + + ), + )} +
+
+ ); +} + function CodeBox({ children }: { children: ReactNode }) { return (
diff --git a/docs-site/content/docs/getting-started/introduction.mdx b/docs-site/content/docs/getting-started/introduction.mdx index 7a6c9b3e..72891d99 100644 --- a/docs-site/content/docs/getting-started/introduction.mdx +++ b/docs-site/content/docs/getting-started/introduction.mdx @@ -1,6 +1,6 @@ --- title: Introduction -description: How KTX gives analytics agents trusted context for warehouse work. +description: What KTX is, how it works, and where to start. --- import { ProductMechanics } from "@/components/product-mechanics"; @@ -23,29 +23,39 @@ import { ProductMechanics } from "@/components/product-mechanics"; Make analytics context usable by agents

- {'KTX turns warehouse metadata, semantic definitions, and business knowledge into reviewable project files that agents can use while planning, querying, and updating analytics work.'} + {'KTX turns warehouse metadata, semantic definitions, BI usage, and team knowledge into local files and runtime tools that database agents can trust.'}

+## Why KTX + +- Schemas show columns, not business rules. +- Agents need trusted metrics, joins, filters, caveats, and provenance. +- KTX captures that context before agents write SQL, docs, or semantic edits. + +## What KTX creates + +| Path | What it gives agents | +|------|----------------------| +| `semantic-layer/` | Measures, dimensions, joins, grain, filters, segments | +| `wiki/` | Business definitions, caveats, policies, analyst notes | +| `raw-sources/` | Extracted metadata, scan output, relationship evidence | +| `.ktx/` | Local indexes, embeddings, setup state, runtime data | + -## What agents can do with KTX - -KTX is built for analytics engineers and data teams who want data agents to -work on real analytics systems, not just generate one-off SQL. - -Use it when agents need to: +## Use it for - **Generate SQL** from approved measures, dimensions, joins, and filters - **Explain provenance** with wiki context and warehouse evidence - **Repair context** through reviewable YAML and Markdown diffs - **Work alongside** dbt, LookML, MetricFlow, Looker, Metabase, and warehouses -KTX works with SQLite, PostgreSQL, Snowflake, BigQuery, ClickHouse, MySQL, and -SQL Server. +Databases: SQLite, PostgreSQL, Snowflake, BigQuery, ClickHouse, MySQL, SQL +Server. -## Read next +## Start here @@ -60,16 +70,7 @@ SQL Server. Complete flag and subcommand reference for every KTX command. + + Machine-readable docs and agent-facing setup notes. + - -## Agent usage notes - -| Agent task | Read next | -|------------|-----------| -| Discover machine-readable docs | [AI Resources](/docs/ai-resources) | -| Learn how a coding assistant should approach KTX | [Agent Quickstart](/docs/ai-resources/agent-quickstart) | -| Set up a new KTX project | [Quickstart](/docs/getting-started/quickstart) | -| Explain what problem KTX solves | [The Context Layer](/docs/concepts/the-context-layer) | -| Scan a database and ingest metadata | [Building Context](/docs/guides/building-context) | -| Edit semantic sources or wiki pages | [Writing Context](/docs/guides/writing-context) | -| Look up exact command flags | [CLI Reference](/docs/cli-reference/ktx-setup) | diff --git a/docs-site/tests/product-mechanics-content.test.mjs b/docs-site/tests/product-mechanics-content.test.mjs index 6992d9a1..bf03abcc 100644 --- a/docs-site/tests/product-mechanics-content.test.mjs +++ b/docs-site/tests/product-mechanics-content.test.mjs @@ -10,7 +10,7 @@ async function readDocsFile(path) { return readFile(join(docsSiteDir, path), "utf8"); } -test("docs introduction shows the ingestion and runtime mechanics early", async () => { +test("docs introduction frames the concept before showing product mechanics", async () => { const introduction = await readDocsFile( "content/docs/getting-started/introduction.mdx", ); @@ -22,14 +22,24 @@ test("docs introduction shows the ingestion and runtime mechanics early", async assert.match(introduction, //); const heroIndex = introduction.indexOf("Make analytics context"); + const whyIndex = introduction.indexOf("## Why KTX"); + const createsIndex = introduction.indexOf("## What KTX creates"); const mechanicsIndex = introduction.indexOf(""); - const useCaseIndex = introduction.indexOf("## What agents can do with KTX"); + const useCaseIndex = introduction.indexOf("## Use it for"); const heroSource = introduction.slice(0, mechanicsIndex); assert.ok(heroIndex >= 0, "introduction should include the custom hero"); assert.ok( - mechanicsIndex > heroIndex, - "mechanics component should appear after the hero", + whyIndex > heroIndex, + "problem framing should appear after the hero", + ); + assert.ok( + createsIndex > whyIndex, + "artifact summary should appear after problem framing", + ); + assert.ok( + mechanicsIndex > createsIndex, + "mechanics component should appear after the artifact summary", ); assert.ok( mechanicsIndex < useCaseIndex, @@ -45,7 +55,9 @@ test("product mechanics component covers source-specific context and SQL expansi const component = await readDocsFile("components/product-mechanics.tsx"); for (const expectedText of [ - "A semantic compiler for analytics agents", + "How KTX works", + "Build context from source evidence", + "Run agent requests through the model", "Ingestion", "Runtime", "wiki/", @@ -53,10 +65,23 @@ test("product mechanics component covers source-specific context and SQL expansi "raw-sources/", ".ktx/", "sl_refs", + "Database structure", + "BI and usage evidence", + "Semantic modeling", "Company documentation", "Notion pages", + "Sources", + "KTX transforms evidence", + "KTX builds the model", + "Outputs KTX writes", + "Postgres", + "Snowflake", + "BigQuery", + "and many others", "Metabase", - "query history", + "Looker", + "MetricFlow", + "LookML", "extract evidence", "reconcile entities", "validate references", @@ -74,12 +99,27 @@ test("product mechanics component covers source-specific context and SQL expansi ); } + assert.doesNotMatch(component, /Product mechanics/); + assert.doesNotMatch(component, /A semantic compiler for analytics agents/); assert.doesNotMatch(component, /KTX does more than retrieve Markdown/); assert.doesNotMatch(component, /Plain Markdown \+ RAG/); assert.doesNotMatch(component, /comparisonRows/); assert.doesNotMatch(component, /ComparisonTable/); assert.doesNotMatch(component, /Not just retrieval/); assert.doesNotMatch(component, /KTX works in two moments/); + assert.doesNotMatch(component, /name: "Metabase and query history"/); + assert.doesNotMatch(component, /name: "dbt, MetricFlow, LookML"/); + assert.doesNotMatch(component, /query history/); + assert.doesNotMatch(component, /analyst notes/); + assert.doesNotMatch(component, /ClickHouse/); + assert.doesNotMatch(component, /MySQL/); + assert.doesNotMatch(component, /SQL Server/); + assert.doesNotMatch(component, /SQLite/); + assert.doesNotMatch( + component, + /\/ktx\/brand\/(?:postgresql|snowflake|bigquery|clickhouse|mysql|sqlserver|sqlite|metabase|dbt|looker|notion)\.svg/, + ); + assert.doesNotMatch(component, /