TrafficGuard · danielcampagnolitg · Feb 3, 2025 · Jan 22, 2025 · Jan 22, 2025 · Jan 22, 2025
diff --git a/Dockerfile b/Dockerfile
@@ -35,6 +35,10 @@ RUN mkdir .sophia
 # Generate the function schemas
 RUN npm run functionSchemas
 
+# Needed to avoid the error "fatal: detected dubious ownership in repository at '/home/sophia'" when running git commands
+# as the application files are owned by the root user so an agent (which runs as the sophia user) can't modify them.
+RUN git config --global --add safe.directory /home/sophia
+
 ENV NODE_ENV=production
 ENV PORT=8080
 EXPOSE 8080

diff --git a/bin/configure b/bin/configure
@@ -28,4 +28,26 @@ fi
 echo Initialising Angular project
 cd frontend
 npm install
-cd ..
+cd ..
+
+# CLI setup -------------
+
+# Setup for bash
+if [ -f ~/.bashrc ]; then
+    if ! grep -q "SOPHIA_HOME" ~/.bashrc; then
+        echo "\n# Sophia CLI environment" >> ~/.bashrc
+        echo "export SOPHIA_HOME=$(pwd)" >> ~/.bashrc
+        echo "export PATH=\$SOPHIA_HOME/bin/path:\$PATH" >> ~/.bashrc
+    fi
+fi
+
+# Setup for zsh
+if [ -f ~/.zshrc ]; then
+    if ! grep -q "SOPHIA_HOME" ~/.zshrc; then
+        echo "\n# Sophia CLI environment" >> ~/.zshrc
+        echo "export SOPHIA_HOME=$(pwd)" >> ~/.zshrc
+        echo "export PATH=\$SOPHIA_HOME/bin/path:\$PATH" >> ~/.zshrc
+    fi
+fi
+
+echo "done"
diff --git a/bin/path/ss b/bin/path/ss
@@ -19,5 +19,15 @@ script=$1
 shift # Shift the arguments so $@ contains the remaining args
 
 CWD=$(pwd)
+
+# Load NVM
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
+
+set -x
 # Run the npm script with any additional arguments and the filesystem arg
-(cd "$SOPHIA_HOME" && npm run "$script" -- --fs="${CWD}" "$@")
+(
+  cd "$SOPHIA_HOME"
+  nvm use
+  npm run "$script" -- --fs="${CWD}" "$@"
+)
diff --git a/docs/docs/agent-concepts.md b/docs/docs/agent-concepts.md
@@ -2,24 +2,32 @@
 
 ## Agent categories
 
