blib/lib/SignalWire/Skills/Builtin/WebSearch.pm

filter: Statementstmt 60.4% 55 / 91 Branchbran 42.3% 11 / 26 Conditioncond 20.5% 7 / 34 MC/DCmcdc 18.7% 3 / 16 Subroutinesub 80.9% 17 / 21 Podpod 0.0% 0 / 5 totaltotal 48.1% 93 / 193 CC 30 SCAR 48.4
CC
30
Cov
48%
search_web
342.0
_wrap_response
10.1
__ANON__
6.0
CRAP 126.1
« blib/lib/SignalWire/POM/PromptObjectModel.pm ↑ Summary blib/lib/SignalWire/Relay/Client.pm »
1 package SignalWire::Skills::Builtin::WebSearch;
2 # Copyright (c) 2025 SignalWire
3 # Licensed under the MIT License.
4 #
5 # Real Google Custom Search client. Mirrors signalwire-python's
6 # skills/web_search/skill.py:GoogleSearchScraper.search_google — issue
7 # an outbound GET to customsearch/v1 with `key`, `cx`, `q`, parse
8 # the JSON `items[]` array, format title+snippet for the LLM.
9 #
10 # Python's full implementation also fetches each result URL and runs
11 # HTML extraction + quality scoring. We ship the search portion (the
12 # part the audit_skills_dispatch contract probes) in the SDK and leave
13 # the page-extraction to the spider skill, so consumers compose the two
14 # when they want full-page text. A Perl port that ships ~600 lines of
15 # BeautifulSoup-equivalent HTML cleanup is a separate piece of work.
16  
17 4 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
18 4 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
19 4 ▶use Moo;
Subroutine BEGIN: called CC=1 SCAR=0.0
20 4 ▶use HTTP::Tiny;
Subroutine BEGIN: called CC=1 SCAR=0.0
21 4 ▶use JSON ();
Subroutine BEGIN: called CC=1 SCAR=0.0
22 4 ▶use URI::Escape qw(uri_escape);
Subroutine BEGIN: called CC=1 SCAR=0.0
23 4 extends 'SignalWire::Skills::SkillBase';
24  
25 4 ▶use SignalWire::Skills::SkillRegistry;
Subroutine BEGIN: called CC=1 SCAR=0.0
26 4 SignalWire::Skills::SkillRegistry->register_skill('web_search', __PACKAGE__);
27  
28 12 ▶has '+skill_name' => (default => sub { 'web_search' });
Subroutine __ANON__: called CC=1 SCAR=0.0
29 12 ▶has '+skill_description' => (default => sub { 'Search the web for information using Google Custom Search API' });
Subroutine __ANON__: called CC=1 SCAR=0.0
30 12 ▶has '+skill_version' => (default => sub { '2.0.0' });
Subroutine __ANON__: called CC=1 SCAR=0.0
31 12 ▶has '+supports_multiple_instances' => (default => sub { 1 });
Subroutine __ANON__: called CC=1 SCAR=0.0
32  
33 # Google CSE base URL. Honor WEB_SEARCH_BASE_URL env var so the audit
34 # fixture (audit_skills_dispatch.py) can redirect us at a local HTTP
35 # server. The override replaces the host+scheme; the canonical
36 # `/customsearch/v1` path is always appended so the documented Google
37 # CSE wire shape is preserved (the audit's `expected_path_substring`
38 # is `customsearch`, which would not appear if we used the override
39 # verbatim).
40 has 'base_url' => (
41 is => 'ro',
42 lazy => 1,
43 0 ▶ default => sub {
Subroutine __ANON__: not called CC=2 SCAR=17.9
44 0 my $override = $ENV{WEB_SEARCH_BASE_URL};
45 0 ▶ return 'https://www.googleapis.com/customsearch/v1' unless $override;
Branch: 1 branch
BranchTrueFalseTotal
unless $override 0 0 0
46 # Strip trailing slash, then append the canonical Google CSE
47 # path so callers see the same URL shape as production.
48 0 $override =~ s{/+$}{};
49 0 return "$override/customsearch/v1";
50 },
51 4 );
52  
53 has '_http' => (
54 is => 'ro',
55 lazy => 1,
56 0 ▶ default => sub {
Subroutine __ANON__: not called CC=1 SCAR=6.9
57 0 HTTP::Tiny->new(
58 agent => 'SignalWire-Perl-WebSearch/2.0',
59 timeout => 15,
60 );
61 },
62 4 );
63  
64 4 ▶sub setup { 1 }
Subroutine setup: called CC=1 SCAR=0.0
Pod undocumented
65  
66 3 ▶sub register_tools {
Subroutine register_tools: called CC=2 SCAR=9.2
Pod undocumented
67 3 my ($self) = @_;
68 3 ▶ my $tool_name = $self->params->{tool_name} // 'web_search';
Condition100%2/2
$self->params->{"tool_name"} // "web_search"
l!l
12
MC/DC100%1/1
$self->params->{"tool_name"} // "web_search"
$self->params->{"tool_name"}
Truth table100%2/2
A
A= $self->params->{"tool_name"}
Aresult
11
00
69  
70 3 my $weak_self = $self;
71 3 require Scalar::Util;
72 3 Scalar::Util::weaken($weak_self);
73  
74 $self->define_tool(
75 name => $tool_name,
76 description => 'Search the web for high-quality information, automatically filtering low-quality results',
77 parameters => {
78 type => 'object',
79 properties => {
80 query => { type => 'string', description => 'The search query' },
81 },
82 required => ['query'],
83 },
84 0 ▶ handler => sub {
Subroutine __ANON__: not called CC=2 SCAR=17.9
85 0 my ($args, $raw) = @_;
86 0 require SignalWire::SWAIG::FunctionResult;
87 0 ▶ my $query = $args->{query} // '';
Condition0%0/2
$args->{"query"} // ""
l!l
00
MC/DC0%0/1
$args->{"query"} // ""
$args->{"query"}
Truth table0%0/2
A
A= $args->{"query"}
Aresult
11
00
88 0 my $text = $weak_self->search_web($query);
89 0 $text = $weak_self->_wrap_response($text);
90 0 return SignalWire::SWAIG::FunctionResult->new(response => $text);
91 },
92 3 );
93 }
94  
95 0 ▶sub search_web {
Subroutine search_web: not called CC=18 SCAR=58.3
Pod undocumented
96 0 my ($self, $query) = @_;
97  
98 0 ▶ my $api_key = $self->params->{api_key} || $ENV{GOOGLE_API_KEY} || '';
Condition0%0/5
$self->params->{'api_key'} || $ENV{'GOOGLE_API_KEY'} || ''
l!l
00
$self->params->{"api_key"} or $ENV{"GOOGLE_API_KEY"}
l!l&&r!l&&!r
000
MC/DC0%0/2
$self->params->{'api_key'} || $ENV{'GOOGLE_API_KEY'} || ''
$self->params->{"api_key"} $ENV{"GOOGLE_API_KEY"}
Truth table0%0/3
A or B
A= $self->params->{"api_key"}B= $ENV{"GOOGLE_API_KEY"}
ABresult
1X1
011
000
99 my $cse_id = $self->params->{search_engine_id}
100 || $self->params->{cx}
101 || $ENV{GOOGLE_CSE_ID}
102 0 ▶ || '';
Condition0%0/8
$self->params->{'search_engine_id'} || $self->params->{'cx'} || $ENV{'GOOGLE_CSE_ID'} || ''
l!l
00
$self->params->{"search_engine_id"} or $self->params->{"cx"} or $ENV{"GOOGLE_CSE_ID"}
l!l&&r!l&&!r
000
$self->params->{"search_engine_id"} or $self->params->{"cx"}
l!l&&r!l&&!r
000
MC/DC0%0/3
$self->params->{'search_engine_id'} || $self->params->{'cx'} || $ENV{'GOOGLE_CSE_ID'} || ''
$self->params->{"search_engine_id"} $self->params->{"cx"} $ENV{"GOOGLE_CSE_ID"}
Truth table0%0/4
A or B or C
A= $self->params->{"search_engine_id"}B= $self->params->{"cx"}C= $ENV{"GOOGLE_CSE_ID"}
ABCresult
1XX1
01X1
0011
0000
103 0 ▶ my $num = $self->params->{num_results} // 3;
Condition0%0/2
$self->params->{"num_results"} // 3
l!l
00
MC/DC0%0/1
$self->params->{"num_results"} // 3
$self->params->{"num_results"}
Truth table0%0/2
A
A= $self->params->{"num_results"}
Aresult
11
00
104 0 ▶ $num = 10 if $num > 10;
Branch: 1 branch
BranchTrueFalseTotal
if $num > 10 0 0 0
105 0 ▶ $num = 1 if $num < 1;
Branch: 1 branch
BranchTrueFalseTotal
if $num < 1 0 0 0
106  
107 0 my $url = $self->base_url
108 . '?key=' . uri_escape($api_key)
109 . '&cx=' . uri_escape($cse_id)
110 . '&q=' . uri_escape($query)
111 . '&num=' . $num;
112  
113 0 my $resp = $self->_http->get($url);
114 0 ▶ unless ($resp->{success}) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($resp->{"success"}) 0 0 0
115 0 return "Web search error: $resp->{status} $resp->{reason}";
116 }
117 0 my $data = eval { JSON::decode_json($resp->{content}) };
118 0 ▶ return "Web search parse error: $@" if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 0 0 0
119  
120 0 ▶ my $items = $data->{items} // [];
Condition0%0/2
$data->{"items"} // []
l!l
00
MC/DC0%0/1
$data->{"items"} // []
$data->{"items"}
Truth table0%0/2
A
A= $data->{"items"}
Aresult
11
00
121 0 ▶ return "No results for: $query" unless @$items;
Branch: 1 branch
BranchTrueFalseTotal
unless @$items 0 0 0
122  
123 0 my @lines;
124 0 my $i = 1;
125 0 for my $item (@$items) {
126 0 ▶ last if $i > $num;
Branch: 1 branch
BranchTrueFalseTotal
if $i > $num 0 0 0
127 0 ▶ my $title = $item->{title} // '';
Condition0%0/2
$item->{"title"} // ""
l!l
00
MC/DC0%0/1
$item->{"title"} // ""
$item->{"title"}
Truth table0%0/2
A
A= $item->{"title"}
Aresult
11
00
128 0 ▶ my $link = $item->{link} // '';
Condition0%0/2
$item->{"link"} // ""
l!l
00
MC/DC0%0/1
$item->{"link"} // ""
$item->{"link"}
Truth table0%0/2
A
A= $item->{"link"}
Aresult
11
00
129 0 ▶ my $snippet = $item->{snippet} // '';
Condition0%0/2
$item->{"snippet"} // ""
l!l
00
MC/DC0%0/1
$item->{"snippet"} // ""
$item->{"snippet"}
Truth table0%0/2
A
A= $item->{"snippet"}
Aresult
11
00
130 0 push @lines, "$i. $title\n $snippet\n $link";
131 0 $i++;
132 }
133 0 return join("\n\n", @lines);
134 }
135  
136 # Wrap a successful search response with optional response_prefix /
137 # response_postfix. Mirrors Python signalwire/skills/web_search/skill.py
138 # (commit 8aad242): prefix/postfix are joined with a blank line on each
139 # side. Error / no-result branches are passed through unwrapped so the
140 # LLM still sees the failure mode verbatim.
141 7 ▶sub _wrap_response {
Subroutine _wrap_response: called CC=10 SCAR=23.1
142 7 my ($self, $text) = @_;
143 7 ▶ return $text unless defined $text && length $text;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $text and length $text 0 7 7
Condition33%1/3
defined $text and length $text
!ll&&!rl&&r
007
MC/DC0%0/2
defined $text and length $text
defined $text length $text
Truth table33%1/3
A and B
A= defined $textB= length $text
ABresult
0X0
100
111
144 # Match Python's "errors don't get wrapped" pattern. The Perl
145 # search_web returns one of three known failure sentinels; anything
146 # else is a real result list.
147 7 ▶ return $text if $text =~ /^Web search error:/;
Branch: 1 branch
BranchTrueFalseTotal
if $text =~ /^Web search error:/ 1 6 7
148 6 ▶ return $text if $text =~ /^Web search parse error:/;
Branch: 1 branch
BranchTrueFalseTotal
if $text =~ /^Web search parse error:/ 1 5 6
149 5 ▶ return $text if $text =~ /^No results for:/;
Branch: 1 branch
BranchTrueFalseTotal
if $text =~ /^No results for:/ 1 4 5
150 4 ▶ my $prefix = $self->params->{response_prefix} // '';
Condition100%2/2
$self->params->{"response_prefix"} // ""
l!l
22
MC/DC100%1/1
$self->params->{"response_prefix"} // ""
$self->params->{"response_prefix"}
Truth table100%2/2
A
A= $self->params->{"response_prefix"}
Aresult
11
00
151 4 ▶ my $postfix = $self->params->{response_postfix} // '';
Condition100%2/2
$self->params->{"response_postfix"} // ""
l!l
22
MC/DC100%1/1
$self->params->{"response_postfix"} // ""
$self->params->{"response_postfix"}
Truth table100%2/2
A
A= $self->params->{"response_postfix"}
Aresult
11
00
152 4 ▶ $text = "$prefix\n\n$text" if length $prefix;
Branch: 1 branch
BranchTrueFalseTotal
if length $prefix 2 2 4
153 4 ▶ $text = "$text\n\n$postfix" if length $postfix;
Branch: 1 branch
BranchTrueFalseTotal
if length $postfix 2 2 4
154 4 return $text;
155 }
156  
157 1 ▶sub get_global_data {
Subroutine get_global_data: called CC=1 SCAR=0.0
Pod undocumented
158 return {
159 1 web_search_enabled => JSON::true,
160 search_provider => 'Google Custom Search',
161 quality_filtering => JSON::true,
162 };
163 }
164  
165 1 ▶sub _get_prompt_sections {
Subroutine _get_prompt_sections: called CC=1 SCAR=0.0
166 return [{
167 1 title => 'Web Search Capability (Quality Enhanced)',
168 body => '',
169 bullets => [
170 'Use web_search to find current information',
171 'Results are quality-filtered automatically',
172 ],
173 }];
174 }
175  
176 1 ▶sub get_parameter_schema {
Subroutine get_parameter_schema: called CC=1 SCAR=0.0
Pod undocumented
177 return {
178 1 %{ SignalWire::Skills::SkillBase->get_parameter_schema },
179 api_key => { type => 'string', required => 1, hidden => 1 },
180 search_engine_id => { type => 'string', required => 1, hidden => 1 },
181 num_results => { type => 'integer', default => 3, min => 1, max => 10 },
182 response_prefix => { type => 'string', default => '' },
183 response_postfix => { type => 'string', default => '' },
184 };
185 }
186  
187 4 1;
« blib/lib/SignalWire/POM/PromptObjectModel.pm ↑ Summary blib/lib/SignalWire/Relay/Client.pm »