xtraceai/xtrace-sdkversión de código abierto del xtrace sdk
La base de datos vectorial cifrada.
Tus datos nunca salen de tu máquina en texto plano.
Todas las bases de datos vectoriales del mercado requieren que entregues tus datos a un tercero en texto plano. XTrace no lo hace. Tus documentos y vectores de embedding se cifran en tu máquina antes de transmitir nada. El servidor almacena y busca sobre texto cifrado — calcula resultados de vecinos más cercanos sin ver nunca el texto plano. Tus datos siguen siendo tuyos, incluso durante la búsqueda.
El SDK tiene dos módulos:
Tu máquina Servidor XTrace
┌────────────────────────┐ ┌─────────────────────────┐
│ │ │ │
│ Documentos + Consultas│ │ Almacena solo texto │
│ │ │ │ cifrado │
│ ▼ │ │ │
│ Embed + Cifrar │── texto cifrado│ Busca sobre vectores │
│ (claves se quedan) │ ─▶│ cifrados │
│ ▲ │ │ (nunca descifra) │
│ │ │◀─ texto cifrado│ Devuelve resultados │
│ Descifrar resultados │ │ cifrados │
│ │ │ │
└────────────────────────┘ └─────────────────────────┘
La clave secreta nunca sale Cero conocimiento
XTrace cifra todo en tu máquina antes de que toque la red. Tu contenido se embedié localmente con un modelo de tu elección, y tanto los vectores resultantes como el texto sin formato se cifran con cifrado homomórfico Paillier y AES-256, respectivamente. El servidor solo almacena y opera sobre texto cifrado. Cuando buscas, tu consulta se cifra de la misma manera. La clave secreta nunca sale de tu entorno, y el servidor nunca ve un solo byte de texto plano. Verifica el cifrado
[!TIP] 🚀 Crea una cuenta gratuita en app.xtrace.ai para obtener tu clave de API y ID de organización. El nivel gratuito tiene límite de velocidad pero es completamente funcional.
# SDK base
uv pip install xtrace-ai-sdk
# Con soporte de embedding local (Sentence Transformers)
uv pip install "xtrace-ai-sdk[embedding]"
Requiere Python 3.11+.
Documentación completa en docs.xtrace.ai, o constrúyela localmente:
cd docs && make html
La forma más rápida de pasar de cero a resultados de búsqueda:
uv pip install "xtrace-ai-sdk[cli]"
xtrace init # configura credenciales + claves de cifrado
xtrace kb create my-first-kb # crea una base de conocimiento (anota el ID de KB)
xtrace xvec load ./my-docs/ <KB_ID> # cifra y sube documentos
xtrace xvec retrieve <KB_ID> "tu consulta" # busca
Ejemplo completo asíncrono:
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())
Este repositorio existe para que puedas verificar el cifrado tú mismo. Las pruebas se ejecutan completamente sin conexión y no requieren una cuenta de XTrace:
uv pip install -e ".[dev]"
pytest tests/x_vec/
test_paillier_encryption.py y test_paillier_lookup_encryption.py verifican los viajes de ida y vuelta de cifrado/descifrado y la suma homomórfica sobre texto cifrado — las mismas primitivas que el SDK usa al enviar datos a XTrace. La clave secreta nunca sale de tu máquina.
Damos la bienvenida a las contribuciones. Consulta CONTRIBUTING.md para obtener directrices.
Apache 2.0 — consulta LICENSE.