docs · v0.7.8 · 빌드 키트

60초 만에 kolm으로 빌드

이 페이지의 모든 예제는 2026-05-11에 kolm.ai에서 실제로 캡처된 응답입니다. 아무 블록이나 복사해 터미널에 붙여넣으면 동작합니다. 동작하지 않으면 이슈를 등록해 주세요.

코드 블록, CLI 명령, API 엔드포인트, 환경 변수 이름, JSON 키는 언어와 무관하게 동일하므로 영문 그대로 유지합니다.

빠른 시작

가입하고 키를 받고, 예제 두 개로 마스킹 (redaction) 함수를 컴파일해 실제 입력에 실행해 봅니다. 여섯 줄이면 끝납니다.

$ curl -sX POST https://kolm.ai/v1/signup \
    -H 'content-type: application/json' \
    -d '{"email":"you@example.com","plan":"free"}'
$ export KOLM_KEY=ks_...                            # 위 응답에서 가져옵니다
$ curl -sX POST https://kolm.ai/v1/synthesize \
    -H "authorization: Bearer $KOLM_KEY" -H 'content-type: application/json' \
    -d '{"name":"redact","positives":[{"input":"token=sk_live_xxx","expected":"[REDACTED]"}]}'
$ curl -sX POST https://kolm.ai/v1/run \
    -H "authorization: Bearer $KOLM_KEY" -H 'content-type: application/json' \
    -d '{"concept_id":"cpt_...","input":"my token=sk_live_abc123"}'

40 마이크로초, HMAC 하나, 서명된 영수증 (signed receipt) 하나. 이게 전부입니다.

인증 (Authentication)

authorization 헤더에 Bearer 토큰을 사용합니다. 토큰은 POST /v1/signup 또는 /signup에서 받습니다. Free 플랜에는 월 10,000회 호출이 포함됩니다.

curl -H "authorization: Bearer ks_..." https://kolm.ai/v1/account

CLI 설치

npm i -g github:sneaky-hippo/kolmogorov-stack
kolm login

회원가입 (Sign up)

POST/v1/signupno auth

curl -X POST https://kolm.ai/v1/signup \
  -H 'content-type: application/json' \
  -d '{"email":"you@example.com","plan":"free"}'

주의: API 키는 한 번만 표시됩니다. 잘 보관해 두세요. 분실 시 POST /v1/account/rotate-key로 회전할 수 있습니다.

Synthesize (합성)

입력/기대 출력 쌍의 목록을, 분류·마스킹·변환을 수행하는 컴파일된 JavaScript 함수로 바꿉니다. concept_id와 품질 점수를 반환합니다.

POST/v1/synthesizebearer

curl -X POST https://kolm.ai/v1/synthesize \
  -H "authorization: Bearer $KOLM_KEY" \
  -H 'content-type: application/json' \
  -d '{ "name":"redact-secrets", "positives":[ { "input":"token=sk_live_xxx", "expected":"[REDACTED]" } ] }'

K-score 게이트는 기본 0.85입니다. 게이트 미만의 컴파일은 실패한 축을 명시하며 accepted: false를 반환합니다. 예제를 더 추가하거나 spec을 조정해 다시 제출하세요.

Run (실행)

컴파일된 concept을 새 입력에 대해 실행합니다. 출력과 함께, 같은 키를 가진 누구나 재검증할 수 있는 서명된 영수증을 반환합니다.

POST/v1/runbearer

curl -X POST https://kolm.ai/v1/run \
  -H "authorization: Bearer $KOLM_KEY" \
  -H 'content-type: application/json' \
  -d '{ "concept_id":"cpt_mp11ol06a...", "input":"my token=sk_live_abc123" }'

영수증 (Receipts)

오늘 제공되는 것: 각 .kolm 아티팩트는 아카이브 내용 (manifest + 레이어 해시) 전체에 대한 단일 HMAC-SHA256 서명을 보유합니다. 각 /v1/run 응답은 source_hash · input_hash · output_hash · version_id · issued_at을 포함한 _kolm 메타데이터 블록을 반환하며, 발행자 또는 공유 테넌트 영수증 시크릿 보유자라면 누구나 재검증할 수 있습니다. 목표 아키텍처: 요청 간 호출별 HMAC 체이닝과 Ed25519 공개키 영수증은 로드맵에 있으며 아직 제공되지 않습니다.

.kolm 포맷

