Skip to content

Commit 6f92688

Browse files
panhongxpanhongx
committed
update doc
1 parent 5efa7d1 commit 6f92688

File tree

9 files changed

+136
-34
lines changed

9 files changed

+136
-34
lines changed

‎docs/javadoc/ai/improve/DecisionContext.html‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -148,10 +148,12 @@ <h3>Constructor Summary</h3>
148148
<table class="memberSummary">
149149
<caption><span>Constructors</span><span class="tabEnd">&nbsp;</span></caption>
150150
<tr>
151-
<th class="colFirst" scope="col">Constructor</th>
151+
<th class="colFirst" scope="col">Modifier</th>
152+
<th class="colSecond" scope="col">Constructor</th>
152153
<th class="colLast" scope="col">Description</th>
153154
</tr>
154155
<tr class="altColor">
156+
<td class="colFirst"><code>protected </code></td>
155157
<th class="colConstructorName" scope="row"><code><span class="memberNameLink"><a href="#%3Cinit%3E(ai.improve.DecisionModel,java.util.Map)">DecisionContext</a></span>&#8203;(<a href="DecisionModel.html" title="class in ai.improve">DecisionModel</a>&nbsp;decisionModel,
156158
java.util.Map&nbsp;givens)</code></th>
157159
<td class="colLast">&nbsp;</td>
@@ -250,8 +252,8 @@ <h3>Constructor Detail</h3>
250252
<ul class="blockListLast">
251253
<li class="blockList">
252254
<h4>DecisionContext</h4>
253-
<pre>public&nbsp;DecisionContext&#8203;(<a href="DecisionModel.html" title="class in ai.improve">DecisionModel</a>&nbsp;decisionModel,
254-
java.util.Map&nbsp;givens)</pre>
255+
<pre>protected&nbsp;DecisionContext&#8203;(<a href="DecisionModel.html" title="class in ai.improve">DecisionModel</a>&nbsp;decisionModel,
256+
java.util.Map&nbsp;givens)</pre>
255257
</li>
256258
</ul>
257259
</li>

‎docs/javadoc/ai/improve/DecisionModel.html‎

