Merge remote-tracking branch 'origin/main' into feature/realtime-api

.github/workflows/publish-to-pypi.yml

@@ -22,6 +22,9 @@ permissions:
 jobs:
   release:
     runs-on: ubuntu-latest
+    permissions:
+      # For PyPI's trusted publishing.
+      id-token: write
 
     steps:
     - uses: actions/checkout@v3

docs/pages/experimental/agents.mdx

@@ -35,8 +35,9 @@ class SimpleEchoAgent(BaseAgent[Text, Text]):
 ```
 
 Let me break this down for you:
-1. `NodeFactory` is a decorator that registers the agent so that it can be used in the dataflow. dataflow is a concept in `aact` that defines how `nodes` are interacting with each other.
-2. Inherit the `BaseAgent` class and specify the input and output channel types in the constructor.
-3. Implement the `aact` method that takes an `Observation` object as input and returns an `AgentAction` object as output. In this case, the agent always says "Hello, ..."
+1. `NodeFactory` is a decorator that registers the agent so that it can be used in the dataflow. Dataflow is a concept in `aact` that defines how `nodes` are interacting with each other.
+2. `channel` is a concept in `redis` pubsub and `aact`. A node can send messages to many channels, and receive messages many channels as well. To subclass `BaseAgent`, you will need to feed two lists of channel-message type pairs to `input_channel_types` and `output_channel_types` respectively.
+3. Inherit the `BaseAgent` class and specify the input and output channel types in the constructor.
+4. Implement the `aact` method that takes an `Observation` object as input and returns an `AgentAction` object as output. In this case, the agent always says "Hello, ..."
 
 For a running example, try out `examples/experimental/tick_and_echo_agents`.

docs/pages/index.mdx

@@ -19,7 +19,7 @@ import { Tabs, TabsContent, TabsList, TabsTrigger } from "../components/ui/tabs"
 </Callout>
 
 Train, deploy, and evaluate Social AI agents
-with <span className="font-display text-xl">Sotopia</span>
+with <Link href="https://sotopia.world/"><span className="font-display text-xl">Sotopia</span></Link>
 
 ## Features
 
@@ -70,6 +70,11 @@ with <span className="font-display text-xl">Sotopia</span>
 </Accordion>
 
 
+## Why Sotopia?
+Sotopia aims at pushing the boundary of artificial social intelligence through simulating realistic social interaction, supporting human-AI interaction, and evaluating the performance of social agents in a unified way.
+
+**Unlike** other multi-agent frameworks ([CrewAI](https://www.crewai.com/), [CAMEL-AI](https://www.camel-ai.org/), [AutoGen](https://microsoft.github.io/autogen/dev/index.html), and [swarm](https://github.com/openai/swarm)), Sotopia provides a wide range of social tasks and characters with different backgrounds and personalities, and creates a asynchronous and information-imperfect social interaction environment.
+
 
 ## Installation
 This package supports Python 3.10 and above. There are two ways to setup the package:

examples/experimental/tick_and_echo_agents/readme.md

@@ -1,5 +1,79 @@
+# Simple example of custom agents
+In this example, we consider two super simple agents:
+
+- Simple Tick Agent: send out a text message at each second.
+- Simple Echo Agent: reply the text message with "Hello, (received message)"
+
+## Implementation of the agents
+You can find the implmentation of the above agents in `tick_and_echo_agents.py`.
+The documentation for creating these agents is [here](https://docs.sotopia.world/experimental/agents). This will not be focus of this example.
+
+## Assemble the agents in the dataflow file
+Dataflow file is used in `aact` to configurate dataflow with writing Python code.
+You can think of the implementation of each node as the LEGO pieces, and the dataflow file as the building instruction manual.
+
+To assemble the two agents above, you can add the following lines to the dataflow file:
+
+```toml
+[[nodes]]
+node_name = "tick_agent" # a unique and arbitrary name in the dataflow
+node_class = "simple_tick_agent" # the class alias
+
+[nodes.node_args] # arguments for the agent's __init__
+input_channel = "tick/secs/1"
+output_channel = "tick"
+```
+
+Similar to the above, you can also create the `echo_agent`.
+
+## Auxiliary nodes
+
+Apart from the agents, there are two auxiliary nodes that you can use immediately (without writing Python code for them).
+
+```toml
+# tick node provides a stable clock for the tick agent
+[[nodes]]
+node_name = "tick"
+node_class = "tick"
+
+# print node lets you view the realtime messages in your channel
+[[nodes]]
+node_name = "print"
+node_class = "print"
+
+[nodes.node_args.print_channel_types]
+# These are all the channels in this example, you can also just print out some of them
+"tick/secs/1" = "tick"
+"tick" = "text"
+"echo_tick" = "text"
+```
+
+## Run this example
+### Prerequisite
+Redis hosted at `localhost:6379`. You would need to update the url in the tick_and_echo_agents.toml if you want to use a different redis database.
+
+### Command
 To run this example, please use aact to launch.
 
 ```bash
 uv run aact run-dataflow examples/experimental/tick_and_echo_agents/tick_and_echo_agents.toml
 ```
+
+## What you can expect to see
+You will see lines of json strings printed out, each of which is a message between the nodes. The following six lines
+```json
+{"timestamp":"2024-10-14T15:23:53.876886","channel":"tick/secs/1","data":{"data_type":"tick","tick":0}}
+{"timestamp":"2024-10-14T15:23:53.878931","channel":"tick","data":{"data_type":"text","text":"Tick 0"}}
+{"timestamp":"2024-10-14T15:23:53.882522","channel":"echo_tick","data":{"data_type":"text","text":"Hello, Tick 0!"}}
+{"timestamp":"2024-10-14T15:23:54.878441","channel":"tick/secs/1","data":{"data_type":"tick","tick":1}}
+{"timestamp":"2024-10-14T15:23:54.880346","channel":"tick","data":{"data_type":"text","text":"Tick 1"}}
+{"timestamp":"2024-10-14T15:23:54.881737","channel":"echo_tick","data":{"data_type":"text","text":"Hello, Tick 1!"}}
+```
+shows the following events:
+
+1. tick node ticks
+2. tick agent received the tick and output a message "Tick 0"
+3. echo agent received the message and echo "Hello, Tick 0!"
+4. 1-3 are repeated.
+
+Each of the message has its timestamp for easy debugging and data recording. You can see that on a normal laptop the latency between nodes reacting to the message is around 1-2 ms, which is often fast enough for real time applications.

sotopia/cli/install/install.py

@@ -169,7 +169,7 @@ def install(
 
     if use_docker:
         try:
-            subprocess.check_output("command -v docker", shell=True)
+            subprocess.check_output("docker --version", shell=True)
         except subprocess.CalledProcessError:
             if system == "Darwin":
                 console.log(

sotopia/generation_utils/generate.py

@@ -56,6 +56,8 @@
     "redis",
     "groq/llama3-70b-8192",
 ]
+# subject to future OpenAI changes
+DEFAULT_BAD_OUTPUT_PROCESS_MODEL = "gpt-4o-mini"
 
 OutputType = TypeVar("OutputType", bound=object)
 

tests/tests.sh

@@ -1 +1 @@
-docker compose -f .devcontainer/docker-compose.yml  run --rm -u root -v $(pwd):/workspaces/sotopia devcontainer /bin/sh -c "export UV_PROJECT_ENVIRONMENT=/workspaces/.venv; cd /workspaces/sotopia; uv run --extra test --extra chat pytest --ignore tests/cli"
+docker compose -f .devcontainer/docker-compose.yml  run --rm -u root -v $(pwd):/workspaces/sotopia devcontainer /bin/sh -c "export UV_PROJECT_ENVIRONMENT=/workspaces/.venv; cd /workspaces/sotopia; uv run --extra test --extra chat pytest tests/experimental"