Animator documentation updates

cmu-sei · Jan 6, 2024 · 5eebd3f · 5eebd3f
1 parent 0e19fa1
commit 5eebd3f
Show file tree

Hide file tree

Showing 3 changed files with 120 additions and 30 deletions.
diff --git a/docs/animator/index.md b/docs/animator/index.md
@@ -33,6 +33,8 @@ curl https://github.com/cmu-sei/GHOSTS-ANIMATOR/blob/master/src/docker-compose.y
 docker compose up -d
 ```
 
+Note, most configuration that you may want to change is located in ./config, and so you can mount that directory to your local machine and make changes there.
+
 Now browse to <http://localhost:5000/>
 
 ## Using Animator to Create NPCs

diff --git a/docs/animator/jobs.md b/docs/animator/jobs.md
@@ -47,3 +47,35 @@ Some tweets contain no insight about the agent. Some disclose some bit of inform
 - Agent decided to disclose some personal detail Z
 
 Other agents — and adversaries — can see and infer from this information!
+
+## Animator Jobs
+
+There are several jobs currently configurable within the Animator system.
+
+### Social Graph
+
+This job is responsible for creating and maintaining the social graph of the agents. It is responsible for creating the initial graph, and then updating it as agents interact with each other, and learn different knowledge types.
+
+### Social Belief
+
+This job is responsible for creating and maintaining the bayesian social belief of the agents. It is responsible for creating the initial belief, and then updating it as agents interact with each other, and learn different knowledge types.
+
+???+ danger "The following are still early beta"
+ Here be dragons
+
+The following run with Animator's use of faker to generate content, but really begin to shine when hooked to a Large Language Model (LLM), either hosted as a cloud service or locally.
+
+### Social Sharing
+
+This job has agents create and post content on social media. It is responsible for creating the initial share based on the agent and their history. After creating a reasonable thing that agent would say on social media, Animator sends an activity to the GHOSTS API proper to send down to the agent to execute.
+
+### Chat
+
+This job has agents chat with each other on an OSS chat platform. It is responsible for creating the initial chat based on the agent and their history. After creating a reasonable thing that agent would say on social media, Animator sends an activity to the GHOSTS API proper to send down to the agent to execute. 
+
+### Full Autonomy
+
+This has agents get their next instruction directly from an LLM, based on who they are and their history. While GHOSTS can execute many of these activities, some activty generated will be beyond the scope of this project, but its inclusion can provide rich histories from which to generate future activities. With a powerful LLM, this generates some exceptionally real activities, but can also be hard to control for the training and exercise audience. 
+
+Initial work in LLM-driven autonomous GHOSTS agents was documented in our technical report titled :material-file-document:[_Simulating Realistic Human Activity Using Large Language Model Directives_](https://insights.sei.cmu.edu/library/simulating-realistic-human-activity-using-large-language-model-directives/){:target="_blank"}.
+
diff --git a/docs/animator/run.md b/docs/animator/run.md
@@ -5,41 +5,97 @@ Animator is a simulation of a population of agents. Animator runs in cycles, and
 ## Setup
 
 - Get the Animator API up and running as outlined [here](index.md)
-- Edit the `appsettings.json` file to enable Animations:
+- The `appsettings.json` file points to Animator-specific configuration, which by default is in `./config/config.json`:
 
 ```json