Lines changed: 60 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -245,9 +245,7 @@ <h3>Method Summary</h3>
245245
<td class="colFirst"><code>protected void</code></td>
246246
<th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#addRewardForDecision(java.lang.String,double)">addRewardForDecision</a></span>&#8203;(java.lang.String&nbsp;decisionId,
247247
double&nbsp;reward)</code></th>
248-
<td class="colLast">
249-
<div class="block">Adds the reward to a specific decision</div>
250-
</td>
248+
<td class="colLast">&nbsp;</td>
251249
</tr>
252250
<tr id="i2" class="altColor">
253251
<td class="colFirst"><code>&lt;T&gt;&nbsp;<a href="Decision.html" title="class in ai.improve">Decision</a>&lt;T&gt;</code></td>
@@ -351,8 +349,10 @@ <h3>Method Summary</h3>
351349
</tr>
352350
<tr id="i21" class="rowColor">
353351
<td class="colFirst"><code><a href="DecisionModel.html" title="class in ai.improve">DecisionModel</a></code></td>
354-
<th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#load(java.net.URL)">load</a></span>&#8203;(java.net.URL&nbsp;url)</code></th>
355-
<td class="colLast">&nbsp;</td>
352+
<th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#load(java.net.URL)">load</a></span>&#8203;(java.net.URL&nbsp;modelUrl)</code></th>
353+
<td class="colLast">
354+
<div class="block">Load a model synchronously.</div>
355+
</td>
356356
</tr>
357357
<tr id="i22" class="altColor">
358358
<td class="colFirst"><code>void</code></td>
@@ -523,6 +523,12 @@ <h4>DecisionModel</h4>
523523
<div class="block">It's an equivalent of DecisionModel(modelName, defaultTrackURL, defaultTrackApiKey)
524524
We suggest to have the defaultTrackURL/defaultTrackApiKey set on startup before creating
525525
any DecisionModel instances.</div>
526+
<dl>
527+
<dt><span class="paramLabel">Parameters:</span></dt>
528+
<dd><code>modelName</code> - Length of modelName must be in range [1, 64]; Only alphanumeric
529+
characters([a-zA-Z0-9]), '-', '.' and '_' are allowed in the modelName
530+
and the first character must be an alphanumeric one.</dd>
531+
</dl>
526532
</li>
527533
</ul>
528534
<a id="&lt;init&gt;(java.lang.String,java.lang.String,java.lang.String)">
@@ -538,7 +544,7 @@ <h4>DecisionModel</h4>
538544
<dt><span class="paramLabel">Parameters:</span></dt>
539545
<dd><code>modelName</code> - Length of modelName must be in range [1, 64]; Only alphanumeric
540546
characters([a-zA-Z0-9]), '-', '.' and '_' are allowed in the modelName
541-
and the first character must be an alphanumeric one;</dd>
547+
and the first character must be an alphanumeric one.</dd>
542548
<dd><code>trackURL</code> - url for tracking decisions. If trackURL is null, no decisions would be
543549
tracked. If trackURL is not a valid URL, an exception would be thrown.</dd>
544550
<dd><code>trackApiKey</code> - will be attached to the header fields of all the post request for tracking</dd>
@@ -582,11 +588,22 @@ <h4>put</h4>
582588
<ul class="blockList">
583589
<li class="blockList">
584590
<h4>load</h4>
585-
<pre class="methodSignature">public&nbsp;<a href="DecisionModel.html" title="class in ai.improve">DecisionModel</a>&nbsp;load&#8203;(java.net.URL&nbsp;url)
591+
<pre class="methodSignature">public&nbsp;<a href="DecisionModel.html" title="class in ai.improve">DecisionModel</a>&nbsp;load&#8203;(java.net.URL&nbsp;modelUrl)
586592
throws java.io.IOException</pre>
593+
<div class="block">Load a model synchronously. Calling this method would block the current thread, so please
594+
try not do it in the UI thread.</div>
587595
<dl>
596+
<dt><span class="paramLabel">Parameters:</span></dt>
597+
<dd><code>modelUrl</code> - A url that can be a local file path, a remote http url that points to a
598+
model file, or a bundled asset. Urls that ends with '.gz' are considered gzip
599+
compressed, and will be handled appropriately. Bundled model asset urls
600+
appears a bit different. Suppose that you have a bundled model file in folder
601+
"assets/models/my_model.xgb.gz", then modelUrl should be
602+
new URL("file:///android_asset/models/my_model.xgb").</dd>
603+
<dt><span class="returnLabel">Returns:</span></dt>
604+
<dd>Returns self.</dd>
588605
<dt><span class="throwsLabel">Throws:</span></dt>
589-
<dd><code>java.io.IOException</code></dd>
606+
<dd><code>java.io.IOException</code> - Thrown if the model failed to load.</dd>
590607
</dl>
591608
</li>
592609
</ul>
@@ -597,6 +614,15 @@ <h4>load</h4>
597614
<li class="blockList">
598615
<h4>loadAsync</h4>
599616
<pre class="methodSignature">public&nbsp;void&nbsp;loadAsync&#8203;(java.net.URL&nbsp;modelUrl)</pre>
617+
<dl>
618+
<dt><span class="paramLabel">Parameters:</span></dt>
619+
<dd><code>modelUrl</code> - A url that can be a local file path, a remote http url that points to a
620+
model file, or a bundled asset. Urls that ends with '.gz' are considered gzip
621+
compressed, and will be handled appropriately. Bundled model asset urls
622+
appears a bit different. Suppose that you have a bundled model file in folder
623+
"assets/models/my_model.xgb.gz", then modelUrl should be
624+
new URL("file:///android_asset/models/my_model.xgb").</dd>
625+
</dl>
600626
</li>
601627
</ul>
602628
<a id="loadAsync(java.net.URL,ai.improve.DecisionModel.LoadListener)">
@@ -614,6 +640,16 @@ <h4>loadAsync</h4>
614640
<div class="block">Notice that it's not recommended to call this method directly in an Android Activity as it
615641
may cause leaks. Before we add a cancel method to allow aborting downloading tasks, you may
616642
have to call loadAsync() in something like a Singleton class.</div>
643+
<dl>
644+
<dt><span class="paramLabel">Parameters:</span></dt>
645+
<dd><code>modelUrl</code> - A url that can be a local file path, a remote http url that points to a
646+
model file, or a bundled asset. Urls that ends with '.gz' are considered gzip
647+
compressed, and will be handled appropriately. Bundled model asset urls
648+
appears a bit different. Suppose that you have a bundled model file in folder
649+
"assets/models/my_model.xgb.gz", then modelUrl should be
650+
new URL("file:///android_asset/models/my_model.xgb").</dd>
651+
<dd><code>listener</code> - The callback that will run when the model is loaded.</dd>
652+
</dl>
617653
</li>
618654
</ul>
619655
<a id="getTrackURL()">
@@ -945,8 +981,11 @@ <h4>random</h4>
945981
<h4>given</h4>
946982
<pre class="methodSignature">public&nbsp;<a href="DecisionContext.html" title="class in ai.improve">DecisionContext</a>&nbsp;given&#8203;(java.util.Map&lt;java.lang.String,&#8203;java.lang.Object&gt;&nbsp;givens)</pre>
947983
<dl>
984+
<dt><span class="paramLabel">Parameters:</span></dt>
985+
<dd><code>givens</code> - Additional context info that will be used with each of the variants to calculate
986+
its feature vector.</dd>
948987
<dt><span class="returnLabel">Returns:</span></dt>
949-
<dd>an IMPDecision object</dd>
988+
<dd>A DecisionContext object.</dd>
950989
</dl>
951990
</li>
952991
</ul>
@@ -1035,7 +1074,12 @@ <h4>addReward</h4>
10351074
<h4>addRewardForDecision</h4>
10361075
<pre class="methodSignature">protected&nbsp;void&nbsp;addRewardForDecision&#8203;(java.lang.String&nbsp;decisionId,
10371076
double&nbsp;reward)</pre>
1038-
<div class="block">Adds the reward to a specific decision</div>
1077+
<dl>
1078+
<dt><span class="paramLabel">Parameters:</span></dt>
1079+
<dd><code>decisionId</code> - unique id of a decision.</dd>
1080+
<dd><code>reward</code> - reward for the decision.
1081+
Adds the reward to a specific decision</dd>
1082+
</dl>
10391083
</li>
10401084
</ul>
10411085
<a id="rank(java.util.List,java.util.List)">
@@ -1047,11 +1091,16 @@ <h4>rank</h4>
10471091
<pre class="methodSignature">public static&nbsp;&lt;T&gt;&nbsp;java.util.List&lt;T&gt;&nbsp;rank&#8203;(java.util.List&lt;T&gt;&nbsp;variants,
10481092
java.util.List&lt;java.lang.Double&gt;&nbsp;scores)</pre>
10491093
<div class="block">This method is likely to be changed in the future. Try not to use it in your code.
1050-
10511094
If variants.size() != scores.size(), an IndexOutOfBoundException exception will be thrown</div>
10521095
<dl>
1096+
<dt><span class="paramLabel">Parameters:</span></dt>
1097+
<dd><code>variants</code> - A list of variants to be ranked.</dd>
1098+
<dd><code>scores</code> - Scores of the variants.</dd>
10531099
<dt><span class="returnLabel">Returns:</span></dt>
10541100
<dd>a list of the variants ranked from best to worst by scores</dd>
1101+
<dt><span class="throwsLabel">Throws:</span></dt>
1102+
<dd><code>java.lang.IllegalArgumentException</code> - Thrown if variants or scores is null; Thrown if
1103+
variants.size() not equal to scores.size().</dd>
10551104
</dl>
10561105
</li>
10571106
</ul>

