Merge pull request #35 from JBGruber/ReadMe

Author: textspur

README.Rmd

@@ -37,7 +37,7 @@ You can install this package from CRAN:
 install.packages("rollama")
 ```
 
-Or you can install the development version  of `rollama` from [GitHub](https://github.com/JBGruber/rollama) with:
+Or you can install the development version  of `rollama` from [GitHub](https://github.com/JBGruber/rollama). This version is updated more frequently and may contain bug fixes (or new bugs):
 
 ``` r
 # install.packages("remotes")
@@ -56,13 +56,11 @@ rollama::ping_ollama()
 
 ### Installation of Ollama through Docker
 
-The advantage of running things through Docker is that the application is isolated from the rest of your system, behaves the same on different systems, and is easy to download and update.
+For beginners we recommend to download Ollama from [their website](https://ollama.com/). However, if you are familiar with Docker, you can also run Ollama through Docker. The advantage of running things through Docker is that the application is isolated from the rest of your system, behaves the same on different systems, and is easy to download and update.
 You can also get a nice web interface.
 After making sure  [Docker](https://docs.docker.com/desktop/) is installed, you can simply use the Docker Compose file from [this gist](https://gist.github.com/JBGruber/73f9f49f833c6171b8607b976abc0ddc).
 
-If you don’t know how to use Docker Compose, you can follow this video to use the compose file and start Ollama and Open WebUI:
-
-[![Install Docker on macOS, Windows and Linux](https://img.youtube.com/vi/iMyCdd5nP5U/0.jpg)](https://www.youtube.com/watch?v=iMyCdd5nP5U)
+If you don’t know how to use Docker Compose, you can follow this [video](https://www.youtube.com/watch?v=iMyCdd5nP5U) to use the compose file and start Ollama and Open WebUI.
 
 ## Example
 
@@ -81,15 +79,22 @@ You can make single requests, which does not store any history and treats each q
 
 ```{r query}
 # ask a single question
-query("why is the sky blue?")
+query("Why is the sky blue? Answer with one sentence.")
+```
+
+With the output argument, we can specify the format of the response. Available options include "text", "list", "data.frame", "response", "httr2_response", and "httr2_request":
+
+```{r output}
+# ask a single question and specify the output format
+query("Why is the sky blue? Answer with one sentence." , output = "text")
 ```
 
 Or you can use the `chat` function, treats all messages sent during an R session as part of the same conversation:
 
 ```{r chat}
 # hold a conversation
-chat("why is the sky blue?")
-chat("and how do you know that?")
+chat("Why is the sky blue? Give a short answer.")
+chat("And how do you know that? Give a short answer.")
 ```
 
 If you are done with a conversation and want to start a new one, you can do that like so:
@@ -103,11 +108,11 @@ new_chat()
 You can set a number of model parameters, either by creating a new model, with a [modelfile](https://jbgruber.github.io/rollama/reference/create_model.html), or by including the parameters in the prompt:
 
 ```{r}
-query("why is the sky blue?", model_params = list(
-  seed = 42,
-  temperature = 0,
-  num_gpu = 0
-))
+query("Why is the sky blue? Answer with one sentence.", output = "text",
+      model_params = list(
+        seed = 42,
+        num_gpu = 0)
+      )
 ```
 
 ```{r include=FALSE, results='asis'}
@@ -131,17 +136,63 @@ options(rollama_server = "http://localhost:11434")
 You can change how a model answers by setting a configuration or system message in plain English (or another language supported by the model):
 
 ```{r config}
-options(rollama_config = "You make answers understandable to a 5 year old")
-query("why is the sky blue?")
+options(rollama_config = "You make short answers understandable to a 5 year old")
+query("Why is the sky blue?")
 ```
 
 By default, the package uses the "llama3.1 8B" model. Supported models can be found at <https://ollama.com/library>.
-To download a specific model make use of the additional information available in "Tags" <https://ollama.com/library/mistral/tags>.
+To download a specific model make use of the additional information available in "Tags" <https://ollama.com/library/llama3.2/tags>.
 Change this via `rollama_model`:
 
 ```{r model}
-options(rollama_model = "mixtral")
-# if you don't have the model yet: pull_model("mixtral")
-query("why is the sky blue?")
+options(rollama_model = "llama3.2:3b-instruct-q4_1")
+# if you don't have the model yet: pull_model("llama3.2:3b-instruct-q4_1")
+query("Why is the sky blue? Answer with one sentence.")
+```
+
+## Easy query generation
+
+The `make_query` function simplifies the creation of structured queries, which can, for example, be used in [annotation tasks](https://jbgruber.github.io/rollama/articles/annotation.html#the-make_query-helper-function).
+
+Main components (check the [documentation](https://jbgruber.github.io/rollama/articles/annotation.html#the-make_query-helper-function) for more options):
+
+- **`text`**: The text(s) to classify.
+- **`prompt`**: Could be a (classification) question
+- **`system`**: Optional system prompt providing context or instructions for the task.
+- **`examples`**: Optional prior examples for one-shot or few-shot learning (user messages and assistant responses).
+
+
+**Zero-shot Example**  
+In this example, the function is used without examples:
+
+```{r make_query}
+# Create a query using make_query
+q_zs <- make_query(
+  text = "the pizza tastes terrible",
+  prompt = "Is this text: 'positive', 'neutral', or 'negative'?",
+  system = "You assign texts into categories. Answer with just the correct category."
+)
+# Print the query
+print(q_zs)
+# Run the query
+query(q_zs, output = "text")
+
 ```
 
+## Learn more
+
+- [Use rollama for annotation tasks](https://jbgruber.github.io/rollama/articles/annotation.html)
+- [Annotate images](https://jbgruber.github.io/rollama/articles/image-annotation.html)
+- [Get text embedding](https://jbgruber.github.io/rollama/articles/text-embedding.html)
+- [Use more models (GGUF format) from Hugging Face](https://jbgruber.github.io/rollama/articles/hf-gguf.html)
+
+
+## Citation
+
+Please cite the package using the [pre print](https://arxiv.org/abs/2404.07654) DOI:  <https://doi.org/10.48550/arXiv.2404.07654> 
+
+
+
+
+
+