econagents 0.2.2__tar.gz → 0.2.3__tar.gz

econagents-0.2.3/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to econagents are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
+follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.3] - 2026-06-29
+
+### Added
+
+- Added a local continuous double auction example with LLM-backed traders,
+  structured market actions, a continuous `market` phase, a receive-only
+  `summary` phase, local verification, and OpenAI-backed run instructions.
+
+### Changed
+
+- Updated game runner logging so an agent's WebSocket transport uses the
+  per-agent run logger, capturing transport send/receive events in the same
+  per-game log files as agent lifecycle events.
+- Included local examples in source distributions while excluding generated
+  local run logs and game specs.
+
+## [0.2.2] - 2026-06-25
+
+### Added
+
+- Added local verification scripts for the prisoner, dictator, and public goods
+  examples so each example can be exercised end-to-end against its local server
+  without making external LLM calls.
+
+### Changed
+
+- Organized the package around explicit hexagonal boundaries:
+  `domain`, `ports`, `runtime`, and `adapters`.
+- Moved protocol, transport, configuration, prompt, parser, state projection,
+  and LLM provider implementations under `econagents.adapters`.
+- Moved roles, state models, events, and stable message types under
+  `econagents.domain`.
+- Moved runtime orchestration, phase handling, experiment factories, and game
+  supervision under `econagents.runtime`.
+- Renamed the participant runtime and behavior policy concepts to `Agent` and
+  `Role`.
+- Renamed the YAML configuration entry point to `YamlExperimentLoader` and the
+  loaded YAML models to `ExperimentSpec`, `RoleSpec`, `AgentSpec`,
+  `StateSpec`, `RuntimeSpec`, and `RunnerSpec`.
+- Renamed the default response parser to `JsonResponseParser`.
+- Updated local examples and local servers for the refactored runtime,
+  transport, prompt rendering, and state projection APIs.
+- Updated OpenAI-backed examples and documentation snippets to use
+  `gpt-5.4-mini`.
+- Updated the prisoner YAML examples to use the standard submit-choice envelope
+  and explicit `phase` and `round` state fields.
+
+### Fixed
+
+- Fixed prompt state resolution in local examples so prompts render the current
+  event-projected state, including per-round prisoner prompts, dictator payout
+  prompts, and public goods personality and payoff prompts.
+- Fixed dictator local server payout ordering so phase-two prompts receive the
+  resolved decision and payout state before the payout phase starts.
+
+[0.2.3]: https://github.com/IBEX-TUDelft/econagents/compare/v0.2.2...v0.2.3
+[0.2.2]: https://github.com/IBEX-TUDelft/econagents/compare/v0.2.1...v0.2.2

