ELIPS exposes two Python surfaces over the same C++ core. The high-level, Chroma-style surface is Client / Collection around RecordInput, Row, and Hit; the FAISS-style Index API offers raw array search. The native handles mirror C++ 1:1 under client.native.

Client / PersistentClient

elips.Client / PersistentClient

Python

elips.Client(*, dimension: int, metric: str = "cosine", index: str = "graph", ...) ; elips.PersistentClient(path: str, *, dimension: int, ...)

C++

elips::open(std::string path, elips::Config cfg) -> std::unique_ptr<elips::Database>

elips.connect (deprecated shim)

Python

elips.connect(path: str, *, dimension: int = 0, metric: str = "cosine", index: str = "graph", embedder=None, device=None) -> Engine

Client opens an in-memory database; PersistentClient opens one on disk. Both subclass Engine and carry the Chroma client surface. The pre-1.1 connect / open openers remain as deprecated shims.

Client / Database

Client.get_or_create_collection

Python

client.get_or_create_collection(name: str, *, embedder=None) -> Collection

C++

elips::Database::collection(std::string name) -> Collection&

Client collection management

Python

client.create_collection(name); client.get_collection(name); client.list_collections() -> list[str]

Client.query_eql

Python

client.query_eql(eql: str, bindings: dict | None = None) -> list[Row]

C++

elips::Database::query(std::string eql, std::map<std::string, Vector> bindings) -> std::vector<Row>

Client.checkpoint / compact / vacuum / close

Python

client.checkpoint(); client.compact(); client.vacuum(); client.close()

C++

db->checkpoint(); db->compact(); db->close();

Transactions live on the native handle: client.native.begin_transaction() (C++ elips::Database::begin_transaction()).

Collection

python

# Chroma-style surface
docs.add(*, ids=None, embeddings=None, documents=None, metadatas=None) -> str | list[str]
docs.upsert(...)                      # same as add
docs.update(*, ids, embeddings=None, documents=None, metadatas=None) -> list[str]
docs.get(ids=None, *, where=None, limit=None, offset=0, include=None) -> list[Row]
docs.delete(ids=None, *, where=None) -> int
docs.query(query_embeddings=None, query_texts=None, *, n_results=10,
           where=None, include=None, max_distance=None, lexical_weight=0.25)
           -> list[Hit] | list[list[Hit]]
docs.count() -> int
docs.peek(n=10) -> list[Row]
# ELIPS extensions
docs.explain(vector, *, top=10, where=None) -> QueryPlan
docs.health() -> CollectionHealth
docs.vacuum(); docs.rebuild(); docs.freeze(); docs.compress()

cpp

// C++ Collection (renamed from Vault; erase -> remove for the keyword clash)
docs.add(vector, payload, document, chunk, lineage);
docs.add_document(text, payload, lineage);
docs.remove(record_id);
docs.get(record_id) -> std::optional<Record>;
docs.scan(where, offset, limit) -> std::vector<Record>;
docs.search(vector, k, where, threshold) -> std::vector<SearchResult>;
docs.search_text(text, k, where) -> std::vector<SearchResult>;
docs.hybrid_search(vector, text, k, where) -> std::vector<SearchResult>;
docs.explain_query(vector, k, where, has_text_component) -> QueryPlan;

Index (FAISS-style)

python

index = elips.IndexIVFFlat(d=128, nlist=316, metric="l2")
index.train(xb); index.add(xb); index.nprobe = 128
D, I = index.search(xq, k=10)       # distances, int64 labels
# Constructors: IndexFlat, IndexIVFFlat, IndexIVFPQ, IndexIVFScalarQuantizer,
#               IndexHNSW, index_factory(d, spec, metric)
# Exact brute force, no build (GPU builds): elips.bf_knn(xq, xb, k, metric="l2", device="metal")

Filter

python

f = (elips.Filter()
     .field("kind").equals("design")
     .and_(elips.Filter().field("year").gte(2023))
     .or_(elips.Filter().field("country").is_in(["US", "GB", "CA"])))

hits = docs.query(query_embeddings=[1.0, 0.0], n_results=10, where=f)

Comparators map to eq, ne, lt, le, gt, ge, gte, plus is_in and contains. Boolean combinators: and_, or_, not_. Pass the result as where= to query/get/delete.

QueryPlan

Field	Meaning
`strategy`	`ann_index` · `exact_candidates` · `full_scan` · `text_probe` · `hybrid_fusion`
`metadata_accelerated`	Whether the planner narrowed via the metadata filter index.
`candidate_count`	Candidate set size when narrowed.
`has_text_component`	Whether the plan includes a text stage.

Types

DocumentAttachment(text, uri=None, mime=None, attributes=)
ChunkInfo(document_key, position, length, attributes=)
EmbeddingLineage(provider, model, revision, attributes=)
SearchResult (C++) — id, distance, payload, document?, chunk?, lineage?, codec.
RecordInput(vector=..., text=..., meta=..., key=..., document=..., chunk=..., lineage=...)
Row(key, meta, document?, vector?, chunk?, lineage?) — .text aliases document.text.
Hit(key, distance, meta, document?, vector?, chunk?, lineage?).
CollectionHealth(name, live, pending_removals, dimension, metric, read_only, sealed, codec, code_bytes)

Errors

All runtime errors derive from ElipsError:

DimensionMismatch — vector width disagrees with identity.
InvalidVector — NaN, empty, or otherwise malformed input.
ConfigError — incompatible config or missing embedder on reopen.
StorageError — write attempted on a read-only handle, or persistence layer failure.
LockConflict — another writer holds the database.
NotFound — record id absent.