Sovereign 8s.is mirror of standardgalactic/algorithmic-institutions
  • Python 95.6%
  • Shell 2.8%
  • HTML 1.6%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
cemrtkn 25fb7c0238 Restore autoresearch.md to the pre-copula reference stack
- reference stack back to plain lin_multinomial after the PR #146
  revert; baselines back to rows <= 1 11/21, mean 1.76
- section 6 points at the 23_stack_sweep_updated sweep (32 stacks)
  again; PD is a failing punisher row once more
- the band-upgrade success rule (f81d9b7) is unchanged
- keeps the section 3 slot/model/artifact table, now with the plain
  multinomial punisher and the 23_2g8a_self reference sim config

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-18 12:00:39 +02:00
.claude Update skill definitions for cluster commands 2026-04-29 14:49:25 +02:00
artifacts Revert "Merge pull request #146 from center-for-humans-and-machines/auto/punisher-severity-copula" 2026-08-18 11:59:37 +02:00
configs Revert "Merge pull request #146 from center-for-humans-and-machines/auto/punisher-severity-copula" 2026-08-18 11:59:37 +02:00
doc Archive completed plans (#103, #114, #119) 2026-08-06 15:48:05 +02:00
experiment_analysis exp 2 analysis 2025-09-17 16:30:30 +02:00
experiments Clean stale configs, pilot-era data, and dead code 2026-08-11 11:02:51 +02:00
notes Restore autoresearch.md to the pre-copula reference stack 2026-08-18 12:00:39 +02:00
plots Revert "Merge pull request #146 from center-for-humans-and-machines/auto/punisher-severity-copula" 2026-08-18 11:59:37 +02:00
reports Update CLAUDE.md and README for the current pipeline 2026-08-06 15:32:50 +02:00
run Add group_payoff_round config and regression test step to plan 2026-03-09 11:54:57 +01:00
scripts Revert "Merge pull request #146 from center-for-humans-and-machines/auto/punisher-severity-copula" 2026-08-18 11:59:37 +02:00
src/aimanager Revert "Merge pull request #146 from center-for-humans-and-machines/auto/punisher-severity-copula" 2026-08-18 11:59:37 +02:00
tests/baselines Revert "Merge pull request #146 from center-for-humans-and-machines/auto/punisher-severity-copula" 2026-08-18 11:59:37 +02:00
.artifactinclude Fix simulation configs and trim .artifactinclude 2026-03-17 15:47:25 +03:00
.env.example Plumb wandb env vars into training SLURM templates 2026-04-22 12:02:29 +02:00
.gitattributes Add dev data. 2022-03-22 11:35:25 +01:00
.gitignore Add evaluation-suite conversion layer (#128) 2026-07-28 14:12:06 +02:00
.pre-commit-config.yaml Remove the legacy notebooks and the djx submodule 2026-08-06 15:57:02 +02:00
.python-version add uv package manager 2026-01-07 13:18:59 +01:00
CLAUDE.md Remove the legacy notebooks and the djx submodule 2026-08-06 15:57:02 +02:00
pyproject.toml Clean stale configs, pilot-era data, and dead code 2026-08-11 11:02:51 +02:00
README.md Trim stale workflow docs and round out the pipeline references 2026-08-06 15:41:37 +02:00
uv.lock Clean stale configs, pilot-era data, and dead code 2026-08-11 11:02:51 +02:00

Setup

Clone repository

git clone git@github.com:center-for-humans-and-machines/algorithmic-institutions.git

Install main package

0. Installing uv

It is advised to use uv as the virtual environment manager. Install uv if you don't have it already:

curl -LsSf https://astral.sh/uv/install.sh | sh

check also uv installation instructions

1. Create and activate virtual environment

The project uses platform-based environment markers in pyproject.toml:

  • Linux: Installs torch==1.11.0+cu113 with CUDA support and PyTorch Geometric subpackages (torch-scatter, torch-sparse, torch-cluster, torch-spline-conv, torch-geometric).
  • Non-Linux (macOS, Windows): Installs torch==1.11.0 (CPU-only) from PyPI without PyTorch Geometric subpackages.

Create and activate a virtual environment using uv:

uv sync

this will create a virtual environment in .venv folder and install all dependencies listed in pyproject.toml file.

You can then activate the virtual environment using:

source .venv/bin/activate

2. Install pre-commit for development

For automated checks to keep codebase structure and code format one needs to install pre-commit

pre-commit install

3. Secrets (.env)

Copy .env.example to .env and fill in the API keys:

cp .env.example .env

To log training runs to Weights & Biases, set WANDB_API_KEY. On Raven, copy the key from an existing project (e.g. the collectively-grounded-llms repo) or grab it from https://wandb.ai/authorize. .env is gitignored; SLURM templates source it to export WANDB_* variables into the job environment.

Alternative: Manual virtual environment setup

If you prefer to set up the virtual environment manually without uv, you can follow these steps:

On Linux (with CUDA):

python3.9 -m venv .venv
. .venv/bin/activate
pip install --upgrade pip
pip install wheel
pip install torch==1.11.0+cu113 -f https://download.pytorch.org/whl/cu113
pip install torch-scatter torch-sparse torch-cluster torch-spline-conv torch-geometric -f https://data.pyg.org/whl/torch-1.11.0+cu113.html
pip install -e ".[dev]"

On macOS/Windows (CPU-only):

python3.9 -m venv .venv
. .venv/bin/activate
pip install --upgrade pip
pip install wheel
pip install torch==1.11.0
pip install -e ".[dev]"

Training, Simulation, Evaluation

All pipelines are config-driven (YAML in configs/) behind one CLI:

python -m aimanager train-ah <config>       # artificial humans (supervised)
python -m aimanager train-manager <config>  # RL manager
python -m aimanager simulate <config>       # set save_per_round: true if the run will be evaluated
python -m aimanager evaluate <config>       # sim vs human metrics, scores, visuals

Training and simulation need the full PyG environment and run on the Raven cluster; evaluation runs locally against the simulation's per_round.parquet.

From the local machine

With an SSH ControlMaster connection active (ssh raven in a separate terminal, persists 12h), the cluster scripts sync the repo and submit the job through the SLURM orchestrators:

scripts/train_cluster.sh ah <config>        # artificial humans
scripts/train_cluster.sh manager <config>   # RL manager
scripts/simulate_cluster.sh <config>        # simulation
scripts/remote_test.sh                      # PyG-dependent tests
scripts/fetch_cluster.sh <remote_path>      # bring results back (no trailing slash)

Skill-based workflow

In Claude Code the same operations are exposed as skills -- /train, /simulate, /test, /fetch-cluster, plus /commit and /pr (see .claude/skills/). Issue labels steering the agent workflow are documented in CLAUDE.md.

Directly on the cluster

From ~/algorithmic-institutions on Raven with the remote .venv activated, run the SLURM orchestrators yourself:

python src/aimanager/artificial_humans/run.py <config>  # submits AH training
python src/aimanager/manager/run.py <config>            # submits manager training
python src/aimanager/simulation/run.py <config>         # submits simulation

Each submits GPU batch jobs (see scripts/run_simulation.sh for the simulation template); single runs can also be executed in place with python -m aimanager <command> <config> on a GPU node.