Class: Vellum::DocumentsClient

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:) ⇒ DocumentsClient

Parameters:



17
18
19
20
 
# File 'lib/vellum_ai/documents/client.rb', line 17

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

Instance Attribute Details

#request_client ⇒ Object (readonly)

Returns the value of attribute request_client.



13
14
15
 
# File 'lib/vellum_ai/documents/client.rb', line 13

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) 


50
51
52
53
54
55
56
57
 
# File 'lib/vellum_ai/documents/client.rb', line 50

def destroy(id:, request_options: nil)
  @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

#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:



30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
 
# File 'lib/vellum_ai/documents/client.rb', line 30

def list(document_index_id: nil, limit: nil, offset: nil, ordering: nil, request_options: nil)
  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

#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:



68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
 
# File 'lib/vellum_ai/documents/client.rb', line 68

def partial_update(id:, label: nil, status: nil, metadata: nil, request_options: nil)
  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

#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:



104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
 
# File 'lib/vellum_ai/documents/client.rb', line 104

def upload(label:, contents:, add_to_index_names: nil, external_id: nil, keywords: nil, metadata: nil,
           request_options: nil)
  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