Methods

API (Application)

Base API template. The API is an extended txtai application, adding the ability to cluster API instances together.

Downstream applications can extend this base template to add/modify functionality.

Source code in txtai/api/base.py

  1. class API(Application):
  2.     """
  3.     Base API template. The API is an extended txtai application, adding the ability to cluster API instances together.
  5.     Downstream applications can extend this base template to add/modify functionality.
  6.     """
  8.     def __init__(self, config, loaddata=True):
  9.         super().__init__(config, loaddata)
  11.         # Embeddings cluster
  12.         self.cluster = None
  13.         if self.config.get("cluster"):
  14.             self.cluster = Cluster(self.config["cluster"])
  16.     # pylint: disable=W0221
  17.     def search(self, query, limit=None, request=None):
  18.         # When search is invoked via the API, limit is set from the request
  19.         # When search is invoked directly, limit is set using the method parameter
  20.         limit = self.limit(request.query_params.get("limit") if request and hasattr(request, "query_params") else limit)
  22.         if self.cluster:
  23.             return self.cluster.search(query, limit)
  25.         return super().search(query, limit)
  27.     def batchsearch(self, queries, limit=None):
  28.         if self.cluster:
  29.             return self.cluster.batchsearch(queries, self.limit(limit))
  31.         return super().batchsearch(queries, limit)
  33.     def add(self, documents):
  34.         """
  35.         Adds a batch of documents for indexing.
  37.         Downstream applications can override this method to also store full documents in an external system.
  39.         Args:
  40.             documents: list of {id: value, text: value}
  42.         Returns:
  43.             unmodified input documents
  44.         """
  46.         if self.cluster:
  47.             self.cluster.add(documents)
  48.         else:
  49.             super().add(documents)
  51.         return documents
  53.     def index(self):
  54.         """
  55.         Builds an embeddings index for previously batched documents.
  56.         """
  58.         if self.cluster:
  59.             self.cluster.index()
  60.         else:
  61.             super().index()
  63.     def upsert(self):
  64.         """
  65.         Runs an embeddings upsert operation for previously batched documents.
  66.         """
  68.         if self.cluster:
  69.             self.cluster.upsert()
  70.         else:
  71.             super().upsert()
  73.     def delete(self, ids):
  74.         """
  75.         Deletes from an embeddings index. Returns list of ids deleted.
  77.         Args:
  78.             ids: list of ids to delete
  80.         Returns:
  81.             ids deleted
  82.         """
  84.         if self.cluster:
  85.             return self.cluster.delete(ids)
  87.         return super().delete(ids)
  89.     def count(self):
  90.         """
  91.         Total number of elements in this embeddings index.
  93.         Returns:
  94.             number of elements in embeddings index
  95.         """
  97.         if self.cluster:
  98.             return self.cluster.count()
  100.         return super().count()
  102.     def limit(self, limit):
  103.         """
  104.         Parses the number of results to return from the request. Allows range of 1-250, with a default of 10.
  106.         Args:
  107.             limit: limit parameter
  109.         Returns:
  110.             bounded limit
  111.         """
  113.         # Return between 1 and 250 results, defaults to 10
  114.         return max(1, min(250, int(limit) if limit else 10))

add(self, documents)

Adds a batch of documents for indexing.

Downstream applications can override this method to also store full documents in an external system.

Parameters:

NameTypeDescriptionDefault
documents

list of {id: value, text: value}

required

Returns:

TypeDescription

unmodified input documents

Source code in txtai/api/base.py

  1. def add(self, documents):
  2.     """
  3.     Adds a batch of documents for indexing.
  5.     Downstream applications can override this method to also store full documents in an external system.
  7.     Args:
  8.         documents: list of {id: value, text: value}
  10.     Returns:
  11.         unmodified input documents
  12.     """
  14.     if self.cluster:
  15.         self.cluster.add(documents)
  16.     else:
  17.         super().add(documents)
  19.     return documents

batchsearch(self, queries, limit=None)

Finds documents in the embeddings model most similar to the input queries. Returns a list of {id: value, score: value} sorted by highest score per query, where id is the document id in the embeddings model.

Parameters:

NameTypeDescriptionDefault
queries

queries text

required
limit

maximum results

None

Returns:

TypeDescription
list of {id

value, score: value} per query

Source code in txtai/api/base.py

  1. def batchsearch(self, queries, limit=None):
  2.     if self.cluster:
  3.         return self.cluster.batchsearch(queries, self.limit(limit))
  5.     return super().batchsearch(queries, limit)

count(self)

Total number of elements in this embeddings index.

Returns:

TypeDescription

number of elements in embeddings index

Source code in txtai/api/base.py

  1. def count(self):
  2.     """
  3.     Total number of elements in this embeddings index.
  5.     Returns:
  6.         number of elements in embeddings index
  7.     """
  9.     if self.cluster:
  10.         return self.cluster.count()
  12.     return super().count()

delete(self, ids)

Deletes from an embeddings index. Returns list of ids deleted.

Parameters:

NameTypeDescriptionDefault
ids

list of ids to delete

required

Returns:

TypeDescription

ids deleted

Source code in txtai/api/base.py

  1. def delete(self, ids):
  2.     """
  3.     Deletes from an embeddings index. Returns list of ids deleted.
  5.     Args:
  6.         ids: list of ids to delete
  8.     Returns:
  9.         ids deleted
  10.     """
  12.     if self.cluster:
  13.         return self.cluster.delete(ids)
  15.     return super().delete(ids)

index(self)

Builds an embeddings index for previously batched documents.

Source code in txtai/api/base.py

  1. def index(self):
  2.     """
  3.     Builds an embeddings index for previously batched documents.
  4.     """
  6.     if self.cluster:
  7.         self.cluster.index()
  8.     else:
  9.         super().index()

search(self, query, limit=None, request=None)

Finds documents in the embeddings model most similar to the input query. Returns a list of {id: value, score: value} sorted by highest score, where id is the document id in the embeddings model.

Parameters:

NameTypeDescriptionDefault
query

query text

required
limit

maximum results, used if request is None

None

Returns:

TypeDescription
list of {id

value, score: value}

Source code in txtai/api/base.py

  1. def search(self, query, limit=None, request=None):
  2.     # When search is invoked via the API, limit is set from the request
  3.     # When search is invoked directly, limit is set using the method parameter
  4.     limit = self.limit(request.query_params.get("limit") if request and hasattr(request, "query_params") else limit)
  6.     if self.cluster:
  7.         return self.cluster.search(query, limit)
  9.     return super().search(query, limit)

upsert(self)

Runs an embeddings upsert operation for previously batched documents.

Source code in txtai/api/base.py

  1. def upsert(self):
  2.     """
  3.     Runs an embeddings upsert operation for previously batched documents.
  4.     """
  6.     if self.cluster:
  7.         self.cluster.upsert()
  8.     else:
  9.         super().upsert()