Metadata-Version: 2.3
Name: ai-nk-cce
Version: 0.2.0
Summary: This repository is used to train AI agents to predict good strategies in a social learning game based on a NK landscape.
Author: Luis Mienhardt
Author-email: mienhardt@mpib-berlin.mpg.de
Requires-Python: >=3.10,<4.0
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
Requires-Dist: dataframe-image (>=0.2.7,<0.3.0)
Requires-Dist: evaluate (>=0.4.3,<0.5.0)
Requires-Dist: matplotlib (>=3.9.2,<4.0.0)
Requires-Dist: networkx (>=3.4.2,<4.0.0)
Requires-Dist: numpy (>=1.26.0,<2.0.0)
Requires-Dist: openai (>=1.52.0,<2.0.0)
Requires-Dist: pandas (>=2.2.3,<3.0.0)
Requires-Dist: pydantic (>=2.0.0,<3.0.0)
Requires-Dist: python-dotenv (>=1.0.1,<2.0.0)
Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
Requires-Dist: scikit-learn (>=1.5.2,<2.0.0)
Requires-Dist: tiktoken (>=0.8.0,<0.9.0)
Requires-Dist: tqdm (>=4.66.0,<5.0.0)
Description-Content-Type: text/markdown

# human-ai-social-learning

[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![PEP8](https://img.shields.io/badge/code%20style-pep8-orange.svg)](https://www.python.org/dev/peps/pep-0008/)

## Description

## Installation

This project uses Poetry for package management. If you haven't installed Poetry yet, please follow the instructions on the [official Poetry website](https://python-poetry.org/docs/#installation).

To install the project:

1. Clone the repository:

   ```bash
   git clone https://github.com/your-username/human-ai-social-learning.git
   cd human-ai-social-learning
   ```

2. Install dependencies with Poetry:

   ```bash
   poetry install
   ```

3. Activate the virtual environment:

   ```bash
   poetry shell
   ```

4. (Optional) Set up Jupyter kernel for notebooks:

   ```bash
   poetry run python -m ipykernel install --user --name nk-cce-kernel
   ```

Now your development environment is set up and ready to use.

### Environment Setup (Optional)

For features that use external APIs, copy `.env.example` to `.env` and fill in
values:

```bash
cp .env.example .env
```

The project uses `python-dotenv` to load `.env`. Keys:

| Variable | Purpose |
|----------|---------|
| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI API endpoint URL |
| `AZURE_OPENAI_API_KEY` | Azure OpenAI API key |
| `HUGGINGFACE_TOKEN` | Hugging Face token (e.g. for `evaluate`) |
| `WANDB_API_KEY` | Weights & Biases API key |

- **Azure OpenAI**: LLM-based agents or API calls.
- **Hugging Face**: If using `evaluate` or HF-hosted models.
- **W&B**: Experiment tracking and logging.

Core simulation (hill climber, BiasedPredictionAgent, fake AI test) does not
require these keys.

## Contributing

We welcome contributions! Please note:

1. Please create a descriptive branch for each contribution (naming convention *feature_type/feature_name*)
2. Follow the project style (PEP 8 for Python).
3. Add tests and run all before commit. (At least one test per function or method.)
4. Write meaningful commit messages.
5. Keep in line with pre-commit linting.
6. Submit a Pull Request, to include your code into main.

### Pre-commit Hooks

We use pre-commit hooks. Installation:

```bash
poetry add pre-commit
pre-commit install
pre-commit run --all-files
```

### Running Tests

Tests need to be run in the virtual environment. You can use Poetry or Visual Studio Code settings to do so automatically.

To run all tests using Poetry run:

```bash
poetry run pytest
```

We included Visual Studio Code settings in the repository.
You can try to use them to run the tests within Visual Studio Code.

```text
.vscode/
├── settings.json
├── launch.json
```

## Documentation

- [Repository structure](doc/repository_structure.md) – modules, tests, dependencies
- [Simulation](doc/simulation.md) – hill climber, landscape selection, fake AI test
- [Evals](doc/evals.md) – NK landscape evaluation
- [Formal models](doc/formal_models/README.md) – oracle, biased prediction agent
- [Notebooks index](doc/notebooks_index.md) – all notebooks, purpose, how to run
- [Find average hill climber landscape](doc/how_to_find_average_hill_climber_landscape.md)
- [Run simulation](doc/how_to_run_simulation.md)
- [Data layout](doc/data_layout.md)

