Metadata-Version: 2.4
Name: iceorb
Version: 1.1.0
Summary: Ice Orb multi-agent system for open-ended wargames with large language models
License: Apache-2.0
License-File: LICENSE
Author: Daniel Hogan
Author-email: 6313241+dphogan@users.noreply.github.com
Requires-Python: >=3.10
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: accelerate
Requires-Dist: fastapi
Requires-Dist: jupyter
Requires-Dist: langchain
Requires-Dist: langchain-chroma
Requires-Dist: langchain-community
Requires-Dist: langchain-huggingface
Requires-Dist: langchain-openai
Requires-Dist: langchain-text-splitters
Requires-Dist: langgraph
Requires-Dist: llama-cpp-python (>=0.3.8)
Requires-Dist: markdown2
Requires-Dist: nicegui
Requires-Dist: numpy
Requires-Dist: openai
Requires-Dist: platformdirs
Requires-Dist: pydantic
Requires-Dist: pyyaml
Requires-Dist: torch
Requires-Dist: torchvision
Requires-Dist: tqdm
Requires-Dist: transformers
Requires-Dist: twine
Requires-Dist: unstructured
Requires-Dist: uvicorn
Requires-Dist: watchfiles
Project-URL: Homepage, https://github.com/dphogan/iceorb
Description-Content-Type: text/markdown

# Ice Orb
***Open-Ended Wargames with Large Language Models***

Ice Orb uses large language models (LLMs) for automated play of "open-ended" text-based wargames, such as seminar games and political wargames.  LLMs enable a light, flexible architecture in which player actions are not restricted to predefined options.  The system allows humans to play against or alongside AI agents with specific personas.  Every stage of the wargame from scenario preparation to post-game analysis can be optionally carried out by AI, humans, or a combination thereof.

Ice Orb is based on Snow Globe, which is described [here](https://arxiv.org/abs/2404.11446).

## Installation

Build the Docker image and run a container.

```
./docker_setup.sh
```

Or, install Ice Orb from PyPI.  For CPU only:

```
pip install iceorb
```

For GPU support:

```
CMAKE_ARGS="-DGGML_CUDA=on" pip install iceorb
```

## AI Simulations

After installation, you can simulate a tabletop exercise about an AI incident response.

```
examples/haiwire.py
```

Or, simulate a political wargame about a geopolitical crisis.

```
examples/ac_sim.py
```

## Human+AI Wargames

To play a game between a human and an AI player, launch the server and start a game:

```
iceorb_server &
examples/ac_game.py
```

Then, open a browser window and navigate to:

```
http://localhost:8000
```

The terminal output will begin with the ID number for the human player.  Type that number into the ID box in the browser window and click `Log In`.

Make sure to run `iceorb_server` from the same file system location where you run the game.  Game-related files will be stored in that location.

## Custom Games

By default, Ice Orb uses a light LLM that runs locally.  For better results, try the OpenAI API:
- Create an environment variable called `OPENAI_API_KEY` with your OpenAI API key in it.  In a bash shell, for example: `export OPENAI_API_KEY=your0key0here`
- In the example game you want to use with OpenAI, find the line that says `super().__init__()` and change it to this: `super().__init__(source='openai', model='gpt-4o')` or similarly for whatever model you want to try.

Beyond that, you can use the examples as starting points for developing your own games, or you can create entirely new game formats using the Python classes provided by Ice Orb.

## License

This repo is released under the [Apache License Version 2.0](LICENSE), except for [jQuery](src/iceorb/terminal/jquery-3.7.1.min.js) which is released under the [MIT License](https://github.com/jquery/jquery/blob/main/LICENSE.txt).

