Python SDK
Python client for workspace search, chat, and embeddings.
The package exposes one public client:
WorkspaceClient: modular client for live API operations such as bucket ingest, catalog lookup, embedding, routing, search, usage, and hosted bucket management.
Install
Base package:
pip install schift
Optional adapters:
pip install "schift[postgres]"
pip install "schift[qdrant]"
pip install "schift[all]"
Development extras:
pip install -e ".[dev]"
Authentication And Base URLs
The modular client reads SCHIFT_API_KEY and a hosted API origin from the
environment. The base URL is a bare origin — no /v1 suffix; version
prefixes belong to request paths:
export SCHIFT_API_KEY=sch_your_key_here
export SCHIFT_API_URL=https://api.schift.io
Equivalent explicit construction:
import os
from schift import WorkspaceClient
client = WorkspaceClient(
api_key="sch_your_key_here",
base_url=os.environ["SCHIFT_API_URL"], # bare origin, e.g. https://api.schift.io
timeout=60.0,
)
Notes:
WorkspaceClientexpects a bare origin (e.g.https://api.schift.io). A legacy trailing/v1is tolerated and stripped automatically, so old configs keep working — but new configs should not include it.- If
base_urlis omitted, setSCHIFT_API_URLorSCHIFT_BASE_URL.
Client Lifecycle
WorkspaceClient holds a shared httpx.Client, so prefer a context manager for short-lived scripts:
from schift import WorkspaceClient
with WorkspaceClient() as client:
models = client.catalog.list()
For long-running processes, keep one WorkspaceClient instance and call close() during shutdown.
Bucket Ingest And Search
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"))],
)
jobs = client.buckets.list_jobs(bucket_id=bucket["id"])
resp = client.buckets.search(
bucket["id"],
"revenue guidance",
top_k=5,
filter={"review_status": "approved"},
)
print(upload["bucket_id"])
print(jobs[0]["status"] if jobs else "queued")
print(resp.context) # paste-ready context with [n] markers
print(resp.citations) # [(1, "report.pdf p.3"), ...]
print(resp[0].text if resp else "no hits")
search() returns a typed SearchResponse (the answer-ready v2 envelope:
results with citations, warnings, degraded) and uses server-packed context
when available. The existing filter= argument sends the consumer's filters
field. Omitted rerank follows the server default; pass rerank=False to
disable it, or set rerank_top_k and context_budget for ranking/context
controls. Optional server diagnostics remain available through .raw and
.to_dict(). For raw chunks use the retrieve
surface:
hits = client.buckets.retrieve(bucket["id"], "revenue guidance", top_k=8)
print(hits.status, hits.operational_status)
for hit in hits:
print(hit.chunk_id, hit.score, hit.text[:80])
Use client.buckets and client.query(..., bucket=...) for retrieval.
The bucket helper also exposes list_collections(), get_job(), list_jobs(), wait_for_job(), and poll_job() so scripts can keep ingest orchestration in one place.
Document Metadata And Connectors
Uploading a document or syncing it in through a connector (Notion, Gmail, Obsidian, …) attaches metadata you can filter on at search time. This section covers what gets filled in automatically, which keys are always reserved, how to add your own metadata, and how to filter with it.
Reserved metadata keys
These keys are populated structurally (field mapping from the connector's API response, or Markdown frontmatter parsing) — never inferred by an LLM. Availability depends on what the source provides; a plain upload with no frontmatter may leave several of these empty.
| Key | Meaning | Always set? |
|---|---|---|
source_kind |
Kind of source (notion_page, email, markdown_note, upload, …) |
yes |
source_created_at |
Original creation time (ISO 8601) | if source provides it |
source_modified_at |
Original last-modified time (ISO 8601) | if source provides it |
source_author |
Author | if source provides it |
source_uri |
Deep link back to the original source | if source provides it |
source_filename |
File name | uploads always; connectors if provided |
source_tags |
Tags/labels from the source (JSON-encoded array string) | if source provides it |
ingested_by |
Who/what ingested it (upload or connector:<provider>) |
yes |
ingested_at |
When Schift received the document | yes |
cclg_source |
Internal lineage identifier | yes |
Avoid naming your own custom metadata keys the same as these — the system value takes precedence.
For Markdown uploads (.md/.markdown), pass parse_frontmatter=True to
upload() to promote YAML frontmatter (created/date/author/tags)
into the reserved keys above:
client.buckets.upload(
bucket["id"],
[("files", ("notes.md", open("notes.md", "rb").read(), "text/markdown"))],
parse_frontmatter=True,
)
Custom metadata
Schift does not read document contents and infer business metadata (e.g.
department, priority) for you — custom metadata is always explicit:
client.buckets.upload(
bucket["id"],
[("files", ("q3-report.pdf", open("q3-report.pdf", "rb").read(), "application/pdf"))],
metadata={"department": "finance", "priority": "high"},
)
Custom metadata is set per document and inherited by every chunk derived
from it. Values must be strings (or JSON-serializable to a string) — the
vector metadata layer stores dict[str, str].
Filtering by metadata
Reserved keys and your own custom keys are filtered the same way — flat,
top-level keys in filter=, not wrapped in a {"metadata": {...}} object:
resp = client.buckets.search(
bucket["id"],
"revenue guidance",
filter={
"source_kind": "email",
"department": "finance",
"source_created_at": {"gte": "2026-01-01"},
},
)
See FilterOperator above for the full operator set (eq/ne/like/
prefix/in/gt/gte/lt/lte/exists). There is no contains
operator today — use like ({"like": "%urgent%"}) for substring matches,
including against JSON-encoded fields like source_tags.
Quickstart
from schift import WorkspaceClient
with WorkspaceClient() as client:
models = client.catalog.list()
vector = client.embed(
"quarterly revenue report",
model="openai/text-embedding-3-small",
)
bucket = client.buckets.create("finance-docs")
client.db.upsert(
collection="finance-docs",
vectors=[
{
"id": "doc-1",
"values": vector.tolist(),
"metadata": {"source": "q1-report"},
}
],
)
hits = client.query(
"revenue guidance",
bucket="finance-docs",
top_k=5,
)
print(models[0]["id"] if models else "no models")
print(hits[0].text if hits else "no hits") # typed SearchResponse
Module Reference
catalog
List available models and inspect one model by ID.
from schift import WorkspaceClient
with WorkspaceClient() as client:
models = client.catalog.list()
model = client.catalog.get("openai/text-embedding-3-small")
embed
The embed module is callable for single-text requests and exposes batch() for multiple texts.
from schift import WorkspaceClient
with WorkspaceClient() as client:
one = client.embed(
"hello world",
model="openai/text-embedding-3-small",
)
many = client.embed.batch(
texts=["hello", "goodbye"],
model="openai/text-embedding-3-small",
dimensions=1024,
)
Return values are NumPy arrays. Both calls go through the OpenAI-shaped
POST /v1/embeddings endpoint ({"input": ..., "model": ...}).
providers
Register your own LLM provider API key (BYOK). Supported providers: "openai", "google", "anthropic".
from schift import WorkspaceClient
with WorkspaceClient() as client:
# Register a key
client.providers.set(
"google",
api_key="AIza...",
# endpoint_url="https://custom-proxy.example.com", # optional
)
# Check whether a provider is configured (api_key is never returned)
status = client.providers.get("openai")
# {"provider": "openai", "configured": True | False, "endpoint_url": None | str}
Rotation: a stored BYOK record shadows any server-side env var or secret for that provider. To rotate, call set() again with the new key — changing env vars alone has no effect on orgs with a BYOK record.
routing
Read or update the server-side routing policy used by Schift when a model is omitted.
from schift import WorkspaceClient
with WorkspaceClient() as client:
current = client.routing.get()
updated = client.routing.set(
primary="openai/text-embedding-3-small",
fallback="google/gemini-embedding-001",
mode="failover",
)
db
Manage hosted buckets and write vectors or raw documents.
from schift import WorkspaceClient
with WorkspaceClient() as client:
vector = client.embed(
"Schift reduces vector migration downtime.",
model="openai/text-embedding-3-small",
)
bucket = client.db.create_collection(
name="product-docs",
dimension=len(vector),
)
client.db.upsert(
collection="product-docs",
vectors=[
{
"id": "doc-1",
"values": vector.tolist(),
"metadata": {"title": "Launch plan"},
}
],
)
client.db.upsert_text(
collection="product-docs",
documents=[
{
"id": "doc-2",
"text": "Schift reduces vector migration downtime.",
"metadata": {"title": "Overview"},
}
],
model="openai/text-embedding-3-small",
)
stats = client.db.collection_stats("product-docs")
Available methods:
create_collection(name, dimension)list_buckets()get_collection(name)collection_stats(name)delete_collection(name)upsert(collection, vectors)upsert_text(collection, documents, model)
query
The query module is callable and supports hosted buckets or an external DB handle.
from schift import WorkspaceClient
with WorkspaceClient() as client:
hosted = client.query(
"vector migration rollback plan",
bucket="product-docs",
top_k=10,
rerank=True,
rerank_top_k=5,
)
passthrough = client.query(
"incident response",
db="prod-search-db",
model="openai/text-embedding-3-small",
top_k=5,
)
rerank
Rerank a list of candidate documents with a cross-encoder style endpoint.
from schift import WorkspaceClient
with WorkspaceClient() as client:
reranked = client.rerank(
"incident response",
documents=[
{"id": "doc-1", "text": "..."},
{"id": "doc-2", "text": "..."},
],
top_k=2,
)
Local Adapters
Standalone read/write adapters for vector stores. They do not call hosted APIs.
Built-in Adapters
NumPy files
from schift.adapters.file import NpyAdapter
adapter = NpyAdapter("embeddings.npy")
pgvector
Requires pip install "schift[postgres]".
from schift.adapters.pgvector import PgVectorAdapter
adapter = PgVectorAdapter(
conninfo="postgresql://user:password@localhost/mydb",
table="documents",
embedding_column="embedding",
id_column="id",
)
Qdrant
Requires pip install "schift[qdrant]".
from schift.adapters.qdrant import QdrantAdapter
adapter = QdrantAdapter(
url="http://localhost:6333",
collection="documents",
api_key=None,
)
Registry Helpers
from schift.adapters import get_adapter, list_adapters
print(list_adapters())
adapter = get_adapter(
{
"type": "npy",
"path": "embeddings.npy",
}
)
Errors
The client raises exceptions from schift.client:
AuthErrorQuotaErrorSDKError
Example:
from schift import WorkspaceClient
from schift import AuthError, QuotaError, SDKError
try:
with WorkspaceClient() as client:
client.catalog.list()
except AuthError:
...
except QuotaError:
...
except SDKError:
...
Development
From clients/sdk/python/:
python -m pip install -e ".[dev]"
python -m ruff check .
python -m pytest
Source Layout
clients/sdk/python/
├── schift/
│ ├── schift_client.py # modular SDK entry point
│ ├── client.py # error types
│ ├── adapters/ # npy, pgvector, qdrant
│ ├── workflow.py # workflow CRUD, blocks, edges, YAML, templates
│ └── *.py # catalog, embed, routing, db, query, rerank, usage
└── docs/ # request/response contracts and schemas
이 SDK는 직접 설정한 Schift API와 그 OpenAI 호환 프록시에 Schift-Version: 2026-10-01을 보내며, 독립 OpenAI 호환 헬퍼는 알려진 Schift 주소 또는 PLATFORM_*·SCHIFT_* API URL 설정과 정확히 같은 origin(스킴·호스트·포트)에만 헤더를 추가한다.
Metadata
Release files for schift 2.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| schift-2.0.0.tar.gz | 376.5 kB | Without provenance | Details for schift-2.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| schift-2.0.0-py3-none-any.whl | Python 3 | none | any | Details for schift-2.0.0-py3-none-any.whl |
Total release size: 443.7 kB
Release files / schift-2.0.0.tar.gz
| Download URL | schift-2.0.0.tar.gz |
|---|---|
| Size | 376.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c52ffc0486c3cb7392ff65ada7b32ba18361f5719002d81b7dc8a57952e8bc1b
|
|
BLAKE2b-256 checksum How to use checksums |
1761d6550e03092b6c9739e3f6afa2fd5034f4a1fdcf6a897cf2fd8051ed7ada
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.17
|
Release files / schift-2.0.0-py3-none-any.whl
| Download URL | schift-2.0.0-py3-none-any.whl |
|---|---|
| Size | 67.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b0a898d472687edfc0149e31c5c69474829a010790506a1b5df87ff4b3f63487
|
|
BLAKE2b-256 checksum How to use checksums |
69cc2926cc647812ef84d31a939e22f6eae5e79681a9cf7134afd5d4488fdc6c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.17
|
Security for schift 2.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.