다섯 개의 파일을 담은 서명된 zip입니다: spec.json (레시피), policy.json (게이트), recall/ (옵션 사이드카), verifier.js (저비용 출력 확인), receipt.json (HMAC 체인). 전체 스키마는 /spec에 있습니다.

K-score

모델 단위가 아니라 아티팩트 단위. 컴파일된 각 .kolm은 자체 평가 세트에서 자체 K-score를 받습니다. 이 점수는 그 아티팩트를 평가하는 것이지, 그 아래의 베이스 모델을 평가하는 것이 아닙니다. 단일 스칼라이며, 배포 기준은 0.85입니다. 계산식은 0.40·A + 0.15·(S + L + C + V)로, 여기서 A는 정확도 (accuracy), S는 특이도 (specificity), L은 지연 (latency), C는 비용 (cost), V는 검증가능성 (verifiability)입니다. 전체 내역은 /k-score에 있습니다.

CLI

여덟 개의 동사가 전체 루프를 다룹니다. API와 동일한 인증을 사용합니다. kolm login은 키를 ~/.kolm/config.json에 저장합니다.

kolm init              # kolm.yaml + examples/ 스캐폴드
kolm compile           # synthesize · 서명 · .kolm 작성
kolm run file.kolm     # 실행 후 영수증 발급
kolm tune --airgap     # 캡처된 실행에서 LoRA 어댑터 학습
kolm rag attach docs/  # BM25 사이드카 빌드
kolm serve --mcp       # Claude Code / Cursor용 로컬 MCP 서버
kolm install claude-code   # 에이전트 하네스 연결
kolm doctor            # env, 키, 포트, 버전 점검

MCP serve

kolm serve --mcp는 로컬 아티팩트를 stdio를 통해 MCP 도구로 노출합니다 (MCP 기본 방식). 클라이언트는 이를 서브프로세스로 실행하며, kolm install <harness> --apply는 claude-code / cursor / continue / cline에 맞는 위치에 spawn 설정을 기록합니다. --http를 전달하면 127.0.0.1:8765에 선택적 HTTP JSON-RPC 엔드포인트가 추가됩니다.

원격 접근

기본 배포는 로컬입니다. kolm serve --local은 런타임을 사용자의 기기에 바인딩하며, 노트북·휴대폰·코딩 에이전트는 사용자가 통제하는 네트워크로 접근합니다. 프롬프트와 출력은 결코 우리의 인프라를 거치지 않습니다. 거칠 인프라 자체가 없기 때문입니다.

벤더를 신뢰하지 않고도 호스팅된 접근을 원하는 팀이라면, 동일한 .kolm을 TEE (Trusted Execution Environment, 신뢰 실행 환경) 안에서 실행할 수 있습니다. 하드웨어 엔클레이브 (AWS Nitro, GCP Confidential, Azure SEV)가 모델, 가중치, 요청 데이터를 봉인하여 kolm도 클라우드 제공자도 읽을 수 없게 합니다. 상대적으로 안전하고 상대적으로 사적입니다. 암호학적 보장은 아니지만, 클라우드 호스팅 추론에 대해 가장 솔직한 표현입니다.

OpenAI 호환성

런타임은 localhost:8765에서 /v1/chat/completions, /v1/models, /v1/embeddings를 노출합니다. OpenAI 호환 클라이언트를 그곳으로 연결하면 됩니다. tool call과 스트리밍은 문서대로 동작합니다. 모든 요청은 서명된 영수증을 발급합니다.

컴플라이언스 팩 (Compliance packs)

컴플라이언스 팩은 (recipe.json + evidence.md + dpia.md + mrm.md + controls.md)의 버전 관리된 번들로, 어떤 마스킹이 필수인지, 어떤 필드를 검증해야 하는지, 감사관이 무엇을 물을지를 부호화합니다. 그래서 엔지니어링 팀이 법무팀이 승인한 동일한 목표에 대해 빌드하게 됩니다.

오늘 세 개의 팩이 제공되며, 각각 data/compliance-packs/<pack>/ 아래에 있습니다: HIPAA (PHI 마스킹, K 기준 0.92), SR 11-7 (Fed Model Risk Management), SOX-lite (AI를 위한 ITGC).

이 번역에 대해

한국어판은 요약본만 다룹니다. 코드 블록, CLI 명령, API 엔드포인트, JSON 형식, 오류 코드는 언어와 무관하므로 영문 그대로입니다. 전체 레퍼런스와 모든 튜토리얼, 최신 예제는 정본 영문 문서를 참조하세요: kolm.ai/docs.