update readme and docs

README.md

@@ -11,7 +11,7 @@ These connectors can automatically perform activities that previously required u
 * ⚖  Informed **decision-making** before gateways
 * ✍🏼 Creative **content generation** (emails, letters, ...)
 * 🌍 **Translation**
-* 📄 **Answering questions** over documents, wikis and other unstructured knowledge
+* 📄 **Answering questions** over documents, wikis and other unstructured knowledge-bases
 * 🗄 Querying **SQL Databases**
 * 🌐 Interacting with **REST APIs**
 * ...and more
@@ -29,13 +29,7 @@ Just provide input and output variable mappings and configure what you want to a
 
 ## 🚀 How to Run Using Docker
 
-Clone the `connector-secrets.txt.sample` template file:
-
-```bash
-cp connector-secrets.txt.sample connector-secrets.txt
-```
-
-In the newly created file, fill in your OpenAI API key and Zeebe cluster information for either Cloud or a local cluster:
+Create a `connector-secrets.txt` file (use `connector-secrets.txt.sample` as a template) and fill in your OpenAI API key and Zeebe cluster information for either Cloud or a local cluster:
 
 ```bash
 OPENAI_API_KEY=<put your key here>
@@ -61,10 +55,10 @@ docker compose -f docker-compose.camunda-platform.yml up -d
 
 ### ▶️ Run connectors
 
-Build and start the connector runtime:
+Run the connector runtime using a pre-built image from DockerHub:
 
 ```bash 
