7d156d9a06
* feat(docs): visualize KTX ingestion with ReactFlow diagram Reframe the introduction around the two user-facing ingestion outputs (wiki and executable semantic layer) and replace the static product-mechanics card flow with a ReactFlow diagram: sources fan into a sequential ingest pipeline, which forks into wiki and semantic-layer outputs connected by a bidirectional "references" edge. Drop the .ktx/raw-sources internal-implementation rows from the intro table and update the content test to guard the new copy. * Improve KTX docs introduction * feat(docs): animate ingestion flow with running dots Replace static smoothstep edges in the introduction page's ingestion diagram with a custom animated edge that runs glowing cyan dots along each path, conveying the source → stage → output flow. Dot duration scales with path length and is hidden under prefers-reduced-motion. * feat(docs): route ingestion atoms through full source→output journey Replace per-edge dots with full-journey particles: each atom is born at a source, threads the entire stage chain, and lands at either the wiki or semantic layer. Particles are tinted by their source's accent so the origin is legible. Each source produces exactly 2 atoms (8 total) to guarantee every input is visibly active, while the destination and begin offsets are randomized per page load. Particles populate on client mount to avoid hydration mismatch, and are hidden under prefers-reduced-motion. |
||
|---|---|---|
| .github/workflows | ||
| assets | ||
| docs | ||
| docs-site | ||
| examples | ||
| packages | ||
| python | ||
| scripts | ||
| website | ||
| .gitignore | ||
| .pre-commit-config.yaml | ||
| .releaserc.cjs | ||
| AGENTS.md | ||
| biome.json | ||
| CLAUDE.md | ||
| conductor.json | ||
| GEMINI.md | ||
| knip.json | ||
| LICENSE | ||
| package.json | ||
| pnpm-lock.yaml | ||
| pnpm-workspace.yaml | ||
| pyproject.toml | ||
| README.md | ||
| release-policy.json | ||
| tsconfig.base.json | ||
| uv.lock | ||
The context layer for analytics agents
by Kaelio
KTX turns warehouse metadata, semantic definitions, and business knowledge into reviewable project files that agents can use to plan, query, and update analytics work.
Use KTX when you want agents to:
- Generate SQL from approved measures and joins
- Repair semantic definitions through reviewable diffs
- Explain metric provenance with warehouse evidence
- Work alongside dbt, MetricFlow, LookML, Looker, Metabase, and Notion
Supports PostgreSQL, Snowflake, BigQuery, ClickHouse, MySQL, SQL Server, and SQLite.
Quick Start
pnpm add --global @kaelio/ktx
ktx setup
ktx status
ktx setup creates or resumes a local KTX project, configures providers and
connections, builds context, and installs agent integration.
Example ktx status output after setup:
KTX project: /home/user/analytics
Project ready: yes
LLM ready: yes (claude-sonnet-4-6)
Embeddings ready: yes (text-embedding-3-small)
Databases configured: yes (postgres-warehouse)
Context sources configured: yes (dbt-main)
KTX context built: yes
Agent integration ready: yes (codex:project)
Common Commands
| Command | Purpose |
|---|---|
ktx setup |
Create, resume, or update a KTX project |
ktx status |
Check project readiness |
ktx connection list |
List configured connections |
ktx connection test <id> |
Test one connection |
ktx ingest <id> |
Build context for one connection |
ktx ingest --all |
Build context for every configured connection |
ktx ingest text <file> |
Capture free-form notes into memory |
ktx sl list |
List semantic-layer sources |
ktx sl search "revenue" |
Search semantic-layer sources |
ktx sl validate <source> --connection-id <id> |
Validate a semantic source |
ktx sl query --measure <measure> --format sql |
Compile semantic-layer SQL |
ktx sql --connection <id> "select 1" |
Execute read-only SQL |
ktx wiki search "revenue definition" |
Search local wiki context |
ktx mcp start |
Start the local MCP server for agent clients |
Project resolution defaults to KTX_PROJECT_DIR, then the nearest ktx.yaml,
then the current directory. Pass --project-dir <path> when scripting.
Project Layout
my-project/
├── ktx.yaml # Project configuration
├── semantic-layer/<connection-id>/ # YAML semantic sources
├── wiki/global/ # Shared business context
├── wiki/user/<user-id>/ # User-scoped notes
├── raw-sources/<connection-id>/ # Ingest artifacts and reports
└── .ktx/ # Local state and secrets, git-ignored
Commit ktx.yaml, semantic-layer/, and wiki/. Keep .ktx/ local.
Agent Usage
Setup can install KTX instructions for Claude Code, Codex, Cursor, OpenCode,
and universal .agents clients:
ktx setup --agents --target codex
Agent-facing workflows typically start with:
ktx sl search "revenue" --json
ktx wiki search "refund policy" --json
ktx sl query --connection-id warehouse --measure orders.revenue --format sql
During agent setup, choose MCP tools + analytics skill for client agents.
Choose MCP tools + analytics skill + admin CLI skill only when a developer
or operator agent also needs pinned ktx admin commands.
The analytics skill teaches client agents the MCP workflow: discover data,
prefer semantic-layer measures, inspect entity details before raw SQL, and
capture durable learnings. Admin CLI skills call ktx commands directly
through a skill file installed in your agent's config:
ktx sl query --measure orders.revenue --dimension orders.status --format sql
ktx wiki search "revenue definition"
ktx sl validate orders
Supported client agents: Claude Code, Claude Desktop, Codex, Cursor, OpenCode,
and clients that can use the printed MCP endpoint or .agents admin skills.
Claude Desktop setup registers a local ktx mcp stdio server in Claude
Desktop's config and generates .ktx/agents/claude/ktx-plugin.zip with the
analytics skill.
The release artifact manifest contains the public npm tarball and the bundled
kaelio-ktx runtime wheel. The python/ktx-sl and python/ktx-daemon
directories remain source packages for development, not public release
artifacts.
Workspace packages
| Package | Purpose |
|---|---|
packages/cli |
CLI entry point |
packages/context |
Core context engine |
packages/llm |
LLM and embedding providers |
packages/connector-bigquery |
BigQuery scan connector |
packages/connector-clickhouse |
ClickHouse scan connector |
packages/connector-mysql |
MySQL scan connector |
packages/connector-postgres |
Postgres scan connector |
packages/connector-snowflake |
Snowflake scan connector |
packages/connector-sqlite |
SQLite scan connector |
packages/connector-sqlserver |
SQL Server scan connector |
python/ktx-sl |
Semantic-layer query planning |
python/ktx-daemon |
Portable compute service |
Development
git clone https://github.com/kaelio/ktx.git
cd ktx
pnpm install
uv sync --all-groups
pnpm run build
pnpm run check
Use the development CLI locally:
pnpm run setup:dev
pnpm run link:dev
ktx-dev --help
KTX is a pnpm + uv workspace:
- TypeScript packages live in
packages/* - CLI source lives in
packages/cli - Python runtime source lives in
python/ktx-slandpython/ktx-daemon - Public docs live in
docs-site/content/docs
Useful checks:
pnpm run type-check
pnpm run test
pnpm run dead-code
uv run pytest -q
Docs
License
KTX is licensed under the Apache License, Version 2.0. See LICENSE.