DOC-927 Add ollama_moderation processor (#150)

Author: asimms41

modules/ROOT/nav.adoc

@@ -159,6 +159,7 @@
 *** xref:components:processors/noop.adoc[]
 *** xref:components:processors/ollama_chat.adoc[]
 *** xref:components:processors/ollama_embeddings.adoc[]
+*** xref:components:processors/ollama_moderation.adoc[]
 *** xref:components:processors/openai_chat_completion.adoc[]
 *** xref:components:processors/openai_embeddings.adoc[]
 *** xref:components:processors/openai_image_generation.adoc[]

modules/components/pages/processors/ollama_chat.adoc

@@ -484,6 +484,32 @@ output:
   stdout: {}
 ```
 --
+Check prompts for unsafe content::
++
+--
+This configuration runs prompts through the https://ollama.com/library/llama-guard3[Llama Guard 3 model^] to check they comply with https://mlcommons.org/2024/04/mlc-aisafety-v0-5-poc/[safety and security standards^]. The model marks the prompts that do not comply as `unsafe`, and the Bloblang mapping deletes them. To check the safety of responses, see the xref:components:processors/ollama_moderation.adoc[`ollama_moderation` processor].
+
+```yaml
+pipeline:
+  processors:
+    - branch:
+        processors:
+          - ollama_chat:
+              model: llama-guard3
+              prompt: ${!this.prompt}
+        result_map: |
+          root.safety = content()
+    # Drop the message from the pipeline if it's unsafe
+    - mapping: |
+        root = if this.safety.has_prefix("unsafe") {
+          deleted()
+        }
+      # The input prompt has been checked for safety.
+    - ollama_chat:
+        model: llama3.2
+        prompt: ${!this.prompt}
+```
+--
 =====
 
 // end::single-source[]

modules/components/pages/processors/ollama_moderation.adoc

@@ -0,0 +1,243 @@
+= ollama_moderation
+// tag::single-source[]
+:type: processor
+:page-beta: true
+:categories: ["AI"]
+
+component_type_dropdown::[]
+
+include::components:partial$ollama_warning.adoc[]
+
+Generates responses to messages in a chat conversation using the Ollama API, and checks the responses to make sure they do not violate https://mlcommons.org/2024/04/mlc-aisafety-v0-5-poc/[safety or security standards^].
+
+ifndef::env-cloud[]
+Introduced in version 4.45.0.
+endif::[]
+
+[tabs]
+======
+Common::
++
+--
+
+```yml
+# Common configuration fields, showing default values
+label: ""
+ollama_moderation:
+  model: llama-guard3 # No default (required)
+  prompt: "" # No default (required)
+  response: "" # No default (required)
+  runner:
+    context_size: 0 # No default (optional)
+    batch_size: 0 # No default (optional)
+  server_address: http://127.0.0.1:11434 # No default (optional)
+```
+
+--
+Advanced::
++
+--
+
+```yml
+# All configuration fields, showing default values
+label: ""
+ollama_moderation:
+  model: llama-guard3 # No default (required)
+  prompt: "" # No default (required)
+  response: "" # No default (required)
+  runner:
+    context_size: 0 # No default (optional)
+    batch_size: 0 # No default (optional)
+    gpu_layers: 0 # No default (optional)
+    threads: 0 # No default (optional)
+    use_mmap: false # No default (optional)
+    use_mlock: false # No default (optional)
+  server_address: http://127.0.0.1:11434 # No default (optional)
+  cache_directory: /opt/cache/connect/ollama # No default (optional)
+  download_url: "" # No default (optional)
+```
+
+--
+======
+
+This processor checks the safety of responses from your chosen large language model (LLM) using either https://ollama.com/library/llama-guard3[Llama Guard 3^] or https://ollama.com/library/shieldgemma[ShieldGemma^]. 
+
+By default, the processor starts and runs a locally-installed Ollama server. Alternatively, to use an already running Ollama server, add your server details to the `server_address` field. You can https://ollama.com/download[download and install Ollama from the Ollama website^].
+
+For more information, see the https://github.com/ollama/ollama/tree/main/docs[Ollama documentation^] and <<Examples, Examples>>.
+
+To check the safety of your prompts, see the xref:components:processors/ollama_chat.adoc#examples[`ollama_chat` processor] documentation.
+
+
+== Fields
+
+=== `model`
+
+The name of the Ollama LLM to use.
+
+*Type*: `string`
+
+Options:
+
+|===
+| Option | Description
+| `llama-guard3`
+a| The Llama Guard 3 model writes the following metadata to each processed message:
+
+* The `@safe` field: If the message content is unsafe, the value is set to either `yes`. Otherwise, it's set to `no`.
+* The `@category` field: When the `@safe` field is set to `yes`, this field returns the category of safety violation. 
+
+For more information, see the https://ollama.com/library/llama-guard3[Llama Guard 3 model description^].
+| `shieldgemma`
+| The ShieldGemma model writes an `@safe` metadata field to each processed message, with the value of `yes` if the message content is unsafe or `no` if it's not. 
+
+For more information, see the https://ollama.com/library/shieldgemma[ShieldGemma model description^].
+
+|===
+
+```yml
+# Examples
+
+model: llama-guard3
+
+model: shieldgemma
+```
+
+=== `prompt`
+
+The prompt you used to generate a response from an LLM.
+
+If you're using the `ollama_chat` processor, you can set the `save_prompt_metadata` field to save the contents of your prompts. You can then run them through `ollama_moderation` processor to check the model responses for safety. For more details, see <<Examples, Examples>>.
+
+You can also check the safety of your prompts. For more information, see the xref:components:processors/ollama_chat.adoc#examples[`ollama_chat` processor] documentation.
+
+This field supports xref:configuration:interpolation.adoc#bloblang-queries[interpolation functions].
+
+*Type*: `string`
+
+
+=== `response`
+
+The LLM's response that you want to check for safety.
+
+This field supports xref:configuration:interpolation.adoc#bloblang-queries[interpolation functions].
+
+*Type*: `string`
+
+
+=== `runner`
+
+Options for the model runner that are used when the model is first loaded into memory.
+
+
+*Type*: `object`
+
+
+=== `runner.context_size`
+
+Sets the size of the context window used to generate the next token. Using a larger context window uses more memory and takes longer to process.
+
+
+*Type*: `int`
+
+
+=== `runner.batch_size`
+
+The maximum number of requests to process in parallel.
+
+
+*Type*: `int`
+
+
+=== `runner.gpu_layers`
+
+Sets the number of layers to offload to the GPU for computation. This generally results in increased performance. By default, the runtime decides the number of layers dynamically.
+
+
+*Type*: `int`
+
+
+=== `runner.threads`
+
+Sets the number of threads to use during response generation. For optimal performance, set this value to the number of physical CPU cores your system has. By default, the runtime decides the optimal number of threads.
+
+
+*Type*: `int`
+
+
+=== `runner.use_mmap`
+
+Map the model into memory. Set to `true` to load only the necessary parts of the model into memory. This setting is only supported on Unix systems.
+
+
+*Type*: `bool`
+
+
+=== `runner.use_mlock`
+
+Set to `true` to lock the model in memory, preventing it from being swapped out when it's mapped into memory. This option can improve performance but reduces the benefits of memory-mapping by increasing RAM usage and slowing model load times.
+
+*Type*: `bool`
+
+
+=== `server_address`
+
+The address of the Ollama server to use. Leave this field blank and the processor starts and runs a local Ollama server, or specify the address of your own local or remote server.
+
+
+*Type*: `string`
+
+
+```yml
+# Examples
+
+server_address: http://127.0.0.1:11434
+```
+
+=== `cache_directory`
+
+If the `server_address` is not set, download the Ollama binary to this directory and use it as a model cache.
+
+*Type*: `string`
+
+
+```yml
+# Examples
+
+cache_directory: /opt/cache/connect/ollama
+```
+
+=== `download_url`
+
+If `server_address` is not set, download the Ollama binary from this URL. The default value is the official Ollama GitHub release for this platform.
+
+*Type*: `string`
+
+== Examples
+
+This example uses Llama Guard 3 to check if another model (LLaVA) responded with a safe or unsafe content.
+
+```yaml
+input:
+  stdin:
+    scanner:
+      lines: {}
+pipeline:
+  processors:
+    - ollama_chat:
+        model: llava
+        prompt: "${!content().string()}"
+        save_prompt_metadata: true
+    - ollama_moderation:
+        model: llama-guard3
+        prompt: "${!@prompt}"
+        response: "${!content().string()}"
+    - mapping: |
+        root.response = content().string()
+        root.is_safe = @safe
+output:
+  stdout:
+    codec: lines
+```
+
+// end::single-source[]