Class: Vellum::AsyncDocumentsClient

Inherits:
Object
  • Object
show all
Defined in:
lib/vellum_ai/documents/client.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(request_client:) ⇒ AsyncDocumentsClient

Parameters:



130
131
132
133
 
# File 'lib/vellum_ai/documents/client.rb', line 130

def initialize(request_client:)
  # @type [AsyncRequestClient]
  @request_client = request_client
end

Instance Attribute Details

#request_client ⇒ Object (readonly)

Returns the value of attribute request_client.



126
127
128
 
# File 'lib/vellum_ai/documents/client.rb', line 126

def request_client
  @request_client
end

Instance Method Details

#destroy(id:, request_options: nil) ⇒ Void

Parameters:

  • id (String) —

    A UUID string identifying this document.

  • request_options (RequestOptions) (defaults to: nil)

Returns:

  • (Void) 


165
166
167
168
169
170
171
172
173
174
 
# File 'lib/vellum_ai/documents/client.rb', line 165

def destroy(id:, request_options: nil)
  Async do
    @request_client.conn.delete do |req|
      req.options.timeout = request_options.timeout_in_seconds unless request_options&.timeout_in_seconds.nil?
      req.headers["X_API_KEY"] = request_options.api_key unless request_options&.api_key.nil?
      req.headers = { **req.headers, **(request_options&.additional_headers || {}) }.compact
      req.url "#{@request_client.default_environment[:Default]}/v1/documents/#{id}"
    end
  end
end

#list(document_index_id: nil, limit: nil, offset: nil, ordering: nil, request_options: nil) ⇒ PaginatedSlimDocumentList

Used to list documents. Optionally filter on supported fields.

Parameters:

  • document_index_id (String) (defaults to: nil) —

    Filter down to only those documents that are included in the specified index. You may provide either the Vellum-generated ID or the unique name of the index specified upon initial creation.

  • limit (Integer) (defaults to: nil) —

    Number of results to return per page.

  • offset (Integer) (defaults to: nil) —

    The initial index from which to return the results.

  • ordering (String) (defaults to: nil) —

    Which field to use when ordering the results.

  • request_options (RequestOptions) (defaults to: nil)

Returns:



143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/vellum_ai/documents/client.rb', line 143

def list(document_index_id: nil, limit: nil, offset: nil, ordering: nil, request_options: nil)
  Async do
    response = @request_client.conn.get do |req|
      req.options.timeout = request_options.timeout_in_seconds unless request_options&.timeout_in_seconds.nil?
      req.headers["X_API_KEY"] = request_options.api_key unless request_options&.api_key.nil?
      req.headers = { **req.headers, **(request_options&.additional_headers || {}) }.compact
      req.params = {
        **(request_options&.additional_query_parameters || {}),
        "document_index_id": document_index_id,
        "limit": limit,
        "offset": offset,
        "ordering": ordering
      }.compact
      req.url "#{@request_client.default_environment[:Default]}/v1/documents"
    end
    PaginatedSlimDocumentList.from_json(json_object: response.body)
  end
end

#partial_update(id:, label: nil, status: nil, metadata: nil, request_options: nil) ⇒ DocumentRead

Update a Document, keying off of its Vellum-generated ID. Particularly useful for updating its metadata.

Parameters:

  • id (String) —

    A UUID string identifying this document.

  • label (String) (defaults to: nil) —

    A human-readable label for the document. Defaults to the originally uploaded file’s file name.

  • status (DOCUMENT_STATUS) (defaults to: nil) —

    The current status of the document

    • ‘ACTIVE` - Active

  • metadata (Hash{String => String}) (defaults to: nil) —

    A JSON object containing any metadata associated with the document that you’d like to filter upon later.

  • request_options (RequestOptions) (defaults to: nil)

Returns:



185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
 
# File 'lib/vellum_ai/documents/client.rb', line 185

def partial_update(id:, label: nil, status: nil, metadata: nil, request_options: nil)
  Async do
    response = @request_client.conn.patch do |req|
      req.options.timeout = request_options.timeout_in_seconds unless request_options&.timeout_in_seconds.nil?
      req.headers["X_API_KEY"] = request_options.api_key unless request_options&.api_key.nil?
      req.headers = { **req.headers, **(request_options&.additional_headers || {}) }.compact
      req.body = {
        **(request_options&.additional_body_parameters || {}),
        label: label,
        status: status,
        metadata: metadata
      }.compact
      req.url "#{@request_client.default_environment[:Default]}/v1/documents/#{id}"
    end
    DocumentRead.from_json(json_object: response.body)
  end
end

#upload(label:, contents:, add_to_index_names: nil, external_id: nil, keywords: nil, metadata: nil, request_options: nil) ⇒ UploadDocumentResponse

Upload a document to be indexed and used for search.

Note: Uses a base url of ‘documents.vellum.ai`.

This is a multipart/form-data request. The ‘contents` field should be a file upload. It also expects a JSON body with the following fields:

  • ‘add_to_index_names: list` - Optionally include the names of all indexes that you’d like this document to be included in

  • ‘external_id: str | None` - Optionally include an external ID for this document. This is useful if you want to re-upload the same document later when its contents change and would like it to be re-indexed.

  • ‘label: str` - A human-friendly name for this document. Typically the filename.

  • ‘keywords: list | None` - Optionally include a list of keywords that’ll be associated with this document. Used when performing keyword searches.

  • ‘metadata: dict[str, Any]` - A stringified JSON object containing any metadata associated with the document that you’d like to filter upon later.

Parameters:

  • add_to_index_names (Array<String>) (defaults to: nil) —

    Optionally include the names of all indexes that you’d like this document to be included in

  • external_id (String) (defaults to: nil) —

    Optionally include an external ID for this document. This is useful if you want to re-upload the same document later when its contents change and would like it to be re-indexed.

  • label (String) —

    A human-friendly name for this document. Typically the filename.

  • contents (String, IO)
  • keywords (Array<String>) (defaults to: nil) —

    Optionally include a list of keywords that’ll be associated with this document. Used when performing keyword searches.

  • metadata (String) (defaults to: nil) —

    A stringified JSON object containing any metadata associated with the document that you’d like to filter upon later.

  • request_options (RequestOptions) (defaults to: nil)

Returns:



223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
 
# File 'lib/vellum_ai/documents/client.rb', line 223

def upload(label:, contents:, add_to_index_names: nil, external_id: nil, keywords: nil, metadata: nil,
           request_options: nil)
  Async do
    response = @request_client.conn.post do |req|
      req.options.timeout = request_options.timeout_in_seconds unless request_options&.timeout_in_seconds.nil?
      req.headers["X_API_KEY"] = request_options.api_key unless request_options&.api_key.nil?
      req.headers = { **req.headers, **(request_options&.additional_headers || {}) }.compact
      req.body = {
        **(request_options&.additional_body_parameters || {}),
        add_to_index_names: add_to_index_names,
        external_id: external_id,
        label: label,
        contents: FileUtilities.as_faraday_multipart(file_like: contents),
        keywords: keywords,
        metadata: metadata
      }.compact
      req.url "#{@request_client.default_environment[:Documents]}/v1/upload-document"
    end
    UploadDocumentResponse.from_json(json_object: response.body)
  end
end