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

filter: Statementstmt 46.3% 45 / 97 Branchbran 0.0% 0 / 24 Conditioncond 7.5% 3 / 40 MC/DCmcdc 5.2% 1 / 19 Subroutinesub 71.4% 15 / 21 Podpod 0.0% 0 / 6 totaltotal 30.9% 64 / 207 CC 31 SCAR 56.5
CC
31
Cov
30%
search_knowledge
600.0
__ANON__
12.0
_build_url
12.0
CRAP 284.5
↑ Summary blib/lib/SignalWire/POM/Section.pm »
1 package SignalWire::Skills::Builtin::Datasphere;
2 # Copyright (c) 2025 SignalWire
3 # Licensed under the MIT License.
4 #
5 # Real DataSphere RAG client. Mirrors signalwire-python's
6 # skills/datasphere/skill.py:_search_knowledge_handler — POST a
7 # JSON body to /api/datasphere/documents/search with HTTP Basic auth
8 # (project_id : token), parse `chunks[]`, format as numbered results.
9  
10 4 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
11 4 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
12 4 ▶use Moo;
Subroutine BEGIN: called CC=1 SCAR=0.0
13 4 ▶use HTTP::Tiny;
Subroutine BEGIN: called CC=1 SCAR=0.0
14 4 ▶use JSON ();
Subroutine BEGIN: called CC=1 SCAR=0.0
15 4 ▶use MIME::Base64 qw(encode_base64);
Subroutine BEGIN: called CC=1 SCAR=0.0
16 4 extends 'SignalWire::Skills::SkillBase';
17  
18 4 ▶use SignalWire::Skills::SkillRegistry;
Subroutine BEGIN: called CC=1 SCAR=0.0
19 4 SignalWire::Skills::SkillRegistry->register_skill('datasphere', __PACKAGE__);
20  
21 8 ▶has '+skill_name' => (default => sub { 'datasphere' });
Subroutine __ANON__: called CC=1 SCAR=0.0
22 8 ▶has '+skill_description' => (default => sub { 'Search knowledge using SignalWire DataSphere RAG stack' });
Subroutine __ANON__: called CC=1 SCAR=0.0
23 8 ▶has '+supports_multiple_instances' => (default => sub { 1 });
Subroutine __ANON__: called CC=1 SCAR=0.0
24  
25 # Honor DATASPHERE_BASE_URL env var so the audit fixture
26 # (audit_skills_dispatch.py) can redirect us at a local HTTP server.
27 # When unset we build the canonical
28 # https://{space}.signalwire.com/api/datasphere/documents/search URL.
29 # When the env var is set, append the canonical
30 # `/api/datasphere/documents/search` path so the audit sees the
31 # expected `datasphere` substring on the wire.
32 has 'base_url' => (
33 is => 'ro',
34 lazy => 1,
35 0 ▶ default => sub {
Subroutine __ANON__: not called CC=2 SCAR=17.9
36 0 my $override = $ENV{DATASPHERE_BASE_URL};
37 0 ▶ return '' unless $override;
Branch: 1 branch
BranchTrueFalseTotal
unless $override 0 0 0
38 0 $override =~ s{/+$}{};
39 0 return "$override/api/datasphere/documents/search";
40 },
41 4 );
42  
43 has '_http' => (
44 is => 'ro',
45 lazy => 1,
46 0 ▶ default => sub {
Subroutine __ANON__: not called CC=1 SCAR=6.9
47 0 HTTP::Tiny->new(
48 agent => 'SignalWire-Perl-DataSphere/1.0',
49 timeout => 30,
50 );
51 },
52 4 );
53  
54 4 ▶sub setup {
Subroutine setup: called CC=1 SCAR=0.0
Pod undocumented
55 4 my ($self) = @_;
56 # Required parameters per Python (skills/datasphere/skill.py:120-127).
57 # The audit harness doesn't always set every value, so missing is
58 # warned but not fatal — the skill still answers, the API call just
59 # fails informatively. Production callers MUST provide all four.
60 4 return 1;
61 }
62  
63 3 ▶sub register_tools {
Subroutine register_tools: called CC=2 SCAR=10.5
Pod undocumented
64 3 my ($self) = @_;
65 3 ▶ my $tool_name = $self->params->{tool_name} // 'search_knowledge';
Condition100%2/2
$self->params->{"tool_name"} // "search_knowledge"
l!l
12
MC/DC100%1/1
$self->params->{"tool_name"} // "search_knowledge"
$self->params->{"tool_name"}
Truth table100%2/2
A
A= $self->params->{"tool_name"}
Aresult
11
00
66  
67 3 my $weak_self = $self;
68 3 require Scalar::Util;
69 3 Scalar::Util::weaken($weak_self);
70  
71 $self->define_tool(
72 name => $tool_name,
73 description => 'Search the knowledge base for information on any topic and return relevant results',
74 parameters => {
75 type => 'object',
76 properties => {
77 query => {
78 type => 'string',
79 description => 'The search query - what information you are looking for',
80 },
81 },
82 required => ['query'],
83 },
84 0 ▶ handler => sub {
Subroutine __ANON__: not called CC=3 SCAR=24.8
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 $query =~ s/^\s+|\s+$//g;
89 0 ▶ unless (length $query) {
Branch: 1 branch
BranchTrueFalseTotal
unless (length $query) 0 0 0
90 0 return SignalWire::SWAIG::FunctionResult->new(
91 response => 'Please provide a search query.',
92 );
93 }
94 0 my $text = $weak_self->search_knowledge($query);
95 0 return SignalWire::SWAIG::FunctionResult->new(response => $text);
96 },
97 3 );
98 }
99  
100 0 ▶sub _build_url {
Subroutine _build_url: not called CC=3 SCAR=24.8
101 0 my ($self) = @_;
102 0 ▶ return $self->base_url if $self->base_url;
Branch: 1 branch
BranchTrueFalseTotal
if $self->base_url 0 0 0
103 0 ▶ my $space = $self->params->{space_name} // '';
Condition0%0/2
$self->params->{"space_name"} // ""
l!l
00
MC/DC0%0/1
$self->params->{"space_name"} // ""
$self->params->{"space_name"}
Truth table0%0/2
A
A= $self->params->{"space_name"}
Aresult
11
00
104 0 return "https://$space.signalwire.com/api/datasphere/documents/search";
105 }
106  
107 0 ▶sub search_knowledge {
Subroutine search_knowledge: not called CC=24 SCAR=64.0
Pod undocumented
108 0 my ($self, $query) = @_;
109  
110 0 ▶ my $project_id = $self->params->{project_id} // $ENV{SIGNALWIRE_PROJECT_ID} // '';
Condition0%0/5
($self->params->{"project_id"} // $ENV{"SIGNALWIRE_PROJECT_ID"}) // ""
l!l
00
$self->params->{"project_id"} // $ENV{"SIGNALWIRE_PROJECT_ID"}
l!l&&r!l&&!r
000
MC/DC0%0/2
($self->params->{"project_id"} // $ENV{"SIGNALWIRE_PROJECT_ID"}) // ""
$self->params->{"project_id"} $ENV{"SIGNALWIRE_PROJECT_ID"}
Truth table0%0/3
A // B
A= $self->params->{"project_id"}B= $ENV{"SIGNALWIRE_PROJECT_ID"}
ABresult
1X1
011
000
111 0 ▶ my $token = $self->params->{token} // $ENV{DATASPHERE_TOKEN} // '';
Condition0%0/5
($self->params->{"token"} // $ENV{"DATASPHERE_TOKEN"}) // ""
l!l
00
$self->params->{"token"} // $ENV{"DATASPHERE_TOKEN"}
l!l&&r!l&&!r
000
MC/DC0%0/2
($self->params->{"token"} // $ENV{"DATASPHERE_TOKEN"}) // ""
$self->params->{"token"} $ENV{"DATASPHERE_TOKEN"}
Truth table0%0/3
A // B
A= $self->params->{"token"}B= $ENV{"DATASPHERE_TOKEN"}
ABresult
1X1
011
000
112 0 ▶ my $document_id = $self->params->{document_id} // '';
Condition0%0/2
$self->params->{"document_id"} // ""
l!l
00
MC/DC0%0/1
$self->params->{"document_id"} // ""
$self->params->{"document_id"}
Truth table0%0/2
A
A= $self->params->{"document_id"}
Aresult
11
00
113  
114 my %payload = (
115 document_id => $document_id,
116 query_string => $query,
117 distance => $self->params->{distance} // 3.0,
118 0 ▶ count => $self->params->{count} // 1,
Condition0%0/4
$self->params->{"distance"} // 3
l!l
00
$self->params->{"count"} // 1
l!l
00
MC/DC0%0/1
$self->params->{"distance"} // 3
$self->params->{"distance"}
MC/DC0%0/1
$self->params->{"count"} // 1
$self->params->{"count"}
Truth table0%0/2
A
A= $self->params->{"distance"}
Aresult
11
00
Truth table0%0/2
A
A= $self->params->{"count"}
Aresult
11
00
119 );
120 0 ▶ $payload{tags} = $self->params->{tags} if defined $self->params->{tags};
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->params->{"tags"} 0 0 0
121 0 ▶ $payload{language} = $self->params->{language} if defined $self->params->{language};
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->params->{"language"} 0 0 0
122 0 ▶ $payload{pos_to_expand} = $self->params->{pos_to_expand} if defined $self->params->{pos_to_expand};
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->params->{"pos_to_expand"} 0 0 0
123 0 ▶ $payload{max_synonyms} = $self->params->{max_synonyms} if defined $self->params->{max_synonyms};
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->params->{"max_synonyms"} 0 0 0
124  
125 0 my $body = JSON::encode_json(\%payload);
126 0 my $auth = encode_base64("$project_id:$token", '');
127  
128 0 my $url = $self->_build_url;
129 0 my $resp = $self->_http->post(
130 $url,
131 {
132 headers => {
133 'Authorization' => "Basic $auth",
134 'Content-Type' => 'application/json',
135 'Accept' => 'application/json',
136 },
137 content => $body,
138 },
139 );
140  
141 0 ▶ unless ($resp->{success}) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($resp->{"success"}) 0 0 0
142 0 return "Sorry, there was an error accessing the knowledge base "
143 . "($resp->{status} $resp->{reason}). Please try again later.";
144 }
145  
146 0 my $data = eval { JSON::decode_json($resp->{content}) };
147 0 ▶ if ($@) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 0 0 0
148 0 return "Sorry, the knowledge base returned an unparseable response.";
149 }
150  
151 # The DataSphere v1 wire shape returns `chunks` (Python uses that
152 # field exclusively, see signalwire-python/skills/datasphere/skill.py:226).
153 # Some upstream fixtures and integrations use `results` for the same
154 # shape — accept either to keep the parser tolerant of incidental
155 # rename without forcing tests through a translation layer.
156 0 ▶ my $chunks = $data->{chunks} // $data->{results} // [];
Condition0%0/5
($data->{"chunks"} // $data->{"results"}) // []
l!l
00
$data->{"chunks"} // $data->{"results"}
l!l&&r!l&&!r
000
MC/DC0%0/2
($data->{"chunks"} // $data->{"results"}) // []
$data->{"chunks"} $data->{"results"}
Truth table0%0/3
A // B
A= $data->{"chunks"}B= $data->{"results"}
ABresult
1X1
011
000
157 0 ▶ unless (ref $chunks eq 'ARRAY' && @$chunks) {
Branch: 1 branch
BranchTrueFalseTotal
unless (ref $chunks eq "ARRAY" and @$chunks) 0 0 0
Condition0%0/3
ref $chunks eq "ARRAY" and @$chunks
!ll&&!rl&&r
000
MC/DC0%0/2
ref $chunks eq "ARRAY" and @$chunks
ref $chunks eq "ARRAY" @$chunks
Truth table0%0/3
A and B
A= ref $chunks eq "ARRAY"B= @$chunks
ABresult
0X0
100
111
158 my $msg = $self->params->{no_results_message}
159 0 ▶ // "I couldn't find any relevant information for '{query}' in the knowledge base. "
Condition0%0/2
$self->params->{"no_results_message"} // "I couldn't find any relevant information for '{query}' in the knowledge base. Try rephrasing your question or asking about a different topic."
l!l
00
MC/DC0%0/1
$self->params->{"no_results_message"} // "I couldn't find any relevant information for '{query}' in the knowledge base. Try rephrasing your question or asking about a different topic."
$self->params->{"no_results_message"}
Truth table0%0/2
A
A= $self->params->{"no_results_message"}
Aresult
11
00
160 . "Try rephrasing your question or asking about a different topic.";
161 0 $msg =~ s/\{query\}/$query/g;
162 0 return $msg;
163 }
164  
165 0 my $count = scalar @$chunks;
166 0 ▶ my $header = $count == 1
Branch: 1 branch
BranchTrueFalseTotal
$count == 1 ? : 0 0 0
167 ? "I found 1 result for '$query':\n\n"
168 : "I found $count results for '$query':\n\n";
169  
170 0 my @blocks;
171 0 my $i = 1;
172 0 for my $chunk (@$chunks) {
173 0 ▶ my $text = $chunk->{text} // $chunk->{content} // $chunk->{chunk};
Condition0%0/6
($chunk->{"text"} // $chunk->{"content"}) // $chunk->{"chunk"}
l!l&&r!l&&!r
000
$chunk->{"text"} // $chunk->{"content"}
l!l&&r!l&&!r
000
MC/DC0%0/3
($chunk->{"text"} // $chunk->{"content"}) // $chunk->{"chunk"}
$chunk->{"text"} $chunk->{"content"} $chunk->{"chunk"}
Truth table0%0/4
A // B // C
A= $chunk->{"text"}B= $chunk->{"content"}C= $chunk->{"chunk"}
ABCresult
1XX1
01X1
0011
0000
174 0 ▶ $text = JSON::encode_json($chunk) unless defined $text;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $text 0 0 0
175 0 push @blocks, "=== RESULT $i ===\n$text\n" . ('=' x 50);
176 0 $i++;
177 }
178 0 return $header . join("\n\n", @blocks);
179 }
180  
181 0 ▶sub get_hints { return [] }
Subroutine get_hints: not called CC=1 SCAR=6.9
Pod undocumented
182  
183 2 ▶sub get_global_data {
Subroutine get_global_data: called CC=2 SCAR=7.2
Pod undocumented
184 2 my ($self) = @_;
185 return {
186 datasphere_enabled => JSON::true,
187 2 ▶ document_id => $self->params->{document_id} // '',
Condition50%1/2
$self->params->{"document_id"} // ""
l!l
20
MC/DC0%0/1
$self->params->{"document_id"} // ""
$self->params->{"document_id"}
Truth table50%1/2
A
A= $self->params->{"document_id"}
Aresult
11
00
188 knowledge_provider => 'SignalWire DataSphere',
189 };
190 }
191  
192 1 ▶sub _get_prompt_sections {
Subroutine _get_prompt_sections: called CC=1 SCAR=0.0
193 return [{
194 1 title => 'Knowledge Search Capability',
195 body => 'You have access to a knowledge base that you can search for information.',
196 bullets => [
197 'Use the search tool to find relevant information',
198 'Provide accurate answers based on search results',
199 ],
200 }];
201 }
202  
203 1 ▶sub get_parameter_schema {
Subroutine get_parameter_schema: called CC=1 SCAR=0.0
Pod undocumented
204 return {
205 1 %{ SignalWire::Skills::SkillBase->get_parameter_schema },
206 space_name => { type => 'string', required => 1 },
207 project_id => { type => 'string', required => 1 },
208 token => { type => 'string', required => 1 },
209 document_id => { type => 'string', required => 1 },
210 count => { type => 'integer', default => 1, min => 1, max => 10 },
211 distance => { type => 'number', default => 3.0 },
212 };
213 }
214  
215 4 1;
↑ Summary blib/lib/SignalWire/POM/Section.pm »