ktx 소개
범용 코딩 에이전트에게 회사 데이터 웨어하우스를 물어보면 매번 스키마를 처음부터 다시 탐색하고, 지표(metric) 계산 로직을 제멋대로 만들어 내며, 사내에서 합의된 정의와 어긋나는 숫자를 돌려주기 쉽습니다. ktx는 이 문제를 풀기 위한 데이터·분석 에이전트용 컨텍스트 레이어(context layer)입니다. 승인된 지표 정의, 조인 가능한 컬럼, 비즈니스 지식을 스스로 만들고 유지하면서, 에이전트가 웨어하우스를 정확하게 질의하도록 가르칩니다.
전통적인 시맨틱 레이어(semantic layer)도 이 문제를 완전히 해결하지는 못합니다. 수작업 유지보수가 계속 필요하고, 회사의 나머지 지식을 흡수하지도 못하기 때문입니다. ktx는 데이터 스택을 자동으로 파악하고 시맨틱 레이어를 구축하는 일과, 위키·문서에 흩어진 지식을 받아들이는 일을 함께 자동화합니다. 그 결과 에이전트는 매 질문마다 SQL을 새로 쓰는 대신, 승인된 지표를 선언적으로 가져올 수 있습니다.
ktx는 로컬에서 동작하며, 웨어하우스 연결은 읽기 전용(read-only)으로 설계되어 데이터베이스에 절대 쓰기를 하지 않습니다. 별도의 호스팅 서비스가 없고, 사용자가 직접 설정한 LLM 제공자로 보내는 것 외에는 어떤 데이터도 기기를 떠나지 않습니다. 모델은 자신의 API 키나 로컬 에이전트 로그인(Claude Code의 Claude Pro/Max 구독, 또는 로컬 Codex 인증)으로 구동하며, ktx가 별도의 사용료를 매기지 않습니다.
ktx가 컨텍스트를 만드는 방법
ktx는 데이터베이스(스키마·키·쿼리 이력), BI 도구(대시보드·탐색·사용 패턴), 모델링 코드(지표·모델·조인·엔티티), 그리고 문서와 노트를 소스로 받아들입니다. 이들을 소스 커넥터로 각 소스의 형태 그대로 읽고, 컨텍스트 빌더가 증거를 제안된 업데이트로 정리하며, 기존 컨텍스트와 병합(reconciliation)한 뒤, 참조와 의미를 검증(validation)합니다.
이 과정의 산출물은 두 가지입니다. 하나는 정의·주의사항·정책·노트를 담아 에이전트가 검색할 수 있는 wiki/*.md 형태의 위키이고, 다른 하나는 지표·조인·차원·필터를 담아 ktx가 SQL로 컴파일하는 semantic-layer/*.yaml 형태의 시맨틱 레이어입니다. 시맨틱 레이어는 원시 테이블과 상위 지표를 조인 그래프(join graph)로 결합해 채즘 트랩(chasm trap)과 팬 트랩(fan trap)을 자동으로 해소하므로, 에이전트가 정규 SQL을 매번 새로 쓰지 않아도 됩니다. ktx는 위키를 정리하면서 중복을 제거하고 소스 간 모순을 사람이 검토하도록 표시합니다.
ktx가 에이전트에 컨텍스트를 제공하는 방법
에이전트는 MCP(Model Context Protocol)를 통해 ktx에 질문합니다. ktx는 위키와 시맨틱 레이어를 전문(full-text)·의미(semantic) 검색으로 함께 뒤져 승인된 지표를 반환하고, 그 지표를 읽기 전용 SQL로 컴파일해 웨어하우스에서 실행한 뒤 결과를 에이전트에 돌려줍니다. Claude Code, Codex, Cursor, OpenCode 같은 에이전트가 이 방식으로 사내에서 합의된 정의에 맞는 답을 얻습니다.
기존 방식과 ktx의 차이
ktx는 저장소에서 범용 에이전트, 전통적 시맨틱 레이어와 자신을 다음과 같이 비교합니다.
| 항목 | 범용 에이전트 | 전통적 시맨틱 레이어 | ktx |
|---|---|---|---|
| 웨어하우스 컨텍스트 자동 구축 | — | — | ✓ |
| 조인 가능 컬럼 탐지 + 팬/채즘 트랩 해소 | — | 수작업 | ✓ |
| 승인된 재사용 지표 정의 | — | ✓ | ✓ |
| 위키·Notion·팀 지식 흡수 | — | — | ✓ |
| 소스 간 모순 표시 | — | — | ✓ |
| 에이전트 실행용 CLI + MCP 제공 | 부분적 | — | ✓ |
ktx 설치와 사용
ktx는 npm 패키지로 설치한 뒤 ktx setup 으로 프로젝트를 만들거나 이어서 설정합니다.
npm install -g @kaelio/ktx
ktx setup
ktx status
주요 명령으로는 연결마다 컨텍스트를 빌드하는 ktx ingest, 시맨틱 소스를 검색하는 ktx sl "revenue", 로컬 위키를 검색하는 ktx wiki "refund policy", 그리고 에이전트 클라이언트를 위한 MCP 서버를 띄우는 ktx mcp start 가 있습니다. ktx는 PostgreSQL, Snowflake, BigQuery, ClickHouse, MySQL, SQL Server, SQLite, DuckDB, Amazon Athena, MongoDB를 지원하며, dbt, MetricFlow, LookML, Looker, Metabase, Sigma, Notion, Google Drive와 연동됩니다. 지원하는 LLM 백엔드는 Anthropic API, Google Vertex AI, AI Gateway, 그리고 Claude Agent SDK를 통한 로컬 Claude Code 세션과 Codex SDK를 통한 로컬 Codex 인증입니다.
ktx의 라이선스
ktx는 Apache License 2.0으로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.
ktx 문서 사이트
ktx 프로젝트 GitHub 저장소
더 읽어보기
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다! 텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다. 
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 