Aetherfy vector SDK reference
Installing the Aetherfy vector SDKs
Both Aetherfy client libraries are distributed as aetherfy-vectors — the same
name in PyPI and npm. The npm package is unscoped: it is aetherfy-vectors,
not @aetherfy/vectors.
| Python | JavaScript / TypeScript | |
|---|---|---|
| Distribution name | aetherfy-vectors | aetherfy-vectors |
| Install | pip install aetherfy-vectors | npm install aetherfy-vectors |
| Version | 1.4.0 | 1.4.0 |
| Minimum runtime | Python >= 3.11 | Node >= 22 |
| Packaging metadata | setup.py (there is no pyproject.toml) | package.json |
The Aetherfy Python distribution ships two import packages from the one
install: aetherfy_vectors (the vector client) and aetherfy_memory (the memory
layer).
pip install aetherfy-vectorsimport aetherfy_vectors
import aetherfy_memoryThe Aetherfy JavaScript package declares an exports map with only the "."
entry. There are no subpath entry points, so aetherfy-vectors/memory does
not resolve. Import everything — including the memory-layer classes — from
the package root.
npm install aetherfy-vectors// Correct: everything comes from the package root.
import { AetherfyVectorsClient, MemoryClient } from 'aetherfy-vectors';
console.log(typeof AetherfyVectorsClient, typeof MemoryClient);Importing from the Aetherfy SDKs
The Aetherfy Python root package re-exports the client, the exception classes, and six models — but not every type you will need. This split is exact:
Exported from the aetherfy_vectors root | Only in aetherfy_vectors.models |
|---|---|
Point, SearchResult, Collection, Schema, FieldDefinition, AnalysisResult | VectorConfig, DistanceMetric, Filter |
Those six root-exported models also resolve from aetherfy_vectors.models, so
both from aetherfy_vectors import Point and
from aetherfy_vectors.models import Point work — pick one spelling and stay
with it. VectorConfig,
DistanceMetric, and Filter are absent from the root __all__ and have only
the .models path.
# Root package: client, models, exceptions.
from aetherfy_vectors import (
AetherfyVectorsClient,
Point,
SearchResult,
Collection,
AetherfyVectorsException,
AuthenticationError,
RateLimitExceededError,
ServiceUnavailableError,
ValidationError,
CollectionNotFoundError,
PointNotFoundError,
RequestTimeoutError,
NetworkError,
ConflictError,
SchemaValidationError,
SchemaNotFoundError,
PartialUpsertError,
CollectionInOtherRegionError,
QuotaExceededError,
)
# NOT re-exported at the root — import these from aetherfy_vectors.models.
from aetherfy_vectors.models import VectorConfig, DistanceMetric, Filter
print(VectorConfig(size=4, distance=DistanceMetric.COSINE))The Aetherfy JavaScript root export includes the client (also the default
export), createClient(), the DistanceMetric enum, every exception class, the
memory-layer classes, DEFAULT_VECTOR_SIZE, and the public types — including
ScrollOptions and ScrollResult, the manual scroll cursor’s option and page
types.
import AetherfyVectorsClient, {
createClient,
DistanceMetric,
DEFAULT_VECTOR_SIZE,
MemoryClient,
Namespace,
Thread,
} from 'aetherfy-vectors';
import type {
ClientConfig,
Collection,
CountOptions,
FieldDefinition,
Filter,
Point,
RetrieveOptions,
Schema,
ScrollIterOptions,
ScrollPoint,
SearchOptions,
SearchResult,
VectorConfig,
} from 'aetherfy-vectors';
const config: ClientConfig = { apiKey: process.env.AETHERFY_API_KEY };
const client = new AetherfyVectorsClient(config);
console.log(DEFAULT_VECTOR_SIZE, DistanceMetric.COSINE, typeof createClient);
console.log(typeof MemoryClient, typeof Namespace, typeof Thread);
client.dispose();Constructing an Aetherfy client
The Aetherfy Python client is synchronous; the Aetherfy JavaScript client is
asynchronous. Both default to the endpoint https://vectors.aetherfy.com.
Python — AetherfyVectorsClient(api_key=None, endpoint=None, api_region=None, timeout=30.0, workspace="auto")
| Parameter | Default | Meaning |
|---|---|---|
api_key | None | API key; falls back to the environment |
endpoint | None | Base URL; defaults to https://vectors.aetherfy.com |
api_region | None | Pin the client to one region |
timeout | 30.0 | Timeout of each request attempt, in seconds |
workspace | "auto" | Required, in effect. "auto" takes the agent’s own workspace from AETHERFY_WORKSPACE_ID; a name scopes every collection call to that workspace. See below |
The constructor takes exactly these arguments: one it does not name is a TypeError, and qdrant-client’s constructor arguments are not accepted.
JavaScript — new AetherfyVectorsClient(config: ClientConfig = {})
ClientConfig field | Default | Meaning |
|---|---|---|
apiKey | unset | API key; falls back to the environment |
endpoint | unset | Base URL; defaults to https://vectors.aetherfy.com |
timeout | 30000 | Timeout of each request attempt, in milliseconds |
workspace | 'auto' | The workspace every collection call is made in: a name, or 'auto' for the agent’s own, from AETHERFY_WORKSPACE_ID. See below |
apiRegion | unset | Pin the client to one region — see the region section below |
The client’s timeout bounds each attempt, so a call retried under the retry rule can take several times as long, while a method’s own timeout is a deadline for the whole call, every attempt and pause included, ending in RequestTimeoutError: Python takes one on search, retrieve, scroll, count, create_collection, delete_collection and create_field_index, and JavaScript only on createFieldIndex (options.timeout, in milliseconds).
import os
from aetherfy_vectors import AetherfyVectorsClient
client = AetherfyVectorsClient(
api_key=os.environ["AETHERFY_API_KEY"],
timeout=60.0, # seconds
)
print(client.get_collections())
client.close()import { AetherfyVectorsClient } from 'aetherfy-vectors';
const client = new AetherfyVectorsClient({
apiKey: process.env.AETHERFY_API_KEY,
timeout: 60000, // milliseconds
});
console.log(await client.getCollections());
client.dispose();Authenticating an Aetherfy client
When you do not pass a key, both Aetherfy SDKs resolve one from the environment in this order:
| Order | Environment variable |
|---|---|
| 1 | AETHERFY_API_KEY |
| 2 | AETHERFY_VECTORS_API_KEY |
Keys are validated client-side against ^afy_(live|test)_[a-zA-Z0-9]{16,}$, so a
truncated or mistyped key fails before any Aetherfy request is made. That regex
is a deliberately permissive client-side check, not the issued format: Aetherfy
generates afy_live_ or afy_test_ followed by exactly 32 hexadecimal
characters — see API keys for the canonical format. Manage
keys at https://app.aetherfy.com/dashboard/settings/api-keys .
import os
from aetherfy_vectors import AetherfyVectorsClient
# Explicit — equivalent to leaving api_key unset when AETHERFY_API_KEY is present.
explicit = AetherfyVectorsClient(api_key=os.environ["AETHERFY_API_KEY"])
implicit = AetherfyVectorsClient()
print(explicit.collection_exists("articles"), implicit.collection_exists("articles"))
explicit.close()
implicit.close()import { AetherfyVectorsClient } from 'aetherfy-vectors';
// Explicit — equivalent to `new AetherfyVectorsClient()` when AETHERFY_API_KEY is set.
const explicit = new AetherfyVectorsClient({ apiKey: process.env.AETHERFY_API_KEY });
const implicit = new AetherfyVectorsClient();
console.log(
await explicit.collectionExists('articles'),
await implicit.collectionExists('articles'),
);
explicit.dispose();
implicit.dispose();A note on the Aetherfy JavaScript exception namespace: the package contains two
different classes named AuthenticationError. The one defined in src/auth.ts is
re-exported from the package root as AuthError so the two do not collide.
AuthenticationError at the root is the transport-level one.
Scoping an Aetherfy client to a workspace
Every collection lives in exactly one workspace, and its name is unique there, so
a client always works in one: it sends every collection call to that workspace’s
routes (/api/v1/workspaces/{workspace}/collections/..., or
/api/v1/workspace-ids/{id}/... for "auto"), and you keep using bare
collection names. See the REST API reference.
The value "auto" is the default, and a sentinel rather than a workspace name. It
reads AETHERFY_WORKSPACE_ID, which Aetherfy injects into every agent, and
addresses the agent’s own workspace by id. That is what makes a client
constructed with no configuration work inside an agent, and it is why renaming the
workspace never breaks the agent.
| You pass | Resulting scope |
|---|---|
| nothing | Same as "auto": both clients default to it |
"auto" inside an agent | The agent’s own workspace, by id |
"auto" anywhere else | Refused at construction: the variable is not set |
| a workspace name | That workspace |
None (Python) / null (JS), or an empty name | Refused at construction |
There is no “no workspace”. A client without one is refused before any request is made, with an error that names both fixes:
A workspace is required: every collection lives in one. Pass a workspace name (workspace=‘my-workspace’), or run inside an Aetherfy agent and keep the default workspace=‘auto’.
and, for "auto" outside an agent:
workspace=‘auto’ reads AETHERFY_WORKSPACE_ID, which is not set: it is set only inside an Aetherfy agent. Pass a workspace name (workspace=‘my-workspace’), or run inside an Aetherfy agent.
(ValueError in Python, Error in JavaScript, with workspace: ... for the
JavaScript spelling.) Both clients expose what they resolved as read-only
properties: workspace is the name (None/undefined when built from the id) and
workspace_id / workspaceId the id (unset when given a name).
"auto" is only the agent’s home. Code that serves several workspaces, one per
customer say, names the workspace for each client, because the agent’s environment
holds one id. The agent’s key must have been granted each of them: see
a workspace per customer.
import os
from aetherfy_vectors import AetherfyVectorsClient
# Inside an Aetherfy agent: its own workspace, by id. Nothing to configure.
home = AetherfyVectorsClient(api_key=os.environ["AETHERFY_API_KEY"])
print(home.workspace_id)
# Anywhere: name the workspace.
acme = AetherfyVectorsClient(api_key=os.environ["AETHERFY_API_KEY"], workspace="acme")
print(acme.workspace)
print(acme.get_collections())
home.close()
acme.close()import { AetherfyVectorsClient } from 'aetherfy-vectors';
// Inside an Aetherfy agent: its own workspace, by id. Nothing to configure.
const home = new AetherfyVectorsClient({ apiKey: process.env.AETHERFY_API_KEY });
console.log(home.workspaceId);
// Anywhere: name the workspace.
const acme = new AetherfyVectorsClient({
apiKey: process.env.AETHERFY_API_KEY,
workspace: 'acme',
});
console.log(acme.workspace);
console.log(await acme.getCollections());
home.dispose();
acme.dispose();An unknown workspace raises WorkspaceNotFoundError, never an empty result, and
collection_exists / collectionExists returns false only when the workspace
exists and the collection is not in it. The SDKs have no collection rename or
move; those are done in the dashboard or with afy collections update and
afy collections move, and code still using the old name gets
CollectionNotFoundError.
The memory layer keeps conversations in a plain __threads__ collection in each
workspace, shared by every agent that lives there.
Pinning an Aetherfy client to a region
The Aetherfy SDKs accept three region identifiers:
| Region |
|---|
us-east-1 |
eu-central-1 |
ap-southeast-1 |
Multi-region replication is a property of the plan, not the client: Free and Starter workspaces are single-region, with the region chosen when the workspace is created, and replication across regions begins at the plan named Performance. Pinning a client does not change what your plan replicates.
In Python, pass api_region to the constructor:
import os
from aetherfy_vectors import AetherfyVectorsClient
client = AetherfyVectorsClient(
api_key=os.environ["AETHERFY_API_KEY"],
api_region="eu-central-1",
)
print(client.get_collections())
client.close()In JavaScript, apiRegion requires region discovery, which is asynchronous.
Passing apiRegion to the new constructor (without an endpoint or environment
override) throws. Use the static create() factory instead:
import { AetherfyVectorsClient } from 'aetherfy-vectors';
// Correct: `create` performs region discovery before returning a client.
const client = await AetherfyVectorsClient.create({
apiKey: process.env.AETHERFY_API_KEY,
apiRegion: 'eu-central-1',
});
console.log(await client.getCollections());
client.dispose();Collection operations in the Aetherfy SDKs
| Operation | Python | JavaScript |
|---|---|---|
| Create | create_collection(collection_name, vectors_config, distance=None, description=None, regions=None) -> Collection | createCollection(collectionName, vectorsConfig, description?, regions?) -> Promise<Collection> |
| Delete | delete_collection(collection_name) -> bool | deleteCollection(collectionName) -> Promise<boolean> |
| List | get_collections() -> List[Collection] | getCollections() -> Promise<Collection[]> |
| Exists | collection_exists(collection_name) -> bool | collectionExists(collectionName) -> Promise<boolean> |
| Get one | get_collection(collection_name) -> Collection | getCollection(collectionName) -> Promise<Collection> |
| Create a payload index | create_field_index(collection_name, field_name, field_schema="keyword", timeout=None) -> bool | createFieldIndex(collectionName, fieldName, fieldSchema?, options?: CreateFieldIndexOptions) -> Promise<boolean> |
| Drop a payload index | delete_field_index(collection_name, field_name) -> bool | deleteFieldIndex(collectionName, fieldName) -> Promise<boolean> |
The Python signature carries a separate distance parameter alongside
vectors_config; the JavaScript signature does not — the distance lives inside
the config object. Aetherfy fixes the rest of the collection configuration
server-side, so there is no place to pass optimizer or index settings in either
SDK.
The two index methods are the exception: a PAYLOAD index is yours to manage.
A filter on an unindexed payload key is scanned rather than looked up, so any
key you filter on for every read — a tenant id, a status, a timestamp you
range over — wants one. field_schema / fieldSchema defaults to
"keyword" and accepts the other simple types ("integer", "float",
"bool", "geo", "datetime", "uuid", "text") or an object for the
parameterised forms; it is forwarded verbatim. Creating an index that already
exists returns at once.
create_field_index / createFieldIndex returns only once the index is built
and usable in the region that answered, so a filter or an order_by scroll on
the key can follow it straight away. While the build is still running, the
Aetherfy SDKs send the create again, which waits for it, and they never return
before it finishes. The wait stops at timeout (seconds in Python; the
timeout option, in milliseconds, in JavaScript) or, without one, at a
10-minute default deadline, with a RequestTimeoutError saying the index is
still building; the build carries on, and calling the method again waits for
it. A timeout at or below 0 is refused with ValidationError before any
request.
delete_field_index / deleteFieldIndex returns True / true whenever the
collection exists, including when that field had no index, and False /
false only when the collection does not exist.
A collection in more than one region gets the index in its other regions
shortly after, not at the same moment. A read served by one of those regions in
the meantime can be refused the same way, so retry an order_by scroll that is
refused right after you create its index.
import os
from aetherfy_vectors import AetherfyVectorsClient
from aetherfy_vectors.models import VectorConfig, DistanceMetric
client = AetherfyVectorsClient(api_key=os.environ["AETHERFY_API_KEY"])
collection = client.create_collection(
collection_name="articles",
vectors_config=VectorConfig(size=4, distance=DistanceMetric.COSINE),
description="Article embeddings",
)
print(collection.name, collection.points_count, collection.regions)
print(client.collection_exists("articles"))
print([c.name for c in client.get_collections()])
print(client.create_field_index("articles", "tenant_id", "keyword"))
print(client.delete_field_index("articles", "tenant_id"))
print(client.delete_collection("articles"))
client.close()import { AetherfyVectorsClient, DistanceMetric } from 'aetherfy-vectors';
const client = new AetherfyVectorsClient({ apiKey: process.env.AETHERFY_API_KEY });
const collection = await client.createCollection(
'articles',
{ size: 4, distance: DistanceMetric.COSINE },
'Article embeddings',
);
console.log(collection.name, collection.points_count, collection.regions);
console.log(await client.collectionExists('articles'));
console.log((await client.getCollections()).map((c) => c.name));
console.log(await client.createFieldIndex('articles', 'tenantId', 'keyword'));
console.log(await client.deleteFieldIndex('articles', 'tenantId'));
console.log(await client.deleteCollection('articles'));
client.dispose();The same Aetherfy collection and payload-index operations run from a shell as
afy collections list|get|create|delete and afy index create|delete, with
--json output, and afy index create waits for the build the way
create_field_index does. See /cli/vectors.
Upserting points with the Aetherfy SDKs
upsert writes points, creating or replacing them by id. Aetherfy caps a single
upsert call at 10 000 points; see limits.
| Operation | Python | JavaScript |
|---|---|---|
| Upsert | upsert(collection_name, points) -> bool | upsert(collectionName, points) -> Promise<boolean> |
Both Aetherfy SDKs accept two shapes for points. Python is typed
Sequence[Union[Point, Dict[str, Any]]], so a Point dataclass and a plain
dict are equally valid; JavaScript is typed
Point[] | Record<string, unknown>[]. The Aetherfy quickstart writes plain
dicts and the Aetherfy examples write Point(...) — both are correct, and
there is no behavioural difference between them.
import os
from aetherfy_vectors import AetherfyVectorsClient, Point
client = AetherfyVectorsClient(api_key=os.environ["AETHERFY_API_KEY"])
ok = client.upsert(
collection_name="articles",
points=[
Point(id=1, vector=[0.1, 0.2, 0.3, 0.4], payload={"lang": "en", "year": 2024}),
Point(id=2, vector=[0.4, 0.3, 0.2, 0.1], payload={"lang": "fr", "year": 2025}),
],
)
print(ok)
client.close()import { AetherfyVectorsClient } from 'aetherfy-vectors';
const client = new AetherfyVectorsClient({ apiKey: process.env.AETHERFY_API_KEY });
const ok = await client.upsert('articles', [
{ id: 1, vector: [0.1, 0.2, 0.3, 0.4], payload: { lang: 'en', year: 2024 } },
{ id: 2, vector: [0.4, 0.3, 0.2, 0.1], payload: { lang: 'fr', year: 2025 } },
]);
console.log(ok);
client.dispose();When an upsert is split into several requests and some of them fail, the
Aetherfy SDKs raise PartialUpsertError, which carries .saved, .total, and
.failed. .saved counts the points confirmed written. A point in .failed may already
have been written: a request that timed out or lost its connection may have been
applied, and a large request is written in parts, so a refusal can come after
part of it was stored. Re-send the points in .failed: an upsert replaces points
by id, so sending them again is safe.
Searching with the Aetherfy SDKs
Python takes the search options as keyword arguments; JavaScript takes a
SearchOptions object.
Python — search(collection_name, query_vector, limit=10, offset=0, query_filter=None, with_payload=True, with_vectors=False, score_threshold=None, search_params=None) -> List[SearchResult]
JavaScript — search(collectionName, queryVector, options: SearchOptions = {}) -> Promise<SearchResult[]>
| Python keyword | JavaScript SearchOptions field | Default |
|---|---|---|
limit | limit | 10 |
offset | offset | 0 |
query_filter | queryFilter | none |
with_payload | withPayload | True / true |
with_vectors | withVectors | False / false |
score_threshold | scoreThreshold | none |
search_params | searchParams | none |
import os
from aetherfy_vectors import AetherfyVectorsClient
client = AetherfyVectorsClient(api_key=os.environ["AETHERFY_API_KEY"])
results = client.search(
collection_name="articles",
query_vector=[0.1, 0.2, 0.3, 0.4],
limit=5,
query_filter={"must": [{"key": "lang", "match": {"value": "en"}}]},
with_payload=True,
with_vectors=False,
score_threshold=0.5,
)
for hit in results:
print(hit.id, hit.score, hit.payload)
client.close()import { AetherfyVectorsClient } from 'aetherfy-vectors';
const client = new AetherfyVectorsClient({ apiKey: process.env.AETHERFY_API_KEY });
const results = await client.search('articles', [0.1, 0.2, 0.3, 0.4], {
limit: 5,
queryFilter: { must: [{ key: 'lang', match: { value: 'en' } }] },
withPayload: true,
withVectors: false,
scoreThreshold: 0.5,
});
for (const hit of results) {
console.log(hit.id, hit.score, hit.payload);
}
client.dispose();Filter syntax is on filtering; engine-level tuning through
search_params / searchParams is on search tuning.
Retrieving, counting, and deleting points with the Aetherfy SDKs
| Operation | Python | JavaScript |
|---|---|---|
| Retrieve by id | retrieve(collection_name, ids, with_payload=True, with_vectors=False) -> List[Dict] | retrieve(collectionName, ids, options: RetrieveOptions = {}) -> Promise<Point[]> |
| Count | count(collection_name, count_filter=None, exact=True) -> int | count(collectionName, options: CountOptions = {}) -> Promise<number> |
| Delete | delete(collection_name, points_selector) -> bool | delete(collectionName, pointsSelector) -> Promise<boolean> |
Two traps live in this group of Aetherfy methods. First, retrieve returns
plain dictionaries in Python but typed Point objects in JavaScript. Second,
count defaults exact to True in Python and false in JavaScript — the
same nominal call computes its answer differently in the two languages, so pass
exact explicitly whenever the number matters.
delete accepts either a list of point ids or a filter object; a list is sent as
points, anything else as filter.
import os
from aetherfy_vectors import AetherfyVectorsClient
client = AetherfyVectorsClient(api_key=os.environ["AETHERFY_API_KEY"])
points = client.retrieve("articles", ids=[1, 2], with_payload=True, with_vectors=True)
for point in points: # dicts in Python
print(point["id"], point.get("payload"))
print(client.count("articles", exact=True))
print(client.count("articles", count_filter={"must": [{"key": "lang", "match": {"value": "en"}}]}, exact=True))
print(client.delete("articles", [1, 2]))
print(client.delete("articles", {"must": [{"key": "lang", "match": {"value": "fr"}}]}))
client.close()import { AetherfyVectorsClient } from 'aetherfy-vectors';
const client = new AetherfyVectorsClient({ apiKey: process.env.AETHERFY_API_KEY });
const points = await client.retrieve('articles', [1, 2], {
withPayload: true,
withVectors: true,
});
for (const point of points) {
// typed Point objects in JavaScript
console.log(point.id, point.payload);
}
console.log(await client.count('articles', { exact: true }));
console.log(
await client.count('articles', {
countFilter: { must: [{ key: 'lang', match: { value: 'en' } }] },
exact: true,
}),
);
console.log(await client.delete('articles', [1, 2]));
console.log(
await client.delete('articles', { must: [{ key: 'lang', match: { value: 'fr' } }] }),
);
client.dispose();Retrieving, counting, searching, writing and deleting Aetherfy points also run
from a shell, as afy points get, afy points count (always exact),
afy points search, afy points upsert and afy points delete; a bulk load
stays the SDKs’ job. See /cli/vectors.
Scrolling a collection with the Aetherfy SDKs
scroll is one page; scroll_iter / scrollIter walks the whole collection for
you. Aetherfy accepts a batch size between 1 and 1000 — outside that range the
Python SDK raises ValueError and the JavaScript SDK raises RangeError, before
any request is sent.
| Operation | Python | JavaScript |
|---|---|---|
| One page | scroll(collection_name, limit=10, offset=None, scroll_filter=None, with_payload=True, with_vectors=False) -> Dict | scroll(collectionName, options) -> Promise<ScrollResult> |
| Iterate | scroll_iter(collection_name, *, batch_size=256, scroll_filter=None, with_payload=True, with_vectors=False) -> Iterator[Dict] | async *scrollIter(collectionName, options: ScrollIterOptions = {}) -> AsyncGenerator<ScrollPoint> |
The page result keys differ: Python returns {"points", "next_page_offset"},
JavaScript returns {points, nextPageOffset}. scroll_iter is keyword-only
in Python — batch_size cannot be passed positionally.
import os
from aetherfy_vectors import AetherfyVectorsClient
client = AetherfyVectorsClient(api_key=os.environ["AETHERFY_API_KEY"])
page = client.scroll("articles", limit=100, with_payload=True)
print(len(page["points"]), page["next_page_offset"])
for point in client.scroll_iter("articles", batch_size=256, with_payload=True):
print(point["id"])
client.close()import { AetherfyVectorsClient } from 'aetherfy-vectors';
const client = new AetherfyVectorsClient({ apiKey: process.env.AETHERFY_API_KEY });
const page = await client.scroll('articles', { limit: 100, withPayload: true });
console.log(page.points.length, page.nextPageOffset);
for await (const point of client.scrollIter('articles', {
batchSize: 256,
withPayload: true,
})) {
console.log(point.id);
}
client.dispose();Mutating payloads with the Aetherfy SDKs
Aetherfy exposes three payload mutations, and every one of them is capped at 512 points per call in both SDKs.
| Operation | Python | JavaScript | Effect |
|---|---|---|---|
| Set (merge) | set_payload(collection_name, payload, points, key=None) | setPayload(collectionName, payload, points, options = {}) | Adds or overwrites the named keys; other keys survive |
| Overwrite (replace) | overwrite_payload(collection_name, payload, points) | overwritePayload(collectionName, payload, points) | Replaces the whole payload |
| Delete keys | delete_payload(collection_name, keys, points) | deletePayload(collectionName, keys, points) | Removes only the named keys |
Payload keys beginning __aetherfy_ are reserved by Aetherfy and stripped from
reads. Two are returned: __aetherfy_agent_id and __aetherfy_deployment_id,
the attested author and deployment of the write — the agent’s id and the
deployment that wrote it (for a task, the run) when an Aetherfy-injected key
made the write, null for both when one of your own keys did. Retrieve, edit,
overwrite works as you would expect on them: you may send those keys back
unchanged, and Aetherfy ignores the values and sets them from your credential.
The reserved keys you never see on a read are rejected with 400
RESERVED_FIELD. See
attested authorship.
import os
from aetherfy_vectors import AetherfyVectorsClient
client = AetherfyVectorsClient(api_key=os.environ["AETHERFY_API_KEY"])
client.set_payload("articles", payload={"reviewed": True}, points=[1, 2])
client.overwrite_payload("articles", payload={"lang": "en"}, points=[1])
client.delete_payload("articles", keys=["reviewed"], points=[1, 2])
client.close()import { AetherfyVectorsClient } from 'aetherfy-vectors';
const client = new AetherfyVectorsClient({ apiKey: process.env.AETHERFY_API_KEY });
await client.setPayload('articles', { reviewed: true }, [1, 2]);
await client.overwritePayload('articles', { lang: 'en' }, [1]);
await client.deletePayload('articles', ['reviewed'], [1, 2]);
client.dispose();Managing payload schemas with the Aetherfy SDKs
Aetherfy can hold a payload schema per collection and enforce it at one of three levels.
| Operation | Python | JavaScript |
|---|---|---|
| Read | get_schema(name) | getSchema(name) |
| Write | set_schema(name, schema, enforcement="off", description=None) -> etag | setSchema(name, schema, enforcementMode='off', description?) |
| Delete | delete_schema(name) | deleteSchema(name) |
| Infer from data | analyze_schema(collection_name, sample_size=1000) | analyzeSchema(collectionName, sampleSize = 1000) |
| Enforcement mode | Behaviour |
|---|---|
off | Schema stored, not enforced |
warn | Violations reported, writes proceed |
strict | Violations reject the write |
set_schema returns the new ETag, which is what you pass to the REST layer’s
If-Match for a compare-and-set update. analyze_schema samples between 100 and
10 000 points; outside that range the call raises before any Aetherfy request.
A write that violates a strict schema raises SchemaValidationError (Python’s
carries .errors).
A collection with no schema is not an error. Both SDKs absorb the API’s 404
SCHEMA_NOT_DEFINED and hand back an empty result instead of raising: Python’s
get_schema returns None, and JavaScript’s getSchema resolves to null.
Test the return value; do not write a SchemaNotFoundError handler around it,
because none is thrown for an absent schema.
import os
from aetherfy_vectors import AetherfyVectorsClient
client = AetherfyVectorsClient(api_key=os.environ["AETHERFY_API_KEY"])
analysis = client.analyze_schema("articles", sample_size=500)
print(analysis)
schema = client.get_schema("articles")
if schema is None:
print("no schema defined for this collection")
else:
print(schema)
client.close()import { AetherfyVectorsClient } from 'aetherfy-vectors';
const client = new AetherfyVectorsClient({ apiKey: process.env.AETHERFY_API_KEY });
const analysis = await client.analyzeSchema('articles', 500);
console.log(analysis);
const schema = await client.getSchema('articles');
if (schema === null) {
console.log('no schema defined for this collection');
} else {
console.log(schema);
}
client.dispose();Point ID rules in the Aetherfy SDKs
Both Aetherfy SDKs validate point ids client-side, identically, before any request leaves the process.
| Accepted | Notes |
|---|---|
| Unsigned integer | 0 <= id <= 2**53 - 1 |
| UUID string | Canonical, 32-hex simple, braced, or urn:uuid: form; case-insensitive |
Anything else raises ValidationError with the message:
Point ID '<id>' is invalid — use an unsigned integer or a UUID string.
The upper bound is 2^53 − 1 because the server’s JSON layer parses numbers as
IEEE-754 doubles; a larger integer could not survive the round trip intact.
In Python, bool is explicitly rejected even though it subclasses int.
Aetherfy performs no coercion in either direction: an integer id comes back
an integer, and a UUID comes back a string. 1 and "1" are not
interchangeable, and "1" is not a valid id at all.
import os
from aetherfy_vectors import AetherfyVectorsClient, Point
client = AetherfyVectorsClient(api_key=os.environ["AETHERFY_API_KEY"])
client.upsert(
"articles",
[
Point(id=42, vector=[0.1, 0.2, 0.3, 0.4]),
Point(id="6f8b9a1c-2d3e-4f50-8a1b-2c3d4e5f6071", vector=[0.4, 0.3, 0.2, 0.1]),
],
)
fetched = client.retrieve("articles", ids=[42, "6f8b9a1c-2d3e-4f50-8a1b-2c3d4e5f6071"])
for point in fetched:
print(type(point["id"]).__name__, point["id"])
client.close()import { AetherfyVectorsClient } from 'aetherfy-vectors';
const client = new AetherfyVectorsClient({ apiKey: process.env.AETHERFY_API_KEY });
await client.upsert('articles', [
{ id: 42, vector: [0.1, 0.2, 0.3, 0.4] },
{ id: '6f8b9a1c-2d3e-4f50-8a1b-2c3d4e5f6071', vector: [0.4, 0.3, 0.2, 0.1] },
]);
const fetched = await client.retrieve('articles', [
42,
'6f8b9a1c-2d3e-4f50-8a1b-2c3d4e5f6071',
]);
for (const point of fetched) {
console.log(typeof point.id, point.id);
}
client.dispose();Reading usage against your plan with the Aetherfy SDKs
Both Aetherfy SDKs expose one analytics method. It calls
GET /api/v1/analytics/usage and returns the response body unchanged.
usage = client.get_usage_stats()
print(usage.tier, usage.collections_count, usage.storage_bytes_used)
print(usage.active_regions)
# Both limit fields are None on an unlimited plan — one sentinel, not two.
if usage.storage_limit_bytes is None:
print('storage: unlimited')
else:
print(f'storage: {usage.usage_percentage}% of {usage.storage_limit_bytes}')const usage = await client.getUsageStats();
console.log(usage.tier, usage.collections_count, usage.storage_bytes_used);
console.log(usage.active_regions);
// Both limit fields are null on an unlimited plan — one sentinel, not two.
if (usage.storage_limit_bytes === null) {
console.log('storage: unlimited');
} else {
console.log(`storage: ${usage.usage_percentage}% of ${usage.storage_limit_bytes}`);
}Both Aetherfy SDKs return the wire’s snake_case here, because both return
the response body raw. That is the same rule that governs Collection one
section down: the JavaScript SDK’s camelCase vocabulary is outbound-only, and
no inbound transform exists in either SDK. A field’s spelling in these objects
is the Aetherfy API’s spelling, not the language’s convention.
The seven fields, what each means, and the null-is-unlimited rule are on
Usage and metrics. Neither Aetherfy SDK wraps
GET /api/v1/analytics/metrics — call that one over REST.
Model shapes in the Aetherfy SDKs
The Aetherfy Python SDK models are dataclasses; the JavaScript models are
interfaces. Most field names are identical in both — the JavaScript SDK’s
camelCase vocabulary applies to the options you SEND, not to the response
bodies you get back, which are returned exactly as the Aetherfy API sends
them. ScrollResult is the one shape below that is genuinely renamed, and
the JavaScript client does that rename by hand.
| Model | Python | JavaScript |
|---|---|---|
| Point | Point(id: Union[str, int], vector: List[float], payload: Optional[Dict] = None) | Point{id, vector, payload?} |
| Search hit | SearchResult(id, score: float, payload=None, vector=None) | SearchResult{id, score, payload?, vector?} |
| Vector config | VectorConfig(size: int, distance: DistanceMetric) | VectorConfig{size, distance} |
| Collection | Collection(name, config, description=None, points_count=None, status=None, regions=None) | Collection{name, description?, config, points_count?, status?, regions?} |
| Usage stats | UsageStats(storage_bytes_used, storage_limit_bytes, collections_count, collections_limit, tier, active_regions, usage_percentage) | UsageStats{storage_bytes_used, storage_limit_bytes, collections_count, collections_limit, tier, active_regions, usage_percentage} |
| Filter | Filter(must=None, must_not=None, should=None) | Filter — see filtering |
| Scroll point | not a distinct type | ScrollPoint{id, vector?, payload?} |
| Scroll page | plain dict {"points", "next_page_offset"} | ScrollResult{points, nextPageOffset} |
DistanceMetric has the same four members in both Aetherfy SDKs. Each sends
the name Aetherfy stores and returns, so all four round-trip: a collection’s
config.distance equals the member’s value.
| Member | Value sent, stored and returned |
|---|---|
COSINE | Cosine |
EUCLIDEAN | Euclid |
DOT | Dot |
MANHATTAN | Manhattan |
Choose the distance knowing what the Aetherfy vector API stores: vectors are kept as
float32, and a COSINE collection normalises each vector to unit length when it is
written, so what you read back is the direction of what you sent, not its magnitude.
The other three distances keep the magnitude. See
what the vector API stores.
Managing an Aetherfy client’s lifetime
The Aetherfy Python client supports the context-manager protocol and an explicit
close(). The Aetherfy JavaScript client has dispose() and destroy(), plus a
testConnection() probe that the Python SDK does not have.
import os
from aetherfy_vectors import AetherfyVectorsClient
# Context manager closes the client on exit.
with AetherfyVectorsClient(api_key=os.environ["AETHERFY_API_KEY"]) as client:
print(client.get_collections())
# Or close it yourself.
client = AetherfyVectorsClient(api_key=os.environ["AETHERFY_API_KEY"])
try:
print(client.collection_exists("articles"))
finally:
client.close()import { AetherfyVectorsClient } from 'aetherfy-vectors';
const client = new AetherfyVectorsClient({ apiKey: process.env.AETHERFY_API_KEY });
try {
console.log(await client.testConnection());
console.log(await client.getCollections());
} finally {
client.dispose();
}Divergences between the two Aetherfy SDKs
These are the differences that change behaviour, not just spelling. Read this table before porting code between the two Aetherfy SDKs.
| Concern | Python | JavaScript |
|---|---|---|
count() default exact | True | false |
| Timeout unit | seconds (30.0) | milliseconds (30000) |
| Scroll page keys | {"points", "next_page_offset"} | {points, nextPageOffset} |
retrieve return type | List[Dict] | Point[] |
| Base exception class | AetherfyVectorsException | AetherfyVectorsError |
| Call style | synchronous | async / await |
| Region pinning | api_region on the constructor | apiRegion requires await Client.create(); new throws |
| Lifecycle | context manager, close() | dispose(), destroy() |
| Connection probe | none | testConnection() |
| Batch-size range error | ValueError | RangeError |
| Unknown search option | native TypeError (no **kwargs sink) | explicit runtime guard throws |
| Memory layer import | import aetherfy_memory | package root only; no aetherfy-vectors/memory subpath |
| Payload mutation cap | 512 points per call | 512 points per call |
Complete Aetherfy SDK method map
| Operation | Python | JavaScript |
|---|---|---|
| Create collection | create_collection | createCollection |
| Delete collection | delete_collection | deleteCollection |
| List collections | get_collections | getCollections |
| Collection exists | collection_exists | collectionExists |
| Get collection | get_collection | getCollection |
| Create payload index | create_field_index | createFieldIndex |
| Delete payload index | delete_field_index | deleteFieldIndex |
| Upsert | upsert | upsert |
| Search | search | search |
| Retrieve | retrieve | retrieve |
| Delete points | delete | delete |
| Count | count | count |
| Scroll one page | scroll | scroll |
| Scroll iterator | scroll_iter | scrollIter |
| Set payload | set_payload | setPayload |
| Overwrite payload | overwrite_payload | overwritePayload |
| Delete payload keys | delete_payload | deletePayload |
| Get schema | get_schema | getSchema |
| Set schema | set_schema | setSchema |
| Delete schema | delete_schema | deleteSchema |
| Analyze schema | analyze_schema | analyzeSchema |
| Usage against plan | get_usage_stats | getUsageStats |
| Close | close / with | dispose / destroy |
| Connection probe | — | testConnection |
The exception classes each Aetherfy SDK raises, and the error codes behind them, are on errors.