REST API

Vectorstore api/v1/vectorstores views.

Vectorstores are created and updated by applying manifests, with smarter apply. These views load and search them, and maintain them:

  • GET vectorstores/: the vectorstores that the user may read.

  • GET vectorstores/<hashed_id>/: a vectorstore that the user may read.

  • GET vectorstores/<hashed_id>/status/: check its status and statistics, now.

  • POST vectorstores/<hashed_id>/deploy/ and POST vectorstores/<hashed_id>/undeploy/.

  • GET vectorstores/<hashed_id>/documents/: its documents.

  • POST vectorstores/<hashed_id>/documents/: add documents, and queue them to be loaded: files, as multipart/form-data, or JSON {"name": ..., "text": ...} or {"url": ...}.

  • DELETE vectorstores/<hashed_id>/documents/<document_id>/: remove a document, and its chunks.

  • POST vectorstores/<hashed_id>/search/: {"query": ..., "k": 4, "searchType": "similarity", "scoreThreshold": null, "fetchK": null, "lambdaMult": null, "filter": {}}.

  • GET vectorstores/<hashed_id>/snapshots/: its snapshots, or backups.

  • POST vectorstores/<hashed_id>/snapshots/: take one now.

  • POST vectorstores/<hashed_id>/snapshots/<snapshot_id>/restore/: restore one.

Reading and searching require read permission. Everything else requires ownership.

The responses are built from the models of smarter.apps.vectorstore.contract.models, which the Smarter api’s OpenAPI document publishes. Errors are Django REST framework’s {"detail": ...}.

class smarter.apps.vectorstore.api.v1.views.VectorstoreDeployView(*args, **kwargs)[source]

Bases: VectorstoreViewBase

Create the database of a vectorstore that the user owns.

post(request, *args, **kwargs)[source]

Deploy the vectorstore: create its database, and, if self-hosted, its server.

Invalidates the owner’s cached vectorstores.

Parameters:
  • request (Request) – The request.

  • kwargs – The url’s arguments: hashed_id or vectorstore_id.

Returns:

The vectorstore, 202 Accepted, or 400 Bad Request if it could not be deployed.

Raises:

Http404 – If it does not exist, or the user does not own it.

class smarter.apps.vectorstore.api.v1.views.VectorstoreDocumentView(*args, **kwargs)[source]

Bases: VectorstoreViewBase

Remove a document, and its chunks, from a vectorstore that the user owns.

delete(request, *args, **kwargs)[source]

Mark a document Deleting, and queue the Celery task that removes it and its chunks.

Parameters:
  • request (Request) – The request.

  • kwargs – The url’s arguments: hashed_id or vectorstore_id, and document_id.

Returns:

The document’s name and status, 202 Accepted.

Raises:

Http404 – If the vectorstore or the document does not exist, or the user does not own it.

class smarter.apps.vectorstore.api.v1.views.VectorstoreDocumentsView(*args, **kwargs)[source]

Bases: VectorstoreViewBase

List a vectorstore’s documents, or add documents to one that the user owns.

get(request, *args, **kwargs)[source]

Return the vectorstore’s documents, newest first.

Parameters:
  • request (Request) – The request.

  • kwargs – The url’s arguments: hashed_id or vectorstore_id.

Returns:

The documents.

Raises:

Http404 – If it does not exist, or the user may not read it.

post(request, *args, **kwargs)[source]

Add documents, and queue them to be loaded.

Files, as multipart/form-data, are read, and their text extracted, now. The files themselves are not kept. Optional metadata, a JSON object, is stored with each chunk.

static sources(request)[source]

The documents of a request: uploaded files, text, or a URL.

class smarter.apps.vectorstore.api.v1.views.VectorstoreListView(*args, **kwargs)[source]

Bases: ContractListMixin, SmarterAuthenticatedListAPIView

The vectorstores that the user may read.

contract_model

alias of VectorstoreApiVectorstore

get_queryset(*args, **kwargs)[source]

Return the vectorstores that the user may read, by name.

Return type:

QuerySet

item(row)[source]

A vectorstore of the response, whose canDelete is the requesting user’s.

serializer_class

alias of VectorstoreSerializer

class smarter.apps.vectorstore.api.v1.views.VectorstoreRestoreView(*args, **kwargs)[source]

Bases: VectorstoreViewBase

Replace a vectorstore’s data with one of its snapshots.

post(request, *args, **kwargs)[source]

Replace the vectorstore’s data with the snapshot of the url.