-"ApplicationSettings": {
- "GhostsApiUrl": "http://localhost:52388/", // this should be root url of your ghosts API server
- "Animations": {
- "IsEnabled": false, // set this to true to enable animation jobs
- "SocialGraph": {
- "IsEnabled": false, // set this to true to enable the entire module (inc. web gui access)
- "IsInteracting": false, // set this to true to actually run the interactions
- "MaximumSteps": 4000, // animator stops when it reaches this many steps 
- "TurnLength": 900, // by default, a step is a cpu cycle, the higher this number, the slower the simulation 
- "ChanceOfKnowledgeTransfer": 0.3,
- "Decay": {
- "StepsTo": 10,
- "ChanceOf": 0.05
+ {
+ "ApplicationDatabaseSettings": {
+ "ConnectionString": "mongodb://ghosts-mongo:32770",
+ "DatabaseName": "AnimatorDb"
+ },
+ "ApplicationSettings": {
+ "GhostsApiUrl": "http://localhost:52388/", //the root url of the Ghosts API
+ "Proxy": "",
+ "Animations": {
+ "IsEnabled": false, //if false, then all animations are disbled
+ "SocialGraph": {
+ "IsEnabled": false, //if false, just this animation is disabled
+ "IsMultiThreaded": true, //helpful to set to false for debugging purposes
+ "IsInteracting": true, //means new agent interactions are being generated
+ "MaximumSteps": 4000, //max steps to execute
+ "TurnLength": 9000, //ms per step
+ "ChanceOfKnowledgeTransfer": 0.3, //chance that an agent will share knowledge with another agent
+ "Decay": {
+ "StepsTo": 10, //min steps to execute before an agent begins forgetting things
+ "ChanceOf": 0.05
+ }
+ },
+ "SocialBelief": {
+ "IsEnabled": false,
+ "IsMultiThreaded": true,
+ "IsInteracting": true,
+ "MaximumSteps": 300,
+ "TurnLength": 9000
+ },
+ "SocialSharing": {
+ "IsEnabled": false,
+ "IsMultiThreaded": true,
+ "IsInteracting": true,
+ "IsSendingTimelinesToGhostsApi": false,
+ "IsSendingTimelinesDirectToSocializer": true,
+ "PostUrl": "http://localhost:8000",
+ "MaximumSteps": 100,
+ "TurnLength": 9000,
+ "ContentEngine": {
+ "Source": "ollama",
+ "Host": "http://localhost:11434",
+ "Model": "chat"
+ }
+ },
+ "Chat": {
+ "IsEnabled": false,
+ "IsMultiThreaded": true,
+ "IsInteracting": true,
+ "MaximumSteps": 300,
+ "TurnLength": 9000,
+ "IsSendingTimelinesToGhostsApi": false,
+ "PostUrl": "http://localhost:8065",
+ "ContentEngine": {
+ "Source": "ollama",
+ "Host": "http://localhost:11434",
+ "Model": "chat"
+ }
+ },
+ "FullAutonomy": {
+ "IsEnabled": false,
+ "IsMultiThreaded": true,
+ "IsInteracting": true,
+ "IsSendingTimelinesToGhostsApi": false,
+ "MaximumSteps": 10000,
+ "TurnLength": 9000,
+ "ContentEngine": {
+ "Source": "ollama",
+ "Host": "http://localhost:11434",
+ "Model": "activity"
+ }
  }
- },
- "SocialSharing": {
- "IsEnabled": false, // set this to true to enable the entire module (inc. web gui access)
- "IsInteracting": false, // set this to true to actually run the interactions
- "IsSendingTimelinesToGhostsApi": false, // set this to true to actually send the timeline commands to the ghosts API
- "IsChatGptEnabled": false, // this is still under development, here be dragons
- "SocializerUrl": "http://socializer.com", // change this to the root url of your in-game social server
- "MaximumSteps": 14000,
- "TurnLength": 9000 // by default, a step is a cpu cycle, the higher this number, the slower the simulation 
- },
- "SocialBelief": {
- "IsEnabled": false, // set this to true to enable the entire module (inc. web gui access)
- "IsInteracting": false, // set this to true to actually run the interactions
- "MaximumSteps": 14000,
- "TurnLength": 9000
  }
+ },
+ "AllowedHosts": "*",
+ "ClientSettings": {
+ },
+ "CorsPolicy": {
+ "Origins": [
+ "http://localhost:4200"
+ ],
+ "Methods": [],
+ "Headers": [],
+ "AllowAnyOrigin": false,
+ "AllowAnyMethod": true,
+ "AllowAnyHeader": true,
+ "SupportsCredentials": true
  }
- },
+ }
  ...
 ```