> For the complete documentation index, see [llms.txt](https://mind-expression-docs.gitbook.io/home/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mind-expression-docs.gitbook.io/home/how-to-guides/intelligent-process/package-engine-conversation.md). # Package: Engine-Conversation ## Class: Conversation ### Introduction **Environment: `container`** A conversation object is a container for all the information related to current conversation. It is the start point to write covnersation rules in a subject. In the rules, you can access the conversation object by using the variable `self` or `conversation`. For example, to bind a parameter from a http header, you can write: ```smalltalk userName := self httpHeaders at: 'x-user-name'. self parameters at: 'user_name' put: userName. ``` All attributes for a conversation object are listed below in category `accessing`. ### Instance Method #### Category: accessing * **`currentInput`** - Returns the current input of the conversation as a string. * **`httpHeaders`** - Returns an object of type [HTTPHeader](#class-httpheader) that contains all the http headers passed from the client to the server. * **`httpRequestBody`** - Returns an object of type [HTTPRequestBody](#class-HTTPRequestBody) that contains the http request body passed from the client to the server. * **`parameters`** - Returns an object of type [Parameter](#class-parameter) that contains all the parameters in current scope. * **`predefinedSubject:`** - Returns a predefined subject object of the given subject type. The subject type can be one of the following: * \#:introduction * \#:conclusion * \#:webhook For example: ```smalltalk introductionSubject := self predefinedSubject: #:introduction. self response: 'introduction subject id is ', introductionSubject id. ``` * **`webhook`** - Returns an object of type [RuntimeWebHook](#class-runtimewebhook) that contains all the information about the runtime webhook request. #### Category: advance operations * **`awaitHTTPResponse:`** - Wait for the HTTP response from the given HTTP client asynchronously. The HTTP client is an object of type [HTTPClient](https://mindx-docs.mind.ai/how-to-guides/intelligent-process/package-kernel-http#class-httpclient). The conversation will be paused at this point and will be resumed after the HTTP response is received. All responses before this point will be sent to the client. For example: ```smalltalk httpClient := HTTPClient new. httpClient url: 'https://webhook.mind.ai/ManualInfo'. httpClient method: #:get. result := self awaitHTTPResponse: httpClient. status := result at: 'status'. status = 200 ifFalse: [ self response: 'Failed to retrieve name from the web hook server!' ]. response := JSONReader fromString: (result at: 'response'). name := response nestedAt: { 'data'. 'full_name' }. self parameters at: 'name' put: name. ``` * **`check:`** - ask for the check step for the parameter value of a given parameter. The parameter name is given as a string. For example: ```smalltalk self check: 'user_name'. ``` * **`response:`** - Show a message as a response. For example: ```smalltalk self response: 'Updated parameter value of x to 10.'. ``` At the present moment, it is utilized solely for debugging purposes, allowing us to display additional information during the development of the subject. ## Class: HTTPHeader ### Introduction **Environment: `container`** A key-value pair is known as a HTTPHeader object for current conversation. The origin of the initial values of http headers can be * the subject configurations for a web hook call * Such http headers are only accessable in before/after rules for a web hook. * additional http headers when requesting a conversation to Mind Expression. * Such http headers are accessable in all rules. The key name, a string, serves as the HTTP header name, while the value, also a string, corresponds to the http header value. To retrieve the value of a http header, you can utilize the following syntax: ```smalltalk a_header := self httpHeaders at: 'a-header-key'. "If the http header is not set, return a default value 100." a_header := (self httpHeaders at: 'a_header_key' ifAbsent: '100') asInteger. ``` Below is an example of setting a default value of a http header: ```smalltalk header := self httpHeaders at: 'webhook_header_key'. header ifNil: [ self httpHeaders at: 'webhook_header_key' put: 'default_webhook_header_value_3' ]. ``` ### Class Method #### Category: accessing * **`at:`** - Get the value of the HTTPHeader with specified name for current webhook. ```smalltalk a_header_key := (self httpHeaders at: 'a_header_key') asInteger. ``` * **`at:ifAbsent:`** - Get the value of the HTTPHeader with specified name, and specify a default value if absent. The parameter for the default value can be: * a code block, which will be evaluated if the HTTPHeader is absent. * a value, which will be returned if the HTTPHeader is absent. ```smalltalk "The default value can be a value." a_header_key := (self httpHeaders at: 'a_header_key' ifAbsent: '100') asInteger. "The default value can be a code block to evaluate." a_header_key := (self httpHeaders at: 'a_header_key' ifAbsent: [(100 + 1) asString]) asInteger. ``` * **`at:put:`** - Update the value of the HTTPHeader with specified name. ```smalltalk self httpHeaders at: 'a_header_key' value: '1000'. ``` * **`headers`** - Get all the HTTP headers as a Dictionary object. ```smalltalk self response: 'http headers: ', self httpHeaders headers asJson. ``` #### Category: reflective operations * **`doesNotUnderstand:`** - By default, for any message that is not understood by a HTTPHeader object, the message will be forwarded to a class [Dictionary](https://mindx-docs.mind.ai/how-to-guides/intelligent-process/package-kernel-objects#class-dictionary), which can unerstand all messages for a Dictionary class. #### Category: removing * **`removeKey:`** - Remove the HTTPHeader with the given name. ```smalltalk self httpHeaders removeKey: 'a_header_key'. ``` ## Class: HTTPRequestBody ### Introduction **Environment: `container`** The HTTPRequestBody class represents the body of an HTTP request in current conversation. This class provides a convenient way to interact with the content of an HTTP request, whether it's a raw string or a structured JSON object. * If the body of the HTTP request is not a json object, you can retrieve it directly by method `rawData`. ```smalltalk "The request body may be a raw string, or a number." rawData := self httpRequestBody rawData. ``` * If the body contains a JSON object, you can interact with it as if it's a `dictionary`, allowing you to retrieve values by their keys. ```smalltalk "Retrieve the value of the key 'user_name' from http request body." userName := self httpRequestBody at: 'user_name' ifAbsent: ''. "store the value of the key 'user_name' as a parameter." self parameters at: 'user_name' put: userName. ``` ### Instance Method #### Category: accessing * **`rawData`** - Get the raw data of the HTTP request body. ```smalltalk " Occasionally, the body of the HTTP request ma be a simple string rather than a JSON object." rawData := self httpRequestBody rawData. ``` #### Category: reflective operations * **`doesNotUnderstand:`** - By default, for any message that is not understood by a HTTPRequestBody object, the message will be forwarded to the request body [dictionary](https://mindx-docs.mind.ai/how-to-guides/intelligent-process/package-kernel-objects#class-dictionary), which can unerstand all messages for a Dictionary class. If the body of the request is a JSON object, you can extract the 'user\_name' key value in this way: ```smalltalk "Retrieve the value of the key 'user_name' from http request body." userName := self httpRequestBody at: 'user_name' ifAbsent: ''. ``` ## Class: Parameter ### Introduction **Environment: `container`** A key-value pair is known as a parameter object within the context of this conversation. It inherits from the `Dictionary` class, so it has all the methods of a [dictionary](https://mindx-docs.mind.ai/how-to-guides/intelligent-process/package-kernel-objects#class-dictionary). The parameter's name, given as a string, serves as the key, while its value, also a string, corresponds to the parameter's value. To retrieve the value of a parameter, you can utilize the following syntax: ```smalltalk cash_flow_string := self parameters at: 'cash_flow'. "If the parameter is not set, will return a default value 100." cash_flow := (self parameters at: 'cash_flow' ifAbsent: '100') asInteger. ``` Below is an example of setting the value of a parameter: ```smalltalk self parameters at: 'cash_flow' put: '1000'. ``` When extracting a parameter from a web hook response using jsonpath, it will retrieve multiple matching values. For instance, if the parameter `cash_flow` is created using the jsonpath expression `$.cash_flow`, the extraction process should be as follows: ```smalltalk cash_flow := (self parameters at: 'cash_flow' ifAbsent: {'100'}) first asInteger. ``` By default, the scope of a parameter is local to current subject, but you can also set the scope to global by using the following syntax: ```smalltalk self parameters at: 'a_global_parameter' value: '1000' as: #global. ``` That means, the parameter `a_global_parameter` will be available to all subjects within the current scope. ### Class Method #### Category: accessing * **`at:`** - Get the specified parameter's value with the provided name within the current subject's scope. A default value is returned if the parameter is not set, provided that a default value is available. ```smalltalk self parameters at: 'cash_flow'. ``` * **`at:put:`** - Update the specified local parameter's value with the provided name within the current subject's scope. ```smalltalk self parameters at: 'cash_flow' value: '1000'. ``` * **`at:put:as:`** - Update the parameter's value with the given name at the specified scope. The scope can be: * `#local` - the parameter will be valid in current subject. * `#global` - the parameter will be valid in all subjects. ```smalltalk "Register a global parameter." self parameters at: 'a_global_parameter' value: '1000' as: #global. ``` * **`getSourceOf:`** - Get the data source of the parameter with specified name. The possible data source can be * `#:input` - the value of the parameter is derived from the query. * `#:history` - the value of the parameter is derived from the previous query. * `#:webhook` - the value of the parameter is derived from a web hook response. * `#:rules` - the value of the parameter is derived by MindScript rules. * `#:default` - The value of the parameter is derived from the default value. * `#':http-headers'` - the value of the parameter is derived from http headers. * nil - the data source of the parameter is not available. ```smalltalk "Get the source of parameter 'a'" source := self parameters getSourceOf: 'a'. ``` #### Category: event handling * **`at:whenBoundSetHandler:`** - Register a block closure to handle the event when the value of the parameter is bound. For example, if the parameter `y` depends on the parameter `x`, and we want to reset `y` when `x` changes, we can write: ```smalltalk self parameters at: 'x' whenBoundSetHandler: [self parameters removeKey: 'y']. ``` #### Category: reflective operations * **`doesNotUnderstand:`** - By default, for any message that is not understood by a Parameter object, the message will be forwarded to a class [Dictionary](https://mindx-docs.mind.ai/how-to-guides/intelligent-process/package-kernel-objects#class-dictionary), which can unerstand all messages for a Dictionary class. #### Category: removing * **`removeKey:`** - Remove the association for the given parameter by its name. ## Class: RuntimeWebHook ### Introduction **Environment: `container`** This class would correspond to the runtime web hooks that are involved in the actual live conversation, handling the HTTP requests and responses. ### Instance Method #### Category: accessing * **`method`** - the HTTP method of the webhook. It can be one of the following values: * \#:get * \#:post * **`request`** - The body string of the webhook request; only applicable for POST requests. If the request is a json string, we can extract the json object by using the following code: ```smalltalk request := JSONReader fromString: self webhook request. event := (request at: 'event'). self parameters at: 'event' put: event. ``` * **`response`** - the response string of the webhook. If the resonse is a json string, we can extract the json object by using the following code: ```smalltalk response := JSONReader fromString: self webhook response. "The key is 'all'" all := response at: 'all'. " If the json path is 'all.0.name', we can get the value by using the following code:" firstName := response nestedAt: {'all'. 1. 'name'}. ``` `response` is only available in after rules for a webhook. * **`statusCode`** - The HTTP status code from the webhook response. It's an integer value like 200, 404, etc. See [the wiki page](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) for more details. When write a rule, we can stop the execution of the rule when webhook fails by using the following code: ```smalltalk "If webhook failed, just return from current rule." self webhook statusCode = 200 ifFalse: [ ^ nil ]. ``` `statusCode` is only available in after rules for a webhook. * **`url`** - This is the actual URL used to call the webhook, also known as the rendered URL of the webhook. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://mind-expression-docs.gitbook.io/home/how-to-guides/intelligent-process/package-engine-conversation.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.