ingenia_api 1.0.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +7 -0
- data/.gitignore +6 -0
- data/Gemfile +3 -0
- data/LICENSE +22 -0
- data/README.md +379 -0
- data/Rakefile +2 -0
- data/examples/bundles.rb +74 -0
- data/examples/classify.rb +9 -0
- data/examples/console.rb +13 -0
- data/examples/helper.rb +15 -0
- data/examples/items.rb +124 -0
- data/examples/run_all_examples.rb +7 -0
- data/examples/similar_to.rb +23 -0
- data/examples/summarize.rb +11 -0
- data/examples/tag_sets.rb +75 -0
- data/examples/tags.rb +80 -0
- data/examples/train_classify_similar_to.rb +42 -0
- data/ingenia-api.gemspec +21 -0
- data/lib/ingenia_api.rb +126 -0
- data/lib/ingenia_api/bundle.rb +62 -0
- data/lib/ingenia_api/html_extractor.rb +24 -0
- data/lib/ingenia_api/item.rb +99 -0
- data/lib/ingenia_api/remote.rb +131 -0
- data/lib/ingenia_api/tag.rb +72 -0
- data/lib/ingenia_api/tag_set.rb +59 -0
- data/spec/fixtures/empty_array.json +1 -0
- data/spec/fixtures/empty_hash.json +1 -0
- data/spec/fixtures/five_knowledge_items_index.json +1 -0
- data/spec/fixtures/knowledge_item.json +2 -0
- data/spec/fixtures/knowledge_items.json +1 -0
- data/spec/fixtures/status.json +1 -0
- data/spec/fixtures/success.json +1 -0
- data/spec/fixtures/user_tags.json +1 -0
- data/spec/ingenia_api/api_spec.rb +126 -0
- data/spec/ingenia_api/bundle_spec.rb +78 -0
- data/spec/ingenia_api/html_extractor_spec.rb +29 -0
- data/spec/ingenia_api/item_spec.rb +115 -0
- data/spec/ingenia_api/tag_set_spec.rb +78 -0
- data/spec/ingenia_api/tag_spec.rb +72 -0
- data/spec/spec_helper.rb +66 -0
- metadata +167 -0
checksums.yaml
ADDED
@@ -0,0 +1,7 @@
|
|
1
|
+
---
|
2
|
+
SHA1:
|
3
|
+
metadata.gz: d60549a09a7217842eca54663c9ef3c8092e6be5
|
4
|
+
data.tar.gz: 33c48d35d517cb29f10d1d7a0848f7e291f3f488
|
5
|
+
SHA512:
|
6
|
+
metadata.gz: e963ee1c903734bf6da99805a53d529d0ba424a871a55c57eaf228ec454c8af99c2d35e790276e08d6f39905305a649d35aba18eedbc71127ca436f9515a8a40
|
7
|
+
data.tar.gz: 052bd5139e6b48f83705c228b079ea5f5cdf845303599a2b4380013f886ddb48baa3f30fd13e49c2a8de06e7235508c5360f9eb61ff7ad92df6b1b320f419844
|
data/.gitignore
ADDED
data/Gemfile
ADDED
data/LICENSE
ADDED
@@ -0,0 +1,22 @@
|
|
1
|
+
Copyright (c) 2014 Retechnica
|
2
|
+
|
3
|
+
MIT License
|
4
|
+
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining
|
6
|
+
a copy of this software and associated documentation files (the
|
7
|
+
"Software"), to deal in the Software without restriction, including
|
8
|
+
without limitation the rights to use, copy, modify, merge, publish,
|
9
|
+
distribute, sublicense, and/or sell copies of the Software, and to
|
10
|
+
permit persons to whom the Software is furnished to do so, subject to
|
11
|
+
the following conditions:
|
12
|
+
|
13
|
+
The above copyright notice and this permission notice shall be
|
14
|
+
included in all copies or substantial portions of the Software.
|
15
|
+
|
16
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
17
|
+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
18
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
19
|
+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
20
|
+
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
21
|
+
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
22
|
+
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
data/README.md
ADDED
@@ -0,0 +1,379 @@
|
|
1
|
+
# Ingenia Ruby gem
|
2
|
+
A gem to wrap the [Ingenia API](https://www.ingeniapi.com/documentation)
|
3
|
+
|
4
|
+
This readme covers the basics of the Ingenia API, but you can do so many more interesting things by using the examples of the API documentation as a guide.
|
5
|
+
|
6
|
+
|
7
|
+
|
8
|
+
### Installation
|
9
|
+
```sh
|
10
|
+
gem install ingenia_api
|
11
|
+
```
|
12
|
+
|
13
|
+
|
14
|
+
### Configuration
|
15
|
+
|
16
|
+
Before any call is made, first set your ingeniapi API key:
|
17
|
+
|
18
|
+
```ruby
|
19
|
+
Ingenia::Api.api_key = 'YOUR_KEY'
|
20
|
+
```
|
21
|
+
|
22
|
+
Optionally setup the version of the API you wish to use, the default is 2.0
|
23
|
+
```ruby
|
24
|
+
Ingenia::Api.version = 2.0
|
25
|
+
```
|
26
|
+
|
27
|
+
|
28
|
+
## Usage Examples
|
29
|
+
|
30
|
+
###Training
|
31
|
+
To make an API call to show ingenia that some text is known to be associated with some tags. This action also creates an Item.
|
32
|
+
|
33
|
+
```ruby
|
34
|
+
Ingenia::Api.train("I enjoy ice cream", [ 'food', 'ice cream', 'positive' ])
|
35
|
+
```
|
36
|
+
|
37
|
+
**response:**
|
38
|
+
|
39
|
+
```plaintext
|
40
|
+
{
|
41
|
+
"bundle_id":525,
|
42
|
+
"created_at":"2015-06-30T09:10:36Z",
|
43
|
+
"id":"62eb0d5ddef05b9a45ba61c6733dc0b3",
|
44
|
+
"last_classified_at":"2015-06-30T09:10:36Z",
|
45
|
+
"updated_at":"2015-06-30T09:10:36Z",
|
46
|
+
"text":"I enjoy ice cream",
|
47
|
+
"tag_sets":[
|
48
|
+
{
|
49
|
+
"New Tag Set":{
|
50
|
+
"id":1803,
|
51
|
+
"tags":[
|
52
|
+
{
|
53
|
+
"id":175983,
|
54
|
+
"name":"food",
|
55
|
+
"user_selected":"t",
|
56
|
+
"user_assigned":true,
|
57
|
+
"score":"0.0",
|
58
|
+
"machine_score":"0",
|
59
|
+
"rule_score":null,
|
60
|
+
"user_assigned_score":"0"
|
61
|
+
},
|
62
|
+
{
|
63
|
+
"id":175984,
|
64
|
+
"name":"ice cream",
|
65
|
+
"user_selected":"t",
|
66
|
+
"user_assigned":true,
|
67
|
+
"score":"0.0",
|
68
|
+
"machine_score":"0",
|
69
|
+
"rule_score":null,
|
70
|
+
"user_assigned_score":"0"
|
71
|
+
},
|
72
|
+
{
|
73
|
+
"id":175985,
|
74
|
+
"name":"positive",
|
75
|
+
"user_selected":"t",
|
76
|
+
"user_assigned":true,
|
77
|
+
"score":"0.0",
|
78
|
+
"machine_score":"0",
|
79
|
+
"rule_score":null,
|
80
|
+
"user_assigned_score":"0"
|
81
|
+
}
|
82
|
+
]
|
83
|
+
}
|
84
|
+
}
|
85
|
+
]
|
86
|
+
}
|
87
|
+
```
|
88
|
+
|
89
|
+
|
90
|
+
###Training with sets of tags
|
91
|
+
Train ingenia that a text item is associated with tags in different groups, or Tag Sets.
|
92
|
+
|
93
|
+
```ruby
|
94
|
+
Ingenia::Api.train("Is ice cream safe?", { 'Subject' => [ 'food', 'safety' ], 'Category' => [ 'question' ] })
|
95
|
+
```
|
96
|
+
|
97
|
+
**response:**
|
98
|
+
|
99
|
+
```plaintext
|
100
|
+
{
|
101
|
+
"bundle_id":525,
|
102
|
+
"created_at":"2015-06-30T09:16:13Z",
|
103
|
+
"id":"d834435bac0aa8b2d64e6c9fe2a67544",
|
104
|
+
"last_classified_at":"2015-06-30T09:16:13Z",
|
105
|
+
"updated_at":"2015-06-30T09:16:13Z",
|
106
|
+
"text":"Is ice cream safe?",
|
107
|
+
"tag_sets":[
|
108
|
+
{
|
109
|
+
"Subject":{
|
110
|
+
"id":1880,
|
111
|
+
"tags":[
|
112
|
+
{
|
113
|
+
"id":175986,
|
114
|
+
"name":"food",
|
115
|
+
"user_selected":"t",
|
116
|
+
"user_assigned":true,
|
117
|
+
"score":"0.0",
|
118
|
+
"machine_score":"0",
|
119
|
+
"rule_score":null,
|
120
|
+
"user_assigned_score":"0"
|
121
|
+
},
|
122
|
+
{
|
123
|
+
"id":175987,
|
124
|
+
"name":"safety",
|
125
|
+
"user_selected":"t",
|
126
|
+
"user_assigned":true,
|
127
|
+
"score":"0.0",
|
128
|
+
"machine_score":"0",
|
129
|
+
"rule_score":null,
|
130
|
+
"user_assigned_score":"0"
|
131
|
+
}
|
132
|
+
]
|
133
|
+
}
|
134
|
+
},
|
135
|
+
{
|
136
|
+
"Category":{
|
137
|
+
"id":1881,
|
138
|
+
"tags":[
|
139
|
+
{
|
140
|
+
"id":175988,
|
141
|
+
"name":"question",
|
142
|
+
"user_selected":"t",
|
143
|
+
"user_assigned":true,
|
144
|
+
"score":"0.0",
|
145
|
+
"machine_score":"0",
|
146
|
+
"rule_score":null,
|
147
|
+
"user_assigned_score":"0"
|
148
|
+
}
|
149
|
+
]
|
150
|
+
}
|
151
|
+
}
|
152
|
+
]
|
153
|
+
}
|
154
|
+
```
|
155
|
+
|
156
|
+
|
157
|
+
###Classification
|
158
|
+
Ask Ingenia to identify which tags are most relevant to some text. This call does not create an Item.
|
159
|
+
|
160
|
+
Classification will only work once you have done some training and Ingenia has an understanding of your Tags.
|
161
|
+
|
162
|
+
```ruby
|
163
|
+
Ingenia::Api.classify("what is the difference between ruby on rails and rake?")
|
164
|
+
```
|
165
|
+
|
166
|
+
**response:**
|
167
|
+
|
168
|
+
```plaintext
|
169
|
+
{
|
170
|
+
"status": "okay",
|
171
|
+
"api_version": "2.0",
|
172
|
+
"data": {
|
173
|
+
"classification_status": "complete",
|
174
|
+
"text": "what is the difference between ruby on rails and rake?",
|
175
|
+
"results": {
|
176
|
+
"Software": {
|
177
|
+
"tags": [
|
178
|
+
{
|
179
|
+
"machine_score": 1.0,
|
180
|
+
"name": "ruby",
|
181
|
+
"id": 80953,
|
182
|
+
"rule_score": 0,
|
183
|
+
"score": 1.0
|
184
|
+
},
|
185
|
+
{
|
186
|
+
"machine_score": 1.0,
|
187
|
+
"name": "ruby in rails",
|
188
|
+
"id": 80958,
|
189
|
+
"rule_score": 0,
|
190
|
+
"score": 1.0
|
191
|
+
},
|
192
|
+
{
|
193
|
+
"machine_score": 0.6325,
|
194
|
+
"name": "rake",
|
195
|
+
"id": 80951,
|
196
|
+
"rule_score": 0,
|
197
|
+
"score": 0.6325
|
198
|
+
}
|
199
|
+
],
|
200
|
+
"id": "42"
|
201
|
+
}
|
202
|
+
}
|
203
|
+
}
|
204
|
+
}
|
205
|
+
```
|
206
|
+
|
207
|
+
notes:
|
208
|
+
|
209
|
+
- Tag set tags are ordered by score with a maximum of six tags per tag set.
|
210
|
+
- Tag scores are always to 4 decimal places - 1.0 being the strongest affinity and 0.001 the weakest.
|
211
|
+
|
212
|
+
###Similar To
|
213
|
+
Find Items that are similar to a given Item. Specify whether Ingenia should find similar items by their tags or items which have the most similar text.
|
214
|
+
|
215
|
+
```ruby
|
216
|
+
item = Ingenia::Item.create(json: { text: "Ice cream makes a great dessert in Summer", tags: [ 'food', 'dessert'] })
|
217
|
+
Ingenia::Item.similar_to(item['id'], :word)
|
218
|
+
|
219
|
+
```
|
220
|
+
|
221
|
+
**response:**
|
222
|
+
|
223
|
+
```plaintext
|
224
|
+
|
225
|
+
[
|
226
|
+
{"item" => {
|
227
|
+
"id" => "d834435bac0aa8b2d64e6c9fe2a67544",
|
228
|
+
"text" => "Is ice cream safe?"},
|
229
|
+
"mode" => "word",
|
230
|
+
"similarity" => 0.411
|
231
|
+
}
|
232
|
+
]
|
233
|
+
```
|
234
|
+
|
235
|
+
Alternatively, we can also retrieve items which are similar without creating new items with
|
236
|
+
```ruby
|
237
|
+
Ingenia::Api.similar_to(text: "Ice cream makes a great dessert in Summer", mode: 'word')
|
238
|
+
|
239
|
+
```
|
240
|
+
|
241
|
+
|
242
|
+
**response:**
|
243
|
+
|
244
|
+
```plaintext
|
245
|
+
|
246
|
+
"status": "okay",
|
247
|
+
"api_version": "2.0",
|
248
|
+
"data": [
|
249
|
+
{
|
250
|
+
"item": {
|
251
|
+
"id": "ce3330e8-5d4a-492d-b5de-0a5dd6511c7e",
|
252
|
+
"text": "Everyone likes ice cream on their Summer holidays."
|
253
|
+
},
|
254
|
+
"mode": "word",
|
255
|
+
"similarity": 0.673
|
256
|
+
},
|
257
|
+
{
|
258
|
+
"item": {
|
259
|
+
"id": "4290a3e4-6a62-4f5e-900d-0a98ad4f8c22",
|
260
|
+
"text": "The best cakes are decorated with cream."
|
261
|
+
},
|
262
|
+
"mode": "word",
|
263
|
+
"similarity": 0.202
|
264
|
+
}
|
265
|
+
]
|
266
|
+
}
|
267
|
+
```
|
268
|
+
|
269
|
+
|
270
|
+
## Items
|
271
|
+
Items are text items, optionally with tags, that you want to permanently store on Ingenia.
|
272
|
+
|
273
|
+
When you create one Ingenia will return a unique id that lets you keep track of the item - you should store this on your system.
|
274
|
+
|
275
|
+
### Create a plain Item
|
276
|
+
```ruby
|
277
|
+
Ingenia::Item.create(json: { text: "How long do elephants remember?"})
|
278
|
+
```
|
279
|
+
|
280
|
+
### Create an Item with Tags (training)
|
281
|
+
This creats the tags if they do not already exist
|
282
|
+
|
283
|
+
```ruby
|
284
|
+
Ingenia::Item.create(json: { text: "Dolphins Have Longest Memories in Animal Kingdom", tags: ["animals", "memory"]})
|
285
|
+
```
|
286
|
+
|
287
|
+
### Create an Item with Tags in multiple TagSets (training)
|
288
|
+
This creates both the tag set and tags if they dont already exist.
|
289
|
+
|
290
|
+
```ruby
|
291
|
+
Ingenia::Item.create(json: { text: "True or False? Sea Lions Never Forget", tag_sets: { category: ["question"], subject: ["animals", "memory"] } } )
|
292
|
+
```
|
293
|
+
|
294
|
+
|
295
|
+
### Create an Item with Tags by id
|
296
|
+
To create an item with tags by id, you must first have created the tags and have their ids, then pass them as an array.
|
297
|
+
|
298
|
+
```ruby
|
299
|
+
Ingenia::Item.create(json: { text: "The Octopus Can Turbocharge Its Memory", tag_ids: [175994, 175995] } )
|
300
|
+
```
|
301
|
+
|
302
|
+
|
303
|
+
### Item CRUD
|
304
|
+
item = Ingenia::Item.create(json: { text: "How do you make cheese?" })
|
305
|
+
|
306
|
+
# Store the item id
|
307
|
+
id = item['id']
|
308
|
+
|
309
|
+
# update the item
|
310
|
+
item = Ingenia::Item.update(id, json: { text: "How do you eat cheese?"})
|
311
|
+
|
312
|
+
# Get an item, together with it's most recent classifications
|
313
|
+
item = Ingenia::Item.get(id)
|
314
|
+
|
315
|
+
# Remove an item
|
316
|
+
Ingenia::Item.destroy(id)
|
317
|
+
|
318
|
+
|
319
|
+
## Tags
|
320
|
+
Tags, or categories, are meaningful words or expressions that you want to associate with your content.
|
321
|
+
|
322
|
+
### Create a tag
|
323
|
+
```ruby
|
324
|
+
tag = Ingenia::Tag.create(name: "Science", tag_set_id: 1803)
|
325
|
+
```
|
326
|
+
### Tag CRUD
|
327
|
+
tag = Ingenia::Tag.create(name: "Science", tag_set_id: 1803)
|
328
|
+
|
329
|
+
# Store the tag id
|
330
|
+
id = tag['id']
|
331
|
+
|
332
|
+
# update the tag
|
333
|
+
tag = Ingenia::Tag.update(id, name: "Scientific Theory")
|
334
|
+
|
335
|
+
# Get a tag
|
336
|
+
tag = Ingenia::Tag.get(id)
|
337
|
+
|
338
|
+
# Remove a tag
|
339
|
+
Ingenia::Tag.destroy(id)
|
340
|
+
|
341
|
+
|
342
|
+
## Tag Sets
|
343
|
+
Tag sets are thematically consistent groups of tags, such as, say, world countries, business sectors, product types, companies, concepts, topics, etc.
|
344
|
+
Tag Sets are used to groups tags that share a common meaning. For example, tags that relate to the subject of an item ("science", "marketing") could be separated from ones that relate to urgency, sender or document type.
|
345
|
+
|
346
|
+
Each tag must belong to at least one set.
|
347
|
+
|
348
|
+
Classification calls will show tags grouped by their tagsets.
|
349
|
+
|
350
|
+
### Create a TagSet
|
351
|
+
```ruby
|
352
|
+
Ingenia::TagSet.create(name: "Topic")
|
353
|
+
```
|
354
|
+
|
355
|
+
### TagSet CRUD
|
356
|
+
tagset = Ingenia::TagSet.create(name: "Urgency")
|
357
|
+
|
358
|
+
# Store the tagset id
|
359
|
+
id = tagset['id']
|
360
|
+
|
361
|
+
# update the tagset
|
362
|
+
tagset = Ingenia::TagSet.update(id, name: "Sender Type")
|
363
|
+
|
364
|
+
# Get a tagset
|
365
|
+
tagset = Ingenia::TagSet.get(id)
|
366
|
+
|
367
|
+
# Remove a tagset
|
368
|
+
Ingenia::TagSet.destroy(id)
|
369
|
+
|
370
|
+
|
371
|
+
## More Information
|
372
|
+
|
373
|
+
See http://ingeniapi.com/reference for more details of the API.
|
374
|
+
|
375
|
+
|
376
|
+
|
377
|
+
## License
|
378
|
+
|
379
|
+
© 2015 Retechnica
|
data/Rakefile
ADDED
data/examples/bundles.rb
ADDED
@@ -0,0 +1,74 @@
|
|
1
|
+
require './helper'
|
2
|
+
|
3
|
+
##
|
4
|
+
# Run a full set of API calls on bundles
|
5
|
+
##
|
6
|
+
|
7
|
+
|
8
|
+
#
|
9
|
+
# Setup
|
10
|
+
#
|
11
|
+
# Set API key to the test user for this gem
|
12
|
+
require 'ingenia_api'
|
13
|
+
Ingenia::Api.api_key = "API_KEY"
|
14
|
+
|
15
|
+
##
|
16
|
+
# Create
|
17
|
+
#
|
18
|
+
example "Create" do
|
19
|
+
# Create a new bundle
|
20
|
+
@new_bundle = Ingenia::Bundle.create(:name => "new bundle")
|
21
|
+
puts "\n created a new bundle:"
|
22
|
+
puts "#{@new_bundle}".green
|
23
|
+
end
|
24
|
+
|
25
|
+
|
26
|
+
##
|
27
|
+
# Index
|
28
|
+
#
|
29
|
+
example "Index" do
|
30
|
+
# Get a list of all your bundles
|
31
|
+
bundles = Ingenia::Bundle.all
|
32
|
+
puts "got #{bundles.length} bundles".green
|
33
|
+
|
34
|
+
# Get the first bundle
|
35
|
+
@test_bundle = bundles.first
|
36
|
+
|
37
|
+
puts "\n First Bundle: ".green
|
38
|
+
puts "#{@test_bundle}".green
|
39
|
+
|
40
|
+
@test_bundle_id = @test_bundle['id']
|
41
|
+
@test_bundle_name = @test_bundle['name']
|
42
|
+
end
|
43
|
+
|
44
|
+
|
45
|
+
##
|
46
|
+
# Show
|
47
|
+
#
|
48
|
+
example "Show" do
|
49
|
+
# Get the updated bundle, including it's text
|
50
|
+
@test_bundle = Ingenia::Bundle.get(@test_bundle_id)
|
51
|
+
puts "\n updated bundle:"
|
52
|
+
puts "#{@test_bundle}".green
|
53
|
+
end
|
54
|
+
|
55
|
+
|
56
|
+
##
|
57
|
+
# Update
|
58
|
+
#
|
59
|
+
example "Update" do
|
60
|
+
# Update its text
|
61
|
+
response = Ingenia::Bundle.update(@test_bundle_id, :name => "updated bundle name new" )
|
62
|
+
puts "#{response}".green
|
63
|
+
end
|
64
|
+
|
65
|
+
|
66
|
+
##
|
67
|
+
# Destroy
|
68
|
+
#
|
69
|
+
example "Destroy" do
|
70
|
+
# Remove this new bundle
|
71
|
+
response = Ingenia::Bundle.destroy(@new_bundle['id'])
|
72
|
+
puts "#{response}".green
|
73
|
+
end
|
74
|
+
|