{econagents-0.2.2 → econagents-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: econagents
-Version: 0.2.2
+Version: 0.2.3
 Summary: A Python library that lets you use LLM agents in economic experiments.
 Project-URL: Homepage, https://github.com/IBEX-TUDelft/econagents
 Project-URL: Repository, https://github.com/IBEX-TUDelft/econagents
@@ -81,11 +81,12 @@ econagents consists of these main components:
 
 ## Example Experiments
 
-The repository includes three example games:
+The repository includes four example games:
 
 1. **`prisoner`**: An iterated Prisoner's Dilemma game with 5 rounds and 2 LLM agents, runs on a local python server (included).
 2. **`dictator`**: A modified Dictator game with 2 LLM agents that runs on a local python server (included).
 3. **`public_goods`**: A public goods game with 4 players that runs on a local python server (included).
+4. **`continuous_double_auction`**: A classical continuous double auction with LLM-backed traders using a continuous market phase.
 
 ### Running the Prisoner's Dilemma game
 

{econagents-0.2.2 → econagents-0.2.3}/README.md

@@ -48,11 +48,12 @@ econagents consists of these main components:
 
 ## Example Experiments
 
-The repository includes three example games:
+The repository includes four example games:
 
 1. **`prisoner`**: An iterated Prisoner's Dilemma game with 5 rounds and 2 LLM agents, runs on a local python server (included).
 2. **`dictator`**: A modified Dictator game with 2 LLM agents that runs on a local python server (included).
 3. **`public_goods`**: A public goods game with 4 players that runs on a local python server (included).
+4. **`continuous_double_auction`**: A classical continuous double auction with LLM-backed traders using a continuous market phase.
 
 ### Running the Prisoner's Dilemma game
 

{econagents-0.2.2 → econagents-0.2.3}/econagents/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.2'
-__version_tuple__ = version_tuple = (0, 2, 2)
+__version__ = version = '0.2.3'
+__version_tuple__ = version_tuple = (0, 2, 3)
 
 __commit_id__ = commit_id = None

{econagents-0.2.2 → econagents-0.2.3}/econagents/runtime/game_runner.py

@@ -289,6 +289,9 @@ class GameRunner:
         """
         agent_logger = self.get_agent_logger(agent_id, self.config.game_id)
         agent.logger = agent_logger
+        transport = getattr(agent, "transport", None)
+        if transport is not None and hasattr(transport, "logger"):
+            transport.logger = agent_logger
 
     async def spawn_agent(self, agent: Agent, agent_id: int) -> None:
         """

econagents-0.2.3/examples/continuous_double_auction/README.md

@@ -0,0 +1,51 @@
+# Continuous Double Auction
+
+This local example implements a continuous double auction, a standard market institution in experimental economics. Buyers have induced private values and cash endowments, sellers have induced private costs, and LLM-backed agents submit bids or asks while the market phase remains open.
+
+The important runtime feature is the continuous phase:
+
+- The server emits `phase-transition` with `phase="market"`.
+- Each agent is configured with `PhaseEngine(continuous_phases={"market"}, min_action_delay=8, max_action_delay=8)`.
+- The agent acts once on entry, then keeps calling the role's LLM-backed market phase until the server moves out of `market`.
+- The default induced schedules give each of the two buyers and two sellers five marginal units. That allows up to ten total unit trades, with several more surplus-preserving trades than the original two-unit schedule.
+- The default local run keeps the market open for 60 seconds, unless all possible units trade first.
+- After the market closes, the server emits a receive-only `summary` phase with final trades, cash balances, and surplus. Agents do not send an action in this phase.
+
+The traders use `ChatOpenAI` and structured output for market orders, so set `OPENAI_API_KEY` before running the LLM-backed experiment. You can set `OPENAI_MODEL` to override the default model.
+
+## Running The Example
+
+Start the local WebSocket server:
+
+```bash
+uv run python examples/continuous_double_auction/server/server.py
+```
+
+In a separate terminal, run the agents:
+
+```bash
+uv run python examples/continuous_double_auction/run_game.py
+```
+
+The runner writes per-game and per-agent logs under `examples/continuous_double_auction/logs/game_<game_id>/`.
+The local server writes submitted orders and trades to `examples/continuous_double_auction/logs/server.log`.
+
+You can also run the end-to-end verification, which starts the server and agents in the same process:
+
+```bash
+uv run python examples/continuous_double_auction/verify.py
+```
+
+## Files
+
+```text
+continuous_double_auction/
+├── agents.py             # LLM-backed trader role and structured action schema
+├── run_game.py           # Local runner using HybridGameRunnerConfig
+├── prompts/              # Trader prompts used by the LLM role
+├── state.py              # EventField-backed market state
+├── verify.py             # Local end-to-end check with a deterministic LLM stub
+└── server/
+    ├── create_game.py    # Game spec and induced value/cost schedule
+    └── server.py         # WebSocket CDA server
+```

econagents-0.2.3/examples/continuous_double_auction/__init__.py

@@ -0,0 +1 @@
+"""Continuous double auction example."""

econagents-0.2.3/examples/continuous_double_auction/agents.py

@@ -0,0 +1,90 @@
+from collections.abc import Iterable
+import os
+from pathlib import Path
+from typing import Literal
+
+from dotenv import load_dotenv
+from pydantic import BaseModel, Field
+
+from econagents import Role
+from econagents.adapters.llm import ChatOpenAI
+from econagents.runtime import Agent, PhaseEngine, create_game_state
+from econagents.runtime.game_runner import GameRunnerConfig, HybridGameRunnerConfig
+
+from examples.continuous_double_auction.state import CDAGameState
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+load_dotenv(REPO_ROOT / ".env", override=True)
+
+MARKET_PHASE = "market"
+SUMMARY_PHASE = "summary"
+
+
+class OrderComponent(BaseModel):
+    """Component marker for CDA order actions."""
+
+    type: Literal["continuous-double-auction:order"] = "continuous-double-auction:order"
+
+
+class OrderMeta(BaseModel):
+    """Outbound action metadata emitted by the trader LLM."""
+
+    type: Literal["submit-order", "hold"]
+    component: OrderComponent = Field(default_factory=OrderComponent)
+
+
+class OrderPayload(BaseModel):
+    """Outbound action payload emitted by the trader LLM."""
+
+    gameId: int
+    side: Literal["buy", "sell"] | None = None
+    price: float | None = Field(default=None, description="Bid or ask price. Required for submit-order.")
+    reason: str | None = Field(default=None, description="Short reason when holding instead of quoting.")
+
+
+class MarketAction(BaseModel):
+    """Structured action emitted by an LLM trader during the continuous market."""
+
+    meta: OrderMeta
+    payload: OrderPayload
+
+
+class Trader(Role[CDAGameState]):
+    """LLM-backed trader role for the local continuous double auction."""
+
+    role = 1
+    name = "trader"
+    llm = ChatOpenAI(
+        model_name=os.getenv("OPENAI_MODEL", "gpt-5.4-mini"),
+        response_kwargs={"max_output_tokens": 300},
+    )
+    task_phases = [MARKET_PHASE]
+    response_schemas = {MARKET_PHASE: MarketAction}
+
+
+def create_cda_agent(*, config: GameRunnerConfig, recovery_code: str) -> Agent:
+    """Create one LLM-backed continuous double auction trader."""
+    if not isinstance(config, HybridGameRunnerConfig):
+        raise TypeError("The continuous double auction example requires HybridGameRunnerConfig.")
+
+    return Agent(
+        url=config.server_url(),
+        auth_mechanism=config.auth_mechanism,
+        auth_mechanism_kwargs={"gameId": config.game_id, "recovery": recovery_code},
+        state=create_game_state(CDAGameState, game_id=config.game_id),
+        role=Trader(),
+        prompts_dir=config.prompts_dir,
+        phase_transition_event=config.phase_transition_event,
+        phase_identifier_key=config.phase_identifier_key,
+        phase_engine=PhaseEngine(
+            continuous_phases=set(config.continuous_phases),
+            min_action_delay=config.min_action_delay,
+            max_action_delay=config.max_action_delay,
+        ),
+        end_game_event=config.end_game_event,
+    )
+
+
+def create_cda_agents(config: GameRunnerConfig, recovery_codes: Iterable[str]) -> list[Agent]:
+    """Create all traders for a runner config."""
+    return [create_cda_agent(config=config, recovery_code=code) for code in recovery_codes]

econagents-0.2.3/examples/continuous_double_auction/prompts/trader_system.jinja2

@@ -0,0 +1,13 @@
+You are a trader in a continuous double auction, a standard experimental economics market.
+
+You have a private role:
+- If you are a buyer, your limit price is your current private value. Submit buy bids at or below both that value and your cash balance.
+- If you are a seller, your limit price is your current private cost. Submit sell asks at or above that cost.
+
+Your goal is to earn surplus on each unit:
+- Buyer surplus = value - transaction price.
+- Seller surplus = transaction price - cost.
+
+Cash balance is a real budget constraint for buyers. Cash flow is the net payments or receipts from trades. Realized surplus is your payoff so far.
+
+Quote one order at a time. Keep prices valid for your role. Hold only if you have no remaining units, if your role is not assigned, or if every possible quote would violate your private limit.

econagents-0.2.3/examples/continuous_double_auction/prompts/trader_user_phase_market.jinja2

@@ -0,0 +1,28 @@
+Current market state:
+- Game ID: {{ meta.game_id }}
+- Trader role: {{ private_information.trader_type }}
+- Current limit price: {{ private_information.limit_price }}
+- Remaining units: {{ private_information.remaining_units }}
+- Cash balance: {{ private_information.cash_balance }}
+- Net cash flow: {{ private_information.cash_flow }}
+- Realized surplus: {{ private_information.surplus }}
+- Inventory: {{ private_information.inventory }}
+- Your actions submitted so far: {{ private_information.actions_submitted }}
+- Best bid: {{ public_information.best_bid }}
+- Best ask: {{ public_information.best_ask }}
+- Last transaction price: {{ public_information.last_price }}
+- Total orders submitted: {{ public_information.order_count }}
+- Transactions so far: {{ public_information.transactions }}
+
+Return one structured action.
+
+If you submit an order:
+- Use meta.type = "submit-order".
+- Use payload.gameId = {{ meta.game_id }}.
+- Use payload.side = "buy" if you are a buyer, or "sell" if you are a seller.
+- Use payload.price as your bid or ask.
+
+If you hold:
+- Use meta.type = "hold".
+- Use payload.gameId = {{ meta.game_id }}.
+- Use payload.reason to explain briefly.

econagents-0.2.3/examples/continuous_double_auction/run_game.py

@@ -0,0 +1,55 @@
+import asyncio
+import logging
+import os
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+from econagents.runtime.game_runner import GameRunner, HybridGameRunnerConfig
+from examples.continuous_double_auction.agents import MARKET_PHASE, create_cda_agents
+from examples.continuous_double_auction.server.create_game import create_game_from_specs
+
+logger = logging.getLogger("continuous_double_auction")
+
+MARKET_DURATION_SECONDS = 60
+SUMMARY_DURATION_SECONDS = 2
+ACTION_DELAY_SECONDS = 8
+
+
+async def main() -> None:
+    """Run a local continuous double auction with LLM-backed traders."""
+    logger.info("Starting Continuous Double Auction example")
+    env_path = Path(__file__).resolve().parents[2] / ".env"
+    load_dotenv(env_path, override=True)
+    logger.info(
+        "Loaded environment from %s; OPENAI_API_KEY is %s",
+        env_path,
+        "set" if os.getenv("OPENAI_API_KEY") else "not set",
+    )
+
+    game_specs = create_game_from_specs(
+        market_duration=MARKET_DURATION_SECONDS,
+        summary_duration=SUMMARY_DURATION_SECONDS,
+    )
+
+    config = HybridGameRunnerConfig(
+        game_id=game_specs["game_id"],
+        logs_dir=Path(__file__).parent / "logs",
+        prompts_dir=Path(__file__).parent / "prompts",
+        log_level=logging.DEBUG,
+        hostname="localhost",
+        port=8766,
+        path="",
+        continuous_phases=[MARKET_PHASE],
+        min_action_delay=ACTION_DELAY_SECONDS,
+        max_action_delay=ACTION_DELAY_SECONDS,
+        max_game_duration=game_specs["market_duration"] + game_specs["summary_duration"] + 45,
+    )
+    agents = create_cda_agents(config, game_specs["recovery_codes"])
+    runner = GameRunner(config=config, agents=agents)
+
+    await runner.run_game()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

econagents-0.2.3/examples/continuous_double_auction/server/__init__.py

@@ -0,0 +1 @@
+"""Server for the continuous double auction example."""

econagents-0.2.3/examples/continuous_double_auction/server/create_game.py

@@ -0,0 +1,108 @@
+import json
+import logging
+import uuid
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s")
+logger = logging.getLogger(__name__)
+
+
+def default_trader_specs() -> list[dict[str, Any]]:
+    """Return a small induced-value schedule for a classic double auction."""
+    return [
+        {
+            "name": "Buyer 1",
+            "trader_type": "buyer",
+            "limit_prices": [110.0, 100.0, 90.0, 80.0, 70.0],
+            "cash_endowment": 450.0,
+        },
+        {
+            "name": "Buyer 2",
+            "trader_type": "buyer",
+            "limit_prices": [105.0, 95.0, 85.0, 75.0, 65.0],
+            "cash_endowment": 425.0,
+        },
+        {"name": "Seller 1", "trader_type": "seller", "limit_prices": [35.0, 45.0, 55.0, 65.0, 75.0]},
+        {"name": "Seller 2", "trader_type": "seller", "limit_prices": [40.0, 50.0, 60.0, 70.0, 80.0]},
+    ]
+
+
+def generate_recovery_codes(num_players: int) -> list[str]:
+    """Generate recovery codes for all traders."""
+    return [str(uuid.uuid4()) for _ in range(num_players)]
+
+
+def save_game_data(
+    specs_path: Path,
+    game_id: int,
+    game_name: str,
+    trader_specs: list[dict[str, Any]],
+    market_duration: int,
+    summary_duration: int,
+) -> Path:
+    """Save game data to the server specs directory."""
+    specs_dir = specs_path.parent / "games"
+    specs_dir.mkdir(parents=True, exist_ok=True)
+
+    recovery_codes = generate_recovery_codes(len(trader_specs))
+    traders = []
+    for spec, recovery in zip(trader_specs, recovery_codes):
+        traders.append({**spec, "recovery": recovery})
+
+    game_data = {
+        "game_id": game_id,
+        "game_name": game_name,
+        "num_players": len(traders),
+        "recovery_codes": recovery_codes,
+        "traders": traders,
+        "market_duration": market_duration,
+        "summary_duration": summary_duration,
+        "created_at": datetime.now().isoformat(),
+    }
+
+    output_file = specs_dir / f"game_{game_id}.json"
+    with output_file.open("w") as f:
+        json.dump(game_data, f, indent=2)
+    logger.info(f"Game data saved to {output_file}")
+    return output_file
+
+
+def create_game_from_specs(
+    trader_specs: list[dict[str, Any]] | None = None,
+    market_duration: int = 60,
+    summary_duration: int = 2,
+) -> dict[str, Any]:
+    """Create a local continuous double auction game spec."""
+    game_id = int(datetime.now().timestamp())
+    game_name = f"Continuous Double Auction {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}"
+    trader_specs = trader_specs or default_trader_specs()
+
+    save_game_data(
+        specs_path=Path(__file__).parent / "games",
+        game_id=game_id,
+        game_name=game_name,
+        trader_specs=trader_specs,
+        market_duration=market_duration,
+        summary_duration=summary_duration,
+    )
+
+    recovery_codes = []
+    game_file = Path(__file__).parent / "games" / f"game_{game_id}.json"
+    with game_file.open("r") as f:
+        recovery_codes = json.load(f)["recovery_codes"]
+
+    return {
+        "game_id": game_id,
+        "game_name": game_name,
+        "num_players": len(trader_specs),
+        "recovery_codes": recovery_codes,
+        "market_duration": market_duration,
+        "summary_duration": summary_duration,
+        "created_at": datetime.now().isoformat(),
+    }