Merge pull request #37 from renbytes/dev-canonicalStudies

seed schelling sim

Author: bordumb

.env.example

@@ -13,12 +13,12 @@ DATABASE_URL=postgresql+asyncpg://admin:password@host.docker.internal:5432/agent
 
 MLFLOW_TRACKING_USERNAME=admin
 MLFLOW_TRACKING_PASSWORD=password
-MLFLOW_TRACKING_URI=http://mlflow:5000
+MLFLOW_TRACKING_URI=http://localhost:5001
 MLFLOW_HTTP_REQUEST_TIMEOUT=10
 
 # --- Optional Services ---
 # NOTE: Redis can still use its service name as it's typically more stable
-REDIS_URL=redis://redis:6379/0
+REDIS_URL=redis://localhost:6379/0
 
 # --- OpenAI API Key (Developer must provide their own) ---
 OPENAI_API_KEY=sk-{your_openai_api_key_here}

Dockerfile

@@ -1,31 +1,39 @@
-# Pin the Python version to match your poetry.lock file
+# Use an official Python base image
 FROM python:3.11.9-slim
 
-# Set the working directory inside the container
-WORKDIR /app
-
-# Use modern ENV syntax
+# Configure environment variables for Python and Poetry
 ENV PYTHONDONTWRITEBYTECODE=1
 ENV PYTHONUNBUFFERED=1
-ENV POETRY_NO_INTERACTION=1 \
-    POETRY_VIRTUALENVS_IN_PROJECT=1 \
-    POETRY_VIRTUALENVS_CREATE=1
+ENV POETRY_HOME="/opt/poetry"
+ENV POETRY_NO_INTERACTION=1
+ENV POETRY_VIRTUALENVS_CREATE=false
 
-# Install build tools, git, AND the graphviz development library
-RUN apt-get update && apt-get install -y build-essential git graphviz-dev
+# Add Poetry's bin directory to the system PATH.
+ENV PATH="$POETRY_HOME/bin:$PATH"
 
-# Install Poetry
-RUN pip install --no-cache-dir poetry
+# Set the working directory
+WORKDIR /app
 
