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

filter: Statementstmt 0.0% 0 / 138 Branchbran 0.0% 0 / 50 Conditioncond 0.0% 0 / 34 MC/DCmcdc 0.0% 0 / 18 Subroutinesub 0.0% 0 / 12 Podpod 0.0% 0 / 9 totaltotal 0.0% 0 / 261 CC 26 SCAR 51.0
CC
26
Cov
0%
new
306.0
_run
90.0
predict
6.0
CRAP 163.3
1 package Peta::NN::Pipeline;
2 # ABSTRACT: models in series, and routed by a classifier
3  
4 # Models put together: in series, where each step's answer is the next step's
5 # input (Apfel -> Äpfel -> Äpfeln), and with routing, where a classifying
6 # step's answer decides which model a later step uses.
7 #
8 # The models stay what they are: each does its one limited transformation and
9 # knows nothing of the others, or of what its parameters mean. What a chain
10 # means is written here, in the pipeline's steps, by whoever builds it.
11 #
12 # This is part of the inference leg: it needs Peta::NN::Inference and the
13 # model files, nothing of the training leg.
14  
15 use v5.36;
16  
17 use Peta::NN::Inference;
18  
19 our $VERSION = '0.2610090';
20  
21 my $ANY = '*'; # in a routing table: the model for every answer not listed
22  
23 # models { name => model }: a model file's path, or an object that answers
24 # (Peta::NN::Inference, or the training leg's Peta::NN::Model)
25 # steps the steps, in order; each is a table with
26 # model the name of a model, or a routing table
27 # { step => { answer => model name, ... } }: the model is chosen by
28 # the answer of the earlier step called `step`; '*' stands for any
29 # answer not listed
30 # params the step's parameters, each one of
31 # 'text' that value, always
32 # \N the Nth argument of the call (0 is the first)
33 # { answer => step } the answer of the earlier step called `step`
34 # name a name for the step, so that later steps can refer to its answer
35 # classify true if the step only looks: its answer is recorded under its
36 # name, and the string goes on to the next step unchanged
37 # pool true if a classifying step answers once for all strings of a
38 # text together (run_texts): every word is evidence, and the
39 # text gets the one answer they point to
40 sub new ($class, %arg) {
41 my $models = $arg{models} // die "models => { name => model, ... } is required\n";
42 my $steps = $arg{steps} // die "steps => [ ... ] is required\n";
43 die "a pipeline needs at least one step\n" if !@$steps;
44  
45 my %model = map {
46 my $model = $models->{$_};
47 $_ => !ref $model ? Peta::NN::Inference->load($model)
48 : $model->can('inference') ? $model->inference
49 : $model
50 } keys %$models;
51  
52 my (%named, $arguments);
53 my $self = bless { model => \%model, steps => [] }, $class;
54 for my $n (0 .. $#$steps) {
55 my %step = %{ $steps->[$n] };
56 my $where = 'step ' . ($n + 1);
57 my $spec = $step{model} // die "$where names no model\n";
58  
59 # Every model a step may use must exist, and a routing step must
60 # route by a step that came before it.
61 my @used = $spec;
62 if (ref $spec eq 'HASH') {
63 my ($by, @more) = keys %$spec;
64 die "$where routes by more than one step\n" if @more;
65 die "$where routes by '$by', which is not an earlier step\n" if !$named{$by};
66 @used = values %{ $spec->{$by} };
67 }
68 defined $model{$_} or die "$where uses the model '$_', which the pipeline does not have\n" for @used;
69  
70 for my $param (@{ $step{params} // [] }) {
71 if (ref $param eq 'HASH') {
72 my $from = $param->{answer} // die "$where has a parameter that is a table without `answer`\n";
73 die "$where takes a parameter from '$from', which is not an earlier step\n" if !$named{$from};
74 }
75 elsif (ref $param eq 'SCALAR') {
76 die "$where has an argument number that is not a whole number\n" if $$param !~ /\A[0-9]+\z/;
77 $arguments = $$param + 1 if $$param + 1 > ($arguments // 0);
78 }
79 elsif (ref $param) { die "$where has a parameter that is neither text, \\N nor { answer => step }\n" }
80 }
81 die "$where only classifies, so it needs a name for its answer\n" if $step{classify} && !defined $step{name};
82 die "$where pools, which is for a step that classifies\n" if $step{pool} && !$step{classify};
83 for my $model (grep { $_->can('kind') } @model{@used}) {
84 die "$where pools, which is for class models\n" if $step{pool} && $model->kind ne 'class';
85 }
86 $named{ $step{name} } = 1 if defined $step{name};
87 push @{ $self->{steps} }, \%step;
88 }
89 $self->{arguments} = $arguments // 0;
90 return $self;
91 }
92  
93 # How many arguments a call takes after the string.
94 sub arguments ($self) { return $self->{arguments} }
95  
96 # Run many strings through the steps. Returns one record per string:
97 # { text, confidence, answers => { step name => answer }, trace => [ ... ] }
98 # with a trace entry [model name, parameters, input, output, confidence] per
99 # step. Strings that reach a step with the same model and parameters go
100 # through it in one pass.
101 sub run ($self, $texts, @arguments) { return $self->_run($texts, [ 0 .. $#$texts ], @arguments) }
102  
103 # Run many texts, each a list of strings (its words, say). Returns for each
104 # text the records of its strings. What differs from run() is a pooling
105 # step: it answers once per text.
106 sub run_texts ($self, $texts, @arguments) {
107 my @of = map { my $n = $_; ($n) x @{ $texts->[$n] } } 0 .. $#$texts;
108 my $states = $self->_run([ map { @$_ } @$texts ], \@of, @arguments);
109 my @result = map { [] } @$texts;
110 push @{ $result[ $of[$_] ] }, $states->[$_] for 0 .. $#of;
111 return \@result;
112 }
113  
114 # $of says for each string which text it belongs to.
115 sub _run ($self, $texts, $of, @arguments) {
116 die sprintf "this pipeline takes %d argument%s after the string, not %d\n",
117 $self->{arguments}, $self->{arguments} == 1 ? '' : 's', scalar @arguments if @arguments != $self->{arguments};
118  
119 my @state = map { { text => $texts->[$_], of => $of->[$_], confidence => 1, answers => {}, trace => [] } } 0 .. $#$texts;
120 for my $step (@{ $self->{steps} }) {
121 my %batch; # "model, parameters" => the states that take this step that way
122 for my $state (@state) {
123 my $spec = $step->{model};
124 my $name = $spec;
125 if (ref $spec) {
126 my ($by) = keys %$spec;
127 my $answer = $state->{answers}{$by};
128 $name = $spec->{$by}{$answer} // $spec->{$by}{$ANY}
129 // die "no model for the answer '$answer' of step '$by'\n";
130 }
131 my @values = map { ref eq 'HASH' ? $state->{answers}{ $_->{answer} } : ref eq 'SCALAR' ? $arguments[$$_] : $_ }
132 @{ $step->{params} // [] };
133 push @{ $batch{ join "\x{1f}", $name, @values }{states} }, $state;
134 $batch{ join "\x{1f}", $name, @values }{call} //= [ $name, @values ];
135 }
136 for my $group (values %batch) {
137 my ($name, @values) = @{ $group->{call} };
138 my @states = @{ $group->{states} };
139 if ($step->{pool}) {
140 my %text;
141 push @{ $text{ $_->{of} } }, $_ for @states;
142 for my $members (values %text) {
143 my ($answer, $share) = @{ $self->{model}{$name}->pooled_for([ map { $_->{text} } @$members ], @values)->[0] };
144 for my $state (@$members) {
145 push @{ $state->{trace} }, [ $name, \@values, $state->{text}, $answer, $share ];
146 $state->{confidence} *= $share;
147 $state->{answers}{ $step->{name} } = $answer;
148 }
149 }
150 next;
151 }
152 my $answers = $self->{model}{$name}->answers([ map { $_->{text} } @states ], @values);
153 for my $n (0 .. $#states) {
154 my ($state, $answer, $confidence) = ($states[$n], @{ $answers->[$n] });
155 push @{ $state->{trace} }, [ $name, \@values, $state->{text}, $answer, $confidence ];
156 $state->{confidence} *= $confidence;
157 $state->{answers}{ $step->{name} } = $answer if defined $step->{name};
158 $state->{text} = $answer if !$step->{classify};
159 }
160 }
161 }
162 return \@state;
163 }
164  
165 # The pipeline's answer for a string; in list context also its confidence,
166 # the product of the steps' confidences: a chain is as sure as all its links
167 # together.
168 sub predict ($self, $text, @arguments) {
169 my ($state) = @{ $self->run([$text], @arguments) };
170 return wantarray ? @$state{qw(text confidence)} : $state->{text};
171 }
172  
173 # The answers for many strings at once, in their order.
174 sub predict_all ($self, $texts, @arguments) {
175 return map { $_->{text} } @{ $self->run($texts, @arguments) };
176 }
177  
178 # The same steps as one fused model (Peta::NN::Fused): the models as they
179 # are, and what happens here between two steps inside it. Options as for
180 # Peta::NN::Fused->new (engine, meta). Only steps in series fuse.
181 sub fuse ($self, %arg) {
182 require Peta::NN::Fused;
183 return Peta::NN::Fused->new(models => $self->{model}, steps => $self->{steps}, %arg);
184 }
185  
186 # What each step did with one string: a list of
187 # [model name, parameters, input, output, confidence].
188 sub trace ($self, $text, @arguments) {
189 my ($state) = @{ $self->run([$text], @arguments) };
190 return @{ $state->{trace} };
191 }
192  
193 1;
194  
195 __END__