Quickstart (빠른 시작) ·
CLI Reference (CLI 참조) ·
Agent Setup (에이전트 설정) ·
Slack

ktx는 에이전트가 승인된 지표 정의(metric definitions), 조인 가능한 컬럼(joinable columns), 그리고 비즈니스 지식으로부터 사용자의 데이터 웨어하우스(warehouse)를 정확하게 쿼리하는 방법을 학습하도록 돕는 자기 개선형 컨텍스트 레이어(context layer)입니다.

참고

ktx를 본인의 LLM API 키 또는 Claude Pro/Max 구독을 통해 실행하세요.
ktx로 인한 추가 사용 요금은 발생하지 않습니다.

범용 에이전트(General-purpose agents)는 데이터 작업에서 어려움을 겪습니다. 이들은 질문할 때마다 데이터 웨어하우스를 다시 탐색하고, 스스로 지표 로직을 만들어내며, 승인된 정의와 일치하지 않는 숫자를 반환합니다.

전통적인 시맨틱 레이어(semantic layers)는 이 문제를 해결하지 못합니다. 이들은 지속적인 수동 유지보수를 요구하며, 회사의 나머지 지식을 흡수하지 못합니다.

ktx는 이 두 가지를 자동으로 수행합니다:

기업 지식으로부터 학습합니다. 위키(wiki) 콘텐츠를 수집하고, 이를 정리하며, 중복을 제거하고, 검토를 위해 모순되는 부분을 인간에게 알립니다.
데이터 스택을 매핑합니다. 테이블을 샘플링하고, 메타데이터(metadata)와 사용 패턴을 캡처하며, 조인 가능한 컬럼을 탐지하고, 에이전트가 더 나은 쿼리를 작성할 수 있도록 소스에 주석을 답니다.
시맨틱 레이어를 구축합니다. 조인 그래프(join graph)를 통해 원시 테이블(raw tables)과 상위 수준의 지표(high-level metrics)를 결합하여 chasm trap 및 fan trap을 자동으로 해결합니다. 이를 통해 에이전트는 매번 표준 SQL(canonical SQL)을 다시 작성하는 대신 선언적(declaratively)으로 지표를 가져옵니다.
실행 시 에이전트에게 서비스를 제공합니다. 위키와 시맨틱 레이어 엔티티(entities) 전체에 걸친 전체 텍스트 검색(full-text search) 및 시맨틱 검색(semantic search)이 결합된 CLI 및 MCP 도구를 제공합니다.

	범용 에이전트 (General-purpose agent)	전통적인 시맨틱 레이어 (Traditional semantic layer)	ktx
데이터 웨어하우스 컨텍스트 자동 구축	—	—	✓
조인 가능한 컬럼 탐지 + fan/chasm trap 해결	—	수동 (Manual)	✓
...

다음과 같은 경우 ktx를 사용하세요:

• Claude Code, Codex, Cursor 또는 OpenCode와 같은 에이전트가 승인된 지표 정의를 사용하여 데이터 웨어하우스를 쿼리하기를 원하는 경우
• 비즈니스 지식이 dbt, Looker, Metabase, Notion 및 팀 위키에 흩어져 있는 경우
• 에이전트가 매 프롬프트마다 로직을 만들어내는 대신 표준 SQL(canonical SQL)을 재사용해야 하는 경우

다음과 같은 경우 ktx를 건너뛰세요:

• SQL 웨어하우스 (SQL warehouse)가 없는 경우 -
  ktx는 그 위에 구축됩니다 - 단 한 번의 즉석 쿼리 (ad-hoc query)만 필요한 경우 -
  psql

또는 노트북 (notebook)만 있어도 충분합니다.

PostgreSQL, Snowflake, BigQuery, ClickHouse, MySQL, SQL Server, SQLite와 함께 작동합니다. dbt, MetricFlow, LookML, Looker, Metabase, Notion과 통합됩니다.

npm install -g @kaelio/ktx
ktx setup
ktx status

ktx setup은

로컬 ktx 프로젝트를 생성하거나 재개하고, 프로바이더 (providers) 및 연결 (connections)을 구성하며, 컨텍스트 (context)를 구축하고, 에이전트 통합 (agent integration)을 설치합니다.

설정 후의 ktx status 예시:

ktx project: /home/user/analytics
Project ready: yes
LLM ready: yes (claude-sonnet-4-6)
...

팁

이미 에이전트를 사용 중인가요? 프로젝트 디렉토리에서 Claude Code, Codex, Cursor 또는 OpenCode에게 다음과 같이 요청하세요:

Run npx skills add Kaelio/ktx --skill ktx and use the ktx skill to install
and configure ktx in this project.

중요

만약 ktx status가

ktx mcp start --project-dir ...를