Parameters:
  • request (Request) – The request.

  • kwargs – The url’s arguments: hashed_id or vectorstore_id, and snapshot_id.

Returns:

The vectorstore, the snapshot and the vector count, or 400 Bad Request if it could not be restored.

Raises:

Http404 – If the vectorstore or the snapshot does not exist, or the user does not own it.

class smarter.apps.vectorstore.api.v1.views.VectorstoreSearchView(*args, **kwargs)[source]

Bases: VectorstoreViewBase

Search a vectorstore that the user may read.

post(request, *args, **kwargs)[source]

Search the vectorstore with the JSON body’s query.

The body may also have k, at most MAX_SEARCH_RESULTS, searchType, scoreThreshold, fetchK, lambdaMult and filter.

Parameters:
  • request (Request) – The request.

  • kwargs – The url’s arguments: hashed_id or vectorstore_id.

Returns:

The results, or 400 Bad Request if the search failed.

Raises:

Http404 – If it does not exist, or the user may not read it.

class smarter.apps.vectorstore.api.v1.views.VectorstoreSnapshotsView(*args, **kwargs)[source]

Bases: VectorstoreViewBase

List a vectorstore’s snapshots, or take one now.

get(request, *args, **kwargs)[source]

Return the vectorstore’s snapshots.

Parameters:
  • request (Request) – The request.

  • kwargs – The url’s arguments: hashed_id or vectorstore_id.

Returns:

The snapshots.

Raises:

Http404 – If it does not exist, or the user may not read it.

post(request, *args, **kwargs)[source]

Take a snapshot of the vectorstore now.

Parameters:
  • request (Request) – The request.

  • kwargs – The url’s arguments: hashed_id or vectorstore_id.

Returns:

The snapshot, 201 Created, or 400 Bad Request if it could not be taken.

Raises:

Http404 – If it does not exist, or the user does not own it.

class smarter.apps.vectorstore.api.v1.views.VectorstoreStatusView(*args, **kwargs)[source]

Bases: VectorstoreViewBase

Check a vectorstore’s status and statistics, now.

get(request, *args, **kwargs)[source]

Reconcile the vectorstore’s status with its database, now, and return it with its statistics.

Parameters:
  • request (Request) – The request.

  • kwargs – The url’s arguments: hashed_id or vectorstore_id.

Returns:

The status, message, vector count and statistics.

Raises:

Http404 – If it does not exist, or the user may not read it.

class smarter.apps.vectorstore.api.v1.views.VectorstoreUndeployView(*args, **kwargs)[source]

Bases: VectorstoreViewBase

Stop serving a vectorstore that the user owns.

A self-hosted server’s data is kept.

post(request, *args, **kwargs)[source]

Undeploy the vectorstore: stop serving it, and keep its data.

Invalidates the owner’s cached vectorstores.

Parameters:
  • request (Request) – The request.

  • kwargs – The url’s arguments: hashed_id or vectorstore_id.

Returns:

The vectorstore, or 400 Bad Request if it could not be undeployed.

Raises:

Http404 – If it does not exist, or the user does not own it.

class smarter.apps.vectorstore.api.v1.views.VectorstoreView(*args, **kwargs)[source]

Bases: VectorstoreViewBase

A vectorstore that the user may read.

get(request, *args, **kwargs)[source]

Return the vectorstore, with canDelete for the requesting user.

Parameters:
  • request (Request) – The request.

  • kwargs – The url’s arguments: hashed_id or vectorstore_id.

Returns:

The vectorstore.

Raises:

Http404 – If it does not exist, or the user may not read it.

serializer_class

alias of VectorstoreSerializer

class smarter.apps.vectorstore.api.v1.views.VectorstoreViewBase(*args, **kwargs)[source]

Bases: SmarterAuthenticatedAPIView

Base class of the views of one vectorstore, identified by hashed_id or vectorstore_id.

get_vectorstore() returns it only if the user may read it, or, with owner=True, owns it. Otherwise it raises Http404, so that other accounts’ vectorstores are not disclosed.

get_service(vectorstore)[source]

Return the service that operates a vectorstore, an instance of service_class.

Parameters:

vectorstore (VectorstoreMeta) – The vectorstore.

Return type:

VectorstoreService

Returns:

Its service.

get_vectorstore(request, owner=False, **kwargs)[source]

Return the vectorstore of the url, if the user may read it, or, with owner, owns it.

