econagents 0.0.1__tar.gz → 0.0.2__tar.gz

econagents-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Delft University of Technology
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{econagents-0.0.1 → econagents-0.0.2}/PKG-INFO

@@ -1,24 +1,43 @@
 Metadata-Version: 2.3
 Name: econagents
-Version: 0.0.1
-Summary: 
-License: Apache-2.0
-Author: Dylan
+Version: 0.0.2
+Summary: econagents is a Python library that lets you use LLM agents in economic experiments. The framework connects LLM agents to game servers through WebSockets and provides a flexible architecture for designing, customizing, and running economic simulations.
+License: MIT License
+         
+         Copyright (c) Delft University of Technology
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
 Requires-Python: >=3.10,<3.13
-Classifier: License :: OSI Approved :: Apache Software License
+Classifier: License :: Other/Proprietary License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Requires-Dist: langsmith (>=0.3.13,<0.4.0)
-Requires-Dist: numpy (>=2.2.3,<3.0.0)
-Requires-Dist: openai (>=1.65.5,<2.0.0)
+Provides-Extra: all
+Provides-Extra: default
+Provides-Extra: langfuse
+Provides-Extra: langsmith
+Provides-Extra: ollama
+Provides-Extra: openai
 Requires-Dist: pydantic (>=2.10.6,<3.0.0)
 Requires-Dist: requests (>=2.32.3,<3.0.0)
-Requires-Dist: typing-extensions (>=4.12.2,<5.0.0)
 Requires-Dist: websockets (>=15.0,<16.0)
-Project-URL: Homepage, https://github.com/iwanalabs/econagents
-Project-URL: Repository, https://github.com/iwanalabs/econagents
 Description-Content-Type: text/markdown
 
 <div align="center">
@@ -61,13 +80,15 @@ econagents consists of four key components:
 
 ## Example Experiments
 
-The repository includes two example experiments:
+The repository includes three example games:
 
 1. **`prisoner`**: An iterated Prisoner's Dilemma game with 5 rounds and 2 LLM agents.
-2. **`tudeflt/harberger`**: A Harberger Tax simulation with LLM agents.
-3. **`tudeflt/futarchy`**: A Futarchy simulation with LLM agents.
+2. **`ibex_tudelft/harberger`**: A Harberger Tax simulation with LLM agents.
+3. **`ibex_tudelft/futarchy`**: A Futarchy simulation with LLM agents.
 
-### Running the Prisoner's Dilemma Experiment
+### Running the Prisoner's Dilemma game
+
+The simplest game to run is a version of the repeated prisoner's dilemma game that runs on your local machine.
 
 ```shell
 # Run the server
@@ -77,6 +98,8 @@ python examples/server/prisoner/server.py
 python examples/prisoner/run_game.py
 ```
 
+Note: you still have to set up the connection to the agents.
+
 ## Key Features
 
 - **Flexible Agent Customization**: Customize agent behavior with Jinja templates or custom Python methods

{econagents-0.0.1 → econagents-0.0.2}/README.md

@@ -38,13 +38,15 @@ econagents consists of four key components:
 
 ## Example Experiments
 
-The repository includes two example experiments:
+The repository includes three example games:
 
 1. **`prisoner`**: An iterated Prisoner's Dilemma game with 5 rounds and 2 LLM agents.
-2. **`tudeflt/harberger`**: A Harberger Tax simulation with LLM agents.
-3. **`tudeflt/futarchy`**: A Futarchy simulation with LLM agents.
+2. **`ibex_tudelft/harberger`**: A Harberger Tax simulation with LLM agents.
+3. **`ibex_tudelft/futarchy`**: A Futarchy simulation with LLM agents.
 
-### Running the Prisoner's Dilemma Experiment
+### Running the Prisoner's Dilemma game
+
+The simplest game to run is a version of the repeated prisoner's dilemma game that runs on your local machine.
 
 ```shell
 # Run the server
@@ -54,6 +56,8 @@ python examples/server/prisoner/server.py
 python examples/prisoner/run_game.py
 ```
 
+Note: you still have to set up the connection to the agents.
+
 ## Key Features
 
 - **Flexible Agent Customization**: Customize agent behavior with Jinja templates or custom Python methods

{econagents-0.0.1 → econagents-0.0.2}/econagents/__init__.py

@@ -1,17 +1,18 @@
 """
-econagents: A Python library for setting up and running economic experiments with LLMs or human subjects.
+econagents: A Python library that lets you use LLM agents in economic experiments. 
 """
 
 from econagents.core.agent_role import AgentRole
 from econagents.core.game_runner import GameRunner, HybridGameRunnerConfig, TurnBasedGameRunnerConfig
 from econagents.core.manager import AgentManager
+from econagents.core.transport import WebSocketTransport
 from econagents.core.manager.phase import PhaseManager, HybridPhaseManager, TurnBasedPhaseManager
 from econagents.core.state.fields import EventField
 from econagents.core.state.game import GameState, MetaInformation, PrivateInformation, PublicInformation
 from econagents.llm.openai import ChatOpenAI
 
 # Don't manually change, let poetry-dynamic-versioning handle it.