출력한다면, 에이전트 클라이언트 (agent client)를 열기 전에 이를 실행하세요.

명령 (Command)	목적 (Purpose)
ktx setup	ktx 프로젝트 생성, 재개 또는 업데이트
ktx status	프로젝트 준비 상태 확인
ktx ingest	구성된 모든 연결에 대한 컨텍스트 구축
ktx sl "revenue"	시맨틱 소스 (semantic sources) 검색
ktx wiki "refund policy"	로컬 위키 (wiki) 페이지 검색
ktx mcp start	에이전트 클라이언트를 위한 MCP 서버 시작

모든 명령, 플래그 (flag) 및 옵션 (option)에 대해서는 CLI 레퍼런스 (CLI Reference)를 참조하세요.

my-project/
├── ktx.yaml # 프로젝트 구성 (Project configuration)
├── semantic-layer/<connection-id>/ # YAML 시맨틱 소스 (semantic sources)
...

ktx.yaml, semantic-layer/, wiki/는 커밋 (Commit) 하세요. .ktx/는 로컬에 유지하세요.

프로젝트 탐색 (Project resolution)은 기본적으로 KTX_PROJECT_DIR을 확인하고, 그다음 가장 가까운 ktx.yaml을, 그다음 현재 디렉토리를 확인합니다. 스크립팅 시에는 --project-dir <path>를 전달하세요.

ktx가 저의 스키마(schema)나 쿼리 결과를 호스팅된 서비스로 전송하나요?
아니요.
ktx는 로컬(locally)에서 실행됩니다. 사용자의 머신을 떠나는 유일한 데이터는 사용자가 설정한 LLM 제공업체로 전송하는 데이터뿐입니다.

어떤 LLM 백엔드(backends)가 지원되나요?
Anthropic API, Google Vertex AI, AI Gateway, 그리고 Claude Agent SDK를 통한 로컬 Claude Code 세션이 지원됩니다. LLM 설정(LLM configuration)을 참조하세요.

ktx는 dbt나 MetricFlow 시맨틱 레이어(semantic layer)와 어떻게 다른가요?
ktx는 해당 레이어들을 흡수(ingests)하여 원시 테이블 조사(raw-table introspection) 및 위키(wiki) 콘텐츠와 결합합니다. 에이전트(Agents)는 분리된 세 개의 표면 대신 하나의 검색 가능한 표면을 갖게 되며, ktx는 여러 소스 간의 모순을 표시(flags)합니다.

ktx를 실행하려면 서버가 돌아가고 있어야 하나요?
호스팅된 서비스는 없습니다. 로컬 MCP 데몬(daemon)은 에이전트 클라이언트가 필요할 때 ktx mcp start를 통해 온디맨드(on demand)로 실행됩니다.

저의 데이터 웨어하우스(warehouse)는 안전한가요?
네. 연결은 읽기 전용(read-only)입니다. ktx는 사용자의 데이터베이스에 절대 쓰기(write)를 수행하지 않습니다.

Slack— 질문을 하고, 만들고 있는 것을 공유하며, 유지 관리자(maintainers)와 대화하세요.
GitHub Issues— 버그를 보고하고 기능을 요청하세요.
Contributing— 저장소(repo)를 설정하고, 테스트를 실행하며, PR(Pull Request)을 생성하세요.

git clone https://github.com/kaelio/ktx.git
cd ktx
pnpm install
...

ktx는 pnpm + uv 워크스페이스(workspace)입니다:

경로	용도
packages/cli	TypeScript CLI 및 배포된 npm 패키지 소스
packages/cli/src/context	핵심 컨텍스트 엔진 (Core context engine)
packages/cli/src/llm	LLM 및 임베딩(embedding) 제공업체
packages/cli/src/connectors	데이터베이스 스캔 커넥터 (Database scan connectors)
python/ktx-sl	시맨틱 레이어(Semantic-layer) 쿼리 계획
python/ktx-daemon	휴대 가능한 컴퓨팅 서비스 (Portable compute service)

로컬 개발용 CLI:

pnpm run setup:dev
pnpm run link:dev
ktx-dev --help

유용한 체크 사항:

pnpm run type-check
pnpm run test
pnpm run dead-code
...

ktx는 설정, 명령 신뢰성 및 데이터 에이전트(data-agent) 워크플로우를 개선하기 위해 대화형 CLI 실행으로부터 익명의 사용 텔레메트리(telemetry)를 수집합니다. 파일 경로, 호스트 이름, SQL, 스키마 이름, 에러 메시지 또는 argv는 기록되지 않습니다. 이벤트 카탈로그 및 옵트아웃(opt-out) 옵션은 텔레메트리(Telemetry) 섹션을 참조하세요.

ktx는 Apache License, Version 2.0에 따라 라이선스가 부여됩니다. LICENSE를 참조하세요.