-docker compose up -d
+docker run --env-file connector-secrets.txt holisticon/camunda-8-connector-gpt:develop
 ```
 
 ## 📚 Connectors Documentation

connector-secrets.txt.sample

@@ -30,3 +30,9 @@ OPENAI_API_KEY=<put your key here>
 #ZEEBE_CLIENT_BROKER_GATEWAY-ADDRESS=localhost:26500
 #CAMUNDA_OPERATE_CLIENT_URL=localhost:8080
 #ZEEBE_CLIENT_SECURITY_PLAINTEXT=true
+
+
+CAMUNDA_CONNECTOR_POLLING_ENABLED=false
+CAMUNDA_CONNECTOR_WEBHOOK_ENABLED=false
+SPRING_MAIN_WEB-APPLICATION-TYPE=none
+OPERATE_CLIENT_ENABLED=false

docker-compose.yml

@@ -4,8 +4,7 @@ services:
 
   gpt-connectors:
     container_name: camunda-8-gpt-connectors
-    build:
-      dockerfile: Dockerfile
+    image: holisticon/camunda-8-connector-gpt:develop
     networks:
       - connector-network
     env_file: ./connector-secrets.txt

docs/foundational-connectors.md

@@ -1,37 +1,100 @@
 # Foundational Connectors
 
+* [🔍 Extract Connector](#-extract-connector)
+* [⚖ Decide Connector](#-decide-connector)
+* [✍🏼 Compose Connector](#-compose-connector)
+* [🌍 Translate Connector](#-translate-connector)
+* [🪄 Generic Connector](#-generic-connector)
+
 ## 🔍 Extract Connector
 
-Can extract or deduce information from multiple input variables, potentially do simple conversions along the way, and store the result in one or more output variables.
+Extracts information from structured or unstructured data in multiple input variables, potentially doing simple conversions along the way, and stores the result in one or more output variables.
 
 ### Configuration
 
-Provide a map of new variables to extract from the input, with descriptions of what they should contain:
+Provide a JSON object schema of the structure to extract from the input, with descriptions of what they should contain:
+```
+{
+  product: {
+      description: "The name of the product",
+      type: "string"
+  },
+  price: {
+      description: "The price of the product",
+      type: "number"
+  },
+  tags: {
+      description: "Tags for the product",
+      type: "array",
+      items: {
+        type: "string",
+        description: "A product tag",
+        enum: ["A", "B", "C"]
+      }
+    }
+}
+```
+
+The following types are supported:
+* string
+* integer
+* number
+* boolean
+* object
+* array
+
+You should always provide a **speaking name and description** and be aware that both are essentially part of the prompt engineering and determine how well the information is extracted.
+
+As seen above, you can provide an enum array if all possible values are known.
+
+Since extracting string values is very common, there is a shorthand:
+
 ```
 {
   firstname: "first name",
-  lastname: "last name",
-  language: "the language that the email body is written in, as ISO code"
+  lastname: "last name"
 }
 ```
 
+This is equivalent to:
+
+```
+{
+  firstname: {
+      description: "first name",
+      type: "string"
+  },
+  lastname: {
+      description: "last name",
+      type: "string"
+  }
+}
+```
+
+#### Extract a list of entities
+
+Select Extraction Mode `Multiple Entities` to extract a list of multiple entity objects, each conforming to the configured schema.
+You can provide an optional description for the entities to extract. 
+
+The result will be a list of objects or an empty list.
+
 ### Result
 A temporary variable `result` that contains a result JSON object of the same form as configured above. Can be mapped to one or more process variables using the result expression.
 
 ---
 
 ## ⚖ Decide Connector
 
-Can make decisions based on multiple input variables and store the result decision and the reasoning behind it in output variables.
+Makes decisions based on multiple input variables and stores the result decision and the reasoning behind it in output variables.
 
 ### Configuration
 
 Provide a natural language description of what the connector should decide, e.g.:
 ```
 Decide what the intention of the customer's mail is.
 ```
-Next, determine an output type (`Boolean`, `Integer` or `String`).
-If not `Boolean`, you may restrict the connector to a classification on a finite set of options, instead of letting it freely choose the values:
+Next, select the Output Type (`Boolean`, `Integer` or `String`).
+If not `Boolean`, you may restrict the connector to a classification on a finite set of options, instead of letting it freely choose the result value:
 ```
 [
   "CANCEL_SUBSCRIPTION",
@@ -48,20 +111,61 @@ A temporary variable `result` that contains a result JSON object with a field `d
 
 ## ✍🏼 Compose Connector
 
-Can compose text like e-mails or letters based on multiple input variables and store the result text in an output variable.
+Composes texts for emails, letters, chat messages, or social media posts based on multiple input variables and stores the result text in an output variable.
 
 ### Configuration
+#### General Properties
+Configure a desired text type, style, tone, language, and length for the text.
+
+#### Variance
+
+Select a Variance value (controls model temperature). `None` will make the output mostly deterministic and more focused. 
+The higher the variance, the more diverse and unpredictable the text becomes. A higher value is a good fit for creating creative content that should change on every run. Select `None` if you want to be as precise as possible and don't need diverse outputs.
+
+#### Template
+
+Select `No Template` to give a description on what the text should cover. Give a sender name (e.g. company name) that will be used in the complimentary close. The recipient should be obvious from the contents of the input variables or the description.
+
+Select `Hybrid AI Template` to provide a text template. The template dictates the shape of the result text. You can use template variables using curly braces. Variables that are present in the input variable mapping are replaced directly, without going through the model. The remaining template variables will be filled in by the LLM. You can use simple variable names if obvious enough, or write full sentences with instructions on what to fill in. The result text is the template with all variables replaced or filled in.
+
+The template is especially helpful to dictate a certain order and presence of text parts/contents, and to guarantee a certain pre-defined structure. 
+
+Example:
+
+```
+Hello {name},
+
+{ thank the customer for his purchase }
+
+Yours,
+{agentName}
+```
+
+Here `name` and `agentName` could be input variables, while the middle part would be generated. `name` and `agentName` will not be sent to the model in any way (be careful that the template variable names correctly match the input variable names). Whitespaces at the beginning and end of a variable are ignored and therefore optional.
+
+#### Alignment
+
+When generated text should be used directly without human control, it can make sense to add a safety layer that ensures appropriate output.
+
+Select an Alignment Principle according to your needs. After generating the preliminary result text, another model will inspect the result with respect to the principle and potentially re-write parts of the text to satisfy the principle.
+There is a set of pre-defined principles available, or select `Custom` to write a custom principle, e.g.:
+
+```
+The text must not contain any offensive or rude language. It should always be polite and professional.
+```
+
+Using this alignment technique, it is generally very unlikely (but not impossible) that a result text will violate the principle, if written correctly.
 
-Configure a desired style, tone and language for the text and describe what it should cover. Give a sender name (e.g. company name) that will be used in the complimentary close. The recipient should be obvious from the contents of the input variables.
+Note that alignment adds token/time overhead and that the OpenAI models are generally already very unlikely to output offensive text, if not provoked. So making sure that a user has no direct or indirect path to influence the text generation is usually enough to obtain safe text.
 
 ### Result
-A temporary variable `result` that directly contains the result text. Can be mapped to a process variables using the result expression.
+A temporary variable `result` that directly contains the result text. Can be mapped to a process variable using the result expression.
 
 ---
 
 ## 🌍 Translate Connector
 
-Can translate multiple input variables to any given language and store the result in one or more output variables
+Translates multiple input variables to any given language and stores the result in one or more output variables
 
 ### Configuration
 

docs/getting-started.md

@@ -31,4 +31,4 @@ As the variable is local, you need to define which parts of the result you want
 { "result": result }
 ```
 
-The resulting JSON object is then merged into the current process variables (so beware variable naming to not overwrite anything).
+The resulting JSON object is then *merged* into the current process variables (so in this example there will be a new or overwritten process variable `result`).