Parameters:
  • request (Request) – The request, whose user’s permissions are checked.

  • owner (bool) – Require that the user owns it, rather than only may read it.

  • kwargs – The url’s arguments: hashed_id or vectorstore_id.

Return type:

VectorstoreMeta

Returns:

The vectorstore.

Raises:

Http404 – If it does not exist, or the user may not read, or own, it.

service_class

alias of VectorstoreService

smarter.apps.vectorstore.api.v1.views.error(message, status=HTTPStatus.BAD_REQUEST)[source]

An error response: Django REST framework’s {"detail": ...}, as every error of the REST api.

Parameters:
  • message (str) – The error’s message.

  • status (int) – The HTTP status. By default 400 Bad Request.

Return type:

Response

Returns:

The response.

URL configuration for the Vectorstore app API.

These are mounted at /api/v1/vectorstores/. See smarter.apps.vectorstore.api.v1.views.

smarter.apps.vectorstore.api.v1.urls.PER_VECTORSTORE = {'': <class 'smarter.apps.vectorstore.api.v1.views.VectorstoreView'>, 'deploy/': <class 'smarter.apps.vectorstore.api.v1.views.VectorstoreDeployView'>, 'documents/': <class 'smarter.apps.vectorstore.api.v1.views.VectorstoreDocumentsView'>, 'documents/<int:document_id>/': <class 'smarter.apps.vectorstore.api.v1.views.VectorstoreDocumentView'>, 'search/': <class 'smarter.apps.vectorstore.api.v1.views.VectorstoreSearchView'>, 'snapshots/': <class 'smarter.apps.vectorstore.api.v1.views.VectorstoreSnapshotsView'>, 'snapshots/<int:snapshot_id>/restore/': <class 'smarter.apps.vectorstore.api.v1.views.VectorstoreRestoreView'>, 'status/': <class 'smarter.apps.vectorstore.api.v1.views.VectorstoreStatusView'>, 'undeploy/': <class 'smarter.apps.vectorstore.api.v1.views.VectorstoreUndeployView'>}

The views of one vectorstore, by URL suffix.

{
    '': <class 'smarter.apps.vectorstore.api.v1.views.VectorstoreView'>,
    'deploy/': <class 'smarter.apps.vectorstore.api.v1.views.VectorstoreDeployView'>,
    'documents/': <class 'smarter.apps.vectorstore.api.v1.views.VectorstoreDocumentsView'>,
    'documents/<int:document_id>/': <class 'smarter.apps.vectorstore.api.v1.views.VectorstoreDocumentView'>,
    'search/': <class 'smarter.apps.vectorstore.api.v1.views.VectorstoreSearchView'>,
    'snapshots/': <class 'smarter.apps.vectorstore.api.v1.views.VectorstoreSnapshotsView'>,
    'snapshots/<int:snapshot_id>/restore/': <class 'smarter.apps.vectorstore.api.v1.views.VectorstoreRestoreView'>,
    'status/': <class 'smarter.apps.vectorstore.api.v1.views.VectorstoreStatusView'>,
    'undeploy/': <class 'smarter.apps.vectorstore.api.v1.views.VectorstoreUndeployView'>,
}
class smarter.apps.vectorstore.api.v1.urls.VectorstoreApiV1ReverseViews[source]

Bases: object

Reverse view names of the Vectorstore api.

Each is available by the vectorstore’s hashed id, and by its id.

url = reverse(
    f"{VectorstoreApiV1ReverseViews.namespace}:{VectorstoreApiV1ReverseViews.search_by_hashed_id}",
    kwargs={"hashed_id": vectorstore.hashed_id},
)
deploy_by_hashed_id = 'vectorstore_deploy_view_by_hashed_id'
document_by_hashed_id = 'vectorstore_document_view_by_hashed_id'
documents_by_hashed_id = 'vectorstore_documents_view_by_hashed_id'
list_view = 'vectorstore_list_view'
namespace = 'api:v1:vectorstore'
restore_by_hashed_id = 'vectorstore_restore_view_by_hashed_id'
search_by_hashed_id = 'vectorstore_search_view_by_hashed_id'
snapshots_by_hashed_id = 'vectorstore_snapshots_view_by_hashed_id'
status_by_hashed_id = 'vectorstore_status_view_by_hashed_id'
undeploy_by_hashed_id = 'vectorstore_undeploy_view_by_hashed_id'
vectorstore_by_hashed_id = 'vectorstore_view_by_hashed_id'