-# Copy dependency files first
-COPY pyproject.toml poetry.lock ./
-COPY agent-sim/pyproject.toml ./agent-sim/
+# Install system dependencies and Poetry itself
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends curl \
+    && curl -sSL https://install.python-poetry.org | python - \
+    && apt-get remove -y curl \
+    && apt-get autoremove -y \
+    && rm -rf /var/lib/apt/lists/*
 
-# Copy the entire project source code BEFORE running install
+# Copy ALL project files before installing dependencies.
+# This ensures Poetry can find the local path dependencies (agent-core, etc.).
 COPY . .
 
-# Install project dependencies using the lock file
-RUN poetry install --no-root
+# Install build dependencies, install Python packages, then remove build dependencies.
+# This ensures packages that need compilation (like ecos, osqp) can be built,
+# while keeping the final image size smaller.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends build-essential cmake git graphviz libgraphviz-dev \
+    && poetry install --without dev \
+    && apt-get purge -y --auto-remove build-essential cmake git graphviz libgraphviz-dev \
+    && rm -rf /var/lib/apt/lists/*
 
-# The command to run when the container starts
+# The default command to run when the container starts
 CMD ["tail", "-f", "/dev/null"]

Makefile

@@ -1,33 +1,114 @@
-.PHONY: setup up down run-example logs
+# ==============================================================================
+# ARLA Project Makefile
+#
+# Provides a simplified interface for managing the Docker-based development
+# environment and running simulations.
+# ==============================================================================
 
-# Default target
-all: up
+.PHONY: help setup up down logs init-db run run-local cli test lint make-gif
+.DEFAULT_GOAL := help
 
-# Set up the environment by copying the example .env file
-setup:
-	@if [ ! -f .env ]; then \
-		echo "--- Setup: Creating .env file from .env.example..."; \
-		cp .env.example .env; \
-	else \
-		echo "--- Setup: .env file already exists."; \
-	fi
-
-# Build and start all services in the background
-up: setup
-	@echo "--- Starting all services with Docker Compose..."
-	docker compose up --build -d
-
-# Stop and remove all services
-down:
-	@echo "--- Stopping all services..."
-	docker compose down
+# --- Variable Definitions ---
+# These variables can be overridden from the command line.
+# Example: make run-local PACKAGE=simulations.new_sim ...
+
+# The Python package of the simulation to run.
+PACKAGE ?= simulations.schelling_sim
+# Path to the base YAML config file for the simulation.
+CONFIG ?= simulations/schelling_sim/config/config.yml
+# Path to the scenario JSON file or experiment YAML file.
+FILE ?= simulations/schelling_sim/scenarios/default.json
+# Number of simulation steps for local runs.
+STEPS ?= 200
+# Generic arguments for the CLI.
+ARGS ?=
+# Default directory for rendering output.
+RENDER_DIR ?= data/gif_renders
+# Default frames per second for rendering GIFs.
+FPS ?= 15
+
+
+# --- Core Docker Commands ---
 
-# Use the direct path to the venv's python executable
-run-example:
-	@echo "--- Running: Executing example scenario inside Docker..."
-	docker compose exec app /app/.venv/bin/python -m agent_sim.main --scenario simulations/soul_sim/scenarios/default.json --steps 50
+## up: Build images and start all services in the background.
+up:
+	@echo "🚀 Building images and starting all services..."
+	@docker compose up -d --build
 
-# View the logs from all running services
+## down: Stop and remove all containers, networks, and volumes.
+down:
+	@echo "🛑 Stopping and removing all services..."
+	@docker compose down -v
+
+## logs: View and follow live logs from all running services.
 logs:
-	@echo "--- Tailing logs from all services..."
-	docker compose logs -f
+	@echo "📜 Tailing logs..."
+	@docker compose logs -f
+
+## init-db: Connects to the DB and creates all necessary tables.
+init-db:
+	@echo "Initializing database and creating tables..."
+	@docker compose exec app poetry run python -m agent_sim.infrastructure.database.init_db
+
+## setup: Create the .env file from the example template.
+setup:
+	@echo "📋 Copying .env.example to .env..."
+	@cp .env.example .env
+	@echo "✅ Done. Please add your OPENAI_API_KEY to the .env file."
+
+
+# --- Simulation & Development Commands ---
+
+## run: Run a full experiment, submitting jobs to the Celery queue.
+run:
+	@echo "▶️ Running experiment from: $(FILE)"
+	@docker compose exec app poetry run agentsim run-experiment $(FILE)
+
+## run-local: Run a single, local simulation for quick testing and debugging.
+run-local:
+	@echo "▶️ Running Local Simulation"
+	@echo "   - Package:  $(PACKAGE)"
+	@echo "   - Config:   $(CONFIG)"
+	@echo "   - Scenario: $(FILE)"
+	@echo "   - Steps:    $(STEPS)"
+	@docker compose exec app poetry run python -m agent_sim.main \
+	  --package $(PACKAGE) \
+	  --config $(CONFIG) \
+	  --scenario $(FILE) \
+	  --steps $(STEPS)
+
+## make-gif: Creates a GIF from the most recent simulation render.
+make-gif:
+	@echo "🎬 Creating GIF from frames in $(RENDER_DIR)..."
+	@poetry run python scripts/create_gif.py $(RENDER_DIR) simulation.gif --fps $(FPS)
+
+## cli: Run any 'agentsim' command inside the container.
+cli:
+	@echo "Running CLI command: agentsim $(ARGS)"
+	@docker compose exec app poetry run agentsim $(ARGS)
+
+## test: Run the full pytest suite inside the container.
+test:
+	@echo "🧪 Running pytest test suite..."
+	@docker compose exec app pytest
+
+## lint: Run the Ruff linter to check for code style issues.
+lint:
+	@echo "🎨 Linting with Ruff..."
+	@docker compose exec app ruff check .
+
+## help: Display this help message.
+help:
+	@echo "ARLA Project Makefile"
+	@echo "---------------------"
+	@echo "Usage: make <target> [VARIABLE=value]"
+	@echo ""
+	@echo "Available Targets:"
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
+	sort | \
+	awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2}'
+	@echo ""
+	@echo "Example Local Run:"
+	@echo "  make run-local FILE=path/to/your.json STEPS=100"
+	@echo ""
+

agent-concurrent/src/agent_concurrent/runners.py

@@ -53,7 +53,9 @@ async def run(self, systems: Sequence[SystemProtocol], current_tick: int) -> Non
             try:
                 await system.update(current_tick=current_tick)
             except Exception as e:
-                print(f"ERROR: System '{system!r}' failed during serial update at tick {current_tick}: {e}")
+                print(
+                    f"ERROR: System '{system!r}' failed during serial update at tick {current_tick}: {e}"
+                )
                 # In a serial runner, we might choose to stop or continue.
                 # For robustness, we'll log and continue.
                 import traceback
@@ -74,7 +76,10 @@ async def run(self, systems: Sequence[SystemProtocol], current_tick: int) -> Non
         Creates a task for each system's update method and runs them concurrently.
         """
         print(f"--- Tick {current_tick}: Running {len(systems)} systems concurrently")
-        tasks = [asyncio.create_task(system.update(current_tick=current_tick)) for system in systems]
+        tasks = [
+            asyncio.create_task(system.update(current_tick=current_tick))
+            for system in systems
+        ]
 
         # Use asyncio.gather with return_exceptions=True to ensure that one
         # failing system does not stop the others.
@@ -83,7 +88,9 @@ async def run(self, systems: Sequence[SystemProtocol], current_tick: int) -> Non
         # After all tasks have completed, check for and log any exceptions.
         for result, system in zip(results, systems):
             if isinstance(result, Exception):
-                print(f"ERROR: System '{system!r}' failed during concurrent update at tick {current_tick}: {result}")
+                print(
+                    f"ERROR: System '{system!r}' failed during concurrent update at tick {current_tick}: {result}"
+                )
                 import traceback
 
                 traceback.print_exception(type(result), result, result.__traceback__)

agent-core/src/agent_core/agents/actions/action_registry.py

@@ -37,14 +37,18 @@ def load_actions_from_paths(self, module_paths: List[str]) -> None:
                 importlib.import_module(path)
                 print(f"  Successfully loaded action module: {path}")
             except ImportError as e:
-                print(f"WARNING: Could not import action module at '{path}'. Error: {e}")
+                print(
+                    f"WARNING: Could not import action module at '{path}'. Error: {e}"
+                )
 
     def register(self, action_class: Type[ActionInterface]) -> Type[ActionInterface]:
         """
         A decorator to register any class that implements the ActionInterface.
         """
         if not issubclass(action_class, ActionInterface):
-            raise TypeError(f"Class {action_class.__name__} must implement ActionInterface to be registered.")
+            raise TypeError(
+                f"Class {action_class.__name__} must implement ActionInterface to be registered."
+            )
 
         try:
             instance = action_class()
@@ -56,7 +60,9 @@ def register(self, action_class: Type[ActionInterface]) -> Type[ActionInterface]
             ) from e
 
         if not isinstance(action_id, str) or not action_id:
-            raise TypeError(f"Action class {action_class.__name__} has an invalid 'action_id' property.")
+            raise TypeError(
+                f"Action class {action_class.__name__} has an invalid 'action_id' property."
+            )
 
         if action_id in self._actions:
             raise ValueError(f"Action with ID '{action_id}' is already registered.")

agent-core/src/agent_core/agents/actions/base_action.py

@@ -75,7 +75,9 @@ def execute(
         raise NotImplementedError
 
     @abstractmethod
-    def get_feature_vector(self, entity_id: str, simulation_state: Any, params: Dict[str, Any]) -> List[float]:
+    def get_feature_vector(
+        self, entity_id: str, simulation_state: Any, params: Dict[str, Any]
+    ) -> List[float]:
         raise NotImplementedError
 
     @staticmethod

agent-core/src/agent_core/cognition/ai_models/openai_client.py

@@ -29,7 +29,9 @@ def get_client() -> OpenAI:
 embedding_cache: Dict[Tuple[str, str], np.ndarray] = {}
 
 
-def get_embedding_with_cache(text: str, embedding_dim: int, llm_config: Optional[Any] = None) -> Optional[np.ndarray]:
+def get_embedding_with_cache(
+    text: str, embedding_dim: int, llm_config: Optional[Any] = None
+) -> Optional[np.ndarray]:
     """Gets an embedding for a single text string, using a cache to avoid repeat API calls."""
     # Use direct attribute access on the Pydantic model
     model_name = llm_config.embedding_model if llm_config else "text-embedding-ada-002"
@@ -50,14 +52,18 @@ class EmbeddingValidationError(Exception):
     """Raised when embedding validation fails."""
 
 
-def validate_embedding(embedding: Any, expected_dim: int, name: str = "embedding") -> bool:
+def validate_embedding(
+    embedding: Any, expected_dim: int, name: str = "embedding"
+) -> bool:
     """Validate embedding dimensions and properties."""
     if embedding is None:
         raise EmbeddingValidationError(f"{name} is None")
     if not isinstance(embedding, np.ndarray):
         raise EmbeddingValidationError(f"{name} is not a numpy array")
     if embedding.shape[0] != expected_dim:
-        raise EmbeddingValidationError(f"{name} dimension mismatch: got {embedding.shape[0]}, expected {expected_dim}")
+        raise EmbeddingValidationError(
+            f"{name} dimension mismatch: got {embedding.shape[0]}, expected {expected_dim}"
+        )
     if np.any(np.isnan(embedding)):
         raise EmbeddingValidationError(f"{name} contains NaN values")
     if np.any(np.isinf(embedding)):
@@ -78,7 +84,9 @@ def get_embedding_from_llm(
     try:
         response = client.embeddings.create(input=text, model=model_name)
         embedding = np.array(response.data[0].embedding).astype(np.float32)
-        validate_embedding(embedding, expected_embedding_dim, f"embedding for '{text[:50]}...'")
+        validate_embedding(
+            embedding, expected_embedding_dim, f"embedding for '{text[:50]}...'"
+        )
         return embedding
     except EmbeddingValidationError:
         raise
@@ -87,7 +95,9 @@ def get_embedding_from_llm(
         return None
 
 
-def get_embeddings_from_llm_batch(texts: List[str], llm_config: Optional[Any] = None) -> Optional[List[np.ndarray]]:
+def get_embeddings_from_llm_batch(
+    texts: List[str], llm_config: Optional[Any] = None
+) -> Optional[List[np.ndarray]]:
     """Gets embeddings for a list of texts in a single, efficient API call."""
     if not texts:
         return []
@@ -104,15 +114,19 @@ def get_embeddings_from_llm_batch(texts: List[str], llm_config: Optional[Any] =
         return None
 
 
-def query_llm(prompt_text: str, llm_config: Optional[Any] = None) -> tuple[str, int, float]:
+def query_llm(
+    prompt_text: str, llm_config: Optional[Any] = None
+) -> tuple[str, int, float]:
     """Queries the LLM, returning the response, token usage, and estimated cost."""
     client = get_client()
 
     # Use direct attribute access on the Pydantic model, providing defaults if it's None
     model_name = llm_config.completion_model if llm_config else "gpt-4.1-nano"
     temp = llm_config.temperature if llm_config else 0.1
     max_tok = llm_config.max_tokens if llm_config else 700
-    prompt_prefix = llm_config.reflection_prompt_prefix if llm_config else "In 300 words or less, "
+    prompt_prefix = (
+        llm_config.reflection_prompt_prefix if llm_config else "In 300 words or less, "
+    )
 
     pricing = {
         "gpt-4o-mini": {"prompt": 0.15 / 1_000_000, "completion": 0.60 / 1_000_000},
@@ -129,15 +143,21 @@ def query_llm(prompt_text: str, llm_config: Optional[Any] = None) -> tuple[str,
         )
 
         response_text = ""
-        if response.choices and response.choices[0].message and response.choices[0].message.content:
+        if (
+            response.choices
+            and response.choices[0].message
+            and response.choices[0].message.content
+        ):
             response_text = response.choices[0].message.content.strip()
 
         usage = response.usage
         if usage:
             prompt_tokens = usage.prompt_tokens
             completion_tokens = usage.completion_tokens
             total_tokens = usage.total_tokens
-            cost = (prompt_tokens * model_pricing["prompt"]) + (completion_tokens * model_pricing["completion"])
+            cost = (prompt_tokens * model_pricing["prompt"]) + (
+                completion_tokens * model_pricing["completion"]
+            )
             return response_text, total_tokens, cost
         else:
             return response_text, 0, 0.0