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.
@@ -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
@@ -0,0 +1,6 @@
1
+ Gemfile.lock
2
+ *.gem
3
+ pkg/
4
+ vendor/
5
+ .idea/
6
+ .bundle/
data/Gemfile ADDED
@@ -0,0 +1,3 @@
1
+ source "https://rubygems.org"
2
+
3
+ gemspec
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.
@@ -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
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env rake
2
+ require "bundler/gem_tasks"
@@ -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
+