Ktx: Open-source context layer to make AI agents reliable on analytics data

AI agents are transforming how teams work with data, but their biggest weakness remains accuracy. When tasked with writing SQL against complex analytics warehouses, these agents frequently produce technically valid yet contextually flawed queries. A new open-source tool called ktx addresses this challenge by introducing an executable context layer that integrates with existing data stacks.

The core problem: why agents struggle with analytics

AI agents excel at generating syntactically correct SQL, but that doesn’t guarantee correct business logic. Consider these real-world scenarios where agents have failed:

• Deprecated column references: A finance team asks an agent for "ARR by customer segment." The agent combines data from multiple tables but unknowingly uses a column that was deprecated months ago, producing reports based on outdated assumptions.

• Join fanout errors: A retail analyst queries product revenue by joining orders to order_items and summing order totals. The SQL executes without errors, but revenue is multiplied once per line item, distorting results unless carefully inspected.

• Attribution mismatches: A marketing team asks which campaigns drove revenue. The agent joins marketing_touches to users to orders but fails to account for the team’s specific attribution model (first touch, last touch, etc.), leading to misguided budget decisions.

These failures stem from agents lacking the executable context that defines business rules, join logic, and data relationships. Traditional solutions like standalone semantic layers or wiki-based documentation provide partial fixes but introduce new challenges in maintenance and context integration.

How ktx bridges the gap between AI and analytics

ktx solves this by splitting context into two complementary formats:

1. Business context: Stored in Markdown wiki pages that are automatically ingested and updated. This includes business definitions, deprecated columns, hidden rules, and any unstructured knowledge relevant to data queries.

1. Technical definitions: Defined in YAML files that specify tables, row grain, joins, measures, dimensions, filters, and filter groups. These files serve as executable documentation that agents can reference when constructing queries.

When an agent needs a metric, it no longer writes raw SQL. Instead, it requests a measure, dimensions, filters, and filter groups from ktx. The tool’s planner:

• Determines the optimal join paths
• Validates row grain consistency
• Prevents join fanout and chasm joins
• Compiles warehouse-specific SQL
• Cross-references unstructured knowledge from the Markdown wiki

This approach combines the reliability of a semantic layer with the flexibility of unstructured documentation, ensuring agents operate within defined business logic without losing access to contextual insights.

Getting started with ktx

ktx supports ingestion from a wide range of sources, including:

• Analytics warehouses (BigQuery, Snowflake, PostgreSQL)
• Modeling tools (dbt, MetricFlow, LookML)
• BI platforms (Looker, Metabase)
• Documentation systems (Notion)

Users can also incorporate corrections from manual interactions, allowing teams to refine outputs over time.

Installation is straightforward:

npm install -g @kaelio/ktx

ktx setup

Alternatively, deploy it via an agent with:

Run npx skills add Kaelio/ktx --skill ktx and use ktx skill to install and configure ktx

What’s next for executable context layers

The release of ktx highlights a growing trend: AI agents need more than just data access to deliver reliable results. They require executable context—structured metadata paired with unstructured knowledge—that aligns technical execution with business intent.

For teams that have struggled with AI-generated SQL errors or spent months building brittle semantic layers, ktx offers a promising alternative. Its open-source nature invites collaboration, allowing the community to refine context definitions and expand integrations.

As AI adoption in analytics accelerates, tools like ktx will likely become essential infrastructure. The focus will shift from "Can the agent write SQL?" to "Can the agent write correct SQL that aligns with our business rules?"