‎docs/javadoc/index-all.html‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -105,9 +105,7 @@ <h2 class="title">A</h2>
105105
<div class="block">This method should only be called on Android platform.</div>
106106
</dd>
107107
<dt><span class="memberNameLink"><a href="ai/improve/DecisionModel.html#addRewardForDecision(java.lang.String,double)">addRewardForDecision(String, double)</a></span> - Method in class ai.improve.<a href="ai/improve/DecisionModel.html" title="class in ai.improve">DecisionModel</a></dt>
108-
<dd>
109-
<div class="block">Adds the reward to a specific decision</div>
110-
</dd>
108+
<dd>&nbsp;</dd>
111109
<dt><a href="ai/improve/package-summary.html">ai.improve</a> - package ai.improve</dt>
112110
<dd>&nbsp;</dd>
113111
<dt><a href="ai/improve/downloader/package-summary.html">ai.improve.downloader</a> - package ai.improve.downloader</dt>
@@ -273,7 +271,9 @@ <h2 class="title">L</h2>
273271
<dt><span class="memberNameLink"><a href="ai/improve/downloader/ModelLoader.html#load(java.lang.String)">load(String)</a></span> - Method in interface ai.improve.downloader.<a href="ai/improve/downloader/ModelLoader.html" title="interface in ai.improve.downloader">ModelLoader</a></dt>
274272
<dd>&nbsp;</dd>
275273
<dt><span class="memberNameLink"><a href="ai/improve/DecisionModel.html#load(java.net.URL)">load(URL)</a></span> - Method in class ai.improve.<a href="ai/improve/DecisionModel.html" title="class in ai.improve">DecisionModel</a></dt>
276-
<dd>&nbsp;</dd>
274+
<dd>
275+
<div class="block">Load a model synchronously.</div>
276+
</dd>
277277
<dt><span class="memberNameLink"><a href="ai/improve/DecisionModel.html#loadAsync(java.net.URL)">loadAsync(URL)</a></span> - Method in class ai.improve.<a href="ai/improve/DecisionModel.html" title="class in ai.improve">DecisionModel</a></dt>
278278
<dd>&nbsp;</dd>
279279
<dt><span class="memberNameLink"><a href="ai/improve/DecisionModel.html#loadAsync(java.net.URL,ai.improve.DecisionModel.LoadListener)">loadAsync(URL, DecisionModel.LoadListener)</a></span> - Method in class ai.improve.<a href="ai/improve/DecisionModel.html" title="class in ai.improve">DecisionModel</a></dt>