+We follow a similar naming convention described in [Building Effective Agents](https://www.anthropic.com/research/building-effective-agents) by Anthropic.
+
+> "Agent" can be defined in several ways. Some customers define agents as fully autonomous systems that operate independently over extended periods, using various tools to accomplish complex tasks. Others use the term to describe more prescriptive implementations that follow predefined workflows. At Anthropic, we categorize all these variations as agentic systems, but draw an important architectural distinction between workflows and agents:
+>
+> Workflows are systems where LLMs and tools are orchestrated through predefined code paths.
+> 
+> Agents, on the other hand, are systems where LLMs dynamically direct their own processes and tool usage, maintaining control over how they accomplish tasks.
+
 ### 1. Autonomous agents
 
 Sophia comes with two autonomous agent types (XML and CodeGen), which applying reasoning to break down
 a user request into a plan to be completed by the available function calls.
 
 The Slack chatbot uses an autonomous agent to provide a response to a user.
 
-Function calls may be to API integrations or create sub-agents.
+Functions may call to API integrations or create sub-agents.
 
 ### 2. Workflow agents
 
 Workflow agents have the control flow logic defined in code, and the results of the LLM calls
-may determine the conditional control flow through the workflow.  This includes the Software Developer/Code Editing agents.
+may determine the conditional control flow through the workflow.  This includes the Software Developer/Code Editing workflow agents.
 
 ## Agent context
 
 The codebase makes use of `AsyncLocalStorage`, which is similar to `ThreadLocal` in Java and `threading.local()` in Python,
-to provide easy lookup of agent state, current user, tool configuration, and default LLMs.
+to provide easy lookup of agent state, current user, tool configuration, and default LLMs for both autonomous agents and workflow agents.
 
 This requires the agent code to run within a AsyncLocalStorage context.
 ```typescript

diff --git a/docs/docs/autonomous-agents.md b/docs/docs/autonomous-agents.md
@@ -1,5 +1,12 @@
 # Autonomous AI Agents
 
+- Reasoning/planning inspired from Google's [Self-Discover](https://arxiv.org/abs/2402.03620) and other papers
+- Memory and function call history for complex workflows
+- Iterative planning with hierarchical task decomposition
+- Sandboxed execution of generated code for multi-step function calling and logic
+- LLM function schemas auto-generated from source code
+- Human-in-the-loop for budget control, agent initiated questions and error handling
+
 Sophia provides two autonomous agents which work to complete the request via a control loop which iteratively (re-)plans and calls the functions available to the agent.
 
 At a high level they share the same internal state, agent memory, human-in-the loop, functional calling history etc. 

diff --git a/docs/docs/chat.md b/docs/docs/chat.md
@@ -1,7 +1,29 @@
-# Chat
+# AI Chat
 
-A basic chat interface like chatgpt.com or claude.ai is provided where you can select the LLM model (or multi-agent model) used for each message generation.
+Sophia provides a chat interface like chatgpt.com or claude.ai.
 
-Attachments and more features are on the roadmap.
+## LLM selection
+
+The LLM model selection can be changed over a conversation.
+
+The model selection also allows selecting the composite implementations of the LLM interface such as multi-agent debate/review implementations or
+fallbacks across multiple.
+
+## Attachments
+
+Images and PDF files can be attached to a message. However, it is required that the LLM selected supports all the file/image types
+in the new and previous messages, otherwise an error will occur.
+
+## Keyboard shortcuts
+
+- **Ctrl - M**: Open the LLM model selection
+- **Ctrl - A**: Add attachment
+- **Ctrl - I**: Open/close the chat info/settings panel
+- **Ctrl - E**: Toggle enter sends the message or adds a new line
+<!--
+- **Ctrl - C**: Toggle caching (Anthropic models only)
+-->
+
+## Screenshots
 
 ![Chats](https://public.trafficguard.ai/sophia/chat.png)
diff --git a/docs/docs/cli.md b/docs/docs/cli.md
@@ -5,6 +5,8 @@ There are two main ways to interact with the system:
 
 ## Running the server & UI
 
+Run the following commands from the sophia git repo root directory.
+
 ### Local install
 In one terminal run
 ```bash
@@ -22,16 +24,39 @@ Run `docker compose up`
 
 The UI will be available at [http://localhost:4200](http://localhost:4200)
 
-## CLI scripts
+## CLI commands
+
+## Running in Docker
+
+To run the CLI scripts when using the Docker container, run the script `./bin/container` from the repo root to first open a bash shell inside the Sophia development container.
+
+### Running outside the repository
+
+To run Sophia agents/workflows via the CLI script described below, in a folder outside the sophia repository, the script at `bin/path/ss` allows you to invoke the Sophia package.json scripts from any directory.
+
+The `bin/configure` script will update your shell configuration files to include it in your PATH.
+
+Either run the `bin/configure` script from the Sophia repository root or copy and run the required section from the script. This will add to your .bashrc and .zshrc files (if they exist) the output of:
+
+```bash
+export SOPHIA_HOME=$(pwd)
+export PATH=$SOPHIA_HOME/bin/path:$PATH
+```
+
+Then from any folder you can run commands like:
 
-To run the CLI scripts when using the Docker container, run the script `./bin/container` to open a bash shell inside the Sophia development container.
+`ss query what test frameworks does this repository use`
 
+Where *query* is the Sophia package.json script. For all the examples in the CLI scripts section above you can replace `npm run` with `ss`
+
+
+### CLI scripts
 
 There are a number of convenience scripts in the package.json for running agents and other scripts such as benchmarks, where the entrypoint file matches `/src/cli/<script-name>.ts`
 
 ### agent
 
-`npm run agent` will run the autonomous agent configured in `src/cli/agent.ts`
+`npm run agent` or `ss agent` will run the autonomous agent configured in `src/cli/agent.ts`. Note that the agent will have the functions available configured in the `agent.ts` file.
 
 If no arguments are supplied the user prompt will be read from `src/cli/agent-in`
 
@@ -44,7 +69,7 @@ npm run agent research the latest news about large language models and write a r
 
 ### code
 
-`npm run code` runs the CodeEditingAgent configured in `src/cli/code.ts`
+`npm run code` or `ss code` runs the [CodeEditingAgent](/software-engineer/) configured in `src/cli/code.ts`
 
 Without arguments the prompt is read from `src/cli/code-in` otherwise it uses the provided arguments for the prompt.
 
@@ -54,12 +79,22 @@ This is a useful for editing the sophia codebase. You could run a command like:
 npm run code In the anthropic vertex class update the pricing for claude 3.5 sonnet to be 3 dollars per million input tokens and 15 dollars per million output tokens
 ```
 
-When editing other local repositories you will need to provide the initial arg `-fs=<path>` to set the agent's virtual filesystem working 
-directory to the repository you want to edit.
+When editing other repositories you will need use the `ss` command to run the agent with its virtual filesystem working 
+directory set to the current shell directory.
+
+### index
+
+`npm run index` or `ss index`
+
+This runs the agent which indexes a repository, and stores the summary index docs under `.sophia/docs`
+
+### slack
+
+`npm run slack` or `ss slack` starts the Slack chatbot. The chatbot will have the functions available defined in `src/modules/slack/slackChatBotService.ts`
 
 ### swe
 
-`npm run swe` runs the SoftwareDeveloperAgent configured in `src/cli/swe.ts`
+`npm run swe` or `ss swe` runs the SoftwareDeveloperAgent configured in `src/cli/swe.ts`
 
 Without arguments the prompt is read from `src/cli/swe-in` otherwise it uses the provided arguments for the prompt.
 
@@ -69,7 +104,7 @@ This agent can be used for process automation and handling requests within the l
 
 ### gen
 
-`npm run gen` runs the script at `src/cli/gen.ts`
+`npm run gen` or `ss gen` runs the script at `src/cli/gen.ts`
 
 This simply generates text from a prompt. As with the other scripts you can provide arguments for a quick prompt. 
 Otherwise, prepare the prompt in `src/cli/gen-in` and don't provide any other arguments.
@@ -90,19 +125,17 @@ Make sure the directory you save the files to is in the .gitignore.
 
 ### scrape
 
-`npm run scrape <url>` runs the PublicWeb.getWebPage function which uses a headless browser to scrape a web page, and then converts
+`npm run scrape <url>` or `ss scrape <url>` runs the PublicWeb.getWebPage function which uses a headless browser to scrape a web page, and then converts
 it to a slim format by using the `@mozilla/readability` module to first extract the main contents of the page, and then the `turndown`
 package to convert the HTML to Markdown, further reducing the token count.
 
 By default, it writes the output to `scrape.md`. Alternatively you can provide an argument for the file to write to.
 
 ### query
 
-`npm run query <question>` runs the codebase query agent at *src/swe/discovery/codebaseQuery.ts* which can answer ad hoc
+`npm run query <question>` or `ss query <question>` runs the codebase query agent at *src/swe/discovery/fileSelectionAgent.ts* which can answer ad hoc
 questions about a codebase/folder contents.
 
-
-
 ## Development
 
 ### Running tests
@@ -116,25 +149,6 @@ npm run test
 ```
 
 
-
-
-## CLI usage optimizations
-
-### Helper CLI script
-
-To run Sophia agents in other folders and repositories, the script at `bin/path/ss` allows you to invoke the Sophia package.json scripts from any directory.
-
-To use this you in your shell config files (e.g. ~/.bashrc, ~/.zshrc)
-
-- Set the `SOPHIA_HOME` variable to the path of the Sophia repository.
-- Add `$SOPHIA_HOME/bin/path` to the `PATH` variable.
-
-Then from any folder you can run commands like:
-
-`ss query what test frameworks does this repository use`
-
-Where *query* is the Sophia package.json script. For all the examples in the CLI scripts section above you can replace `npm run` with `ss`
-
 ### Speech-to-text
 
 Speech-to-text is useful writing longer prompts with additional details to guide the agents.

diff --git a/docs/docs/index.md b/docs/docs/index.md
@@ -4,63 +4,36 @@
   <img src="https://public.trafficguard.ai/sophia/banner.png" alt="Sophia banner"/>
 </p>
 <p align="center">
-  <em><b>The open TypeScript platform for AI agents and LLM based workflows</b></em><br/>
+  <em><b><span style="font-size: x-large">The open TypeScript platform for AI agents, workflows & chat</span></b></em><br/>
   <small>The Ancient Greek word <em><b>sophía (σοφία)</b></em> variously translates to "clever, skillful, intelligent, wise"</small>
 </p>
 
-Sophia is a full-featured platform for developing and running agents, LLM based workflows and chatbots.
+Sophia is a full-featured platform for developing and running autonomous agents, LLM based workflows, Slack chatbots, AI chat and more.
 
 Included are capable software engineering agents, which have assisted building the platform.
 
-## Key features
+## High level features
 
 - [Advanced Autonomous agents](https://sophia.dev/autonomous-agents)
+    - Faster/cheaper actions by generated function calling code (with sandboxed execution)
+    - Complex tasks supported with memory, function call history, live files, file store etc.
+    - Cost management with configurable Human-in-the-loop settings and cost tracking
+    - Persistent state management. Restart from completion/error/human-in-loop
 - [Software developer agents](https://sophia.dev/software-engineer/)
+    - Local repository editing
+    - Ticket-to-pull request workflow
+    - Repository indexing and ad-hoc query agents
+    - Leverages [Aider](https://aider.chat/) for diff editing
 - [Pull request code review agent](https://sophia.dev/code-review/)
 - [AI chat interface](https://sophia.dev/chat/)
 - [Slack chatbot](https://sophia.dev/chatbot/)
-- Supports many LLM services - OpenAI, Anthropic (native & Vertex), Gemini, Groq, Fireworks, Together.ai, DeepSeek, Ollama, Cerebras, X.ai
+- Supports many LLM services - OpenAI, Anthropic (native & Vertex), Gemini, Groq, Fireworks, Together.ai, DeepSeek, Ollama, Cerebras, X.ai and more.
+- Simple LLM interface wrapping the [Vercel ai](https://sdk.vercel.ai/) package to add tracing and cost tracking.
 - Multi-agent [extend-reasoning implementations](https://github.com/TrafficGuard/sophia/tree/main/src/llm/multi-agent) of the LLM interface
-- Configurable Human-in-the-loop settings
 - Functional callable tools (Filesystem, Jira, Slack, Perplexity, Google Cloud, Gitlab, GitHub etc)
-- CLI and Web UI interface
-- Run locally or deployed on the cloud with multi-user/SSO
 - OpenTelemetry based observability
 - Leverages the extensive Python AI ecosystem through executing Python scripts/packages
 
-## Autonomous agents
-
-- Reasoning/planning inspired from Google's [Self-Discover](https://arxiv.org/abs/2402.03620) and other papers
-- Memory and function call history for complex workflows
-- Iterative planning with hierarchical task decomposition
-- Sandboxed execution of generated code for multi-step function calling and logic
-- LLM function schemas auto-generated from source code
-- Human-in-the-loop for budget control, agent initiated questions and error handling
-
-Full details at the [Autonomous agent docs](https://sophia.dev/autonomous-agents)
-
-## Software developer agents
-
-- Code Editing Agent for local repositories
-    - Auto-detection of project initialization, compile, test and lint
-    - Task file selection agent selects the relevant files
-    - Design agent creates the implementation plan.
-    - Code editing loop with compile, lint, test, fix (editing delegates to [Aider](https://aider.chat/))
-      - Compile error analyser can search online, add additional files and packages
-    - Final review of the changes with an additional code editing loop if required.
-- Software Engineer Agent (For ticket to Pull Request workflow):
-    - Find the appropriate repository from GitLab/GitHub
-    - Clone and create branch
-    - Call the Code Editing Agent
-    - Create merge request
-- Code Review agent:
-    - Configurable code review guidelines
-    - Posts comments on GitLab merge requests at the appropriate line with suggested changes
-- Repository ad hoc query agent
-- Codebase awareness - optional index creation used by the task file selection agent
-
-Full details at the [Software developer agents](https://sophia.dev/software-engineer/) docs.
-
 ## Flexible run/deploy options
 
 - Run from the repository or the provided Dockerfile in single user mode.

diff --git a/docs/docs/software-engineer.md b/docs/docs/software-engineer.md
@@ -1,6 +1,6 @@
 # AI Coding Agents
 
-The Sophia software/coding agents build upon the project [Aider](https://aider.chat/), providing additional layers around it for more autonomous use cases.
+The Sophia software/coding agents build upon the project [Aider](https://aider.chat/), providing additional agents around it for quality and automation.
 
 ## Code Editing Agent
 

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -39,18 +39,20 @@ nav:
       - 'Setup': setup.md
       - 'CLI': cli.md
       - 'Environment variables': environment-variables.md
-      - 'Observability': observability.md
-  - Concepts:
-    - functions.md
-    - agent-concepts.md
+      - 'Observability / Tracing': observability.md
+      - 'LLMs': llms.md
   - Agents:
+    - agent-concepts.md
     - autonomous-agents.md
     - software-engineer.md
     - code-review.md
-    - chatbot.md
     - examples.md
-  - integrations.md
-  - chat.md
+  - Function Calling:
+    - functions.md
+    - integrations.md
+  - Chat:
+    - chat.md
+    - chatbot.md
   - roadmap.md
   - Blog:
       - blog/index.md