Skip to main content

AI Server Developer Guide

Welcome to the Synthergy AI server developer guide! This page is designed to help you get started on contributing to the AI server component of the project.

Project Repository​

The AI server for Synthergy is hosted in the synthergy-ai repository on GitHub. This repository contains all of the code needed to run the AI server on your local machine.

To access the repository, you will need to join the synthergy-game organization on GitHub. Once you have been added to the organization, you will be able to clone the repository and start contributing.

Project Structure​

The AI server is built using Python, Flask, and LangChain. The project structure is as follows:

synthergy-ai/
├── src/
│   ├── actions.py       # Constants for actions players can take
│   ├── agent.py         # Agent class for managing AI players
│   ├── agent_socket.py  # Socket.io interface for AI players
│   ├── events.py        # Constants for Socket.io events
│   ├── factions.py      # Constants for player factions
│   ├── game_state.py    # Game state type definitions
│   ├── lobby.py         # Lobby state type definitions
│   ├── message.py       # Message constants and type definitions
│   ├── model.py         # Functions for interfacing with OpenAI models
│   ├── phases.py        # Constants for game phases
│   ├── roles.py         # Constants for player roles
│   ├── schemas.py       # Pydantic schemas for LangChain data validation
│   ├── server.py        # Flask server entry point
│   ├── util.py          # Utility functions

Running the Project​

To get started with the AI server, follow these steps:

  1. Clone the synthergy-ai repository.
  2. Install the project dependencies by running pip install -r requirements.txt in the project directory.
  3. Create a file named .env in the project directory with the following content:
    • OPENAI_API_KEY=your_openai_api_key
    • Replace your_openai_api_key with your OpenAI API key.
  4. Start the server by running python src/server.py

The server should now be running on http://localhost:5000! You won't be able to access the server directly in your browser, but you can follow the steps below to summon AI players to join games.

Summoning AI Players​

Once the AI server is running, you can summon AI players to games by querying the /ai/add_agents endpoint with a POST request. The request JSON body should include the following parameters:

  • lobby_code: The lobby code of the game the AI players should join.
  • num_agents: The number of AI players to add to the game.

Here's an example request using curl:

curl -X POST http://localhost:5000/ai/add_agents -H "Content-Type: application/json" -d '{"lobby_code": "A1B2", "num_agents": 3}'

This request will add 3 AI players to the game lobby with the code A1B2, who will then participate in the game once it starts.

Notes:

  • The AI players will connect to a lobby on the production server by default. You can modify the url parameter of the Socket class in agent_socket.py to connect to a different game server (e.g., a local development server).
  • Any empty slots in the game lobby will be filled with AI players from the production server when the game starts. To prevent this, make sure to fill all slots with human players or your AI players before starting the game.

Running the Linter​

The AI server uses GitHub Actions for continuous integration. This means that every pull request will be automatically run against the project's linter to ensure that the changes do not introduce any new bugs or issues. To avoid any issues with your pull request, make sure to run the tests and linter locally before pushing your changes:

# Install mypy (if not already installed)
pip install mypy
# Run the linter
mypy .

Contributing​

Please refer to the contributing guide for information on how to make contributions on GitHub.

Resources​