Class: RubyLLM::Citation

Inherits:
Object
  • Object
show all
Includes:
Support::Inspectable
Defined in:
lib/ruby_llm/citation.rb

Overview

A Citation links a span of generated text to the source material that supports it. Providers return citations in different shapes. RubyLLM normalizes all of them into Citation objects on Message#citations. Fields a provider does not report are nil.

chat = RubyLLM.chat(model: 'claude-sonnet-5').with_citations
response = chat.ask "Who created Ruby?", with: "facts.txt"

response.citations.each do |citation|
citation.title      # => "facts.txt"
citation.cited_text # => the quoted passage from facts.txt
citation.text       # => the span of the answer it supports
end

Constant Summary

Constants included from Support::Inspectable

Support::Inspectable::TRUNCATE_AT

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Support::Inspectable

#full_inspect, #inspect, #pretty_print

Constructor Details

#initialize(options = {}) ⇒ Citation

:nodoc:



57
58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/ruby_llm/citation.rb', line 57

def initialize(options = {}) # :nodoc:
  @url = options[:url]
  @title = options[:title]
  @cited_text = options[:cited_text]
  @text = options[:text]
  @start_index = options[:start_index]
  @end_index = options[:end_index]
  @source_id = options[:source_id]
  @source_index = options[:source_index]
  @start_page = options[:start_page]
  @end_page = options[:end_page]
end

Instance Attribute Details

#cited_text ⇒ Object (readonly)

The quoted snippet from the source material, or nil.



28
29
30
 
# File 'lib/ruby_llm/citation.rb', line 28

def cited_text
  @cited_text
end

#end_index ⇒ Object (readonly)

The character offset where the cited span ends in the response content, or nil.



42
43
44
 
# File 'lib/ruby_llm/citation.rb', line 42

def end_index
  @end_index
end

#end_page ⇒ Object (readonly)

The last page of a PDF citation (1-indexed, inclusive), or nil.



55
56
57
 
# File 'lib/ruby_llm/citation.rb', line 55

def end_page
  @end_page
end

#source_id ⇒ Object (readonly)

The provider's identifier for the cited source, or nil.



45
46
47
 
# File 'lib/ruby_llm/citation.rb', line 45

def source_id
  @source_id
end

#source_index ⇒ Object (readonly)

The 0-indexed position of the source document or search result, or nil.



49
50
51
 
# File 'lib/ruby_llm/citation.rb', line 49

def source_index
  @source_index
end

#start_index ⇒ Object (readonly)

The character offset where the cited span starts in the response content, or nil.

response.content[citation.start_index...citation.end_index] == citation.text # => true



38
39
40
 
# File 'lib/ruby_llm/citation.rb', line 38

def start_index
  @start_index
end

#start_page ⇒ Object (readonly)

The first page of a PDF citation (1-indexed, inclusive), or nil.



52
53
54
 
# File 'lib/ruby_llm/citation.rb', line 52

def start_page
  @start_page
end

#text ⇒ Object (readonly)

The span of the response content this citation supports, or nil.



31
32
33
 
# File 'lib/ruby_llm/citation.rb', line 31

def text
  @text
end

#title ⇒ Object (readonly)

The title or filename of the cited source, or nil.



25
26
27
 
# File 'lib/ruby_llm/citation.rb', line 25

def title
  @title
end

#url ⇒ Object (readonly)

The URL of the cited source, when citing the web, or nil.



22
23
24
 
# File 'lib/ruby_llm/citation.rb', line 22

def url
  @url
end

Class Method Details

.from_h(data) ⇒ Object

:nodoc:



70
71
72
 
# File 'lib/ruby_llm/citation.rb', line 70

def self.from_h(data) # :nodoc:
  new(Support::Utils.deep_symbolize_keys(data))
end

Instance Method Details

#==(other) ⇒ Object Also known as: eql?

Returns true if other is a Citation with the same attributes, false otherwise.



96
97
98
 
# File 'lib/ruby_llm/citation.rb', line 96

def ==(other)
  other.is_a?(Citation) && to_h == other.to_h
end

#hash ⇒ Object

:nodoc:



101
102
103
 
# File 'lib/ruby_llm/citation.rb', line 101

def hash # :nodoc:
  to_h.hash
end

#inspect_attributes ⇒ Object

:nodoc:



74
75
76
 
# File 'lib/ruby_llm/citation.rb', line 74

def inspect_attributes # :nodoc:
  { url: url, title: title, start_index: start_index, end_index: end_index }
end

#to_h ⇒ Object

Returns the citation as a Hash with symbol keys, omitting nil fields.



79
80
81
82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/ruby_llm/citation.rb', line 79

def to_h
  {
    url: url,
    title: title,
    cited_text: cited_text,
    text: text,
    start_index: start_index,
    end_index: end_index,
    source_id: source_id,
    source_index: source_index,
    start_page: start_page,
    end_page: end_page
  }.compact
end