-__version__ = "0.0.1"
+__version__ = "0.0.2"
 
 __all__: list[str] = [
     "AgentRole",
@@ -28,4 +29,5 @@ __all__: list[str] = [
     "TurnBasedGameRunnerConfig",
     "HybridGameRunnerConfig",
     "EventField",
+    "WebSocketTransport",
 ]

{econagents-0.0.1 → econagents-0.0.2}/econagents/core/agent_role.py

@@ -9,7 +9,7 @@ from jinja2.sandbox import SandboxedEnvironment
 
 from econagents.core.logging_mixin import LoggerMixin
 from econagents.core.state.game import GameStateProtocol
-from econagents.llm.openai import ChatOpenAI
+from econagents.llm.base import BaseLLM
 
 StateT_contra = TypeVar("StateT_contra", bound=GameStateProtocol, contravariant=True)
 
@@ -17,7 +17,7 @@ StateT_contra = TypeVar("StateT_contra", bound=GameStateProtocol, contravariant=
 class AgentProtocol(Protocol):
     role: ClassVar[int]
     name: ClassVar[str]
-    llm: ChatOpenAI
+    llm: BaseLLM
     task_phases: ClassVar[list[int]]
 
 
@@ -41,12 +41,12 @@ class AgentRole(ABC, Generic[StateT_contra], LoggerMixin):
     """Unique identifier for this role"""
     name: ClassVar[str]
     """Human-readable name for this role"""
-    llm: ChatOpenAI
+    llm: BaseLLM
     """Language model instance for generating responses"""
     task_phases: ClassVar[list[int]] = []  # Empty list means no specific phases are required
     """List of phases this agent should participate in (empty means all phases)"""
     task_phases_excluded: ClassVar[list[int]] = []  # Empty list means no phases are excluded
-
+    """ Alternative way to specify phases this agent should participate in, listed phases are excluded (empty means nothing excluded)"""
     # Regex patterns for method name extraction
     _SYSTEM_PROMPT_PATTERN: ClassVar[Pattern] = re.compile(r"get_phase_(\d+)_system_prompt")
     _USER_PROMPT_PATTERN: ClassVar[Pattern] = re.compile(r"get_phase_(\d+)_user_prompt")
@@ -109,9 +109,9 @@ class AgentRole(ABC, Generic[StateT_contra], LoggerMixin):
 
         Template resolution order:
 
-        1. Agent-specific phase prompt (e.g., "agent_name_system_phase_1.jinja2")
+        1. Role-specific phase prompt (e.g., "role_name_system_phase_1.jinja2")
 
-        2. Agent-specific general prompt (e.g., "agent_name_system.jinja2")
+        2. Role-specific general prompt (e.g., "role_name_system.jinja2")
 
         3. All-role phase prompt (e.g., "all_system_phase_1.jinja2")
 

{econagents-0.0.1 → econagents-0.0.2}/econagents/core/game_runner.py

@@ -4,14 +4,14 @@ import queue
 from contextvars import ContextVar
 from logging.handlers import QueueHandler, QueueListener
 from pathlib import Path
-from typing import Optional, Type
+from typing import Literal, Optional, Type
 
 from pydantic import BaseModel, Field
 
-from econagents.core.manager.base import AgentManager
 from econagents.core.manager.phase import PhaseManager
 from econagents.core.state.game import GameState
 from econagents.core.transport import AuthenticationMechanism, SimpleLoginPayloadAuth
+from econagents.llm.observability import get_observability_provider
 
 ctx_agent_id: ContextVar[str] = ContextVar("agent_id", default="N/A")
 
@@ -59,6 +59,10 @@ class GameRunnerConfig(BaseModel):
     state_class: Optional[Type[GameState]] = None
     """Class to use for the state"""
 
+    # Observability configuration
+    observability_provider: Optional[Literal["langsmith", "langfuse"]] = None
+    """Name of the observability provider to use. Options: 'langsmith' or 'langfuse'"""
+
 
 class TurnBasedGameRunnerConfig(GameRunnerConfig):
     """Configuration class for TurnBasedGameRunner."""
@@ -299,12 +303,22 @@ class GameRunner:
             agent_manager.auth_mechanism = self.config.auth_mechanism
             agent_manager.logger.debug(f"Injected default auth mechanism: {agent_manager.auth_mechanism}")
 
+        if agent_manager.llm_provider and self.config.observability_provider:
+            try:
+                provider = get_observability_provider(self.config.observability_provider)
+                agent_manager.llm_provider.observability = provider
+                agent_manager.logger.debug(
+                    f"Injected {self.config.observability_provider} observability provider into LLM provider"
+                )
+            except Exception as e:
+                agent_manager.logger.error(f"Failed to initialize observability provider: {e}")
+
         if isinstance(self.config, HybridGameRunnerConfig):
             agent_manager.continuous_phases = set(self.config.continuous_phases)
             agent_manager.min_action_delay = self.config.min_action_delay
             agent_manager.max_action_delay = self.config.max_action_delay
             agent_manager.logger.debug(
-                f"Injected default continuous phases: {agent_manager.continuous_phases}, min action delay: {agent_manager.min_action_delay}, max action delay: {agent_manager.max_action_delay}"
+                f"Injected default continuous-time phases: {agent_manager.continuous_phases}, min action delay: {agent_manager.min_action_delay}, max action delay: {agent_manager.max_action_delay}"
             )
 
     def _inject_agent_logger(self, agent_manager: PhaseManager, agent_id: int) -> None:

{econagents-0.0.1 → econagents-0.0.2}/econagents/core/manager/phase.py

@@ -17,16 +17,14 @@ class PhaseManager(AgentManager, ABC):
     """
     Abstract manager that handles the concept of 'phases' in a game.
 
-    This manager standardizes the interface for phase-based games with hooks for
-    phase transitions and optional continuous phase handling.
+    This manager standardizes the interface for phase-based games with optional
+    continuous-time phase handling.
 
     Features:
     1. Standardized interface for starting a phase
 
     2. Optional continuous "tick loop" for phases
 
-    3. Hooks for "on phase start," "on phase end," and "on phase transition event"
-
     All configuration parameters can be:
 
     1. Provided at initialization time
@@ -38,8 +36,8 @@ class PhaseManager(AgentManager, ABC):
         phase_transition_event (Optional[str]): Event name for phase transitions
         phase_identifier_key (Optional[str]): Key in the event data that identifies the phase
         continuous_phases (Optional[set[int]]): set of phase numbers that should be treated as continuous
-        min_action_delay (Optional[int]): Minimum delay in seconds between actions in continuous phases
-        max_action_delay (Optional[int]): Maximum delay in seconds between actions in continuous phases
+        min_action_delay (Optional[int]): Minimum delay in seconds between actions in continuous-time phases
+        max_action_delay (Optional[int]): Maximum delay in seconds between actions in continuous-time phases
         state (Optional[GameState]): Game state object to track game state
         agent_role (Optional[AgentRole]): Agent role instance to handle game phases
         auth_mechanism (Optional[AuthenticationMechanism]): Authentication mechanism to use
@@ -145,12 +143,12 @@ class PhaseManager(AgentManager, ABC):
 
     @property
     def continuous_phases(self) -> set[int]:
-        """Get the set of continuous phases."""
+        """Get the set of continuous-time phases."""
         return self._continuous_phases  # type: ignore
 
     @continuous_phases.setter
     def continuous_phases(self, value: set[int]):
-        """Set the continuous phases."""
+        """Set the continuous-time phases."""
         self._continuous_phases = value
 
     @property
@@ -183,6 +181,13 @@ class PhaseManager(AgentManager, ABC):
         """Set the prompts directory."""
         self._prompts_dir = value
 
+    @property
+    def llm_provider(self):
+        """Get the LLM provider from the agent role."""
+        if self._agent_role and hasattr(self._agent_role, "llm"):
+            return self._agent_role.llm
+        return None
+
     async def start(self):
         """Start the manager."""
         # TODO: is there a better place to do this?
@@ -220,38 +225,27 @@ class PhaseManager(AgentManager, ABC):
         Handle a phase transition.
 
         This method is the main orchestrator for phase transitions:
-        1. If leaving a continuous phase, stops the continuous task
-        2. Calls the on_phase_end hook for the old phase
-        3. Updates the current phase
-        4. Calls the on_phase_start hook for the new phase
-        5. Starts a continuous task if entering a continuous phase
-        6. Executes a single action if entering a non-continuous phase
+        1. If leaving a continuous-time phase, stops the continuous task
+        2. Updates the current phase
+        3. Starts a continuous task if entering a continuous-time phase
+        4. Executes a single action if entering a non-continuous-time phase
 
         Args:
             new_phase (Optional[int]): The new phase number
         """
         self.logger.info(f"Transitioning to phase {new_phase}")
 
-        # If we were in a continuous phase, stop it
+        # If we were in a continuous-time phase, stop it
         if self.in_continuous_phase and new_phase != self.current_phase:
-            self.logger.info(f"Stopping continuous phase {self.current_phase}")
+            self.logger.info(f"Stopping continuous-time phase {self.current_phase}")
             self.in_continuous_phase = False
             if self._continuous_task:
                 self._continuous_task.cancel()
                 self._continuous_task = None
 
-        # Call the on_phase_end hook for the old phase
-        old_phase = self.current_phase
-        if old_phase is not None:
-            await self.on_phase_end(old_phase)
-
-        # Update current phase
         self.current_phase = new_phase
 
         if new_phase is not None:
-            # Call the on_phase_start hook for the new phase
-            await self.on_phase_start(new_phase)
-
             # If the new phase is continuous, start a continuous task
             if self.continuous_phases and new_phase in self.continuous_phases:
                 self.in_continuous_phase = True
@@ -260,12 +254,12 @@ class PhaseManager(AgentManager, ABC):
                 # Execute an initial action
                 await self.execute_phase_action(new_phase)
             else:
-                # Execute a single action for non-continuous phases
+                # Execute a single action for non-continuous-time phases
                 await self.execute_phase_action(new_phase)
 
     async def _continuous_phase_loop(self, phase: int):
         """
-        Run a loop that periodically executes actions for a continuous phase.
+        Run a loop that periodically executes actions for a continuous-time phase.
 
         Args:
             phase (int): The phase number
@@ -277,16 +271,16 @@ class PhaseManager(AgentManager, ABC):
                 self.logger.debug(f"Waiting {delay} seconds before next action in phase {phase}")
                 await asyncio.sleep(delay)
 
-                # Check if we're still in the same continuous phase
+                # Check if we're still in the same continuous-time phase
                 if not self.in_continuous_phase or self.current_phase != phase:
                     break
 
                 # Execute the action
                 await self.execute_phase_action(phase)
         except asyncio.CancelledError:
-            self.logger.info(f"Continuous phase {phase} loop cancelled")
+            self.logger.info(f"Continuous-time phase {phase} loop cancelled")
         except Exception as e:
-            self.logger.exception(f"Error in continuous phase {phase} loop: {e}")
+            self.logger.exception(f"Error in continuous-time phase {phase} loop: {e}")
 
     @abstractmethod
     async def execute_phase_action(self, phase: int):
@@ -301,30 +295,8 @@ class PhaseManager(AgentManager, ABC):
         """
         pass
 
-    async def on_phase_start(self, phase: int):
-        """
-        Hook that is called when a phase starts.
-
-        Subclasses can override this to implement custom behavior.
-
-        Args:
-            phase (int): The phase number
-        """
-        pass
-
-    async def on_phase_end(self, phase: int):
-        """
-        Hook that is called when a phase ends.
-
-        Subclasses can override this to implement custom behavior.
-
-        Args:
-            phase (int): The phase number
-        """
-        pass
-
     async def stop(self):
-        """Stop the manager and cancel any continuous phase tasks."""
+        """Stop the manager and cancel any continuous-time phase tasks."""
         self.in_continuous_phase = False
         if self._continuous_task:
             self._continuous_task.cancel()
@@ -337,7 +309,8 @@ class TurnBasedPhaseManager(PhaseManager):
     A manager for turn-based games that handles phase transitions.
 
     This manager inherits from PhaseManager and provides a concrete implementation
-    for executing actions in each phase.
+    for executing actions in each phase. All phases are treated as turn-based,
+    meaning actions are only taken when explicitly triggered (no continuous actions).
 
     Args:
         url (Optional[str]): WebSocket server URL
@@ -416,7 +389,11 @@ class HybridPhaseManager(PhaseManager):
     A manager for games that combine turn-based and continuous action phases.
 
     This manager extends PhaseManager and configures it with specific phases
-    that should be treated as continuous.
+    that should be treated as continuous. By default, all phases are treated as
+    turn-based unless explicitly included in the continuous_phases parameter.
+
+    For continuous-time phases, the manager will automatically execute actions periodically
+    with random delays between min_action_delay and max_action_delay seconds.
 
     Args:
         continuous_phases (Optional[set[int]]): Set of phase numbers that should be treated as continuous
@@ -425,8 +402,8 @@ class HybridPhaseManager(PhaseManager):
         auth_mechanism_kwargs (Optional[dict[str, Any]]): Keyword arguments for the authentication mechanism
         phase_transition_event (Optional[str]): Event name for phase transitions
         phase_identifier_key (Optional[str]): Key in the event data that identifies the phase
-        min_action_delay (Optional[int]): Minimum delay in seconds between actions in continuous phases
-        max_action_delay (Optional[int]): Maximum delay in seconds between actions in continuous phases
+        min_action_delay (Optional[int]): Minimum delay in seconds between actions in continuous-time phases
+        max_action_delay (Optional[int]): Maximum delay in seconds between actions in continuous-time phases
         state (Optional[GameState]): Game state object to track game state
         agent_role (Optional[AgentRole]): Agent role instance to handle game phases
         logger (Optional[logging.Logger]): Logger instance for tracking events

econagents-0.0.2/econagents/llm/__init__.py

@@ -0,0 +1,20 @@
+from econagents.llm.base import BaseLLM, LLMProvider
+from econagents.llm.observability import ObservabilityProvider, get_observability_provider
+
+# Import specific implementations if available
+try:
+    from econagents.llm.openai import ChatOpenAI
+except ImportError:
+    pass
+
+try:
+    from econagents.llm.ollama import ChatOllama
+except ImportError:
+    pass
+
+__all__: list[str] = [
+    "BaseLLM",
+    "LLMProvider",
+    "ObservabilityProvider",
+    "get_observability_provider",
+]

econagents-0.0.2/econagents/llm/base.py

@@ -0,0 +1,62 @@
+from abc import ABC, abstractmethod
+from typing import Any, Protocol, runtime_checkable
+
+from econagents.llm.observability import ObservabilityProvider, get_observability_provider
+
+
+@runtime_checkable
+class LLMProvider(Protocol):
+    """Protocol for LLM providers."""
+
+    async def get_response(
+        self,
+        messages: list[dict[str, Any]],
+        tracing_extra: dict[str, Any],
+        **kwargs: Any,
+    ) -> str:
+        """Get a response from the LLM."""
+        ...
+
+    def build_messages(self, system_prompt: str, user_prompt: str) -> list[dict[str, Any]]:
+        """Build messages for the LLM."""
+        ...
+
+
+class BaseLLM(ABC):
+    """Base class for LLM implementations."""
+
+    observability: ObservabilityProvider = get_observability_provider("noop")
+
+    def build_messages(self, system_prompt: str, user_prompt: str) -> list[dict[str, Any]]:
+        """Build messages for the LLM.
+
+        Args:
+            system_prompt: The system prompt for the LLM.
+            user_prompt: The user prompt for the LLM.
+
+        Returns:
+            The messages for the LLM.
+        """
+        return [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt},
+        ]
+
+    @abstractmethod
+    async def get_response(
+        self,
+        messages: list[dict[str, Any]],
+        tracing_extra: dict[str, Any],
+        **kwargs: Any,
+    ) -> str:
+        """Get a response from the LLM.
+
+        Args:
+            messages: The messages for the LLM.
+            tracing_extra: The extra tracing information.
+            **kwargs: Additional arguments to pass to the LLM.
+
+        Returns:
+            The response from the LLM.
+        """
+        ...

econagents-0.0.2/econagents/llm/observability.py

@@ -0,0 +1,282 @@
+"""Observability interfaces for LLM providers."""
+
+import importlib.util
+import logging
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class ObservabilityProvider(ABC):
+    """Base class for observability providers."""
+
+    @abstractmethod
+    def track_llm_call(
+        self,
+        name: str,
+        model: str,
+        messages: List[Dict[str, Any]],
+        response: Any,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Track an LLM call directly without creating a run tree.
+
+        Args:
+            name: Name of the operation.
+            model: Model used for the call.
+            messages: Messages sent to the model.
+            response: Response from the model.
+            metadata: Additional metadata for the call.
+        """
+        ...
+
+
+class NoOpObservability(ObservabilityProvider):
+    """No-op observability provider that does nothing."""
+
+    def track_llm_call(
+        self,
+        name: str,
+        model: str,
+        messages: List[Dict[str, Any]],
+        response: Any,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """No-op implementation of track_llm_call."""
+        pass
+
+
+class LangSmithObservability(ObservabilityProvider):
+    """LangSmith observability provider."""
+
+    def __init__(self) -> None:
+        """Initialize the LangSmith observability provider."""
+        self._check_langsmith_available()
+
+    def _check_langsmith_available(self) -> None:
+        """Check if LangSmith is available."""
+        if not importlib.util.find_spec("langsmith"):
+            raise ImportError("LangSmith is not installed. Install it with: pip install econagents[langsmith]")
+
+    def _create_run_tree(
+        self,
+        name: str,
+        run_type: str,
+        inputs: Dict[str, Any],
+    ) -> Any:
+        """Create a LangSmith run tree.
+
+        Args:
+            name: Name of the run.
+            run_type: Type of the run (e.g., "chain", "llm").
+            inputs: Inputs for the run.
+
+        Returns:
+            A LangSmith RunTree object.
+        """
+        try:
+            from langsmith.run_trees import RunTree
+
+            run_tree = RunTree(name=name, run_type=run_type, inputs=inputs)
+            run_tree.post()
+            return run_tree
+        except ImportError:
+            logger.warning("LangSmith is not available. Using no-op run tree.")
+            return {"name": name, "run_type": run_type, "inputs": inputs}
+
+    def _create_child_run(
+        self,
+        parent_run: Any,
+        name: str,
+        run_type: str,
+        inputs: Dict[str, Any],
+    ) -> Any:
+        """Create a child run in LangSmith.
+
+        Args:
+            parent_run: Parent RunTree object.
+            name: Name of the child run.
+            run_type: Type of the child run.
+            inputs: Inputs for the child run.
+
+        Returns:
+            A child RunTree object.
+        """
+        try:
+            child_run = parent_run.create_child(
+                name=name,
+                run_type=run_type,
+                inputs=inputs,
+            )
+            child_run.post()
+            return child_run
+        except (ImportError, AttributeError):
+            logger.warning("LangSmith create_child failed. Using no-op child run.")
+            return {"name": name, "run_type": run_type, "inputs": inputs, "parent": parent_run}
+
+    def _end_run(
+        self,
+        run: Any,
+        outputs: Dict[str, Any],
+    ) -> None:
+        """End a LangSmith run with outputs.
+
+        Args:
+            run: RunTree object to end.
+            outputs: Outputs of the run.
+        """
+        try:
+            run.end(outputs=outputs)
+            run.patch()
+        except (ImportError, AttributeError) as e:
+            logger.warning(f"LangSmith end_run failed: {e}")
+
+    def track_llm_call(
+        self,
+        name: str,
+        model: str,
+        messages: List[Dict[str, Any]],
+        response: Any,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Track an LLM call using LangSmith RunTree.
+
+        Args:
+            name: Name of the operation.
+            model: Model used for the call.
+            messages: Messages sent to the model.
+            response: Response from the model.
+            metadata: Additional metadata for the call.
+        """
+        try:
+            # Create a top-level run
+            run_tree = self._create_run_tree(
+                name=name, run_type="chain", inputs={"messages": messages, "metadata": metadata or {}}
+            )
+
+            # Create LLM child run
+            child_run = self._create_child_run(
+                parent_run=run_tree, name=f"{model} Call", run_type="llm", inputs={"messages": messages}
+            )
+
+            # End the runs
+            self._end_run(child_run, outputs=response)
+
+            # Get the content from the response if it's in the expected format
+            output_content = None
+            if hasattr(response, "choices") and response.choices:
+                if hasattr(response.choices[0], "message") and hasattr(response.choices[0].message, "content"):
+                    output_content = response.choices[0].message.content
+
+            self._end_run(run_tree, outputs={"response": output_content or response})
+        except Exception as e:
+            logger.warning(f"Failed to track LLM call with LangSmith: {e}")
+
+
+class LangFuseObservability(ObservabilityProvider):
+    """LangFuse observability provider."""
+
+    def __init__(self) -> None:
+        """Initialize the LangFuse observability provider."""
+        self._check_langfuse_available()
+        self._langfuse_client = None
+
+    def _check_langfuse_available(self) -> None:
+        """Check if LangFuse is available."""
+        if not importlib.util.find_spec("langfuse"):
+            raise ImportError("LangFuse is not installed. Install it with: pip install econagents[langfuse]")
+
+    def _get_langfuse_client(self) -> Any:
+        """Get or create a LangFuse client."""
+        if self._langfuse_client is None:
+            try:
+                from langfuse import Langfuse
+
+                self._langfuse_client = Langfuse()
+            except ImportError:
+                logger.warning("LangFuse is not available.")
+                return None
+        return self._langfuse_client
+
+    def track_llm_call(
+        self,
+        name: str,
+        model: str,
+        messages: List[Dict[str, Any]],
+        response: Any,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Track an LLM call using LangFuse generation.
+
+        Args:
+            name: Name of the operation.
+            model: Model used for the call.
+            messages: Messages sent to the model.
+            response: Response from the model.
+            metadata: Additional metadata for the call.
+        """
+        client = self._get_langfuse_client()
+        if client is None:
+            return
+
+        try:
+            # Create a generation in Langfuse
+            trace = client.trace(name=name, metadata={"model": model, **metadata} if metadata else {}, input=messages)
+            generation = trace.generation(
+                name=name + "_generation",
+                model=model,
+                model_parameters=metadata.get("model_parameters", {}) if metadata else {},
+                input=messages,
+                metadata=metadata or {},
+            )
+
+            # Get response content in appropriate format
+            output_content = response
+            if hasattr(response, "choices") and response.choices:
+                if hasattr(response.choices[0], "message") and hasattr(response.choices[0].message, "content"):
+                    output_content = response.choices[0].message.content
+            elif isinstance(response, dict) and "message" in response and "content" in response["message"]:
+                output_content = response["message"]["content"]
+
+            # Update generation and set end time
+            generation.end(output=output_content)
+            trace.update(output=output_content)
+
+            # Flush to ensure all requests are sent
+            client.flush()
+        except Exception as e:
+            logger.warning(f"Failed to track LLM call with LangFuse: {e}")
+
+
+def get_observability_provider(provider_name: str = "noop") -> ObservabilityProvider:
+    """Get an observability provider by name.
+
+    Args:
+        provider_name: The name of the provider to get.
+                      Options: "noop", "langsmith", "langfuse"
+
+    Returns:
+        An observability provider.
+
+    Raises:
+        ValueError: If the provider_name is invalid.
+    """
+    if provider_name == "noop":
+        return NoOpObservability()
+    elif provider_name == "langsmith":
+        try:
+            return LangSmithObservability()
+        except ImportError as e:
+            logger.warning(f"Failed to initialize LangSmith: {e}")
+            logger.warning("Falling back to NoOpObservability")
+            return NoOpObservability()
+    elif provider_name == "langfuse":
+        try:
+            return LangFuseObservability()
+        except ImportError as e:
+            logger.warning(f"Failed to initialize LangFuse: {e}")
+            logger.warning("Falling back to NoOpObservability")
+            return NoOpObservability()
+    else:
+        raise ValueError(f"Invalid observability provider: {provider_name}")

econagents-0.0.2/econagents/llm/ollama.py

@@ -0,0 +1,77 @@
+import importlib.util
+import json
+import logging
+from typing import Any, Dict, List, Optional
+
+from econagents.llm.base import BaseLLM
+
+logger = logging.getLogger(__name__)
+
+
+class ChatOllama(BaseLLM):
+    """A wrapper for LLM queries using Ollama."""
+
+    def __init__(
+        self,
+        model_name: str,
+        host: Optional[str] = None,
+    ) -> None:
+        """Initialize the Ollama LLM interface.
+
+        Args:
+            model_name: The model name to use.
+            host: The host for the Ollama API (e.g., "http://localhost:11434").
+        """
+        self._check_ollama_available()
+        self.model_name = model_name
+        self.host = host
+
+    def _check_ollama_available(self) -> None:
+        """Check if Ollama is available."""
+        if not importlib.util.find_spec("ollama"):
+            raise ImportError("Ollama is not installed. Install it with: pip install econagents[ollama]")
+
+    async def get_response(
+        self,
+        messages: List[Dict[str, Any]],
+        tracing_extra: Dict[str, Any],
+        **kwargs: Any,
+    ) -> str:
+        """Get a response from the LLM.
+
+        Args:
+            messages: The messages for the LLM.
+            tracing_extra: The extra tracing information.
+            **kwargs: Additional arguments to pass to the LLM.
+
+        Returns:
+            The response from the LLM.
+
+        Raises:
+            ImportError: If Ollama is not installed.
+        """
+        try:
+            from ollama import AsyncClient
+
+            client = AsyncClient(host=self.host)
+
+            response = await client.chat(
+                model=self.model_name,
+                messages=messages,
+                **kwargs,
+            )
+
+            # End the LLM run
+            self.observability.track_llm_call(
+                name="ollama_chat_completion",
+                model=self.model_name,
+                messages=messages,
+                response=response,
+                metadata=tracing_extra,
+            )
+
+            return response["message"]["content"]
+
+        except ImportError as e:
+            logger.error(f"Failed to import Ollama: {e}")
+            raise ImportError("Ollama is not installed. Install it with: pip install econagents[ollama]") from e

econagents-0.0.2/econagents/llm/openai.py

@@ -0,0 +1,77 @@
+import importlib.util
+import logging
+from typing import Any, Optional
+
+from econagents.llm.base import BaseLLM
+
+logger = logging.getLogger(__name__)
+
+
+class ChatOpenAI(BaseLLM):
+    """A wrapper for LLM queries using OpenAI."""
+
+    def __init__(
+        self,
+        model_name: str = "gpt-4o",
+        api_key: Optional[str] = None,
+    ) -> None:
+        """Initialize the OpenAI LLM interface.
+
+        Args:
+            model_name: The model name to use.
+            api_key: The API key to use for authentication.
+        """
+        self.model_name = model_name
+        self.api_key = api_key
+        self._check_openai_available()
+
+    def _check_openai_available(self) -> None:
+        """Check if OpenAI is available."""
+        if not importlib.util.find_spec("openai"):
+            raise ImportError("OpenAI is not installed. Install it with: pip install econagents[openai]")
+
+    async def get_response(
+        self,
+        messages: list[dict[str, Any]],
+        tracing_extra: dict[str, Any],
+        **kwargs: Any,
+    ) -> str:
+        """Get a response from the LLM.
+
+        Args:
+            messages: The messages for the LLM.
+            tracing_extra: The extra tracing information.
+            **kwargs: Additional arguments to pass to the LLM.
+
+        Returns:
+            The response from the LLM.
+
+        Raises:
+            ImportError: If OpenAI is not installed.
+        """
+        try:
+            from openai import AsyncOpenAI
+
+            client = AsyncOpenAI(api_key=self.api_key)
+
+            # Create OpenAI completion
+            response = await client.chat.completions.create(
+                model=self.model_name,
+                messages=messages,  # type: ignore
+                response_format={"type": "json_object"},
+                **kwargs,
+            )
+
+            # Track the LLM call using the observability provider
+            self.observability.track_llm_call(
+                name="openai_chat_completion",
+                model=self.model_name,
+                messages=messages,
+                response=response,
+                metadata=tracing_extra,
+            )
+
+            return response.choices[0].message.content
+        except ImportError as e:
+            logger.error(f"Failed to import OpenAI: {e}")
+            raise ImportError("OpenAI is not installed. Install it with: pip install econagents[openai]") from e

{econagents-0.0.1 → econagents-0.0.2}/pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["poetry-core>=1.0.0", "poetry-dynamic-versioning>=1.0.1"]
+requires = ["poetry-core>=1.0.0", "poetry-dynamic-versioning>=1.0.0,<2.0.0"]
 build-backend = "poetry_dynamic_versioning.backend"
 
 [tool.poetry-dynamic-versioning]
@@ -7,37 +7,59 @@ enable = false
 vcs = "git"
 style = "semver"
 
-[tool.poetry]
+[project]
 name = "econagents"
-version = "0.0.1"  # Do not change, let poetry-dynamic-versioning handle it.
+license = { file = "LICENSE" }
+description = "econagents is a Python library that lets you use LLM agents in economic experiments. The framework connects LLM agents to game servers through WebSockets and provides a flexible architecture for designing, customizing, and running economic simulations."
+readme = "README.md"
 homepage = "https://github.com/iwanalabs/econagents"
 repository = "https://github.com/iwanalabs/econagents"
-license = "Apache-2.0"
-description = ""
-authors = ["Dylan"]
-readme = "README.md"
+dynamic = ["version"]
+
+[tool.poetry]
+name = "econagents"
+version = "0.0.2"  # Do not change, let poetry-dynamic-versioning handle it.
 packages = [{include = "econagents"}]
 include = ["econagents/*.so", "econagents/*.pyd"]  # Compiled extensions
 
 [tool.poetry.build]
 generate-setup-file = false
 
-[tool.poetry.scripts]
-
 [tool.poetry.dependencies]
 # Be as loose as possible if writing a library.
 python = ">=3.10,<3.13"
-typing-extensions = "^4.12.2"
-openai = "^1.65.5"
-langsmith = "^0.3.13"
-numpy = "^2.2.3"
-websockets = "^15.0"
 pydantic = "^2.10.6"
 requests = "^2.32.3"
+websockets = "^15.0"
+
+# Optional dependencies
+[tool.poetry.group.openai]
+optional = true
+
+[tool.poetry.group.openai.dependencies]
+openai = "^1.68.2"
+
+[tool.poetry.group.ollama]
+optional = true
+
+[tool.poetry.group.ollama.dependencies]
+ollama = "^0.1.9"
+
+[tool.poetry.group.langsmith]
+optional = true
+
+[tool.poetry.group.langsmith.dependencies]
+langsmith = "^0.3.19"
+
+[tool.poetry.group.langfuse]
+optional = true
+
+[tool.poetry.group.langfuse.dependencies]
+langfuse = "^2.60.2"
 
 [tool.poetry.group.docs.dependencies]
 myst-parser = {extras = ["linkify"], version = "^4.0.1"}
-sphinx = "~7.4.7"
+sphinx = "~8.1.3"
 sphinx_rtd_theme = "~3.0.2"
 gitpython = ">=3.1.31"
 sphinx-copybutton = "^0.5.2"
@@ -52,7 +74,7 @@ pytest-mock = ">=3.7.0"
 python-dotenv = "^1.0.1"
 jupyter = "^1.1.1"
 nest-asyncio = "^1.6.0"
-ruff = "^0.9.7"
+ruff = "^0.11.2"
 types-requests = "^2.32.0.20250306"
 pytest-asyncio = "^0.25.3"
 
@@ -151,3 +173,11 @@ ignore = [
 
 [tool.codespell]
 skip = 'poetry.lock,'
+
+[tool.poetry.extras]
+openai = ["openai"]
+ollama = ["ollama"]
+langsmith = ["langsmith"]
+langfuse = ["langfuse"]
+default = ["openai", "langsmith"]
+all = ["openai", "ollama", "langsmith", "langfuse"]

econagents-0.0.1/econagents/llm/__init__.py

@@ -1,3 +0,0 @@
-from econagents.llm.openai import ChatOpenAI
-
-__all__: list[str] = ["ChatOpenAI"]

econagents-0.0.1/econagents/llm/openai.py

@@ -1,61 +0,0 @@
-from typing import Any, Optional
-
-from langsmith import traceable
-from langsmith.wrappers import wrap_openai
-from openai import AsyncOpenAI
-
-
-class ChatOpenAI:
-    """
-    A simple wrapper for LLM queries, e.g. using OpenAI and LangSmith.
-    """
-
-    def __init__(
-        self,
-        model_name: str = "gpt-4o",
-        api_key: Optional[str] = None,
-    ) -> None:
-        """Initialize the LLM interface."""
-        self.model_name = model_name
-        self.api_key = api_key
-
-    def build_messages(self, system_prompt: str, user_prompt: str):
-        """Build messages for the LLM.
-
-        Args:
-            system_prompt (str): The system prompt for the LLM.
-            user_prompt (str): The user prompt for the LLM.
-
-        Returns:
-            list[dict[str, Any]]: The messages for the LLM.
-        """
-        return [
-            {"role": "system", "content": system_prompt},
-            {"role": "user", "content": user_prompt},
-        ]
-
-    @traceable
-    async def get_response(
-        self,
-        messages: list[dict[str, Any]],
-        tracing_extra: dict[str, Any],
-        **kwargs: Any,
-    ):
-        """Get a response from the LLM.
-
-        Args:
-            messages (list[dict[str, Any]]): The messages for the LLM.
-            tracing_extra (dict[str, Any]): The extra tracing information.
-
-        Returns:
-            str: The response from the LLM.
-        """
-        client = wrap_openai(AsyncOpenAI(api_key=self.api_key))
-        response = await client.chat.completions.create(
-            messages=messages,  # type: ignore
-            model=self.model_name,
-            response_format={"type": "json_object"},
-            langsmith_extra=tracing_extra,
-            **kwargs,
-        )
-        return response.choices[0].message.content