blib/lib/Peta/NN/Chain.pm untested

filter: Statementstmt 0.0% 0 / 346 Branchbran 0.0% 0 / 106 Conditioncond 0.0% 0 / 115 MC/DCmcdc 0.0% 0 / 62 Subroutinesub 0.0% 0 / 41 Podpod 0.0% 0 / 33 totaltotal 0.0% 0 / 703 CC 54 SCAR 35.4
CC
54
Cov
0%
_wire
110.0
_model
72.0
new
56.0
CRAP 34.3
1 package Peta::NN::Chain;
2 # ABSTRACT: models put together into a model
3  
4 # Models put together into a model.
5 #
6 # my $plural = chain(umlaut => $umlaut, ending => $ending);
7 # print $plural->predict('apfel', gender => 'masculine');
8 #
9 # A chain is what one writes; Peta::NN::Pipeline and Peta::NN::Fused are what
10 # runs it. Its parts are named and come in order, and each part is a model,
11 # a model file, or another chain, whose parts then become parts of this one:
12 # what is put together is again something to put together.
13 #
14 # What a part does follows from what it is:
15 #
16 # a model that rewrites (edit, rewrite) its answer is the string the next
17 # part reads
18 # a model that classifies (class) its answer is kept under the
19 # part's name; the string passes on
20 # pooled($model) the same for a whole text at once:
21 # every string of the text is
22 # evidence, all get the one answer
23 # chosen($part => { answer => model }) one of several models, chosen for
24 # each string by what the part
25 # named $part answered; '*' stands
26 # for every answer not listed
27 #
28 # Parameters go by name. A part's model is given `gender`: if an earlier part
29 # of the chain is called gender, its answer is the value; if not, gender is
30 # an argument of the chain, and whoever asks the chain names it. Two parts
31 # that are given the same name are given the same value.
32 #
33 # A chain answers through the pipeline of its parts, or through the same
34 # fused when it is asked to (on 'gpu'), which is the same function. It is
35 # saved as one file, its parts in it as they are.
36  
37 use v5.36;
38  
39 use Exporter qw(import);
40 use Storable ();
41  
42 use Peta::NN::Inference;
43 use Peta::NN::Pipeline;
44  
45 our $VERSION = '0.2610090';
46 our @EXPORT_OK = qw(chain pooled chosen fixed train_together);
47  
48 our $FORMAT = 'Peta::NN chain';
49  
50 # The layout of a chain's file.
51 # 1 the parts as they were given (models' data under their names), and
52 # the arguments' names
53 our $LAYOUT = 1;
54  
55 my $ANY = '*';
56  
57 # --- how parts are written --------------------------------------------------------
58  
59 # chain(name => part, ...): the same as Peta::NN::Chain->new.
60 sub chain (@parts) { return __PACKAGE__->new(@parts) }
61  
62 # A classifying model that judges a whole text at once.
63 sub pooled ($model) { return bless { model => $model }, 'Peta::NN::Chain::Pooled' }
64  
65 # A model with some of what it is given settled once and for all:
66 # fixed($model, genus => 'masculine'). The chain then does not ask for it.
67 sub fixed ($model, %values) {
68 die "fixed(\$model, name => value, ...)\n" if !%values;
69 return bless { model => $model, values => \%values }, 'Peta::NN::Chain::Fixed';
70 }
71  
72 # One of several models, chosen by the answer of an earlier part:
73 # chosen(language => { ces => $czech, deu => $german, '*' => $other }).
74 sub chosen ($by, $models) {
75 die "chosen(part => { answer => model, ... })\n" if ref $by || ref $models ne 'HASH' || !%$models;
76 return bless { by => $by, models => $models }, 'Peta::NN::Chain::Chosen';
77 }
78  
79 # Train models that have nothing to do with each other side by side:
80 # train_together({ name => model, ... }, $data, %options), the data and the
81 # options being those of a chain's train(). The names are what the data is
82 # given by where the models learn from different data.
83 sub train_together ($models, $data, %how) {
84 __PACKAGE__->new(map { $_ => $models->{$_} } sort keys %$models)->train($data, %how);
85 return;
86 }
87  
88 # --- putting it together -------------------------------------------------------------
89  
90 # A model as a part: what it is called, and the model data it answers from.
91 sub _model ($name, $model) {
92 if (ref $model eq 'Peta::NN::Chain::Fixed') {
93 my $of = _model($name, $model->{model});
94 defined { map { $_ => 1 } @{ $of->{given} } }->{$_} or die "the part '$name' fixes '$_', which its model is not given\n" for keys %{ $model->{values} };
95 return { %$of, fixed => $model->{values} };
96 }
97 # A model that is yet to be trained: it is a part, and the chain cannot answer until train().
98 return { name => $name, pending => $model, kind => $model->{kind}, given => [ @{ $model->{given} // [] } ] }
99 if ref $model && ref $model ne 'HASH' && $model->isa('Peta::NN::Model') && !$model->net;
100 my $data = !ref $model ? Peta::NN::Inference::read_file($model, $Peta::NN::Inference::FORMAT)
101 : ref $model eq 'HASH' ? $model
102 : $model->can('data') ? $model->data
103 : die "the part '$name' is not a model, a model file or a chain\n";
104 my $read = eval { Peta::NN::Inference->new($data) } or die "the part '$name': $@";
105 die "the part '$name' has parameters without names; a model in a chain is given names for them (given => [...])\n"
106 if @{ $data->{params} // [] } && !$data->{given};
107 return { name => $name, data => $data, model => $read, kind => $data->{kind}, given => [ @{ $data->{given} // [] } ],
108 (ref $model && ref $model ne 'HASH' && $model->isa('Peta::NN::Model') ? (trained => $model) : ()) };
109 }
110  
111 # name => part, in order. A part is a model (Peta::NN::Model, trained;
112 # Peta::NN::Inference; a model file's path), pooled(...), chosen(...), or a
113 # chain.
114 sub new ($class, @parts) {
115 die "a chain is made of name => part, name => part, ...\n" if !@parts || @parts % 2;
116 my $self = bless { parts => [], model => {} }, $class;
117 while (my ($name, $part) = splice @parts, 0, 2) {
118 die "a part's name is plain text\n" if ref $name || !length $name;
119 if (ref $part && ref $part ne 'HASH' && $part->isa(__PACKAGE__)) { # a chain: its parts are parts of this one
120 $self->_add(%$_) for @{ $part->{parts} };
121 }
122 elsif (ref $part eq 'Peta::NN::Chain::Chosen') {
123 my %models = map { $_ => _model("$name-" . ($_ eq $ANY ? 'other' : $_), $part->{models}{$_}) } keys %{ $part->{models} };
124 $self->_add(name => $name, by => $part->{by}, models => \%models);
125 }
126 elsif (ref $part eq 'Peta::NN::Chain::Pooled') { $self->_add(name => $name, pooled => 1, models => { $ANY => _model($name, $part->{model}) }) }
127 else { $self->_add(name => $name, models => { $ANY => _model($name, $part) }) }
128 }
129 return $self->_wire;
130 }
131  
132 # One more part: { name, models => { answer or '*' => model }, by, pooled }.
133 sub _add ($self, %part) {
134 die "the chain has two parts called '$part{name}'\n" if grep { $_->{name} eq $part{name} } @{ $self->{parts} };
135 for my $model (values %{ $part{models} }) {
136 die "the chain has two models called '$model->{name}'\n" if $self->{model}{ $model->{name} };
137 $self->{model}{ $model->{name} } = $model;
138 }
139 my ($any) = values %{ $part{models} };
140 my $class = $any->{kind} eq 'class';
141 die "the part '$part{name}' chooses between models that classify and models that rewrite\n"
142 if grep { ($_->{kind} eq 'class') != $class } values %{ $part{models} };
143 die "the part '$part{name}' is pooled, which is for a model that classifies\n" if $part{pooled} && !$class;
144 push @{ $self->{parts} }, { %part, classifies => $class ? 1 : 0 };
145 return;
146 }
147  
148 # The pipeline of the parts: each parameter is an earlier part's answer if a
149 # part that classifies has its name, and an argument of the chain if not.
150 sub _wire ($self) {
151 delete @$self{qw(pipeline fused)};
152 my (%answers, @arguments, %position, @steps);
153 for my $part (@{ $self->{parts} }) {
154 my %step; # only a part that classifies has an answer to keep under its name
155 @step{qw(name classify pool)} = ($part->{name}, 1, $part->{pooled} ? 1 : 0) if $part->{classifies};
156  
157 my @models = values %{ $part->{models} };
158 my @given = @{ $models[0]{given} };
159 die "the models the part '$part->{name}' chooses from are not given the same parameters\n"
160 if grep { "@{ $_->{given} }" ne "@given" } @models;
161 my $fixed = $models[0]{fixed} // {};
162 $step{params} = [
163 map {
164 my $name = $_;
165 defined $fixed->{$name} ? "$fixed->{$name}"
166 : $answers{$name} ? { answer => $name }
167 : \($position{$name} //= do { push @arguments, $name; $#arguments })
168 } @given
169 ];
170  
171 if (defined $part->{by}) {
172 die "the part '$part->{name}' chooses by '$part->{by}', which is not an earlier part that classifies\n" if !$answers{ $part->{by} };
173 $step{model} = { $part->{by} => { map { $_ => $part->{models}{$_}{name} } keys %{ $part->{models} } } };
174 }
175 else { $step{model} = $models[0]{name} }
176 push @steps, \%step;
177 $answers{ $part->{name} } = 1 if $part->{classifies};
178 }
179 $self->{given} = \@arguments;
180 $self->{steps} = \@steps;
181 # It answers once all its models are trained.
182 $self->{pipeline} = Peta::NN::Pipeline->new(models => { map { $_ => $self->{model}{$_}{model} } keys %{ $self->{model} } }, steps => \@steps)
183 if !grep { $_->{pending} } values %{ $self->{model} };
184 return $self;
185 }
186  
187 # --- what it is ---------------------------------------------------------------------------
188  
189 # The names of its arguments, in the order the parts first need them.
190 sub given ($self) { return @{ $self->{given} } }
191  
192 # The names of its parts, in order.
193 sub parts ($self) { return map { $_->{name} } @{ $self->{parts} } }
194  
195 # The names of its models, in the order of the parts; a part that chooses has several.
196 sub models ($self) { return map { my $part = $_; map { $part->{models}{$_}{name} } sort keys %{ $part->{models} } } @{ $self->{parts} } }
197  
198 # One of its models, as the inference leg's.
199 sub model ($self, $name) {
200 my $model = $self->{model}{$name} // die "this chain has no model '$name' (it has: @{[ $self->models ]})\n";
201 return $model->{model} // die "the model '$name' is not trained yet; train() the chain\n";
202 }
203  
204 # The names of the parts that classify: what a record's answers are.
205 sub answers ($self) { return map { $_->{name} } grep { $_->{classifies} } @{ $self->{parts} } }
206  
207 sub n_params ($self) {
208 my $n = 0;
209 $n += $self->model($_)->n_params for $self->models;
210 return $n;
211 }
212  
213 # The pipeline that runs it.
214 sub pipeline ($self) {
215 # A model that was to be trained may have been, by its own train() or by another chain's.
216 my @since = grep { $_->{pending} && $_->{pending}->net } values %{ $self->{model} };
217 for my $part (@since) {
218 my $model = delete $part->{pending};
219 @$part{qw(data model trained)} = ($model->data, $model->inference, $model);
220 }
221 $self->_wire if @since;
222 return $self->{pipeline} // die sprintf "this chain cannot answer yet: %s not trained; train() it\n",
223 join ', ', map { "'$_' is" } grep { $self->{model}{$_}{pending} } $self->models;
224 }
225  
226 # The same fused, on 'cpu' or 'gpu'; dies with the reason if its parts do not fuse.
227 sub fused ($self, $engine = 'cpu') {
228 require Peta::NN::Fused;
229 $self->pipeline;
230 return $self->{fused}{$engine} //= Peta::NN::Fused->new(
231 models => { map { $_ => $self->{model}{$_}{data} } keys %{ $self->{model} } }, steps => $self->{steps}, engine => $engine);
232 }
233  
234 # Where it answers from now on: 'pipeline' (as it starts), or fused on 'cpu'
235 # or 'gpu'. Returns the chain.
236 sub on ($self, $where) {
237 die "a chain answers through its 'pipeline', or fused on 'cpu' or 'gpu', not on '$where'\n" if $where !~ /\A(?:pipeline|cpu|gpu)\z/;
238 $self->fused($where) if $where ne 'pipeline';
239 $self->{on} = $where;
240 return $self;
241 }
242  
243 sub _runner ($self) {
244 my $on = $self->{on} // 'pipeline';
245 return $on eq 'pipeline' ? $self->pipeline : $self->fused($on);
246 }
247  
248 # --- training -----------------------------------------------------------------------------------
249  
250 # Train the models of the chain that are not trained yet, on data
251 # (Peta::NN::Data), each as Peta::NN::Model's train() does it: on the fields
252 # it reads, answers and is given, to its goal if it has one. They have
253 # nothing to do with each other, so they are trained side by side, as many
254 # at a time as PETA_NN_WORKERS says. The options are those of a model's
255 # train(). Returns the chain, which can answer now.
256 sub train ($self, $data, %how) {
257 require Peta::NN::Model;
258 require Peta::NN::Parallel;
259 my @pending = grep { $_->{pending} } map { $self->{model}{$_} } $self->models;
260 # One data for all, or for each model its own: { model => data, ..., '*' => data for the others }.
261 my $data_of = sub ($name) {
262 return $data if ref $data ne 'HASH';
263 return $data->{$name} // $data->{$ANY} // die "there is no data to train the model '$name' on\n";
264 };
265 my @done = Peta::NN::Parallel::in_parallel(Peta::NN::Parallel::workers(), map {
266 my ($model, $on) = ($_->{pending}, $data_of->($_->{name}));
267 sub { $model->train($on, %how); return { state => $model->state, report => $model->report, reached => $model->reached } }
268 } @pending);
269 for my $part (@pending) {
270 my ($model, $done) = (delete $part->{pending}, shift @done);
271 # What a child process trained comes back as a training state, into the model the caller holds.
272 my $trained = Peta::NN::Model->from_state($done->{state}, backend => $model->{backend});
273 @$model{qw(layers side vocab labels params net)} = @$trained{qw(layers side vocab labels params net)};
274 delete @$model{qw(inference card)};
275 @$model{qw(report reached)} = @$done{qw(report reached)};
276 @$part{qw(data model trained)} = ($model->data, $model->inference, $model);
277 }
278 return $self->_wire;
279 }
280  
281 # What the jobs that trained the chain's models have to say, model by model;
282 # for the models that were trained to a goal.
283 sub report ($self) {
284 $self->pipeline;
285 return join '', map { my $of = $self->{model}{$_}{trained}; $of && $of->report ? "== $_ ==\n" . $of->report . "\n" : () } $self->models;
286 }
287  
288 # How the chain does on data: the share of records for which it turns the
289 # field `from` into the field `to`, of those that are held out (`unseen`)
290 # and of each mark of the data. Its arguments are the records' fields of the
291 # same names. With answer => a part that classifies, it is that part's
292 # answer that is held against `to`.
293 sub score ($self, $data, %arg) {
294 defined $arg{$_} or die "score(\$data, from => the field the chain reads, to => the field it is to give)\n" for qw(from to);
295 my @names = $self->given;
296 my %of = (unseen => $data->held, map { $_ => $data->shown->marked($_) } $data->marks);
297 my %score;
298 for my $name (keys %of) {
299 my @records = $of{$name}->records or next;
300 my %together; # the records that are asked with the same arguments
301 push @{ $together{ join "\x{1f}", @$_{@names} } }, $_ for @records;
302 my $right = 0;
303 for my $group (values %together) {
304 my $answers = $self->run([ map { $_->{ $arg{from} } } @$group ], map { $_ => $group->[0]{$_} } @names);
305 $right += grep { (defined $arg{answer} ? $answers->[$_]{answers}{ $arg{answer} } : $answers->[$_]{text}) eq $group->[$_]{ $arg{to} } } 0 .. $#$group;
306 }
307 $score{$name} = $right / @records;
308 }
309 return \%score;
310 }
311  
312 # --- answering --------------------------------------------------------------------------------
313  
314 # What a caller named, as the arguments in their order.
315 sub _arguments ($self, @named) {
316 my @names = @{ $self->{given} };
317 my $takes = @names ? 'takes ' . join(', ', map { "$_ => ..." } @names) : 'takes no arguments';
318 die "this chain $takes\n" if @named != 2 * @names;
319 my %named = @named;
320 return map { delete $named{$_} // die "this chain $takes; '$_' is missing\n" } @names;
321 }
322  
323 # One record per string: { text, confidence, answers => { part => answer } }.
324 sub run ($self, $texts, @named) {
325 my @arguments = $self->_arguments(@named);
326 return [ map { { text => $_->{text}, confidence => $_->{confidence}, answers => $_->{answers} } } @{ $self->_runner->run($texts, @arguments) } ];
327 }
328  
329 # The same for texts, each a list of strings; returns the records per text.
330 # A pooled part answers once per text.
331 sub run_texts ($self, $texts, @named) {
332 my @arguments = $self->_arguments(@named);
333 return [ map { [ map { { text => $_->{text}, confidence => $_->{confidence}, answers => $_->{answers} } } @$_ ] } @{ $self->_runner->run_texts($texts, @arguments) } ];
334 }
335  
336 # The chain's answer for a string: the string as its parts have rewritten
337 # it; in list context also its confidence, the product of the parts'.
338 sub predict ($self, $text, @named) {
339 my ($record) = @{ $self->run([$text], @named) };
340 return wantarray ? @$record{qw(text confidence)} : $record->{text};
341 }
342  
343 # The answers for many strings at once, in their order.
344 sub predict_all ($self, $texts, @named) {
345 return map { $_->{text} } @{ $self->run($texts, @named) };
346 }
347  
348 # --- a file -----------------------------------------------------------------------------------
349  
350 # A model's data as it goes into a file: as it came from its own file, or
351 # with its weights packed in full if it came as a trained model.
352 sub _stored ($data, $bits) {
353 return $data if !defined $bits || !grep { ref eq 'ARRAY' } map { @{ $_->{weights} } } @{ $data->{layers} };
354 return {
355 %$data,
356 format => $Peta::NN::Inference::FORMAT,
357 layout => $Peta::NN::Inference::LAYOUT,
358 bits => $bits,
359 layers => [ map { +{ %$_, weights => [ map { Peta::NN::Inference::pack_weights($_, $bits) } @{ $_->{weights} } ] } } @{ $data->{layers} } ],
360 };
361 }
362  
363 # With how many bits each model's weights went into the file at the last
364 # save(): { model => 8 or 32 }; nothing for a model that came from a file.
365 sub stored ($self) { return $self->{stored} }
366  
367 # How many bits a model's weights are stored with. A model that came from a
368 # file stays as it is. One that was trained here is stored with 32 bits; or,
369 # when the caller says by which data to judge, with 8 if the model as stored
370 # then still answers every record of that data the way the trained one does,
371 # and with 32 if not.
372 sub _bits_for ($part, $judge) {
373 my $data = $part->{data};
374 return undef if !grep { ref eq 'ARRAY' } map { @{ $_->{weights} } } @{ $data->{layers} }; # as it came from its file
375 my $trained = $part->{trained};
376 return 32 if !$judge || !$trained || !defined $trained->{from};
377 my $records = ref $judge eq 'HASH' ? $judge->{ $part->{name} } // $judge->{$ANY} : $judge;
378 return 32 if !$records;
379 my $pairs = $records->pairs(from => $trained->{from}, to => $trained->{to}, given => $trained->{given} // []);
380 my %with; # the values given => the strings asked with them
381 push @{ $with{ join "\x{1f}", @$_[ 2 .. $#$_ ] } }, $_ for @$pairs;
382 my $small = Peta::NN::Inference->new(_stored($data, 8));
383 for my $group (values %with) {
384 my @values = @{ $group->[0] }[ 2 .. $#{ $group->[0] } ];
385 my @texts = map { $_->[0] } @$group;
386 my ($a, $b) = map { join "\x{1f}", map { $_->[0] } @{ $_->answers(\@texts, @values) } } $small, $part->{model};
387 return 32 if $a ne $b;
388 }
389 return 8;
390 }
391  
392 # Write the chain to one file: its parts, each model as it is. Models that
393 # were trained here are stored with 32-bit weights; with small => data (or
394 # { model => data, ... }) each of them with 8 bits if it then still answers
395 # every record of that data as before. A table of what the file is to say of
396 # itself (name, description, ...) may follow. stored() says what was done.
397 sub save ($self, $file, %meta) {
398 my $judge = delete $meta{small};
399 $self->pipeline;
400 $self->{stored} = { map { $_ => _bits_for($self->{model}{$_}, $judge) } keys %{ $self->{model} } };
401 Storable::nstore({
402 format => $FORMAT,
403 layout => $LAYOUT,
404 version => $VERSION,
405 parts => [ map { my $part = $_; my ($any) = values %{ $part->{models} };
406 +{ %$part{qw(name by pooled)}, fixed => $any->{fixed}, models => { map { $_ => $part->{models}{$_}{name} } keys %{ $part->{models} } } } } @{ $self->{parts} } ],
407 models => { map { $_ => _stored($self->{model}{$_}{data}, $self->{stored}{$_}) } keys %{ $self->{model} } },
408 meta => { created => time, %meta },
409 }, $file);
410 return $self;
411 }
412  
413 # A chain from a file: a chain's file, or a single model's file, which is a
414 # chain of that one part (called by the file's name without its ending).
415 sub load ($class, $file) {
416 my $data = eval { Storable::retrieve($file, 0) };
417 die "$file cannot be read as a chain or a model: " . ($@ =~ s/ at \S+ line \d+.*//sr || "$!") . "\n" if ref $data ne 'HASH';
418 if (($data->{format} // '') eq $Peta::NN::Inference::FORMAT) {
419 my ($name) = $file =~ m{([^/]+?)(?:\.[^./]*)?\z};
420 return $class->new($name => $data);
421 }
422 die "$file is neither a chain's file nor a model's\n" if ($data->{format} // '') ne $FORMAT;
423 die sprintf "$file is in layout %s, and this version reads layout %d; save it again\n", $data->{layout} // '?', $LAYOUT if ($data->{layout} // '') ne $LAYOUT;
424 die "$file is a malformed chain: no parts or no models\n" if ref $data->{parts} ne 'ARRAY' || ref $data->{models} ne 'HASH';
425  
426 my $self = bless { parts => [], model => {}, meta => $data->{meta} }, $class;
427 eval {
428 for my $part (@{ $data->{parts} }) {
429 my %models = map {
430 my $name = $part->{models}{$_};
431 my $model = $data->{models}{$name} // die "the part '$part->{name}' uses the model '$name', which is not in the file\n";
432 $_ => _model($name, $part->{fixed} ? fixed($model, %{ $part->{fixed} }) : $model)
433 } keys %{ $part->{models} };
434 $self->_add(name => $part->{name}, models => \%models, map { $_ => $part->{$_} } grep { defined $part->{$_} } qw(by pooled));
435 }
436 $self->_wire;
437 1;
438 } or die "$file is a malformed chain: $@";
439 return $self;
440 }
441  
442 # What there is to know about the chain, for a human.
443 sub info ($self) {
444 return {
445 %{ $self->{meta} // {} },
446 format => $FORMAT,
447 version => $VERSION,
448 kind => 'chain',
449 parts => [ map { my $part = $_; defined $part->{by} ? "$part->{name}, chosen by $part->{by}" : $part->{pooled} ? "$part->{name}, pooled" : $part->{name} } @{ $self->{parts} } ],
450 given => [ $self->given ],
451 answers => [ $self->answers ],
452 weights => $self->n_params,
453 models => { map { $_ => $self->model($_)->info } $self->models },
454 };
455 }
456  
457 1;
458  
459 __END__