사용자 머신                              XTrace 서버
┌────────────────────────┐                ┌─────────────────────────┐
│                        │                │                         │
│  문서 + 질의            │                │  암호문만 저장           │
│         │              │                │                         │
│         ▼              │                │  암호화된 벡터           │
│  임베딩 후 암호화        │── 암호문 ────▶│  검색                   │
│  (키는 여기에 유지)      │                │  (절대 복호화하지 않음)   │
│         ▲              │                │                         │
│         │              │◀─ 암호문 ────│  암호화된 결과 반환       │
│  결과 복호화             │                │                         │
│                        │                │                         │
└────────────────────────┘                └─────────────────────────┘
  비밀 키는 절대 떠나지 않음                   영지식

# Base SDK
uv pip install xtrace-ai-sdk

# 로컬 임베딩 지원 포함 (Sentence Transformers)
uv pip install "xtrace-ai-sdk[embedding]"

cd docs && make html

uv pip install "xtrace-ai-sdk[cli]"

xtrace init                                    # 자격 증명 + 암호화 키 설정
xtrace kb create my-first-kb                   # 지식 베이스 생성 (KB ID 기록)
xtrace xvec load ./my-docs/ <KB_ID>            # 문서 암호화 후 업로드
xtrace xvec retrieve <KB_ID> "your query"      # 검색

import asyncio
from xtrace_sdk.x_vec.utils.execution_context import ExecutionContext
from xtrace_sdk.x_vec.crypto.key_provider import PassphraseKeyProvider
from xtrace_sdk.x_vec.data_loaders.loader import DataLoader
from xtrace_sdk.x_vec.inference.embedding import Embedding
from xtrace_sdk.integrations.xtrace import XTraceIntegration
from xtrace_sdk.x_vec.retrievers.retriever import Retriever

# One-time setup: generate your private cryptographic state and save it
provider = PassphraseKeyProvider("your-secret-passphrase")
ctx = ExecutionContext.create(
    key_provider=provider,
    homomorphic_client_type="paillier_lookup",
    embedding_length=512,
    key_len=1024,
    path="data/exec_context",
)

embed  = Embedding("sentence_transformer", "mixedbread-ai/mxbai-embed-large-v1", 512)
xtrace = XTraceIntegration(org_id="your_org_id", api_key="your_api_key")

async def main():
    # Encrypt and store documents — content and vectors never leave in plaintext
    loader = DataLoader(ctx, xtrace)
    docs   = [{"chunk_content": "XTrace encrypts your embeddings.", "meta_data": {}}]
    vectors = [await embed.bin_embed(d["chunk_content"]) for d in docs]
    index, db = await loader.load_data_from_memory(docs, vectors)
    await loader.dump_db(db, index=index, kb_id="your_kb_id")

    # Query with an encrypted vector — the server never sees the query in plaintext
    retriever = Retriever(ctx, xtrace)
    vec     = await embed.bin_embed("How does XTrace protect my data?")
    ids     = await retriever.nn_search_for_ids(vec, k=3, kb_id="your_kb_id")
    results = await retriever.retrieve_and_decrypt(ids, kb_id="your_kb_id")
    for r in results:
        print(r["chunk_content"])

asyncio.run(main())

uv pip install -e ".[dev]"
pytest tests/x_vec/