Skip to main content

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:

  • WorkspaceClient expects a bare origin (e.g. https://api.schift.io). A legacy trailing /v1 is tolerated and stripped automatically, so old configs keep working — but new configs should not include it.
  • If base_url is omitted, set SCHIFT_API_URL or SCHIFT_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.

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:

  • AuthError
  • QuotaError
  • SDKError

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)

Source distribution for schift 2.0.0
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)

Table of built distributions (wheels) for schift 2.0.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page