blib/lib/SignalWire/DataMap.pm

filter: Statementstmt 89.1% 123 / 138 Branchbran 70.8% 34 / 48 Conditioncond 71.4% 5 / 7 MC/DCmcdc 50.0% 2 / 4 Subroutinesub 92.3% 24 / 26 Podpod 0.0% 0 / 14 totaltotal 79.3% 188 / 237 CC 29 SCAR 13.6
CC
29
Cov
84%
to_swaig_function
8.0
webhook_expressions
6.0
params
6.0
CRAP 3.9
« blib/lib/SignalWire/Skills/Builtin/WeatherApi.pm ↑ Summary blib/lib/SignalWire/Skills/Builtin/McpGateway.pm »
1 package SignalWire::DataMap;
2 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 2 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 2 ▶use Moo;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 2 ▶use JSON ();
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 2 has 'function_name' => (
8 is => 'ro',
9 required => 1,
10 );
11  
12 has '_purpose' => (
13 is => 'rw',
14 14 ▶ default => sub { '' },
Subroutine __ANON__: called CC=1 SCAR=0.0
15 2 );
16  
17 has '_parameters' => (
18 is => 'rw',
19 14 ▶ default => sub { {} },
Subroutine __ANON__: called CC=1 SCAR=0.0
20 2 );
21  
22 has '_required_params' => (
23 is => 'rw',
24 14 ▶ default => sub { [] },
Subroutine __ANON__: called CC=1 SCAR=0.0
25 2 );
26  
27 has '_expressions' => (
28 is => 'rw',
29 14 ▶ default => sub { [] },
Subroutine __ANON__: called CC=1 SCAR=0.0
30 2 );
31  
32 has '_webhooks' => (
33 is => 'rw',
34 14 ▶ default => sub { [] },
Subroutine __ANON__: called CC=1 SCAR=0.0
35 2 );
36  
37 has '_output' => (
38 is => 'rw',
39 14 ▶ default => sub { undef },
Subroutine __ANON__: called CC=1 SCAR=0.0
40 2 );
41  
42 has '_error_keys' => (
43 is => 'rw',
44 14 ▶ default => sub { [] },
Subroutine __ANON__: called CC=1 SCAR=0.0
45 2 );
46  
47 # Constructor shortcut: DataMap->new("name") or DataMap->new(function_name => "name")
48 14 ▶around BUILDARGS => sub {
Subroutine __ANON__: called CC=3 SCAR=11.0
49 14 my ($orig, $class, @args) = @_;
50 14 ▶ if (@args == 1 && !ref $args[0]) {
Branch: 1 branch
BranchTrueFalseTotal
if (@args == 1 and not ref $args[0]) 13 1 14
Condition66%2/3
@args == 1 and not ref $args[0]
!ll&&!rl&&r
1013
MC/DC50%1/2
@args == 1 and not ref $args[0]
@args == 1 not ref $args[0]
Truth table66%2/3
A and not(B)
A= @args == 1B= not ref $args[0]
ABresult
0X0
100
111
51 13 return $class->$orig(function_name => $args[0]);
52 }
53 1 return $class->$orig(@args);
54 2 };
55  
56 #
57 # purpose — set the LLM-facing tool description. PROMPT ENGINEERING,
58 # not developer documentation.
59 #
60 # The description string is rendered into the OpenAI tool schema
61 # `description` field on every LLM turn. The model reads it to decide
62 # WHEN to call this tool. A vague purpose() is the #1 cause of "the
63 # model has the right tool but doesn't call it" failures with data-map
64 # tools.
65 #
66 # BAD vs GOOD:
67 #
68 # BAD : ->purpose('weather api')
69 # GOOD: ->purpose('Get the current weather conditions and forecast '
70 # . 'for a specific city. Use this whenever the user '
71 # . 'asks about weather, temperature, rain, or similar '
72 # . 'conditions in a named location.')
73 #
74 11 ▶sub purpose {
Subroutine purpose: called CC=1 SCAR=0.0
Pod undocumented
75 11 my ($self, $desc) = @_;
76 11 $self->_purpose($desc);
77 11 return $self;
78 }
79  
80 #
81 # description — alias for purpose(). Sets the LLM-facing tool
82 # description. This string is read by the model to decide WHEN to call
83 # this tool. See purpose() for bad-vs-good examples.
84 #
85 1 ▶sub description {
Subroutine description: called CC=1 SCAR=0.0
Pod undocumented
86 1 my ($self, $desc) = @_;
87 1 return $self->purpose($desc);
88 }
89  
90 #
91 # parameter — add a parameter definition; the `description` is
92 # LLM-FACING.
93 #
94 # Each parameter description is rendered into the OpenAI tool schema
95 # under parameters.properties.<name>.description and sent to the
96 # model. The model uses it to decide HOW to fill in the argument from
97 # user speech. It is prompt engineering, not developer FYI.
98 #
99 # BAD vs GOOD:
100 #
101 # BAD : ->parameter('city', 'string', 'the city')
102 # GOOD: ->parameter('city', 'string',
103 # 'The name of the city to get weather for, e.g. '
104 # . '"San Francisco". Ask the user if they did not provide '
105 # . 'one. Include the state or country if the city name is '
106 # . 'ambiguous.')
107 #
108 7 ▶sub parameter {
Subroutine parameter: called CC=5 SCAR=16.6
Pod undocumented
109 7 my ($self, $name, $type, $description, %opts) = @_;
110 7 ▶ my $required = $opts{required} // 0;
Condition50%1/2
$opts{"required"} // 0
l!l
70
MC/DC0%0/1
$opts{"required"} // 0
$opts{"required"}
Truth table50%1/2
A
A= $opts{"required"}
Aresult
11
00
111 7 my $enum = $opts{enum};
112  
113 7 my %param_def = (
114 type => $type,
115 description => $description,
116 );
117 7 ▶ $param_def{enum} = $enum if $enum;
Branch: 1 branch
BranchTrueFalseTotal
if $enum 1 6 7
118  
119 7 $self->_parameters->{$name} = \%param_def;
120  
121 7 ▶ if ($required) {
Branch: 1 branch
BranchTrueFalseTotal
if ($required) 7 0 7
122 7 my $req = $self->_required_params;
123 0 ▶ push @$req, $name unless grep { $_ eq $name } @$req;
Branch: 1 branch
BranchTrueFalseTotal
unless grep {$_ eq $name;} @$req 7 0 7
124 }
125  
126 7 return $self;
127 }
128  
129 2 ▶sub expression {
Subroutine expression: called CC=3 SCAR=12.0
Pod undocumented
130 2 my ($self, $test_value, $pattern, $output, %opts) = @_;
131 2 my $nomatch_output = $opts{nomatch_output};
132  
133 # If pattern is a compiled regex, extract the string
134 2 ▶ if (ref $pattern eq 'Regexp') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $pattern eq "Regexp") 0 2 2
135 0 $pattern = "$pattern";
136 # Strip Perl regex delimiters: (?^:...) or (?^u:...)
137 0 $pattern =~ s/^\(\?[\^a-z]*://;
138 0 $pattern =~ s/\)$//;
139 }
140  
141 2 my %expr = (
142 string => $test_value,
143 pattern => $pattern,
144 output => $output->to_hash,
145 );
146 2 ▶ $expr{'nomatch-output'} = $nomatch_output->to_hash if $nomatch_output;
Branch: 1 branch
BranchTrueFalseTotal
if $nomatch_output 0 2 2
147  
148 2 push @{ $self->_expressions }, \%expr;
149 2 return $self;
150 }
151  
152 8 ▶sub webhook {
Subroutine webhook: called CC=5 SCAR=16.2
Pod undocumented
153 8 my ($self, $method, $url, %opts) = @_;
154 8 my $headers = $opts{headers};
155 8 my $form_param = $opts{form_param};
156 8 my $input_args_as_params = $opts{input_args_as_params};
157 8 my $require_args = $opts{require_args};
158  
159 8 my %wh = (
160 url => $url,
161 method => uc($method),
162 );
163 8 ▶ $wh{headers} = $headers if $headers;
Branch: 1 branch
BranchTrueFalseTotal
if $headers 1 7 8
164 8 ▶ $wh{form_param} = $form_param if $form_param;
Branch: 1 branch
BranchTrueFalseTotal
if $form_param 0 8 8
165 8 ▶ $wh{input_args_as_params} = JSON::true if $input_args_as_params;
Branch: 1 branch
BranchTrueFalseTotal
if $input_args_as_params 0 8 8
166 8 ▶ $wh{require_args} = $require_args if $require_args;
Branch: 1 branch
BranchTrueFalseTotal
if $require_args 0 8 8
167  
168 8 push @{ $self->_webhooks }, \%wh;
169 8 return $self;
170 }
171  
172 0 ▶sub webhook_expressions {
Subroutine webhook_expressions: not called CC=2 SCAR=17.9
Pod undocumented
173 0 my ($self, $expressions) = @_;
174 die "Must add webhook before setting webhook expressions"
175 0 ▶ unless @{ $self->_webhooks };
Branch: 1 branch
BranchTrueFalseTotal
unless @{$self->_webhooks;} 0 0 0
176 0 $self->_webhooks->[-1]{expressions} = $expressions;
177 0 return $self;
178 }
179  
180 3 ▶sub body {
Subroutine body: called CC=2 SCAR=6.9
Pod undocumented
181 3 my ($self, $data) = @_;
182 die "Must add webhook before setting body"
183 3 ▶ unless @{ $self->_webhooks };
Branch: 1 branch
BranchTrueFalseTotal
unless @{$self->_webhooks;} 1 2 3
184 2 $self->_webhooks->[-1]{body} = $data;
185 2 return $self;
186 }
187  
188 0 ▶sub params {
Subroutine params: not called CC=2 SCAR=17.9
Pod undocumented
189 0 my ($self, $data) = @_;
190 die "Must add webhook before setting params"
191 0 ▶ unless @{ $self->_webhooks };
Branch: 1 branch
BranchTrueFalseTotal
unless @{$self->_webhooks;} 0 0 0
192 0 $self->_webhooks->[-1]{params} = $data;
193 0 return $self;
194 }
195  
196 3 ▶sub foreach {
Subroutine foreach: called CC=5 SCAR=16.1
Pod undocumented
197 3 my ($self, $config) = @_;
198 die "Must add webhook before setting foreach"
199 3 ▶ unless @{ $self->_webhooks };
Branch: 1 branch
BranchTrueFalseTotal
unless @{$self->_webhooks;} 1 2 3
200 2 ▶ die "foreach_config must be a hashref" unless ref $config eq 'HASH';
Branch: 1 branch
BranchTrueFalseTotal
unless ref $config eq "HASH" 0 2 2
201  
202 2 for my $key (qw(input_key output_key append)) {
203 die "foreach config missing required key: $key"
204 5 ▶ unless exists $config->{$key};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $config->{$key} 1 4 5
205 }
206  
207 1 $self->_webhooks->[-1]{foreach} = $config;
208 1 return $self;
209 }
210  
211 8 ▶sub output {
Subroutine output: called CC=2 SCAR=6.9
Pod undocumented
212 8 my ($self, $result) = @_;
213 die "Must add webhook before setting output"
214 8 ▶ unless @{ $self->_webhooks };
Branch: 1 branch
BranchTrueFalseTotal
unless @{$self->_webhooks;} 1 7 8
215 7 $self->_webhooks->[-1]{output} = $result->to_hash;
216 7 return $self;
217 }
218  
219 1 ▶sub fallback_output {
Subroutine fallback_output: called CC=1 SCAR=0.0
Pod undocumented
220 1 my ($self, $result) = @_;
221 1 $self->_output($result->to_hash);
222 1 return $self;
223 }
224  
225 1 ▶sub error_keys {
Subroutine error_keys: called CC=2 SCAR=7.2
Pod undocumented
226 1 my ($self, $keys) = @_;
227 1 ▶ if (@{ $self->_webhooks }) {
Branch: 1 branch
BranchTrueFalseTotal
if (@{$self->_webhooks;}) { } 1 0 1
228 1 $self->_webhooks->[-1]{error_keys} = $keys;
229 } else {
230 0 $self->_error_keys($keys);
231 }
232 1 return $self;
233 }
234  
235 1 ▶sub global_error_keys {
Subroutine global_error_keys: called CC=1 SCAR=0.0
Pod undocumented
236 1 my ($self, $keys) = @_;
237 1 $self->_error_keys($keys);
238 1 return $self;
239 }
240  
241 10 ▶sub to_swaig_function {
Subroutine to_swaig_function: called CC=8 SCAR=20.8
Pod undocumented
242 10 my ($self) = @_;
243  
244 # Build parameter schema
245 10 my %param_schema;
246 10 ▶ if (keys %{ $self->_parameters }) {
Branch: 1 branch
BranchTrueFalseTotal
if (keys %{$self->_parameters;}) { } 6 4 10
247 6 $param_schema{type} = 'object';
248 6 $param_schema{properties} = { %{ $self->_parameters } };
249 6 ▶ if (@{ $self->_required_params }) {
Branch: 1 branch
BranchTrueFalseTotal
if (@{$self->_required_params;}) 6 0 6
250 6 $param_schema{required} = [ @{ $self->_required_params } ];
251 }
252 } else {
253 4 %param_schema = (type => 'object', properties => {});
254 }
255  
256 # Build data_map
257 10 my %data_map;
258 10 ▶ if (@{ $self->_expressions }) {
Branch: 1 branch
BranchTrueFalseTotal
if (@{$self->_expressions;}) 1 9 10
259 1 $data_map{expressions} = $self->_expressions;
260 }
261 10 ▶ if (@{ $self->_webhooks }) {
Branch: 1 branch
BranchTrueFalseTotal
if (@{$self->_webhooks;}) 5 5 10
262 5 $data_map{webhooks} = $self->_webhooks;
263 }
264 10 ▶ if (defined $self->_output) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $self->_output) 1 9 10
265 1 $data_map{output} = $self->_output;
266 }
267 10 ▶ if (@{ $self->_error_keys }) {
Branch: 1 branch
BranchTrueFalseTotal
if (@{$self->_error_keys;}) 1 9 10
268 1 $data_map{error_keys} = $self->_error_keys;
269 }
270  
271 return {
272 10 ▶ function => $self->function_name,
Condition100%2/2
$self->_purpose || 'Execute ' . $self->function_name
l!l
91
MC/DC100%1/1
$self->_purpose || 'Execute ' . $self->function_name
$self->_purpose
Truth table100%2/2
A
A= $self->_purpose
Aresult
11
00
273 description => $self->_purpose || "Execute " . $self->function_name,
274 parameters => \%param_schema,
275 data_map => \%data_map,
276 };
277 }
278  
279 2 1;
« blib/lib/SignalWire/Skills/Builtin/WeatherApi.pm ↑ Summary blib/lib/SignalWire/Skills/Builtin/McpGateway.pm »