SDK

Schift는 Python과 TypeScript용 일급 SDK(software development kit)와 터미널 워크플로우용 Python CLI(command-line interface)를 제공한다. 세 가지 인터페이스(interface)는 모두 동일한 REST API를 호출하고 동일한 API key(API 키)로 인증한다.

SDK 패키지

패키지	언어	설치	사용 사례
schift	Python	pip install schift	Python 앱, 노트북, 데이터 파이프라인
@schift-io/sdk	TypeScript	npm install @schift-io/sdk	Node, 브라우저, 대시보드 통합
schift-cli	Python CLI	pip install schift-cli	반복 가능한 터미널 워크플로우 및 운영

참고: 레거시 배포, 제공자, 에이전트 워크플로우와의 호환성을 위해 오래된 npm @schift-io/cli가 여전히 존재한다. 버킷(bucket), 카탈로그(catalog), 사용량(usage), 벤치마크(benchmark), 마이그레이션(migration) 워크플로우를 유지보수하려면 Python schift-cli 패키지를 사용하세요.

인증

워크스페이스(workspace) 대시보드에서 API key(API 키)를 생성한 다음, 환경 변수(environment variable)나 명시적인 생성자 인자(constructor argument)로 구성한다.

export SCHIFT_API_KEY=sch_your_key_here
export SCHIFT_API_URL=<your-api-url>/v1

이 환경에서는 SCHIFT_API_URL을 {apiUrl}/v1(으)로 설정하세요. SDK는 API origin(API 기본 주소)을 찾을 때 fallback(대체 값)으로 SCHIFT_BASE_URL도 읽는다. CLI는 먼저 SCHIFT_API_KEY를 읽고, 그 다음 schift auth login으로 기록된 ~/.schift/config.json을 fallback(대체 값)으로 사용한다.

환경 변수

변수	사용 대상	용도
SCHIFT_API_KEY	Python SDK, TypeScript SDK, CLI	API 키 (sch_...)
SCHIFT_API_URL	Python SDK, TypeScript SDK, CLI	전체 API 기본 URL, 보통 /v1로 끝남
SCHIFT_BASE_URL	Python SDK, TypeScript SDK	/v1 경로를 제외한 API origin

참고: SCHIFT_API_URL이 없을 때 SDK와 CLI는 운영 origin을 가정하지 않는다. 로컬, 스테이징, 호스팅 워크스페이스에 대해 명시적으로 설정하세요.

Python SDK

Python SDK는 두 가지 클라이언트 스타일을 제공한다.

• WorkspaceClient: 버킷(bucket) ingest(수집), search(검색), embedding(임베딩), usage(사용량), hosted workflow(호스팅 워크플로우) 등 실시간 API 작업용 모듈형 클라이언트이다.
• Client: 로컬에서 실행되는 Projection 객체를 fitting(학습)하고 다운로드하는 레거시 projection(투영) 클라이언트이다.

WorkspaceClient

from schift import WorkspaceClient

with WorkspaceClient() as client:
    bucket = client.buckets.create(name="finance-docs")
    upload = client.buckets.upload(
        bucket["id"],
        [("files", ("q1-report.pdf", open("q1-report.pdf", "rb").read(), "application/pdf"))],
    )
    hits = client.buckets.search(
        bucket["id"],
        "revenue guidance",
        top_k=5,
    )

WorkspaceClient는 공유 httpx.Client를 유지하므로, 짧게 실행되는 스크립트에는 context manager(컨텍스트 매니저) 사용을 권장한다. 장기 실행 프로세스의 경우 인스턴스 하나를 유지하고 종료 시 close()를 호출하세요.

핵심 모듈

모듈	예시 호출	용도
catalog	client.catalog.list()	임베딩 모델 목록 조회
embed	client.embed(text, model=...)	단일 텍스트 임베딩
embed.batch	client.embed.batch(texts=[...])	배치 임베딩
buckets	client.buckets.create(name=...)	버킷 수집 및 검색
db	client.db.upsert(collection=...)	원시 벡터 및 문서 upsert
query	client.query("...", bucket=...)	호스팅 버킷 또는 패스스루 검색
rerank	client.rerank(query, documents=[...])	후보 재정렬
providers	client.providers.set("openai", api_key=...)	BYOK 제공자 키
routing	client.routing.set(primary=..., fallback=...)	서버 측 모델 라우팅
pii	client.redact_pii(text, types=[...])	한국 PII 마스킹
usage	client.usage.get(period="30d")	사용량 요약
workflow	client.workflow.create_rag(name=...)	워크플로우 CRUD 및 실행
bench	client.bench.run(source=..., target=...)	마이그레이션 품질 벤치마크

레거시 projection 클라이언트

from schift import Client