‎docs/javadoc/member-search-index.zip‎

0 Bytes
Binary file not shown.

‎docs/javadoc/overview-summary.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
<!-- NewPage -->
33
<html lang="en">
44
<head>
5-
<!-- Generated by javadoc (11.0.11) on Wed May 18 21:21:28 CST 2022 -->
5+
<!-- Generated by javadoc (11.0.11) on Thu May 19 15:03:23 CST 2022 -->
66
<title>improveai API</title>
77
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
88
<script type="text/javascript">window.location.replace('index.html')</script>

‎docs/javadoc/package-search-index.zip‎

0 Bytes
Binary file not shown.

‎docs/javadoc/type-search-index.zip‎

0 Bytes
Binary file not shown.

‎improveai/src/main/java/ai/improve/DecisionModel.java‎

Lines changed: 42 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -95,7 +95,19 @@ public static void put(String modelName, DecisionModel decisionModel) {
9595
instances.put(modelName, decisionModel);
9696
}
9797

98-
public DecisionModel load(URL url) throws IOException {
98+
/**
99+
* Load a model synchronously. Calling this method would block the current thread, so please
100+
* try not do it in the UI thread.
101+
* @param modelUrl A url that can be a local file path, a remote http url that points to a
102+
* model file, or a bundled asset. Urls that ends with '.gz' are considered gzip
103+
* compressed, and will be handled appropriately. Bundled model asset urls
104+
* appears a bit different. Suppose that you have a bundled model file in folder
105+
* "assets/models/my_model.xgb.gz", then modelUrl should be
106+
* new URL("file:///android_asset/models/my_model.xgb").
107+
* @return Returns self.
108+
* @throws IOException Thrown if the model failed to load.
109+
*/
110+
public DecisionModel load(URL modelUrl) throws IOException {
99111
final IOException[] downloadException = {null};
100112
LoadListener listener = new LoadListener() {
101113
@Override
@@ -114,7 +126,7 @@ public void onError(IOException e) {
114126
}
115127
};
116128

117-
loadAsync(url, listener);
129+
loadAsync(modelUrl, listener);
118130
synchronized (lock) {
119131
try {
120132
lock.wait();
@@ -131,6 +143,14 @@ public void onError(IOException e) {
131143
return this;
132144
}
133145

146+
/**
147+
* @param modelUrl A url that can be a local file path, a remote http url that points to a
148+
* model file, or a bundled asset. Urls that ends with '.gz' are considered gzip
149+
* compressed, and will be handled appropriately. Bundled model asset urls
150+
* appears a bit different. Suppose that you have a bundled model file in folder
151+
* "assets/models/my_model.xgb.gz", then modelUrl should be
152+
* new URL("file:///android_asset/models/my_model.xgb").
153+
*/
134154
public void loadAsync(URL modelUrl) {
135155
loadAsync(modelUrl, null);
136156
}
@@ -146,6 +166,7 @@ public void loadAsync(URL modelUrl) {
146166
* appears a bit different. Suppose that you have a bundled model file in folder
147167
* "assets/models/my_model.xgb.gz", then modelUrl should be
148168
* new URL("file:///android_asset/models/my_model.xgb").
169+
* @param listener The callback that will run when the model is loaded.
149170
* */
150171
@Deprecated
151172
public void loadAsync(URL modelUrl, LoadListener listener) {
@@ -388,7 +409,9 @@ public Object random(Object...variants) {
388409
}
389410

390411
/**
391-
* @return an IMPDecision object
412+
* @param givens Additional context info that will be used with each of the variants to calculate
413+
* its feature vector.
414+
* @return A DecisionContext object.
392415
*/
393416
public DecisionContext given(Map<String, Object> givens) {
394417
return new DecisionContext(this, givens);
@@ -464,7 +487,7 @@ protected List<Double> scoreInternal(List variants, Map<String, ?> givens) {
464487
* @param reward the reward to add. Must not be NaN, or Infinity.
465488
* @throws IllegalArgumentException Thrown if `reward` is NaN or Infinity
466489
* @throws IllegalStateException Thrown if trackURL is null, or called on non-Android platform.
467-
* */
490+
*/
468491
public void addReward(double reward) {
469492
if(Double.isInfinite(reward) || Double.isNaN(reward)) {
470493
throw new IllegalArgumentException("reward must not be NaN or infinity");
@@ -482,8 +505,10 @@ public void addReward(double reward) {
482505
}
483506

484507
/**
508+
* @param decisionId unique id of a decision.
509+
* @param reward reward for the decision.
485510
* Adds the reward to a specific decision
486-
* */
511+
*/
487512
protected void addRewardForDecision(String decisionId, double reward) {
488513
if(Double.isInfinite(reward) || Double.isNaN(reward)) {
489514
throw new IllegalArgumentException("reward must not be NaN or infinity");
@@ -502,20 +527,24 @@ protected void addRewardForDecision(String decisionId, double reward) {
502527

503528
/**
504529
* This method is likely to be changed in the future. Try not to use it in your code.
505-
*
506530
* If variants.size() != scores.size(), an IndexOutOfBoundException exception will be thrown
531+
* @param variants A list of variants to be ranked.
532+
* @param scores Scores of the variants.
507533
* @return a list of the variants ranked from best to worst by scores
508-
* */
534+
* @throws IllegalArgumentException Thrown if variants or scores is null; Thrown if
535+
* variants.size() not equal to scores.size().
536+
*/
509537
public static <T> List<T> rank(List<T> variants, List<Double> scores) {
510-
// check the size of variants and scores, and use the bigger one so that
511-
// an IndexOutOfBoundOfException would be thrown later
512-
int size = variants.size();
513-
if(scores.size() > variants.size()) {
514-
size = scores.size();
538+
if(variants == null || scores == null) {
539+
throw new IllegalArgumentException("variants or scores can't be null");
540+
}
541+
542+
if(variants.size() != scores.size()) {
543+
throw new IllegalArgumentException("variants.size() must equal to scores.size()");
515544
}
516545

517546
Integer[] indices = new Integer[variants.size()];
518-
for(int i = 0; i < size; ++i) {
547+
for(int i = 0; i < variants.size(); ++i) {
519548
indices[i] = i;
520549
}
521550

‎improveai/src/test/java/ai/improve/DecisionModelTest.java‎

Lines changed: 24 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -287,6 +287,28 @@ public void testRank() {
287287
}
288288
}
289289

290+
@Test
291+
public void testRank_null_variants() {
292+
try {
293+
DecisionModel.rank(null, Arrays.asList(0.1, 0.2));
294+
} catch (IllegalArgumentException e) {
295+
e.printStackTrace();
296+
return ;
297+
}
298+
fail(DefaultFailMessage);
299+
}
300+
301+
@Test
302+
public void testRank_null_scores() {
303+
try {
304+
DecisionModel.rank(Arrays.asList("hi", "hello"), null);
305+
} catch (IllegalArgumentException e) {
306+
e.printStackTrace();
307+
return ;
308+
}
309+
fail(DefaultFailMessage);
310+
}
311+
290312
@Test
291313
public void testRankInvalid_largerVariants() {
292314
int count = 100;
@@ -301,7 +323,7 @@ public void testRankInvalid_largerVariants() {
301323

302324
try {
303325
DecisionModel.rank(variants, scores);
304-
} catch (IndexOutOfBoundsException e) {
326+
} catch (IllegalArgumentException e) {
305327
return ;
306328
}
307329
fail("An IndexOutOfBoundException should have been thrown, we should never reach here");
@@ -321,7 +343,7 @@ public void testRankInvalid_largerScores() {
321343

322344
try {
323345
DecisionModel.rank(variants, scores);
324-
} catch (IndexOutOfBoundsException e) {
346+
} catch (IllegalArgumentException e) {
325347
return ;
326348
}
327349
fail("An IndexOutOfBoundException should have been thrown, we should never reach here");

0 commit comments

Comments
 (0)