Class: VectorAmp::IntelligenceResource

Inherits:
Object
  • Object
show all
Defined in:
lib/vector_amp/intelligence.rb

Overview

Intelligence API resource for retrieval-augmented question answering.

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(transport) ⇒ IntelligenceResource

Parameters:

  • transport (#request) —

    API transport.



10
11
12
 
# File 'lib/vector_amp/intelligence.rb', line 10

def initialize(transport)
  @transport = transport
end

Class Method Details

.normalize_dataset_ids(dataset_ids) ⇒ Array<String>

Normalize a dataset scope for the wire.

POST /intelligence/query scopes with dataset_ids and reads an absent field as "every dataset the caller can see". The singular dataset_id is retired and now draws a 400, and the "all" sentinel it carried says nothing an omitted field does not, so both are dropped here rather than transmitted.

Parameters:

  • dataset_ids (Array<String>, String, nil) —

    requested scope.

Returns:

  • (Array<String>) —

    normalized dataset ids.



57
58
59
 
# File 'lib/vector_amp/intelligence.rb', line 57

def self.normalize_dataset_ids(dataset_ids)
  Array(dataset_ids).map { |id| id.to_s.strip }.reject { |id| id.empty? || id == "all" }
end

Instance Method Details

#append_message(session_id, role:, content:, metadata: nil) ⇒ Hash

Append a message to a session.

Parameters:

  • session_id (String) —

    session id.

  • role (String) —

    message role: user, assistant, system, or tool.

  • content (String) —

    message content.

  • metadata (Hash, nil) (defaults to: nil) —

    optional message metadata.

Returns:

  • (Hash) —

    created message.



104
105
106
107
 
# File 'lib/vector_amp/intelligence.rb', line 104

def append_message(session_id, role:, content:, metadata: nil)
  body = Utils.compact_hash(role: role, content: content, metadata: metadata)
  @transport.request(:post, "/intelligence/sessions/#{session_id}/messages", body: body)
end

#create_session(title: nil, dataset_id: nil, workspace_id: nil, metadata: nil) ⇒ Hash

Create an intelligence conversation session.

Parameters:

  • title (String, nil) (defaults to: nil) —

    optional session title.

  • dataset_id (String, nil) (defaults to: nil) —

    optional dataset scope.

  • workspace_id (String, nil) (defaults to: nil) —

    optional workspace id.

  • metadata (Hash, nil) (defaults to: nil) —

    optional session metadata.

Returns:

  • (Hash) —

    created session.



67
68
69
70
71
72
73
74
75
 
# File 'lib/vector_amp/intelligence.rb', line 67

def create_session(title: nil, dataset_id: nil, workspace_id: nil, metadata: nil)
  body = Utils.compact_hash(
    title: title,
    dataset_id: dataset_id,
    workspace_id: workspace_id,
    metadata: metadata
  )
  @transport.request(:post, "/intelligence/sessions", body: body)
end

#delete_session(session_id) ⇒ Hash

Delete an intelligence session.

Parameters:

  • session_id (String) —

    session id.

Returns:

  • (Hash) —

    delete response.



94
95
96
 
# File 'lib/vector_amp/intelligence.rb', line 94

def delete_session(session_id)
  @transport.request(:delete, "/intelligence/sessions/#{session_id}")
end

#get_session(session_id) ⇒ Hash

Fetch an intelligence session.

Parameters:

  • session_id (String) —

    session id.

Returns:

  • (Hash) —

    session resource.



87
88
89
 
# File 'lib/vector_amp/intelligence.rb', line 87

def get_session(session_id)
  @transport.request(:get, "/intelligence/sessions/#{session_id}")
end

#list_messages(session_id, limit: 100) ⇒ Hash

List messages in a session.

Parameters:

  • session_id (String) —

    session id.

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

    page size; defaults to 100.

Returns:

  • (Hash) —

    response envelope with messages.



113
114
115
 
# File 'lib/vector_amp/intelligence.rb', line 113

def list_messages(session_id, limit: 100)
  @transport.request(:get, "/intelligence/sessions/#{session_id}/messages", query: { limit: limit })
end

#list_sessions(limit: 50) ⇒ Hash

List intelligence sessions.

Parameters:

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

    page size; defaults to 50.

Returns:

  • (Hash) —

    response envelope with sessions.



80
81
82
 
# File 'lib/vector_amp/intelligence.rb', line 80

def list_sessions(limit: 50)
  @transport.request(:get, "/intelligence/sessions", query: { limit: limit })
end

#query(query, dataset_ids: nil, top_k: nil, conversation_history: nil, include_sources: nil, stream: false, **unknown) {|chunk| ... } ⇒ Hash, ...

Ask an intelligence query, optionally scoped to datasets and streamed.

Parameters:

  • query (String) —

    natural-language question.

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

    datasets to scope the question to; omit to search every dataset the API key can see.

  • top_k (Integer, nil) (defaults to: nil) —

    optional retrieval result count.

  • conversation_history (Array<Hash>, nil) (defaults to: nil) —

    optional prior conversation messages.

  • include_sources (Boolean, nil) (defaults to: nil) —

    include source chunks/citations when supported.

  • stream (Boolean) (defaults to: false) —

    stream chunks when true; defaults to false.

Yield Parameters:

  • chunk (Object) —

    streamed response chunk when stream is true.

Returns:

  • (Hash, Enumerator, Object) —

    response hash, enumerator without a stream block, or transport stream result.



24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
 
# File 'lib/vector_amp/intelligence.rb', line 24

def query(query, dataset_ids: nil, top_k: nil, conversation_history: nil, include_sources: nil, stream: false, **unknown, &block)
  Utils.ensure_no_unknown!(unknown, "query")
  scope = self.class.normalize_dataset_ids(dataset_ids)
  body = Utils.compact_hash(
    query: query,
    # An absent dataset_ids is how the API says "every dataset you can see";
    # an empty array would be a narrower, different request.
    dataset_ids: scope.empty? ? nil : scope,
    top_k: top_k,
    conversation_history: conversation_history,
    include_sources: include_sources,
    stream: stream
  )

  if stream
    return enum_for(:query, query, dataset_ids: dataset_ids, top_k: top_k,
                    conversation_history: conversation_history, include_sources: include_sources,
                    stream: true) unless block

    @transport.request(:post, "/intelligence/query", body: body, stream: true, &block)
  else
    @transport.request(:post, "/intelligence/query", body: body)
  end
end