blib/lib/Database/BI/Summary.pm

filter: Statementstmt 99.0% 101 / 102 Branchbran 90.4% 38 / 42 Conditioncond 75.8% 22 / 29 MC/DCmcdc 50.0% 7 / 14 Subroutinesub 100% 11 / 11 Podpod 100% 1 / 1 totaltotal 90.4% 180 / 199 CC 36 SCAR 23.2
CC
36
Cov
93%
generate
16.7
_template_summary
12.0
_call_anthropic
5.0
CRAP 10.2
« blib/lib/Database/BI/Calc.pm ↑ Summary blib/lib/Database/BI/Ask.pm »
1 package Database::BI::Summary;
2  
3 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 1 our $VERSION = '0.023.1';
7  
8 1 ▶use Carp qw(croak);
Subroutine BEGIN: called CC=1 SCAR=0.0
9 1 ▶use Digest::MD5 qw(md5_hex);
Subroutine BEGIN: called CC=1 SCAR=0.0
10 1 ▶use Encode qw(encode_utf8);
Subroutine BEGIN: called CC=1 SCAR=0.0
11 1 ▶use Readonly;
Subroutine BEGIN: called CC=1 SCAR=0.0
12  
13 1 Readonly my $MAX_SUMMARY_INSIGHTS => 5;
14 1 Readonly my $CACHE_TTL_S => 3600; # 1 hour
15  
16 1 my %_cache; # fingerprint => { text, source, ts }
17  
18 # ---------------------------------------------------------------------------
19 # generate(%args) -> { text, source, cached }
20 #
21 # args:
22 # insights arrayref of insight hashrefs (from Insights::compute)
23 # spec_key the l= spec value (used internally; never sent to LLM)
24 # label human-readable dataset name
25 # row_count number of rows analysed
26 # ai_config optional hashref { provider, api_key, model }
27 # use_ai 1 to request LLM polish (honoured only when ai_config is set
28 # and ai_config->{api_key} is non-empty)
29 # ai_allowed optional code ref, called just before a provider call (not
30 # for a cached answer); false means do not call, so the
31 # template text is returned, uncached, as 'template_limited'
32 # ---------------------------------------------------------------------------
33 9 ▶sub generate {
Subroutine generate: called CC=16 SCAR=28.2
Pod documented
34 9 my (%args) = @_;
35 9 ▶ my $insights = $args{insights} // [];
Condition100%2/2
$args{"insights"} // []
l!l
81
MC/DC100%1/1
$args{"insights"} // []
$args{"insights"}
Truth table100%2/2
A
A= $args{"insights"}
Aresult
11
00
36 9 ▶ my $label = $args{label} // 'dataset';
Condition100%2/2
$args{"label"} // "dataset"
l!l
81
MC/DC100%1/1
$args{"label"} // "dataset"
$args{"label"}
Truth table100%2/2
A
A= $args{"label"}
Aresult
11
00
37 9 ▶ my $row_count = $args{row_count} // 0;
Condition100%2/2
$args{"row_count"} // 0
l!l
81
MC/DC100%1/1
$args{"row_count"} // 0
$args{"row_count"}
Truth table100%2/2
A
A= $args{"row_count"}
Aresult
11
00
38 my $use_ai = ($args{use_ai} && $args{ai_config}
39 9 ▶ && length($args{ai_config}{api_key} // ''))
Branch: 1 branch
BranchTrueFalseTotal
$args{'use_ai'} && $args{'ai_config'} && length($args{'ai_config'}{'api_key'} // '') ? : 4 5 9
Condition75%6/8
$args{"use_ai"} and $args{"ai_config"} and length($args{"ai_config"}{"api_key"} // "")
!ll&&!rl&&r
414
$args{"use_ai"} and $args{"ai_config"}
!ll&&!rl&&r
405
$args{"ai_config"}{"api_key"} // ""
l!l
50
MC/DC33%1/3
$args{"use_ai"} and $args{"ai_config"} and length($args{"ai_config"}{"api_key"} // "")
$args{"use_ai"} $args{"ai_config"} $args{"ai_config"}{"api_key"}
Truth table50%2/4
A and B and C
A= $args{"use_ai"}B= $args{"ai_config"}C= $args{"ai_config"}{"api_key"}
ABCresult
0XX0
10X0
1100
1111
40 ? 1 : 0;
41 9 ▶ my $ai_config = $use_ai ? $args{ai_config} : undef;
Branch: 1 branch
BranchTrueFalseTotal
$use_ai ? : 4 5 9
42  
43 9 my $fp = _fingerprint($insights, $use_ai, $label, $row_count);
44 9 ▶ if (my $cached = $_cache{$fp}) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $cached = $_cache{$fp}) 2 7 9
45 2 ▶ if ((time() - $cached->{ts}) < $CACHE_TTL_S) {
Branch: 1 branch
BranchTrueFalseTotal
if (time - $$cached{"ts"} < $CACHE_TTL_S) 2 0 2
46 2 return { text => $cached->{text}, source => $cached->{source}, cached => 1 };
47 }
48 }
49  
50 7 my ($text, $source);
51 7 ▶ if ($use_ai && ref($args{ai_allowed}) eq 'CODE' && !$args{ai_allowed}->()) {
Branch: 1 branch
BranchTrueFalseTotal
if ($use_ai and ref $args{"ai_allowed"} eq "CODE" and not $args{"ai_allowed"}()) 0 7 7
Condition50%3/6
$use_ai and ref $args{"ai_allowed"} eq "CODE" and not $args{"ai_allowed"}()
!ll&&!rl&&r
700
$use_ai and ref $args{"ai_allowed"} eq "CODE"
!ll&&!rl&&r
520
MC/DC0%0/3
$use_ai and ref $args{"ai_allowed"} eq "CODE" and not $args{"ai_allowed"}()
$use_ai ref $args{"ai_allowed"} eq "CODE" not $args{"ai_allowed"}()
Truth table50%2/4
A and B and not(C)
A= $use_aiB= ref $args{"ai_allowed"} eq "CODE"C= not $args{"ai_allowed"}()
ABCresult
0XX0
10X0
1100
1111
52 # Not cached: once the limit lifts, the same summary may ask again.
53 0 return { text => _template_summary($insights, $label, $row_count), source => 'template_limited', cached => 0 };
54 }
55 7 ▶ if ($use_ai) {
Branch: 1 branch
BranchTrueFalseTotal
if ($use_ai) { } 2 5 7
56 2 eval { ($text, $source) = _llm_summary($insights, $label, $row_count, $ai_config) };
57 2 ▶ if ($@) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 1 1 2
58 1 $text = _template_summary($insights, $label, $row_count);
59 1 $source = 'template_fallback';
60 }
61 } else {
62 5 $text = _template_summary($insights, $label, $row_count);
63 5 $source = 'template';
64 }
65  
66 7 $_cache{$fp} = { text => $text, source => $source, ts => time() };
67 7 return { text => $text, source => $source, cached => 0 };
68 }
69  
70 # ---------------------------------------------------------------------------
71 # _fingerprint(\@insights, $use_ai, $label, $row_count) -> $hex
72 #
73 # Holds everything the text is made from. The detail counts: two period deltas
74 # can share a headline while their figures differ. md5_hex takes bytes only, and
75 # croaks on a wide character, so the string is encoded first.
76 # ---------------------------------------------------------------------------
77 19 ▶sub _fingerprint {
Subroutine _fingerprint: called CC=3 SCAR=11.0
78 19 my ($insights, $use_ai, $label, $row_count) = @_;
79 my $str = ($use_ai ? 'ai:' : 'tmpl:')
80 . "L:${label}:R:${row_count}:"
81 19 ▶ . join('|', map { "$_->{kind}:$_->{headline}:" . ($_->{detail} // '') } @$insights);
Branch: 1 branch
BranchTrueFalseTotal
$use_ai ? : 5 14 19
Condition50%1/2
$$_{"detail"} // ""
l!l
130
MC/DC0%0/1
$$_{"detail"} // ""
$$_{"detail"}
Truth table50%1/2
A
A= $$_{"detail"}
Aresult
11
00
82 19 return md5_hex(encode_utf8($str));
83 }
84  
85 # ---------------------------------------------------------------------------
86 # _template_summary(\@insights, $label, $row_count) -> $text
87 # ---------------------------------------------------------------------------
88 19 ▶sub _template_summary {
Subroutine _template_summary: called CC=12 SCAR=24.9
89 19 my ($insights, $label, $row_count) = @_;
90 19 my @sentences;
91 19 ▶ push @sentences, sprintf('%s: %d row%s analysed.',
Branch: 1 branch
BranchTrueFalseTotal
$row_count == 1 ? : 15 4 19
92 $label, $row_count, ($row_count == 1 ? '' : 's'));
93  
94 19 my %by_kind;
95 19 for my $ins (@$insights) {
96 15 push @{ $by_kind{ $ins->{kind} } }, $ins;
97 }
98  
99 19 my $count = 0;
100 19 for my $kind (qw(outlier period_delta top_mover seasonality)) {
101 76 ▶ last if $count >= $MAX_SUMMARY_INSIGHTS;
Branch: 1 branch
BranchTrueFalseTotal
if $count >= $MAX_SUMMARY_INSIGHTS 0 76 76
102 76 ▶ my $items = $by_kind{$kind} or next;
Branch: 1 branch
BranchTrueFalseTotal
my $items = $by_kind{$kind} or next 11 65 76
103 11 my $first = $items->[0];
104 11 ▶ if ($kind eq 'outlier') {
Branch: 4 branches
BranchTrueFalseTotal
if ($kind eq 'outlier') { } 4 7 11
elsif ($kind eq 'period_delta') { } 2 5 7
elsif ($kind eq 'top_mover') { } 3 2 5
elsif ($kind eq 'seasonality') { } 2 0 2
105 4 my $n = scalar @$items;
106 4 ▶ if ($n == 1) {
Branch: 1 branch
BranchTrueFalseTotal
if ($n == 1) { } 3 1 4
107 3 push @sentences, "An unusual value was detected: $first->{headline}.";
108 } else {
109 1 push @sentences, "$n outliers detected, including: $first->{headline}.";
110 }
111 } elsif ($kind eq 'period_delta') {
112 2 push @sentences, "$first->{headline}. $first->{detail}.";
113 } elsif ($kind eq 'top_mover') {
114 3 push @sentences, "Top movement: $first->{headline}.";
115 } elsif ($kind eq 'seasonality') {
116 2 push @sentences, "A repeating seasonal pattern was detected: $first->{headline}.";
117 }
118 11 $count++;
119 }
120  
121 19 ▶ push @sentences, 'No significant patterns were detected.' if $count == 0;
Branch: 1 branch
BranchTrueFalseTotal
if $count == 0 11 8 19
122 19 return join(' ', @sentences);
123 }
124  
125 # ---------------------------------------------------------------------------
126 # _llm_summary(\@insights, $label, $row_count, $ai_config) -> ($text, 'llm')
127 #
128 # Sends only aggregate facts (insight kinds, headlines, details) to the LLM.
129 # Never sends file paths, raw row data, or the spec_key.
130 # ---------------------------------------------------------------------------
131 4 ▶sub _llm_summary {
Subroutine _llm_summary: called CC=4 SCAR=13.9
132 4 my ($insights, $label, $row_count, $ai_config) = @_;
133  
134 4 ▶ my $provider = lc($ai_config->{provider} // 'anthropic');
Condition100%2/2
$$ai_config{"provider"} // "anthropic"
l!l
31
MC/DC100%1/1
$$ai_config{"provider"} // "anthropic"
$$ai_config{"provider"}
Truth table100%2/2
A
A= $$ai_config{"provider"}
Aresult
11
00
135 4 ▶ croak "Unsupported AI provider: $provider" unless $provider eq 'anthropic';
Branch: 1 branch
BranchTrueFalseTotal
unless $provider eq "anthropic" 2 2 4
136  
137 2 my $n = scalar @$insights;
138 2 ▶ $n = $MAX_SUMMARY_INSIGHTS if $n > $MAX_SUMMARY_INSIGHTS;
Branch: 1 branch
BranchTrueFalseTotal
if $n > $MAX_SUMMARY_INSIGHTS 1 1 2
139 6 my @facts = map { "- [$_->{kind}] $_->{headline}. $_->{detail}" }
140 2 @{$insights}[0 .. $n - 1];
141  
142 2 my $prompt = 'Summarise these data insights about "' . $label . '" ('
143 . $row_count . ' rows) in 2-3 plain-English sentences. '
144 . "Use only the facts provided:\n\n"
145 . join("\n", @facts)
146 . "\n\nSummary:";
147  
148 2 my $response_text = _call_anthropic($prompt, $ai_config);
149 2 $response_text =~ s/\A\s+//;
150 2 $response_text =~ s/\s+\z//;
151 2 return ($response_text, 'llm');
152 }
153  
154 # ---------------------------------------------------------------------------
155 # _call_anthropic($prompt, $ai_config) -> $response_text
156 # ---------------------------------------------------------------------------
157 8 ▶sub _call_anthropic {
Subroutine _call_anthropic: called CC=5 SCAR=16.1
158 8 my ($prompt, $ai_config) = @_;
159  
160 8 require LWP::UserAgent;
161 8 require HTTP::Request;
162 8 require JSON::PP; # core since Perl 5.013009; MIN_PERL_VERSION is 5.028000
163  
164 8 ▶ my $model = $ai_config->{model} // 'claude-haiku-5-5';
Condition50%1/2
$$ai_config{"model"} // "claude-haiku-5-5"
l!l
08
MC/DC0%0/1
$$ai_config{"model"} // "claude-haiku-5-5"
$$ai_config{"model"}
Truth table50%1/2
A
A= $$ai_config{"model"}
Aresult
11
00
165 8 my $api_key = $ai_config->{api_key};
166  
167 8 my $body = JSON::PP::encode_json({
168 model => $model,
169 max_tokens => 256,
170 messages => [{ role => 'user', content => $prompt }],
171 });
172  
173 8 my $ua = LWP::UserAgent->new(timeout => 30);
174 8 my $req = HTTP::Request->new(
175 'POST',
176 'https://api.anthropic.com/v1/messages',
177 [
178 'Content-Type' => 'application/json',
179 'x-api-key' => $api_key,
180 'anthropic-version' => '2023-06-01',
181 ],
182 $body,
183 );
184  
185 8 my $resp = $ua->request($req);
186 8 ▶ croak sprintf('Provider error: %s', $resp->status_line) unless $resp->is_success;
Branch: 1 branch
BranchTrueFalseTotal
unless $resp->is_success 1 7 8
187  
188 7 my $data = JSON::PP::decode_json($resp->decoded_content);
189 6 my $text = eval { $data->{content}[0]{text} };
190 6 ▶ croak 'No text in provider response' unless defined $text && length $text;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $text and length $text 5 1 6
Condition100%3/3
defined $text and length $text
!ll&&!rl&&r
411
MC/DC100%2/2
defined $text and length $text
defined $text length $text
Truth table100%3/3
A and B
A= defined $textB= length $text
ABresult
0X0
100
111
191 1 return $text;
192 }
193  
194 1 1;
195  
196 __END__
« blib/lib/Database/BI/Calc.pm ↑ Summary blib/lib/Database/BI/Ask.pm »