STK Inspect
There are several ways to save knowledge when your agent runs. You can save as text (.karl or .mf file), as JSON, as a single binary database (.kb file) or a Serialized Temporal Knowledge (STK) base (.stk file). The stk_inspect tool is specialized in analyzing and stepping through the STK history and printing useful information about the current state or end state. The tool has a lot of different command line options and includes a batch mode (for inspecting things automatedly) and an interactive mode (for a developing stepping through execution with breakpoints). In this wiki, we'll describe the core features.
- The STK Inspect Tool
- The Command Line Options
- Required Parameters
- Batch Mode
- Interactive Mode
- Registering Capnproto Types
- Argument Parameter Files
[-b|--batch commands] load batch events from command line
[-bf|--batch-file file] load batch events from file
[-f|--stk-file file] STK file to load and analyze
[-h|--help] print help menu (i.e., this menu)
[-c|--check logic] logic to evaluate to check stats.
[-chf|--check-file file] KaRL file with check. See -c for options
[-k|--print-knowledge] print final knowledge
[-kp|--print-prefix pfx] filter prints by prefix. Can be multiple.
[-ks|--print-stats] print stats knowledge base contents
[-l|--level level] the logger level (0+, higher is higher detail)
[-lcp prfx] prefix of knowledge to load from checkpoint
[-ls|--load-size bytes] size of buffer needed for file load
[-n|--capnp tag:msg_type] register tag with given message schema.
[-nf|--capnp-file] load capnp file. Must appear after -n and -ni.
[-ni|--capnp-import ] add directory to capnp directory imports.
[-ns|--no-summary ] do not print or save summary stats per var at the end
[-s|--save file] save the results to a file
The only required parameter is -f or --stk-file, which specifies the file you want to analyze. Everything else is a decorator on how the file will be analyzed or stepped through.
You can use -b to read events from the command line in the format <seconds offset>:<command>, which can be chained together with other -b events on the command line to form a long list of batch events. These events can be added in any order, and the seconds offset is a double which can specify arbitrary second precision. The stk_inspect tool will sort batch events by seconds offset to enforce the appropriate calling order.
The -bf option can be used to load a text file that contains a list of batch events separated by new lines. For instance, the following file would execute commands at 5s, 10s, 15s, and 20s.
5: print_stats
10: add_prefix agent.0.location agent.0.orientation; print_stats
15: print
20: print_all; clear_prefixes
The above will print all stats for all variables about hertz rates, updates, etc. at 5s. At 10s, it will add limiting print prefixes for agent.0.location and agent.0.orientation and then print stats for these two variables. At 15s, it will print the value of the two variables. At 20s, it will print the stats and values for these two variables, and then it will clear all prefixes. If another print happens as part of the end summary, all variables will be printed because of the clear_prefixes call.
add_prefix arg: add a prefix limiter to prints
clear_prefixes: clears all prefix limiters
eval arg: evaluates logic in current state
eval_stats arg: evaluates logic in current stats
exit code: exit the application with a code
help: print this menu
list_prefixes: lists all prefix limiters
print: print current knowledge
print_stats: print current var stats
print_all: print current knowledge & var stats
quit: leave interactive shell
shell: enter an interactive shell
If you provide a batch command of shell, it will enter you into an interactive shell that allows you to run individual commands. For instance, if you were to do the following:
stk_inspect -f my_saved_knowledge.stk -ns -b "5: shell"
Then this would love your custom my_saved_knowledge.stk file with no printed summaries at the end and launch into an interactive shell at 5s into the playback of the STK. The interactive shell will prompt you for a command with What would you like to do? (help for usage info):, and you can input any individual commands from batch mode.
stk_inspect can be configured to load and register Capnp types for usage in inspecting variables and values. To use these tools for Capnp types, we use the following and in the following order:
-ni <schema directory>: the schema directory to find a capnp type`
-n <tag:type>: the tag is the type name as registered in a MADARA knowledge base. The type is the name of the Capnp type as defined in a schema file.
-nf <schema directory>/<type file>: the schema file to load
An example loading:
stk_inspect -ni $GAMS_ROOT/src/gams/types -n Imu:Imu -nf $GAMS_ROOT/src/gams/types/Imu.capnp
Argument parameters can be tedious, especially when needing to load many Capnproto type schemas or when repeating commonly used parameters. The stk_inspect command line tool helps to alleviate this through parameter files, which can be passed through the command line with the -cf or --config-file option or by populating a default file at $HOME/.madara/stk_inspect.cfg with the parameters of your choosing. The parameter files are separated by newlines for each flag or argument and parameter pairing. For instance, the following is a valid parameter file:
-k
-l 3
Which would instruct karl to print final knowledge and also set the logging level to 3 (LOG_MAJOR). The file could be saved to $HOME/.madara/stk_inspect.cfg and these options would always be loaded on every invocation of stk_inspect. If you wanted to only load the file conditionally, you would save the file at a preferred location and then pass the configuration file in with -cf or --config-file