ai-nk-cce 0.2.0

This repository is used to train AI agents to predict good strategies in a social learning game based on a NK landscape.

human-ai-social-learning

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.

To install the project:

1. Clone the repository:

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

2. Install dependencies with Poetry:

   poetry install
   

3. Activate the virtual environment:

   poetry shell
   

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

   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:

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:

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:

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.

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

Documentation

• Repository structure – modules, tests, dependencies
• Simulation – hill climber, landscape selection, fake AI test
• Evals – NK landscape evaluation
• Formal models – oracle, biased prediction agent
• Notebooks index – all notebooks, purpose, how to run
• Find average hill climber landscape
• Run simulation
• Data layout