Metadata-Version: 2.4
Name: dcs-simulation-engine
Version: 0.4.0
Summary: A textual environment for simulating diverse cognitive systems.
Author-email: dcs <dcs@psych.gatech.edu>
License-Expression: MIT
Project-URL: Homepage, https://github.com/diverse-cognitive-systems-group/dcs-simulation-engine
Project-URL: Issues, https://github.com/diverse-cognitive-systems-group/dcs-simulation-engine/issues
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: bcrypt<5.0.0,>=4.0.0
Requires-Dist: dotenv<0.10.0,>=0.9.9
Requires-Dist: fastapi<1.0.0,>=0.118.0
Requires-Dist: httpx<0.29.0,>=0.28.1
Requires-Dist: jinja2<4.0,>=3.0
Requires-Dist: loguru<0.8.0,>=0.7.3
Requires-Dist: matplotlib>=3.10.8
Requires-Dist: numpy>=2.3.5
Requires-Dist: openai<2.0.0,>=1.99.9
Requires-Dist: packaging>=26.0
Requires-Dist: pandas>=3.0.1
Requires-Dist: plotly>=6.6.0
Requires-Dist: pydantic<3.0.0,>=2.11.9
Requires-Dist: pymongo<5.0.0,>=4.15.3
Requires-Dist: pyyaml<7.0.0,>=6.0.2
Requires-Dist: rich<15.0.0,>=14.1.0
Requires-Dist: seaborn>=0.13.2
Requires-Dist: typer>=0.24.1
Requires-Dist: uvicorn[standard]<0.38.0,>=0.37.0
Requires-Dist: uvloop<0.23.0,>=0.22.1
Requires-Dist: websockets<17.0,>=16.0
Provides-Extra: dev
Requires-Dist: httpx<0.29.0,>=0.28.1; extra == "dev"
Requires-Dist: ipykernel<7.0.0,>=6.30.1; extra == "dev"
Requires-Dist: jupyter<2.0.0,>=1.1.1; extra == "dev"
Requires-Dist: mkdocs-material<10.0.0,>=9.6.19; extra == "dev"
Requires-Dist: mkdocs<2.0.0,>=1.6.1; extra == "dev"
Requires-Dist: mkdocstrings[python]<0.31.0,>=0.30.0; extra == "dev"
Requires-Dist: mongomock<5.0.0,>=4.3.0; extra == "dev"
Requires-Dist: mypy<2.0.0,>=1.17.1; extra == "dev"
Requires-Dist: plotly>=6.6.0; extra == "dev"
Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
Requires-Dist: pytest<10.0.0,>=9.0.3; extra == "dev"
Requires-Dist: ruff<0.13.0,>=0.12.10; extra == "dev"
Requires-Dist: types-pyyaml>=6.0.12.20250822; extra == "dev"
Requires-Dist: yamale<7.0.0,>=6.0.0; extra == "dev"
Provides-Extra: notebooks
Requires-Dist: ipykernel>=6.31.0; extra == "notebooks"
Requires-Dist: itables>=2.7.0; extra == "notebooks"
Requires-Dist: jupyter>=1.1.1; extra == "notebooks"
Requires-Dist: matplotlib>=3.10.8; extra == "notebooks"
Requires-Dist: networkx>=3.6.1; extra == "notebooks"
Requires-Dist: pandas>=3.0.1; extra == "notebooks"
Requires-Dist: plotly>=6.6.0; extra == "notebooks"
Requires-Dist: scikit-learn>=1.8.0; extra == "notebooks"
Requires-Dist: seaborn>=0.13.2; extra == "notebooks"
Requires-Dist: sentence-transformers>=5.2.3; extra == "notebooks"
Dynamic: license-file

# Diverse Cognitive Systems (DCS) Simulation Engine 

*A playground for interacting with diverse cognitive systems.*

<a href="https://dcs-demo-ui.fly.dev" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/UI%20Demo-blue" alt="UI Demo"></a>
<a href="https://dcs-demo-api.fly.dev/docs" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/API%20Demo-blue" alt="API Demo"></a>
<a href="https://diverse-cognitive-systems-group.github.io/dcs-simulation-engine/" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/Docs-blue" alt="Documentation"></a>
[![Build Status](https://github.com/diverse-cognitive-systems-group/dcs-simulation-engine/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/diverse-cognitive-systems-group/dcs-simulation-engine/actions/workflows/ci.yml)

## What is this?

A gameplay framework for interacting with diverse cognitive systems, including neurodivergent humans, artificial intelligences, and hybrid systems.

![RPG-style DCS-SE gameplay](docs/assets/full-turn.gif)

Users configure the engine with games, scenarios, objectives, characters, and environments, then run simulations through various clients (such as a web UI for human players).

Within a collaborative improvisational environment, player characters and other simulated characters interact as a cast with distinct abilities, goals, and cognitive profiles. Interaction unfolds primarily through language — including action, imagination, communication, and world-building — in a format inspired by tabletop roleplaying games.

## How can I use it?

### Try web demo instantly (no setup)
[👉 Web Demo](https://dcs-demo-ui.fly.dev) for a time and rate limited version of the engine. No setup required.

### Quickstart
Alternatively, you can run the engine from your computer with your own API keys. 

#### 1. Install the package

```sh
pip install dcs-simulation-engine

# use --help after any dcs command to see usage info
dcs --help
```

#### 2. Set up API keys

Add your API keys to a local .env file or set them as environment variables. See `.env.example`.

#### 3. Run the engine

The first time you try and run it you will be prompted for your API keys if you haven't set them up in the `.env` file yet. You will also need to install [Docker](https://docs.docker.com/engine/install/) if you haven't already - the engine uses Docker containers to run the simulations.

```sh
dcs engine start --config examples/run_configs/demo.yml
```

Users can design, run, and deploy custom engine configurations—including their own games and characters.

[👉 Usage](https://diverse-cognitive-systems-group.github.io/dcs-simulation-engine/user_guide/overview.html) for the full user guide.

### Features

| Item | Supported | Notes |
|------|----------|------|
| Easy setup (pip, setup, run) | ✅ | Minimal friction onboarding |
| Out-of-the-box platform support | ✅ | Includes: built-in games & characters, default React web UI, autoplay client, local + Fly.io runs, reporting & analytics |
| Headless / modular usage | ✅ | Engine can run without default clients or deployment stack |
| Custom deployments & providers | ✅ | Containerized; deploy anywhere, plug in custom infra/UI |
| YAML run configurations | ✅ | Reproducible, config-driven runs |
| Configurable game parameters | ✅ | Optional game-specific configurations |
| Dev workflows & container | ✅ | Extensible + consistent onboarding |
| Example workflows | ✅ | Provided in `examples/` |
| Python game classes | ✅ | Flexible, expressive game logic |
| Game lifecycle validation | ✅ | Setup, step, finish, score |
| Python runtime performance | ⚠️ | Not ideal for ultra low-latency use cases; performant AI |

See <a href="https://diverse-cognitive-systems-group.github.io/dcs-simulation-engine/" target="_blank" rel="noopener noreferrer">docs</a> for more details on features, usage, and development.

---

_Developed and maintained by the Diverse Cognitive Systems (DCS) group at [Georgia Tech](https://www.gatech.edu/), within the [Sonification Lab](http://sonify.psych.gatech.edu/). Contact: [dcs@psych.gatech.edu](mailto:dcs@psych.gatech.edu)._
