Python CGOS Client

This client connects Go programs that implement the GTP protocol to the Computer Go Server (CGOS). If you downloaded this, you know what they are. Any GTP engine is supported, not just those written in Python.

Information

Please read the change log.

For the avoidance of doubt: this licence makes no claim whatsoever about the Go programs used with this client, in particular any programs using this client to connect to CGOS shall not meet the definition of a "covered work", or derivative work, under this license.

The CGOS server and TCL client are © Don Daily and others and are not included here.

Features
Usage
GTP
- GTP Commands
- GTP Extensions
Configuration

Features

Features in common with standard CGOS TCL client:

Textual configuration file
Waits for server restart when server crashes or is unreachable (checks every 30 seconds + small random amount)
Supports resume if the engine crashes. Just restart the client and it will catch up the game.
Kill file to terminate connections
Supports multiple engines, and automatic switching (but the behaviour is slightly different)

Additional features:

Local SGF persistence (with move times and results)
Support for observers. Any GTP engine or display, like GoGUI, can be used to observe games locally.
GTP extensions that can help with your engine's logging
Separate detailed logging files for: CGOS, the engine and the observer (if any). Standard output stream logging at high level for user observation.
From time to time, shows some stats: uptime, games won, games lost. May be expanded with e-mail notification in the future.

Features not yet supported:

Engine switching is not yet supported

Usage

Developed on Python 2.6, no extensions required. It may work on Python 2.5, but that is not tested. If you are using Windows, get the package from here, it's a good standalone installer. You will have to provide a configuration file. See sample.cfg for an example, or see below. Run the client using:

# Windows
C:\Python26\Python bin\cgosclient.py config.cfg

# Unix		
python bin/cgosclient.py config.cfg

To kill the client, please place a "kill file" in the location you specified in the configuration file. You may of course kill the process, too, but the kill file will ensure that you will finish the current game and log off nicely. After the engine quits, the kill file will be deleted.

Note: If a kill file is put in place, the client will quit ASAP if it is not currently in a game. In practice, this means when the next status message is received by the server, usually within a minute.

GTP Commands

Playing engines need the following GTP commands:

Mandatory: list_commands, boardsize, clear_board, komi, play, genmove, quit
Optional: time_left, time_settings

If the time commands are missing, no time control instructions will be passed to the engine. Further notes:

time_left will always be sent immediately before genmove, as with the TCL client
quit: if your engine or observer takes too long to respond, it will be sent a terminate signal to make sure it does not get up anymore

GTP Extensions

The following GTP extensions are available. If your engine records its own logs, or writes its own SGF records with analysis information in them, you may find them useful.

Command When Called Meaning

cgos-opponent_name Between boardsize and first move Gives the name of the opponent engine (the CGOS login name)

cgos-gameover After two passes, resignation or illegal move Final result as reported by the server. Will be in format required by SGF RE property, meaning:

B+{score} or W+{score}, e.g. B+0.5, or
B+Resign or W+Resign, or
B+Time or W+Time, or
B+Forfeit or W+Forfeit

Command	When Called	Meaning
cgos-opponent_name	Between boardsize and first move	Gives the name of the opponent engine (the CGOS login name)
cgos-gameover	After two passes, resignation or illegal move	Final result as reported by the server. Will be in format required by SGF RE property, meaning: `B+{score}` or `W+{score}`, e.g. `B+0.5`, or `B+Resign` or `W+Resign`, or `B+Time` or `W+Time`, or `B+Forfeit` or `W+Forfeit`

Logging

The client will produce the following log files at debug level - standard output stream logging is at info level or higher only:

engine.log - Log of GTP command stream to and from the engine
cgos.log - Client/server command stream
observer.log - Log of GTP stream to observer GTP engine, if any

All of these log files are set up as rolling files that be renamed engine.log.1, and so on, when they get beyond 2MB. A maximum of 5 rolling log files is kept.

Displaying Games Using GoGUI

The Python CGOS client can stream the GTP command stream to a secondary engine called an "observer" engine. It is up to you how you use this, for example:

You could run a secondary copy of your program and show move evaluations
You can run GoGUI and get a local view of what your program is doing when it is playing. This means that a) you do not have to connect using the server viewing client and b) you save the server a bit of work.

First, download GoGUI from gogui.sourceforge.net. Next, make sure you use gogui-display as an observer in your configuration file, like so in Windows:

GTPObserver:
    CommandLine = C:\Program Files\Java\jdk1.6.0_13\bin\java.exe -jar C:\path\to\gogui-1.1.9\lib\gogui-display.jar

Please do not use javaw.exe, stick with java.exe, or the input stream to gogui-display will be cut off. In Linux:

GTPObserver:
    CommandLine = /usr/bin/java -jar /path/to/gogui-1.1.9/lib/gogui-display.jar

Either way, please note that if you close the GoGUI window, the client will think the observer engine crashed and terminate your connection. You will then have to restart to resume your game. If you wish to stop displaying, put a kill file in place (see above), then start the client again without an observer.

Alternating Between Multiple Engines

In the configuration file, each GTP engine has an attribute called NumberOfGames. This attribute is mandatory in this version of the client, even if there is only one engine, though in the case of one engine it is ignored. Multiple GTP engines are played sequentially in a round-robin fashion. For example, if NumberOfGames is set to 2 for EngineA and to 3 for EngineB, the client will play the engines as follows:

Game Engine

1 EngineA

2 EngineA

3 EngineB

4 EngineB

5 EngineB

6 EngineA

7 EngineA

8 EngineB

9 ...

Game	Engine
1	EngineA
2	EngineA
3	EngineB
4	EngineB
5	EngineB
6	EngineA
7	EngineA
8	EngineB
9	...

Recommendations:

If you are planning to play for a long time (e.g. a day or longer of 9x9), set the game counts to five or higher. This minimises the number of reconnects and restarts that have to be performed.
If your engines leak memory, set it lower - but set up at least two engines or the attribute will be ignored.

Sample Configuration

This sample configuration shows how GNU Go can be connected to play on CGOS, 9x9 board size, and with GoGUI running locally to view all games. In addition, the client will play round-robin between two engine configurations, running the engine at level 8 for 5 games, followed by level 10 for 2 games, and then starting over.

Common:
  KillFile = kill.txt
  
GTPEngine:
  # Name to display on console / in logs
  Name = Gnugo Level 8
  
  CommandLine = gnugo.exe --mode gtp --score aftermath --capture-all-dead --chinese-rules --level 8
  
  ServerHost = cgos.boardspace.net
  ServerPort = 6867
  ServerUser = myuser
  ServerPassword = mypw
  
  # Switch to next engine after this many games
  NumberOfGames = 5
  
  # Optional: persist games here
  SGFDirectory = ..\sgf9x9
  
GTPEngine:
  Name = Gnugo Level 10
  CommandLine = gnugo.exe --mode gtp --score aftermath --capture-all-dead --chinese-rules --level 10
  
  ServerHost = cgos.boardspace.net
  ServerPort = 6867
  ServerUser = myuser-level10
  ServerPassword = mypw-level10
  
  # Switch back to first engine after this many games
  NumberOfGames = 2
  
  # Optional: persist games here
  SGFDirectory = ..\sgf9x9
  
   
# Observer engine (e.g. GoGUI)
GTPObserver:
  CommandLine = C:\Program Files\Java\jdk1.6.0_13\bin\java.exe -jar C:\path\to\gogui-1.1.9\lib\gogui-display.jar