legacy = Client(api_key="sch_your_key_here")
projection = legacy.fit(
    source=source_pairs,
    target=target_pairs,
    source_model="openai/text-embedding-3-small",
    target_model="google/gemini-embedding-001",
    project_name="openai-to-gemini",
)
projection.save("./projection-openai-to-gemini")

저장된 Projection(투영)은 오프라인으로 다시 불러와 로컬 migration(마이그레이션) 엔진에 적용할 수 있는다:

from schift import Projection
from schift.migrate import migrate
from schift.adapters.file import NpyAdapter

projection = Projection.load("./projection-openai-to-gemini")
source = NpyAdapter("old_embeddings.npy")
sink = NpyAdapter("new_embeddings.npy")

migrate(source=source, sink=sink, projection=projection, batch_size=2048)

TypeScript SDK

TypeScript SDK는 WorkspaceClient를 중심으로 구성된다.

import { WorkspaceClient } from "@schift-io/sdk";

const client = new WorkspaceClient({
  apiKey: process.env.SCHIFT_API_KEY!,
  baseUrl: process.env.SCHIFT_API_URL!,
});

await client.createBucket({ name: "company-docs" });
const file = new File([await readFile("manual.pdf")], "manual.pdf", {
  type: "application/pdf",
});
await client.db.upload("company-docs", { files: [file] });

const results = await client.bucketSearch("company-docs", {
  query: "refund policy",
  topK: 5,
});

핵심 메서드

메서드	용도
embed(request)	단일 텍스트 임베딩
embedBatch(request)	배치 임베딩
search(request)	벡터 검색
bucketSearch(nameOrId, request)	버킷 검색
chat(request)	버킷 기반 RAG 채팅
chatStream(request)	스트리밍 RAG 채팅
webSearch(query, maxResults?)	웹 검색
redactPii(request)	한국 PII 마스킹
mask(text, options)	편의 PII 마스크
restorePii(request)	PII 토큰 로컬 복원
providers.set(provider, config)	BYOK 제공자 키 등록
workflows.create(request)	워크플로우 생성
workflows.run(id, inputs)	워크플로우 실행
tools.openai() / tools.anthropic() / tools.vercelAI()	제공자 SDK용 도구 정의

참고: 완전한 TypeScript 클래스 및 타입 참고 자료는 SDK API 레퍼런스를 참조하세요.

CLI

Python schift-cli 패키지는 schift 실행 파일을 설치한다.

pip install schift-cli
schift auth login
schift auth status

명령 그룹

명령	용도
schift auth ...	로컬 인증 상태 관리
schift catalog ...	지원되는 임베딩 모델 조회
schift embed ...	텍스트에서 임베딩 생성
schift bench ...	두 모델 간 마이그레이션 품질 평가
schift migrate ...	투영 적합 및 데이터베이스 마이그레이션 실행
schift db ...	버킷 생성, 목록 조회, 상세 조회
schift upload ...	버킷에 파일 업로드
schift jobs ...	수집 작업 조회, 재처리, 취소
schift search ...	버킷 검색 실행
schift query ...	버킷 검색의 호환성 별칭
schift usage ...	집계된 사용량 및 과금 요약 표시

일반적인 워크플로우

export SCHIFT_API_KEY=sch_your_key_here
export SCHIFT_API_URL=<your-api-url>/v1

schift upload ./handbook.pdf --bucket company-docs
schift jobs list --bucket company-docs
schift search "revenue report" --bucket company-docs --top-k 5

SchiftIndex

SchiftIndex는 워크스페이스(workspace) 버킷(bucket)으로 반복 가능한 소스 수집을 위한 SDK 관리 sync surface(동기화 표면)이다. 팀이 로컬 manifest(매니페스트), text diff(텍스트 차이), checkpointed sync(체크포인트 동기화), retry(재시도), Obsidian vault(옵시디언 볼트) 동기화 같은 소스별 adapter(어댑터)가 필요할 때 사용하세요.

cd "/path/to/Obsidian Vault"
schift-index init --manifest schift.index.json --template dot-vault
SCHIFT_API_KEY=... schift-index sync --manifest schift.index.json --cloud

오류 처리

Python SDK 오류:

from schift import WorkspaceClient
from schift import AuthError, QuotaError, SDKError

try:
    with WorkspaceClient() as client:
        client.catalog.list()
except AuthError:
    ...
except QuotaError:
    ...
except SDKError:
    ...

TypeScript SDK 오류 클래스:

import { AuthError, QuotaError, PlatformError } from "@schift-io/sdk";

try {
  await client.embed({ text: "test" });
} catch (err) {
  if (err instanceof AuthError) {
    // 401
  } else if (err instanceof QuotaError) {
    // 402
  } else if (err instanceof PlatformError) {
    // 403, 422, 429, 500, 502
  }
}

같이 보기

• SDK API 레퍼런스
• 버킷(Buckets)
• 워크플로우 API
• 워크플로우 가이드
• 버킷 개념