ChatScript/HTMLDOCUMENTATION/ChatScript-Command-Line-Parameters.html at master · OregonJunco/ChatScript

405 lines (405 loc) · 24.6 KB
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <meta http-equiv="Content-Style-Type" content="text/css" />
  <meta name="generator" content="pandoc" />
  <title></title>
  <style type="text/css">code{white-space: pre;}</style>
<h1 id="chatscript-command-line-parameters">ChatScript Command Line Parameters</h1>
<p>Copyright Bruce Wilcox, gowilcox@gmail.com www.brilligunderstanding.com<br> <br>Revision 2/12/2019 cs9.1</p>
<h1 id="command-line-parameters">Command Line Parameters</h1>
<p>You can give parameters on the run command or in a config file or via a http request. The default config file is <code>cs_init.txt</code> at the top level of CS (if the file exists). Or you can name where the file is on a command line parameter <code>config=xxx</code>. If you have secret information that you don't want stored in a config file or exposed on a command line then you can request the config data from a URL. Use the command line parameter configurl=http://xxx to specify the address of the data. Additional command line parameters, configheader=xxx, can be included to define HTTP request headers. If there are several headers then use separate configheader=xxx configheader=yyy etc parameters for each header name/value pair.</p>
<p>Config file data are command line parameters, 1 per line, like below:</p>
<pre><code>noboot 
port=20</code></pre>
<p>Some parameters require a value and use the <code>=</code> format with no spaces. Other parameters may only require you name the parameter (they have no choices of values).s</p>
<p>Actual command line parameters have priority over config file values, and those have priority over http requested values.</p>
<h2 id="memory-options">Memory options</h2>
<p>Chatscript statically allocates its memory and so (barring unusual circumstance) will not allocate memory every during its interactions with users. These parameters can control those allocations. Done typically in a memory poor environment like a cellphone.</p>
<col width="17%" />
<col width="82%" />
</colgroup>
<tr class="header">
<th>option</th>
<th>description</th>
<tr class="odd">
<td><code>buffer=50</code></td>
<td>how many buffers to allocate for general use (80 is default)</td>
<tr class="even">
<td><code>buffer=15x80</code></td>
<td>allocate 15 buffers of 80k bytes each (default buffer size is 80k)</td>
<p>Most chat doesn't require huge output and buffers around 20k each will be more than enough. 20 buffers is often enough too (depends on recursive issues in your scripts).</p>
<p>If the system runs out of buffers, it will perform emergency allocations to try to get more, but in limited memory environments (like phones) it might fail. You are not allowed to allocate less than a 20K buffer size.</p>
<col width="17%" />
<col width="82%" />
</colgroup>
<tr class="header">
<th>option</th>
<th>description</th>
<tr class="odd">
<td><code>dict=n</code></td>
<td>limit dictionary to this size entries</td>
<tr class="even">
<td><code>text=n</code></td>
<td>limit string space to this many bytes</td>
<tr class="odd">
<td><code>fact=n</code></td>
<td>limit fact pool to this number of facts</td>
<tr class="even">
<td><code>hash=n</code></td>
<td>use this hash size for finding dictionary words (bigger = faster access)</td>
<tr class="odd">
<td><code>cache=50x1</code></td>
<td>allocate a 50K buffer for handling 1 user file at a time. A server might want to cache multiple users at a time.</td>
<p>A default version of ChatScript will allocate much more than it needs, because it doesn't know what you might need.</p>
<p>If you want to use the least amount of memory (multiple servers on a machine or running on a mobile device), you should look at the USED line on startup and add small amounts to the entries (unless your application does unusual things with facts).</p>
<p>If you want to know how much, try doing <code>:show stats</code> and then <code>:source REGRESS/bigregress.txt</code>. This will run your bot against a wide range of input and the stats at the end will include the maximum values needed during a volley. To be paranoid, add beyond those valuse. Take your max dict value and double it. Same with max fact. Add 10000 to max text.</p>
<p>Just for reference, for our most advanced bot, the actual max values used were: max dict: 346 max fact: 689 max text: 38052.</p>
<p>And the maximum rules executed to find an answer to an input sentence was 8426 (not that you control or care). Typical rules executed for an input sentence was 500-2000 rules. For example, add 1000 to the dict and fact used amounts and 10 (kb) to the string space to have enough normal working room.</p>
<h2 id="output-options">Output options</h2>
<col width="21%" />
<col width="78%" />
</colgroup>
<tr class="header">
<th>option</th>
<th>description</th>
<tr class="odd">
<td><code>output=nnn</code></td>
<td>limits output line length for a bot to that amount (forcing crnl as needed). 0 is unlimited.</td>
<tr class="even">
<td><code>outputsize=80000</code></td>
<td>is the maximum output that can be shipped by a volley from the bot without getting truncated.</td>
<p>Actually the <code>outputsize</code> value is somewhat less, because routines generating partial data for later incorporation into the output also use the buffer and need some usually small amount of clearance. You can find out how close you have approached the max in a session by typing <code>:memstats</code>. If you need to ship a lot of data around, you can raise this into the megabyte range and expect CS will continue to function. 80K is the default. For normal operation, when you change <code>outputsize</code> you should also change <code>logsize</code> to be at least as much, so that the system can do complete logs. You are welcome to set log size lots smaller if you don't care about the log.</p>
<h2 id="file-options">File options</h2>
<col width="17%" />
<col width="82%" />
</colgroup>
<tr class="header">
<th>option</th>
<th>description</th>
<tr class="odd">
<td><code>livedata=xxx</code></td>
<td>name relative or absolute path to your own private LIVEDATA folder. Do not add trailing / on this path<br>Recommended is you use <code>RAWDATA/yourbotfolder/LIVEDATA</code> to keep all your data in one place. You can have your own live data, yet use ChatScripts default <code>LIVEDATA/SYSTEM</code> and <code>LIVEDATA/ENGLISH</code> by providing paths to the <code>system=</code> and <code>english=</code> parameters as well as the <code>livedata=</code> parameter</td>
<tr class="even">
<td><code>topic=xxx</code></td>
<td>name relative or absolute path to your own private TOPIC folder. Do not add trailing / on this path <code>/</code></td>
<tr class="odd">
<td><code>buildfiles=xxx</code></td>
<td>name relative or absolute path to your own folder where filesxxx.txt is found. Do not add trailing / on this path <code>/</code></td>
<tr class="even">
<td><code>users=xxx</code></td>
<td>name relative or absolute path to where you want the USERS folder to be. Do not add trailing <code>/</code></td>
<tr class="odd">
<td><code>logs=xxx</code></td>
<td>name relative or absolute path to where you want the LOGS folder to be. Do not add trailing <code>/</code></td>
<tr class="even">
<td><code>userlog</code></td>
<td>Store a user-bot log in USERS directory (default)</td>
<tr class="odd">
<td><code>nouserlog</code></td>
<td>Don't store a user-bot log</td>
<tr class="even">
<td><code>tmp=xxx</code></td>
<td>name relative or absolute path to where you want the TMP folder to be. Do not add trailing <code>/</code></td>
<h2 id="execution-options">Execution options</h2>
<col width="19%" />
<col width="80%" />
</colgroup>
<tr class="header">
<th>option</th>
<th>description</th>
<tr class="odd">
<td><code>source=xxxx</code></td>
<td>Analogous to the <code>:source</code> command. The file is executed</td>
<tr class="even">
<td><code>login=xxxx</code></td>
<td>The same as you would name when asked for a login, this avoids having to ask for it. Can be <code>login=george</code> or <code>login=george:harry</code> or whatever</td>
<tr class="odd">
<td><code>build0=filename</code></td>
<td>runs <code>:build</code> on the filename as level0 and exits with 0 on success or 4 on failure</td>
<tr class="even">
<td><code>build1=filename</code></td>
<td>runs <code>:build</code> on the filename as level1 and exits with 0 on success or 4 on failure.<br>Eg. ChatScript <code>build0=files0.txt</code> will rebuild the usual level 0</td>
<tr class="odd">
<td><code>debug=:xxx</code></td>
<td>xxx runs the given debug command and then exits. Useful for <code>:trim</code>, for example or more specific <code>:build</code> commands</td>
<tr class="even">
<td><code>param=xxxxx</code></td>
<td>data to be passed to your private code</td>
<tr class="odd">
<td><code>bootcmd=xxx</code></td>
<td>runs this command string before CSBOOT is run; use it to trace the boot process</td>
<tr class="even">
<td><code>trace</code></td>
<td>turn on all tracing.</td>
<tr class="odd">
<td><code>redo</code></td>
<td>see documentation for :redo in <a href="ChatScript-Debugging-Manual.html">ChatScript Debugging Manual</a> manual</td>
<tr class="even">
<td><code>noboot</code></td>
<td>Do not run any boot script on engine startup</td>
<tr class="odd">
<td><code>logsize=n</code></td>
<td>When server log file exceeds n megabytes, rename it and start with a new file.</td>
<tr class="even">
<td><code>defaultbot=name</code></td>
<td>overrides defaultbot table for what bot to default to</td>
<tr class="odd">
<td><code>inputlimit=n</code></td>
<td>truncate user input line to this size</td>
<tr class="even">
<td><code>trustpos</code></td>
<td>obey word~n and other pos restrictions in keywords</td>
<p>Trustpos is normally off by default because CS is only about 94% accurate in its built-in pos-tagging. So it prefers to wrongly match by allowing all pos values Of a word rather than miss a match. Ergo concept: <sub>all(feel</sub>n) will match any use of &quot;feel&quot; rather than just noun meaning. But combining CS with Treetagger for english (if you license it) is better at pos-tagging than either alone, making it competitive with the best taggers in the world.</p>
<p>Here few command line parameters usage examples of usual edit/compile developement phase, running ChatScript from a Linux terminal console (standalone mode):</p>
<p>Rebuild <em>level0</em> (compiling system ChatScript files, listed usually in file <code>files0.txt</code>):</p>
<pre><code>BINARIES/LinuxChatScript64 local build0=files0.txt </code></pre>
<p>Rebuild <em>level1</em>, compiling bot <em>Mybot</em> (files listed in file <code>filesMybot.txt</code>), showing build report on screen (stdout):</p>
<pre><code>BINARIES/LinuxChatScript64 local build1=filesMybot.txt </code></pre>
<p>Rebuild and run: If building phase is without building errors, you can run the just built <em>Mybot</em> in local mode (interactive console) with user name <em>Amy</em>:</p>
<pre><code>BINARIES/LinuxChatScript64 local login=Amy</code></pre>
<p>Build bot <em>Mybot</em> and run ChatScript with user <em>Amy</em>:</p>
<pre><code>BINARIES/LinuxChatScript64 local build1=filesMybot.txt &amp;&amp;  BINARIES/LinuxChatScript64 local login=Amy</code></pre>
<h2 id="bot-variables">Bot variables</h2>
<p>You can create predefined bot variables by simply naming permanent variables on the command line, using V to replace $ (since Linux shell scripts don't like $). Eg.</p>
<pre><code>ChatScript Vmyvar=fatcat</code></pre>
<pre><code>ChatScript Vmyvar=&quot;tony is here&quot;</code></pre>
<pre><code>ChatScript &quot;Vmyvar=tony is here&quot;</code></pre>
<p>Quoted strings will be stored without the quotes. Bot variables are always reset to their original value at each volley, even if you overwrite them during a volley. This can be used to provide server-host specific values into a script. Nor will they be saved in The user's topic file across volleys. This also applies to variables defined during any CS_BOOT</p>
<h2 id="no-such-bot-specific---nosuchbotrestarttrue">No such bot-specific - nosuchbotrestart=true</h2>
<p>If the system does not recognize the bot name requested, it can automatically restart a server (on the presumption that something got damaged). If you don't expect no such bot to happen, you can enable this restart using <code>nosuchbotrestart=true</code>. Default is false.</p>
<h2 id="time-options">Time options</h2>
<col width="19%" />
<col width="80%" />
</colgroup>
<tr class="header">
<th>option</th>
<th>description</th>
<tr class="odd">
<td><code>Timer=15000</code></td>
<td>if a volley lasts more than 15 seconds, abort it and return a timeout message.</td>
<tr class="even">
<td><code>Timer=18000x10</code></td>
<td>same as above, but more roughly, higher number after the x reduces how frequently it samples time, reducing the cost of sampling</td>
<h2 id="translateconcept-google-api-key"><code>:TranslateConcept</code> Google API Key</h2>
<col width="19%" />
<col width="80%" />
</colgroup>
<tr class="header">
<th>option</th>
<th>description</th>
<tr class="odd">
<td><code>apikey=xxxxxx</code></td>
<td>is how you provide a google translate api key to <code>:translateconcept</code></td>
<h1 id="security">Security</h1>
<p>Typically security parameters only are used in a server configuration.</p>
<col width="19%" />
<col width="80%" />
</colgroup>
<tr class="header">
<th>option</th>
<th>description</th>
<tr class="odd">
<td><code>sandbox</code></td>
<td>If the engine is not allowed to alter the server machine other than through the standard ChatScript directories, you can start it with the parameter <code>sandbox</code> which disables Export and System calls.</td>
<tr class="even">
<td><code>nodebug</code></td>
<td>Users may not issue debug commands (regardless of authorizations). Scripts can still do so.</td>
<tr class="odd">
<td><code>authorize=&quot;&quot;</code></td>
<td>bunch of authorizations &quot;&quot;. The contents of the string are just like the contents of the authorizations file for the server. Each entry separated from the other by a space. This list is checked first. If it fails to authorize AND there is a file, then the file will be checked also. Otherwise authorization is denied.</td>
<tr class="even">
<td><code>encrypt=xxxxx</code><br><code>decrypt=xxxxx</code></td>
<td>These name URLs that accept JSON data to encrypt and decrypt user data. User data is of two forms, topic data and LTM data. LTM data is intended to be more personalized for a user, so if <code>encrypt</code> is set, LTM will be encrypted. User topic data is often just execution state of the user and potentially big, so by default it is not encrypted. You can request encryption using <code>userencrypt</code> as a command line parameter to encrypt the topic file and <code>ltmdecrypt</code> to encrypt the ltm file.</td>
<p>The JSON data sent to the URL given by the parameters looks like this:</p>
<pre><code>{&quot;datavalues&quot;: {&quot;x&quot;: &quot;...&quot;}} </code></pre>
<p>where ... is the text to encrypt or decrypt. Data from CS will be filled into the ... and are JSON compatible.</p>
<h1 id="server-parameters">Server Parameters</h1>
<p>Either Mac/LINUX or Windows versions accept the following command line args:</p>
<col width="23%" />
<col width="76%" />
</colgroup>
<tr class="header">
<th>option</th>
<th>description</th>
<tr class="odd">
<td><code>port=xxx</code></td>
<td>This tells the system to be a server and to use the given numeric port. You must do this to tell Windows to run as a server. The standard port is 1024 but you can use any port.</td>
<tr class="even">
<td><code>local</code></td>
<td>The opposite of the port command, this says run the program as a stand-alone system, not as a server.</td>
<tr class="odd">
<td><code>interface=127.0.0.1</code></td>
<td>By default the value is <code>0.0.0.0</code> and the system directly uses a port that may be open to the internet. You can set the interface to a different value and it will set the local port of the TCP connection to what you designate.</td>
<h1 id="user-data">User Data</h1>
<p>Scripts can direct the system to store individualized data for a user in the user's topic file in USERS. It can store user variables (<code>$xxx</code>) or facts. Since variables hold only a single piece of information a script already controls how many of those there are. But facts can be arbitrarily created by a script and there is no natural limit. As these all take up room in the user's file, affecting how long it takes to process a volley (due to the time it takes to load and write back a topic file), you may want to limit how many facts each user can have written. This is unrelated to universal facts the system has at its permanent disposal as part of the base system.</p>
<p><code>userfacts=n</code> limits a user file to saving only the n most recently created facts of a user (this does not include facts stored in fact sets). Overridden if the user has <code>$cs_userfactlimit</code> set to some value</p>
<h3 id="user-caching">User Caching</h3>
<p>Each user is tracked via their topic file in USERS. The system must load it and write it back for each volley and in some cases will become I/O bound as a result (particularly if the filesystem is not local).</p>
<p>You can direct the system to keep a cache in memory of recent users, to reduce the I/O volume. It will still write out data periodically, but not every volley. Of course if you do this and the server crashes, writebacks may not have happened and some system rememberance of user interaction will be lost.</p>
<p>Of course if the system crashes, user's may not think it unusually that the chatbot forgot some of what happened. By default, the system automatically writes to disk every volley, If you use a different value, a user file will never be more out of date than that.</p>
<pre><code>cache=20
cache=20x1</code></pre>
<p>This specifies how many users can be cached in memory and how big the cache block in kb should be for a user. The default block size is <code>50</code> (50,000 bytes). User files typically are under 20,000 bytes.</p>
<p>If a file is too big for the block, it will just have to write directly to and from the filesystem. The default cache count is 1, telling how many users to cache at once, but you can explicitly set how many users get cached with the number after the &quot;x&quot;. If the second number is 0, then no caching is done and users have no data saved. They remember nothing from volley to volley.</p>
<p>Do not use caching with fork. The forks will be hiding user data from each other.</p>
<pre><code>save=n</code></pre>
<p>This specifies how many volleys should elapse before a cached user is saved to disk. Default is 1. A value of 0 not only causes a user's data to be written out every volley, but also causes the user record to be dropped from the cache, so it is read back in every time it is needed (handy when running multi-core copies of chatscript off the same port).</p>
<p>Note, if you change the default to a number higher than 1, you should always use <code>:quit</code> to end a server. Merely killing the process may result in loss of the most recent user activity.</p>
<h2 id="logging-or-not">Logging or Not</h2>
<p>In stand-alone mode the system logs what a user says with a bot in the USERS folder. It can also do this in server mode. It can also log what the server itself does. But logging slows down the system. Particularly if you have an intervening server running and it is logging things, you may have no use whatsoever for ChatScript's logging.</p>
<pre><code>Userlog</code></pre>
<p>Store a user-bot log in USERS directory. Stand-alone default if unspecified.</p>
<pre><code>Nouserlog</code></pre>
<p>Don't store a user-bot log. Server default if unspecified.</p>
<pre><code>Serverlog</code></pre>
<p>Write a server log. Server default if unspecified. The server log will be put into the LOGS directory under serverlogxxx.txt where xxx is the port.</p>
<pre><code>Noserverprelog</code></pre>
<p>Normally CS writes of a copy of input before server begins work on it to server log. Helps see what crashed the server (since if it crashes you get no log entry). This turns it off to improve performance.</p>
<pre><code>hidefromlog=&quot;label label2 label3&quot;</code></pre>
<p>If there is data you don't want reflected into either server or user log files, this is the parameter. Maybe you don't want an authorization code recorded, or whatever. This presumes the data is part of some JSON object. You name one or more labels and when those are found in data outbound to a log file, the label and its value will be omitted.</p>
<pre><code>Serverctrlz</code></pre>
<p>Have server terminate its output with 0x00 0xfe 0xff as a verification the client received the entire message, since without sending to server, client cannot be positive the connection wasn't broken somewhere and await more input forever.</p>
<pre><code>Noserverlog</code></pre>
<p>Don't write a server log.</p>
<pre><code>Fork=n</code></pre>
<p>If using LINUX EVSERVER, you can request extra copies of ChatScript (to run on each core for example). n specifies how many additional copies of ChatScript to launch.</p>
<pre><code>Serverretry</code></pre>
<p>Allows <code>:retry</code> to work from a server - don't use this except for testing a single-person on a server as it slows down the server.</p>
<pre><code>servertrace</code></pre>
<p>when present, forces all users to have tracing turned on. Traces go to the user logs.</p>
<pre><code>repeatLimit=n</code></pre>
<p>Servers are subject to malicious inputs, often generated as repeated words over and over. This detects repeated input and if the number of sequential repeats is non-zero and equal or greater to this parameter, such inputs will be truncated to just the initial repeats. All other input in this volley will be discarded.</p>
<pre><code>erasename=myname</code></pre>
<p>:reset, when called from running script, is unable to fully reset the system. Facts that have already been created are not destroyed and user variables that have been defined are not erased, only ones in the bot definition are changed back to their default settings. The erasename parameter is used to perform a full reset prior to loading th user topic file. The incoming input is scanned for the text given, and if found the system bypasses loading the topic file and instead just initializes a fresh bot. The actual erasename seen in input will be converted to all blanks, so it will not disturb normal behavior, either in OOB input or user input.</p>
<p>The default value for this is: <code>csuser_erase</code> which you can change to anything else you want.</p>
<h2 id="no-such-bot-specific---nosuchbotrestarttrue-1">No such bot-specific - nosuchbotrestart=true</h2>
<p>If the system does not recognize the bot name requested, it can automatically restart a server (on the presumption that something got damaged). If you don't expect no such bot to happen, you can enable this restart using <code>nosuchbotrestart=true</code>. Default is false.</p>
<h2 id="testing-a-server">Testing a server</h2>
<p>There are various configurations for having an instance be a client to test a server.</p>
<pre><code>client=xxxx:yyyy</code></pre>
<p>This says be a client to test a remote server at IP xxxx and port yyyy. You will be able to &quot;login&quot; to this client and then send and receive messages with a server.</p>
<pre><code>client=localhost:yyyy</code></pre>
<p>This says be a client to test a local server on port yyyy. Similar to above.</p>
<pre><code>Load=1</code></pre>
<p>This creates a localhost client that constantly sends messages to a server. Works its way through <code>REGRESS/bigregress.txt</code> as its input (over 100K messages). Can assign different numbers to create different loading clients (e.g., load=10 creates 10 clients).</p>
<pre><code>Dual</code></pre>
<p>Yet another client. But this one feeds the output of the server back as input for the next round. There are also command line parameters for controlling memory usage which are not specific to being a server.</p>
FilesExpand file tree

ChatScript-Command-Line-Parameters.html

Latest commit

History

ChatScript-Command-Line-Parameters.html

File metadata and controls
