ktx는 AI 에이전트가 SQL 웨어하우스를 정확하게 쿼리할 수 있도록 승인된 메트릭 정의, 조인 가능한 컬럼, 비즈니스 지식을 자동으로 구축하고 유지 관리하는 오픈소스 컨텍스트 레이어입니다.
Overview
일반적인 AI 에이전트는 데이터 작업 시 매번 웨어하우스를 재탐색하고 자체 메트릭 로직을 발명하여 승인된 정의와 일치하지 않는 숫자를 반환하는 문제를 겪습니다. 기존 시맨틱 레이어는 수동 유지보수가 필요하고 회사의 비즈니스 지식을 흡수하지 못합니다. ktx는 이러한 문제를 해결하기 위해 설계된 실행 가능한 컨텍스트 레이어로, Claude Code, Codex, Cursor 등 다양한 AI 에이전트와 통합됩니다.
ktx는 MCP(Model Context Protocol)를 통해 에이전트에 서비스되며, 로컬에서 실행되어 스키마나 쿼리 결과를 외부 호스티드 서비스로 전송하지 않습니다.
How It Works
ktx는 두 가지 주요 흐름으로 동작합니다.
컨텍스트 구축 (Ingestion)
- 소스 연결: 데이터베이스(PostgreSQL, Snowflake, BigQuery, ClickHouse, MySQL, SQL Server, SQLite), BI 도구(Looker, Metabase, dbt, MetricFlow, LookML), 위키(Notion 등)를 연결합니다.
- 컨텍스트 엔진: 소스에서 메타데이터, 사용 패턴, 문서를 수집합니다.
- 정리 및 검증: 중복 제거, 모순 플래깅, 테이블 샘플링, 조인 가능한 컬럼 탐지, 소스 주석 처리를 수행합니다.
- 출력: 위키 Markdown과 시맨틱 레이어 YAML을 생성합니다.
쿼리 서빙 (Serving)
- 에이전트가 MCP를 통해 ktx에 쿼리합니다.
- ktx가 위키와 시맨틱 레이어에서 전체 텍스트 및 시맨틱 검색을 수행합니다.
- 승인된 메트릭과 컨텍스트를 반환합니다.
- 읽기 전용 SQL로 컴파일하여 웨어하우스에 실행합니다.
주요 특징
- 자동 지식 학습: 회사 위키, 문서를 수집, 정리, 중복 제거 및 모순 플래깅.
- 데이터 스택 매핑: 테이블 샘플링, 메타데이터 캡처, 조인 가능 컬럼 탐지.
- 시맨틱 레이어 구축: chasm trap과 fan trap을 자동으로 해결하는 조인 그래프를 통해 선언적 메트릭 접근 제공.
- MCP 및 CLI 제공:
ktx mcp start로 MCP 서버 실행,ktx sl "revenue"로 시맨틱 검색,ktx wiki "refund policy"로 위키 검색. - 읽기 전용 설계: 데이터베이스에 쓰기 작업을 절대 수행하지 않음.
Setup
npm install -g @kaelio/ktx
ktx setup
ktx statusktx setup은 로컬 ktx 프로젝트를 생성하고, 공급자와 연결을 구성하며, 컨텍스트를 구축하고 에이전트 통합을 설치합니다.
프로젝트 구조
my-project/
├── ktx.yaml # 프로젝트 설정
├── semantic-layer/<connection-id>/ # YAML 시맨틱 소스
├── wiki/global/ # 공유 비즈니스 컨텍스트
├── wiki/user/<user-id>/ # 사용자별 노트
├── raw-sources/<connection-id>/ # 수집 아티팩트
└── .ktx/ # 로컬 상태 및 시크릿