lib/Langertha/Skeid/OpenAPI.pm

filter: Statementstmt 100% 79 / 79 Branchbran 91.3% 42 / 46 Conditioncond 72.7% 16 / 22 MC/DCmcdc 41.6% 5 / 12 Subroutinesub 100% 13 / 13 Podpod 100% 3 / 3 totaltotal 90.2% 158 / 175 CC 37 SCAR 33.6
CC
37
Cov
93%
document
37.8
BEGIN
1.0
BEGIN
1.0
CRAP 28.8
« lib/Langertha/Skeid/UsageStore/JsonLog.pm ↑ Summary blib/lib/Langertha/Skeid/CustomerSource/DBI.pm »
1 package Langertha::Skeid::OpenAPI;
2 86 our $VERSION = '0.004';
3 # ABSTRACT: OpenAPI 3.1 description built from the proxy's route table
4 86 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 86 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 86 ▶use Carp qw(croak);
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8  
9 # --- component schemas ------------------------------------------------------------------------
10  
11 86 my %SCHEMA = (
12 Error => {
13 type => 'object',
14 properties => {
15 error => {
16 type => 'object',
17 properties => {
18 message => { type => 'string' },
19 type => { type => 'string' },
20 code => { type => [ 'string', 'null' ] },
21 },
22 required => ['message'],
23 },
24 },
25 description => 'The error object of the face the route belongs to. The OpenAI shape is shown; '
26 . 'the Anthropic and Ollama routes answer in their own client dialects.',
27 },
28 Object => { type => 'object', additionalProperties => \1 },
29 ModelList => {
30 type => 'object',
31 properties => {
32 object => { type => 'string', const => 'list' },
33 data => {
34 type => 'array',
35 items => {
36 type => 'object',
37 properties => {
38 id => { type => 'string' },
39 object => { type => 'string', const => 'model' },
40 created => { type => 'integer' },
41 owned_by => { type => 'string' },
42 },
43 required => [ 'id', 'object' ],
44 },
45 },
46 },
47 required => [ 'object', 'data' ],
48 },
49 ChatCompletionRequest => {
50 type => 'object',
51 properties => {
52 model => { type => 'string', description => 'A node model or an alias name.' },
53 messages => {
54 type => 'array',
55 items => {
56 type => 'object',
57 properties => { role => { type => 'string' }, content => {} },
58 required => ['role'],
59 },
60 },
61 stream => { type => 'boolean' },
62 temperature => { type => 'number' },
63 max_tokens => { type => 'integer' },
64 tools => { type => 'array', items => { type => 'object' } },
65 tool_choice => {},
66 },
67 required => [ 'model', 'messages' ],
68 },
69 EmbeddingsRequest => {
70 type => 'object',
71 properties => {
72 model => { type => 'string' },
73 input => { oneOf => [ { type => 'string' }, { type => 'array', items => { type => 'string' } } ] },
74 },
75 required => [ 'model', 'input' ],
76 },
77 RerankRequest => {
78 type => 'object',
79 properties => {
80 model => { type => 'string' },
81 query => { type => 'string' },
82 documents => { type => 'array', minItems => 1, items => {} },
83 top_n => { type => 'integer' },
84 },
85 required => [ 'model', 'query', 'documents' ],
86 },
87 AudioRequest => {
88 type => 'object',
89 properties => {
90 file => { type => 'string', contentMediaType => 'application/octet-stream' },
91 model => { type => 'string' },
92 stream => { type => 'boolean' },
93 },
94 required => [ 'file', 'model' ],
95 },
96 DocumentsFileRequest => {
97 type => 'object',
98 description => 'docling-serve\'s form: the files plus its option fields, relayed as sent.',
99 properties => {
100 files => { type => 'array', items => { type => 'string', contentMediaType => 'application/octet-stream' } },
101 },
102 required => ['files'],
103 },
104 DocumentsSourceRequest => {
105 type => 'object',
106 description => 'docling-serve\'s source body: inline files (base64) and options, relayed as sent.',
107 properties => {
108 file_sources => {
109 type => 'array',
110 items => {
111 type => 'object',
112 properties => { base64_string => { type => 'string' }, filename => { type => 'string' } },
113 required => [ 'base64_string', 'filename' ],
114 },
115 },
116 options => { type => 'object' },
117 },
118 required => ['file_sources'],
119 },
120 AnthropicMessagesRequest => {
121 type => 'object',
122 properties => {
123 model => { type => 'string' },
124 max_tokens => { type => 'integer' },
125 system => { oneOf => [ { type => 'string' }, { type => 'array', items => { type => 'object' } } ] },
126 messages => { type => 'array', items => { type => 'object' } },
127 stream => { type => 'boolean' },
128 },
129 required => [ 'model', 'max_tokens', 'messages' ],
130 },
131 OllamaChatRequest => {
132 type => 'object',
133 properties => {
134 model => { type => 'string' },
135 messages => { type => 'array', items => { type => 'object' } },
136 stream => { type => 'boolean', description => 'Streams unless false.' },
137 },
138 required => [ 'model', 'messages' ],
139 },
140 OllamaGenerateRequest => {
141 type => 'object',
142 properties => {
143 model => { type => 'string' },
144 prompt => { type => 'string' },
145 system => { type => 'string' },
146 stream => { type => 'boolean', description => 'Streams unless false.' },
147 },
148 required => [ 'model', 'prompt' ],
149 },
150 NodeList => {
151 type => 'object',
152 properties => { nodes => { type => 'array', items => { type => 'object' } } },
153 },
154 );
155  
156 # One example body per request schema; $model is the first name GET /v1/models lists.
157 my %EXAMPLE = (
158 8 ▶ ChatCompletionRequest => sub { +{ model => $_[0], messages => [ { role => 'user', content => 'Hello' } ] } },
Subroutine __ANON__: called CC=1 SCAR=0.0
159 8 ▶ EmbeddingsRequest => sub { +{ model => $_[0], input => 'The quick brown fox' } },
Subroutine __ANON__: called CC=1 SCAR=0.0
160 16 ▶ RerankRequest => sub { +{ model => $_[0], query => 'What is Skeid?', documents => [ 'A routing proxy.', 'A fruit.' ] } },
Subroutine __ANON__: called CC=1 SCAR=0.0
161 8 ▶ DocumentsSourceRequest => sub { +{ options => { to_formats => ['md'] },
Subroutine __ANON__: called CC=1 SCAR=0.0
162 file_sources => [ { base64_string => 'JVBERi0xLjQK', filename => 'document.pdf' } ] } },
163 8 ▶ AnthropicMessagesRequest => sub { +{ model => $_[0], max_tokens => 256, messages => [ { role => 'user', content => 'Hello' } ] } },
Subroutine __ANON__: called CC=1 SCAR=0.0
164 8 ▶ OllamaChatRequest => sub { +{ model => $_[0], stream => \0, messages => [ { role => 'user', content => 'Hello' } ] } },
Subroutine __ANON__: called CC=1 SCAR=0.0
165 8 ▶ OllamaGenerateRequest => sub { +{ model => $_[0], stream => \0, prompt => 'Hello' } },
Subroutine __ANON__: called CC=1 SCAR=0.0
166 86 );
167  
168 # --- path templates ---------------------------------------------------------------------------
169  
170  
171 173 ▶sub path_template {
Subroutine path_template: called CC=1 SCAR=0.0
Pod documented
172 173 my ($self, $pattern) = @_;
173 173 (my $t = $pattern) =~ s/[:#*]([A-Za-z_][A-Za-z0-9_]*)/{$1}/g;
174 173 return $t;
175 }
176  
177 173 ▶sub path_params {
Subroutine path_params: called CC=1 SCAR=0.0
Pod documented
178 173 my ($self, $pattern) = @_;
179 173 return $pattern =~ /[:#*]([A-Za-z_][A-Za-z0-9_]*)/g;
180 }
181  
182  
183 12 ▶sub document {
Subroutine document: called CC=37 SCAR=36.3
Pod documented
184 12 my ($self, %arg) = @_;
185 12 ▶ my $kind = $arg{kind} // 'client';
Condition50%1/2
$arg{"kind"} // "client"
l!l
120
MC/DC0%0/1
$arg{"kind"} // "client"
$arg{"kind"}
Truth table50%1/2
A
A= $arg{"kind"}
Aresult
11
00
186 12 ▶ croak "unknown document kind '$kind'" unless $kind eq 'client' || $kind eq 'admin';
Branch: 1 branch
BranchTrueFalseTotal
unless $kind eq "client" or $kind eq "admin" 0 12 12
Condition66%2/3
$kind eq "client" or $kind eq "admin"
l!l&&r!l&&!r
840
MC/DC0%0/2
$kind eq "client" or $kind eq "admin"
$kind eq "client" $kind eq "admin"
Truth table66%2/3
A or B
A= $kind eq "client"B= $kind eq "admin"
ABresult
1X1
011
000
187 12 ▶ my $entries = $arg{entries} || [];
Condition50%1/2
$arg{'entries'} || []
l!l
120
MC/DC0%0/1
$arg{'entries'} || []
$arg{'entries'}
Truth table50%1/2
A
A= $arg{'entries'}
Aresult
11
00
188 12 ▶ my $models = $arg{models} || [];
Condition50%1/2
$arg{'models'} || []
l!l
120
MC/DC0%0/1
$arg{'models'} || []
$arg{'models'}
Truth table50%1/2
A
A= $arg{'models'}
Aresult
11
00
189 12 ▶ my $model = @$models ? $models->[0] : 'my-model';
Branch: 1 branch
BranchTrueFalseTotal
@$models ? : 8 4 12
190 12 ▶ my $scheme = $kind eq 'admin' ? 'admin_key' : 'client_auth';
Branch: 1 branch
BranchTrueFalseTotal
$kind eq 'admin' ? : 4 8 12
191  
192 12 my (%paths, %used, %tags);
193 12 for my $e (@$entries) {
194 171 for my $pattern (@{$e->{paths}}) {
195 173 my $template = $self->path_template($pattern);
196 173 my @params = $self->path_params($pattern);
197 173 for my $method (@{$e->{methods}}) {
198 my $op = {
199 181 ▶ operationId => $e->{id} . (@{$e->{methods}} > 1 ? '_' . lc($method) : '')
Branch: 1 branch
BranchTrueFalseTotal
@{$e->{'paths'};} > 1 ? : 12 169 181
200 181 ▶ . (@{$e->{paths}} > 1 ? '_' . ($pattern =~ /\*/ ? 'path' : 'root') : ''),
Branch: 1 branch
BranchTrueFalseTotal
$pattern =~ /\*/ ? : 6 6 12
201 summary => $e->{summary},
202 181 ▶ tags => [ $e->{tag} ],
Branch: 1 branch
BranchTrueFalseTotal
@{$e->{'methods'};} > 1 ? : 12 169 181
203 };
204 181 ▶ $op->{description} = $e->{description} if defined $e->{description};
Branch: 1 branch
BranchTrueFalseTotal
if defined $e->{"description"} 42 139 181
205 181 $tags{$e->{tag}} = 1;
206  
207 181 my @parameters = map { +{ name => $_, in => 'path', required => 1, schema => { type => 'string' } } } @params;
208 # A route that takes its input in the query (the realtime WebSocket, skeid k95).
209 push @parameters, map {
210 +{ name => $_->{name}, in => 'query', required => ($_->{required} ? \1 : \0),
211 16 ▶ (defined $_->{description} ? (description => $_->{description}) : ()),
Branch: 2 branches
BranchTrueFalseTotal
$_->{'required'} ? : 8 8 16
defined $_->{'description'} ? : 16 0 16
212 schema => { type => 'string' } }
213 181 ▶ } @{ $e->{query} || [] };
Condition100%2/2
$e->{'query'} || []
l!l
8173
MC/DC100%1/1
$e->{'query'} || []
$e->{'query'}
Truth table100%2/2
A
A= $e->{'query'}
Aresult
11
00
214 181 ▶ $op->{parameters} = \@parameters if @parameters;
Branch: 1 branch
BranchTrueFalseTotal
if @parameters 24 157 181
215  
216 181 ▶ if (defined $e->{request}) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $e->{"request"}) 88 93 181
217 88 ▶ croak "unknown request schema '$e->{request}'" unless $SCHEMA{$e->{request}};
Branch: 1 branch
BranchTrueFalseTotal
unless $SCHEMA{$e->{"request"}} 0 88 88
218 88 $used{$e->{request}} = 1;
219 88 ▶ my $media = ($e->{request_type} // 'json') eq 'multipart' ? 'multipart/form-data' : 'application/json';
Branch: 1 branch
BranchTrueFalseTotal
($e->{'request_type'} // 'json') eq 'multipart' ? : 24 64 88
Condition100%2/2
$e->{"request_type"} // "json"
l!l
2464
MC/DC100%1/1
$e->{"request_type"} // "json"
$e->{"request_type"}
Truth table100%2/2
A
A= $e->{"request_type"}
Aresult
11
00
220 88 my $content = { schema => { '$ref' => '#/components/schemas/' . $e->{request} } };
221 88 ▶ $content->{example} = $EXAMPLE{$e->{request}}->($model) if $EXAMPLE{$e->{request}};
Branch: 1 branch
BranchTrueFalseTotal
if $EXAMPLE{$e->{"request"}} 64 24 88
222 88 $op->{requestBody} = { required => \1, content => { $media => $content } };
223 }
224  
225 181 ▶ my $ok_schema = $e->{response} // 'Object';
Condition100%2/2
$e->{"response"} // "Object"
l!l
12169
MC/DC100%1/1
$e->{"response"} // "Object"
$e->{"response"}
Truth table100%2/2
A
A= $e->{"response"}
Aresult
11
00
226 181 ▶ croak "unknown response schema '$ok_schema'" unless $SCHEMA{$ok_schema};
Branch: 1 branch
BranchTrueFalseTotal
unless $SCHEMA{$ok_schema} 0 181 181
227 181 $used{$ok_schema} = 1;
228 181 $used{Error} = 1;
229 181 ▶ my %ok = ( description => $e->{response_description} // 'The answer.' );
Condition50%1/2
$e->{"response_description"} // "The answer."
l!l
0181
MC/DC0%0/1
$e->{"response_description"} // "The answer."
$e->{"response_description"}
Truth table50%1/2
A
A= $e->{"response_description"}
Aresult
11
00
230 181 ▶ if ($e->{stream}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($e->{'stream'}) { } 60 121 181
231 60 $ok{description} .= ' With "stream": true, a text/event-stream.';
232 $ok{content} = {
233 60 'application/json' => { schema => { '$ref' => '#/components/schemas/' . $ok_schema } },
234 'text/event-stream' => { schema => { type => 'string' } },
235 };
236 }
237 else {
238 121 $ok{content} = { 'application/json' => { schema => { '$ref' => '#/components/schemas/' . $ok_schema } } };
239 }
240 # An upgrade is not a document: the success is 101, and there is no body to describe.
241 %ok = ( description => 'Switching protocols: the connection is a WebSocket from here on.' )
242 181 ▶ if $e->{websocket};
Branch: 1 branch
BranchTrueFalseTotal
if $e->{"websocket"} 8 173 181
243 $op->{responses} = {
244 181 ▶ ($e->{websocket} ? ('101' => \%ok) : ('200' => \%ok)),
Branch: 1 branch
BranchTrueFalseTotal
$e->{'websocket'} ? : 8 173 181
245 default => {
246 description => 'An error: 4xx for a request the caller got wrong, 5xx for the proxy or its node.',
247 content => { 'application/json' => { schema => { '$ref' => '#/components/schemas/Error' } } },
248 },
249 };
250  
251 181 ▶ if ($e->{public}) {
Branch: 2 branches
BranchTrueFalseTotal
if ($e->{'public'}) { } 8 173 181
elsif ($kind eq 'client' and not $arg{'client_auth'}) { } 104 69 173
252 8 $op->{security} = [];
253 }
254 ▶ elsif ($kind eq 'client' && !$arg{client_auth}) {
Condition100%3/3
$kind eq "client" and not $arg{"client_auth"}
!ll&&!rl&&r
3039104
MC/DC100%2/2
$kind eq "client" and not $arg{"client_auth"}
$kind eq "client" not $arg{"client_auth"}
Truth table100%3/3
A and not(B)
A= $kind eq "client"B= not $arg{"client_auth"}
ABresult
0X0
100
111
255 # No client_auth section: a key is not required, only used for policy and metering.
256 104 $op->{security} = [ {}, { $scheme => [] } ];
257 }
258 else {
259 69 $op->{security} = [ { $scheme => [] } ];
260 }
261  
262 181 $paths{$template}{lc $method} = $op;
263 }
264 }
265 }
266  
267 12 ▶ my $title = $kind eq 'admin' ? 'Skeid admin API' : 'Skeid';
Branch: 1 branch
BranchTrueFalseTotal
$kind eq 'admin' ? : 4 8 12
268 my %doc = (
269 openapi => '3.1.0',
270 info => {
271 title => $title,
272 version => $arg{version} // '0',
273 description => $kind eq 'admin'
274 ? 'The control-plane routes under /skeid. Every one needs the admin API key.'
275 : 'An LLM routing proxy. One API key, several client formats (OpenAI, Anthropic, Ollama), '
276 . 'models behind it chosen by Skeid. Describes the routes this deployment serves.',
277 },
278 49 tags => [ map { +{ name => $_ } } sort keys %tags ],
279 paths => \%paths,
280 components => {
281 12 ▶ schemas => { map { $_ => $SCHEMA{$_} } sort keys %used },
Branch: 2 branches
BranchTrueFalseTotal
$kind eq 'admin' ? : 4 8 12
$kind eq 'admin' ? : 4 8 12
Condition50%1/2
$arg{"version"} // 0
l!l
120
MC/DC0%0/1
$arg{"version"} // 0
$arg{"version"}
Truth table50%1/2
A
A= $arg{"version"}
Aresult
11
00
282 securitySchemes => {
283 $scheme => {
284 type => 'http',
285 scheme => 'bearer',
286 description => $kind eq 'admin'
287 ? 'The admin API key (admin_api_key).'
288 : 'A Skeid customer key, as "Authorization: Bearer <key>". The Anthropic face also '
289 . 'accepts it as an x-api-key header. With a client_auth section in the config only '
290 . 'listed keys are let in (401 otherwise).',
291 },
292 },
293 },
294 );
295 12 return \%doc;
296 }
297  
298 86 1;
299  
300 __END__
« lib/Langertha/Skeid/UsageStore/JsonLog.pm ↑ Summary blib/lib/Langertha/Skeid/CustomerSource/DBI.pm »