---

name: client-api description: "Guides clip_client.Client connectivity, encoding, ranking, indexing, searching, async calls, callbacks, and client-side troubleshooting." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

Client API

Use this sub-skill when the user wants to call CLIP-as-service from Python or diagnose client-side behavior against an already-running server.

Trigger examples

• "Use clip_client.Client to encode these text and image inputs."
• "Why does Client.profile() fail with AioRpcError?"
• "Rank text prompts against an image using CLIP-as-service."
• "Use async aencode or callbacks for a large stream."
• "Call index/search from the client after my search Flow is running."

Read first

• references/api-reference.md for verified method signatures, parameters, return types, input rules, and endpoint mapping.
• references/workflows.md for copyable recipes: connectivity profile, encoding, DocArray inputs, ranking, async calls, and client calls for search.
• references/troubleshooting.md for invalid scheme, direct string input, empty input, missing embeddings, connectivity, TLS/auth, non-unique IDs, and callback issues.
• scripts/check_client_api.py to verify client imports/signatures safely; it only contacts a server when --server is supplied.

Boundary routing

• If the server is not started yet or the user needs Flow YAML, model/runtime choice, Docker, TLS certificates, replicas, or monitoring, route to server-runtime.
• If the task is to build the AnnLite search Flow, validate n_dim, or reason about sharding/polling, route to search-retrieval.
• If the task is only package installation or optional dependency diagnosis, also read the root install map.

Minimal client pattern

from clip_client import Client

client = Client("grpc://0.0.0.0:51000")
latency = client.profile()
embeddings = client.encode(["a red car", "a blue bicycle"])
print(latency, embeddings.shape)

Use TLS schemes (grpcs, https, websockets/wss) only when the server was started with matching TLS configuration. Use credential={"Authorization": "<token>"} or the CLIP_AUTH_TOKEN environment variable for authenticated gRPC/HTTP endpoints.

Input and output rules to preserve

• Passing a single bare string to encode, index, or search is an error; wrap it in a list.
• encode(list[str]) returns a NumPy array. encode(DocumentArray) or encode(list[Document]) returns a DocumentArray containing the same objects with embeddings filled.
• Ranking expects each root Document to have cross-modal candidates in .matches unless source is overridden.
• Empty inputs return empty list/DocumentArray depending on input type and method.
• Order and complete result gathering rely on unique Document.id values.

Common decision points

1. Protocol: match the URI scheme to the server (grpc, http, or websocket; add s for TLS variants).
2. Input representation: use strings for simple text/image URIs; use Document/DocumentArray when you need explicit text/uri/blob/tensor fields, nested matches, chunks, or metadata preservation.
3. Batching: adjust batch_size and prefetch for memory/network behavior; very large streams may warn when length is unknown or high.
4. Callbacks: if on_done/on_always owns result collection, methods can return None instead of assembled results.
5. Search client calls: Client.index and Client.search require a server Flow with an indexer. An encoder-only server can encode/rank but not search a corpus.

Verification hints

Run the safe signature check before writing code in an unfamiliar environment:

python sub-skills/client-api/scripts/check_client_api.py

If a real server is available and the user approves a network call, profile it explicitly:

python sub-skills/client-api/scripts/check_client_api.py --server grpc://127.0.0.1:51000 --profile