Initial issue doc

docs/how-to/how-to-run-examples.md

@@ -0,0 +1,154 @@
+# How to run the examples
+
+## How to generate the example files
+
+In order to use the examples provided in `OpenAIExamples`,
+you'll need to have some examples files available locally.
+
+To create all required files you can execute:
+
+```smalltalk
+OpenAIExamples new generateExampleFiles
+```
+
+This will create, inside the *open-ai* directory:
+
+- answers-example.jsonl
+- classifications-example.jsonl
+- file-that-will-be-deleted.jsonl
+- fine-tune-example.jsonl
+- search-example.jsonl
+
+## How to configure your API key
+
+Before running the examples, you must provide a valid API key.
+
+1. [Sign up](https://beta.openai.com/signup) for an OpenAI account.
+
+2. Go to your
+[API keys](
+https://beta.openai.com/account/api-keys
+)
+and click on the *Create new secret key* button.
+
+3. Click on the *Copy* link next to your recently created key.
+
+4. Create a file named *apikey.secret* in the *open-ai* directory.
+
+5. Paste the copied key into the file, then save it.
+
+## How to invoke the APIs with the examples
+
+Several examples are provided which show a possible use case for the diferent APIs.
+
+The example methods return an object that extracts the relevant answer
+from  the full API respose.
+This is intended for the examples to illustrate how to navigate the structure
+of the responses of the different APIs wrapped.
+
+### Files API
+
+Examples using the [Files API](https://beta.openai.com/docs/api-reference/files)
+
+OpenAI offers by default 1 GB storage *per organization*.
+For individual users this means 1 GB as well.
+There is no cost associated with managing files.
+This means that running the examples in this section will not reduce
+your free balance.
+
+Files are uploaded asynchronously.
+Uploading returns a *File ID* than can be used later to check the file status.
+You can't use a file until it's status is **processed**.
+
+All uploads in the examples will wait up to 20 seconds, polling every second,
+until the upload is complete.
+
+The uploading method in the examples `OpenAIExamples>>#idForFileNamed:intendedFor:`
+checks whether a file with the same name was already uploaded.
+If it's already there, it does not re-upload it.
+Since OpenAI allows multiple files with the same name,
+failing to check first would result in an ever increasing use of your storage.
+
+Running `OpenAIExamples new files` will list the files currently registered.
+In case you have not yet made any upload, the example will upload `open-ai/fine-tune-example.jsonl`.
+
+Running `OpenAIExamples new downloadAndRemoveFile` will upload `open-ai/file-that-will-be-deleted.jsonl`.
+After uploading is complete, the file will be deleted.
+This is just meant to show the steps to both upload and delete a file.
+
+Running `OpenAIExamples new deleteAllFiles` will **delete all files**
+declared to your OpenAI account.
+**Always use this example with caution**.
+
+### Answers API
+
+Examples using the [Answers API](https://beta.openai.com/docs/api-reference/answers)
+
+Running `OpenAIExamples new answers` will ask *where is France?'*
+using as context the information `France is in Europe` and
+`Canada is in America` and `Japan is in Asia`.
+To explain to OpenAI how to extract information from context,
+it will provide the example that given the context `this car is 2 meters long`
+and the question `how long is this car` the answer should be `2 meters`.
+This use case does not employ the Files API, all processing is done in the moment.
+
+Running `OpenAIExamples new answersFromFile` will do the same,
+ but the context is provided by the file `answers-example.jsonl`.
+The file is uploaded, and then the question is asked to OpenAI.
+
+### Search API
+
+Examples using the [Search API](https://beta.openai.com/docs/api-reference/searches)
+
+Running `OpenAIExamples new search` will try to find `bulldog` in the list  
+`cat dog car building vehicle person`.
+The result is the list ordered by how closely they match the query.
+
+Running `OpenAIExamples new searchFromFile` will first upload the file `search-example.jsonl`,
+then present the query `the dog feels happy in a building where some person lives`.
+The result is the list of *documents* listed in the file sorted by
+relevance to the query.
+
+### Completions API
+
+Examples using the [Completions API](https://beta.openai.com/docs/api-reference/completions)
+
+Running `OpenAIExamples new completions` will ask for the next word
+after the sequence `This is the day`.
+Note that you can easily ask for more words by changing
+the collaborator sent to `changeMaximumNumberOfTokensTo:`.
+Keep in mind that this will increase the cost of each run of the example
+since more *tokens* will be generated.
+
+The completions API benefits from using the more complex (and expensive) OpenAI engines.
+To try them out in the example, add:
+
+```smalltalk
+apiClient changeEngineTo: 'davinci'.
+```
+
+If you do this, it is also a good idea to increase the numbers of tokens
+as explained before.
+
+Remember that the DaVinci engine is **75 times more expensive**
+than the default Ada engine.
+
+### Classifications API
+
+Examples using the [Classifications API](https://beta.openai.com/docs/api-reference/classifications)
+
+Running `OpenAIExamples new classifications` will ask OpenAI to classify
+the sentence `the weather is great` as either `happy` OR `sad`,
+considering the samples `the grass is green` is `happy`,
+`the sky is pretty` is `happy` and `the soil is rotten` is `sad`.
+
+Running `OpenAIExamples new classificationsFromFile` will upload the examples
+in the file `classifications-example.jsonl`,
+then ask to classify the sentence `movie is very good`
+as either `Positive` or `Negative`.
+
+Running `OpenAIExamples new classificationsFromFileWithoutLabels` will also
+upload the file and present the query `movie is very good`.
+Only this time no classification options are provided.
+OpenAI is free to choose how to classify the sentence,
+based on its pre-training in interpreting text.

docs/reference/Answers API.md

@@ -0,0 +1,81 @@
+# Answers API
+
+Offers access to the [features mentioned here](https://beta.openai.com/docs/api-reference/answers).
+
+The API can be accessed using the class `AnswersAPIClient`.
+
+## Instance Creation
+
+To create a Files API client, you need a *RESTful API Client*
+and an *OpenAI API key*.
+
+You can obtain a *RESTful API Client* by evaluating: `RESTfulAPIClient cachingOnLocalMemory`.
+
+You should be able to obtain an API Key by following the [steps mentioned here](../how-to/how-to-run-examples.md).
+Afterwards you can access the key by sending
+`'open-ai/apikey.secret' asFileReference contents`.
+
+So to create the Answers API Client you can evaluate:
+
+```smalltalk
+| restfulClient apiKey answersAPIClient |
+
+restfulClient := RESTfulAPIClient cachingOnLocalMemory.
+apiKey := 'open-ai/apikey.secret' asFileReference contents.
+
+answersAPIClient := AnswersAPIClient
+                     accessingAPIsWith: restfulClient
+                     authenticatedWith: apiKey
+```
+
+## Public protocol
+
+### answer: *question* against: *documents* given: *examples* within: *context*
+
+Executes a POST call to obtain the answer to the question indicated.
+A collection of strings is used as the document list,
+where the information will be looked up.
+Aditionally you must provide a question-answer example,
+along with a context that contains the document
+that would have been relevant to answer the example.
+
+As specified [here](https://beta.openai.com/docs/api-reference/answers/create),
+the response will include an *anwsers* element which will contain
+the possible answers to the question.
+
+As an example, suppose you want to present the Answers API
+with the query `where is France?`.
+
+You need to provide several documents that might contain the answer.
+The example will provide 3 sentences:
+`France is in Europe` and `Canada is in America` and `Japan is in Asia`.
+
+Also an example must be chosen,
+with a logic similar to the one you are expecting the API to apply.
+
+You can tell the API that given the document
+`this car is 2 meters long` and the question
+`how long is this car?` the answer is `2 meters`.
+
+The above example with be written as follows:
+
+```smalltalk
+answersAPIClient answer: 'where is France?'
+                 against: #('France is in Europe'
+                            'Canada is in America'
+                            'Japan is in Asia' )
+                 given: ( Array with: #( 'how long is this car?' '2 meters' ) )
+                 within: 'this car is 2 meters long'.
+```
+
+### changeSearchEngineTo: *engine id*
+
+The *model* and *search moodel* are separate parameters in the API.
+The wrapper defaults to **Ada** for both
+to minimize the default cost of using the API client.
+
+### changeEngineTo: *engine id*
+
+The *model* and *search moodel* are separate parameters in the API.
+The wrapper defaults to **Ada** for both
+to minimize the default cost of using the API client.

docs/reference/Files API.md

@@ -0,0 +1,102 @@
+# Files API
+
+Offers access to the [features mentioned here](https://beta.openai.com/docs/api-reference/files).
+
+The API can be accessed using the class `FilesAPIClient`.
+
+## Instance Creation
+
+To create a Files API client, you need a *RESTful API Client*
+and an *OpenAI API key*.
+
+You can obtain a *RESTful API Client* by evaluating: `RESTfulAPIClient cachingOnLocalMemory`.
+
+You should be able to obtain an API Key by following the [steps mentioned here](../how-to/how-to-run-examples.md).
+Afterwards you can access the key by sending
+`'open-ai/apikey.secret' asFileReference contents`.
+
+So to create the Files API Client you can evaluate:
+
+```smalltalk
+| restfulClient apiKey filesAPIClient |
+
+restfulClient := RESTfulAPIClient cachingOnLocalMemory.
+apiKey := 'open-ai/apikey.secret' asFileReference contents.
+
+filesAPIClient := FilesAPIClient
+                     accessingAPIsWith: restfulClient
+                     authenticatedWith: apiKey
+```
+
+## Public protocol
+
+### listFiles
+
+Executes a GET call to obtain the list of all files currently uploaded
+to your OpenAI account.
+
+As specified [here](https://beta.openai.com/docs/api-reference/files/list),
+the response will contain a *data* element with a list of files,
+where each includes information such as
+id, name, size, creation stamp and purpose.
+
+To use it, just evaluate:
+
+```smalltalk
+filesAPIClient listFiles
+```
+
+### idForProcessed: *file reference* intendedFor: *purpose* waiting: *time*
+
+Executes a POST call to upload a file. This requires,
+apart from the reference to the desired file,
+a **purpose** that OpenAI requires to know beforehand,
+to confirm the format is correct for the intended API use.
+The method also asks for a maximum time to wait for the file to be processed.
+
+As specified [here](https://beta.openai.com/docs/api-reference/files/upload),
+the response will contain information such as
+id, name, size, creation stamp and purpose.
+The *id* is obtained and used as the method return.
+
+An undocumented (so far) feature of OpenAI is that when querying for a specific file,
+a *status* is returned.
+Unless the status is listed as **processed**,
+the file can't be used in the other APIs.
+
+This method will poll the status every second up to the maximum specified.
+In case the status is not processed,
+it will raise an Exception to let the user know.
+This does not mean that OpenAI won't eventually have the file ready for use,
+only that it was not so in the time period indicated.
+
+An example using this method, in case you want to upload the file at `open-ai/answers-example.jsonl`,
+to be later used with the answers API,
+implies evaluating:
+
+```smalltalk
+apiClient
+    idForProcessed: 'open-ai/answers-example.jsonl' asFileReference
+    intendedFor: 'answers'
+    waiting: 4 seconds
+```
+
+### retrieveFileIdentifiedBy: *file id*
+
+Executes a DELETE request, to remove from your storage
+the file with the *id* indicated.
+
+You can obtain the *id* but either keeping the returned value of an upload,
+or by checking the *id* attribute when listing your files
+using the `listFiles` method.
+
+As specified [here](https://beta.openai.com/docs/api-reference/files/delete),
+the response will include an attribute *deleted*,
+which will be *true* as long as the deletion could be completed.
+
+As an example, if you have a file which returned the id `file-XjGxS3KTG0uNmNOK362iJua3`,
+you would delete it by evaluating:
+
+```smalltalk
+apiClient retrieveFileIdentifiedBy: 'file-XjGxS3KTG0uNmNOK362iJua3'
+```