gunn.facades package

Submodules

gunn.facades.message module

Message-oriented facade interface for multi-agent simulation.

This module provides a message-oriented interface that wraps the Orchestrator functionality, allowing developers to interact with the simulation using event-driven patterns like emit() for broadcasting and subscription-based message delivery.

class gunn.facades.message.MessageSubscription(agent_id, message_types=None, handler=None)

ベースクラス: object

Represents a message subscription for an agent.

パラメータ:

• agent_id (str)

• message_types (set[str] | None)

• handler (Callable[[str, dict[str, Any]], None] | Callable[[str, dict[str, Any]], Any] | None)

matches(message_type)

Check if this subscription matches a message type.

戻り値の型:

bool

パラメータ:

message_type (str)

Args:

message_type: Message type to check

Returns:

True if subscription matches, False otherwise

class gunn.facades.message.MessageFacade(orchestrator=None, config=None, world_id='default', timeout_seconds=30.0)

ベースクラス: object

Message-oriented facade wrapping Orchestrator functionality.

Provides an event-driven interface with emit() for broadcasting and subscription-based message delivery while operating on the same underlying event system as other facades.

Requirements addressed: - 5.3: Developers call env.emit() to broadcast events through ObservationPolicy filtering - 5.4: Agents receive messages according to their observation policies - 5.5: Operates on the same underlying event system

パラメータ:

• orchestrator (Orchestrator | None)

• config (OrchestratorConfig | None)

• world_id (str)

• timeout_seconds (float)

async initialize()

Initialize the underlying orchestrator and start message delivery.

戻り値の型:

None

async register_agent(agent_id, policy)

Register an agent with the simulation.

戻り値の型:

None

パラメータ:

• agent_id (str)

• policy (ObservationPolicy)

Args:

agent_id: Unique identifier for the agent policy: Observation policy for this agent

Raises:

ValueError: If agent_id is invalid or already registered RuntimeError: If maximum agents exceeded

async emit(message_type, payload, source_id, schema_version='1.0.0')

Broadcast an event through observation policies.

This method implements requirement 5.3: developers call env.emit() to broadcast events through ObservationPolicy filtering.

戻り値の型:

None

パラメータ:

• message_type (str)

• payload (dict[str, Any])

• source_id (str)

• schema_version (str)

Args:

message_type: Type of message being emitted payload: Message payload data source_id: Identifier of the message source schema_version: Schema version for the message

Raises:

ValueError: If message_type or source_id is invalid BackpressureError: If backpressure limits are exceeded ValidationError: If message validation fails TimeoutError: If emission times out

Requirements addressed: - 5.3: WHEN using message facade THEN developers SHALL call env.emit() to broadcast events through ObservationPolicy filtering

async subscribe(agent_id, message_types=None, handler=None)

Subscribe an agent to specific message types.

This method implements requirement 5.4: agents receive messages according to their observation policies.

戻り値の型:

MessageSubscription

パラメータ:

• agent_id (str)

• message_types (set[str] | None)

• handler (Callable[[str, dict[str, Any]], None] | Callable[[str, dict[str, Any]], Any] | None)

Args:

agent_id: Agent identifier message_types: Set of message types to subscribe to (None = all types) handler: Optional message handler function

Returns:

MessageSubscription object for managing the subscription

Raises:

ValueError: If agent_id is not registered

Requirements addressed: - 5.4: WHEN using message facade THEN agents SHALL receive messages according to their observation policies

async unsubscribe(subscription)

Remove a message subscription.

戻り値の型:

None

パラメータ:

subscription (MessageSubscription)

Args:

subscription: Subscription to remove

async get_messages(agent_id, timeout=None)

Get pending messages for an agent.

戻り値の型:

list[dict[str, Any]]

パラメータ:

• agent_id (str)

• timeout (float | None)

Args:

agent_id: Agent identifier timeout: Optional timeout for waiting for messages

Returns:

List of pending messages

Raises:

ValueError: If agent_id is not registered TimeoutError: If timeout is exceeded

async wait_for_message(agent_id, message_type=None, timeout=None)

Wait for a specific message for an agent.

戻り値の型:

dict[str, Any]

パラメータ:

• agent_id (str)

• message_type (str | None)

• timeout (float | None)

Args:

agent_id: Agent identifier message_type: Optional specific message type to wait for timeout: Optional timeout for waiting

Returns:

The received message

Raises:

ValueError: If agent_id is not registered TimeoutError: If timeout is exceeded

async shutdown()

Shutdown the message facade and clean up resources.

Cancels all delivery tasks and shuts down the orchestrator.

戻り値の型:

None

get_orchestrator()

Get the underlying orchestrator instance.

戻り値の型:

Orchestrator

Returns:

The orchestrator instance used by this facade

Requirements addressed: - 5.5: Both facades operate on the same underlying event system

set_timeout(timeout_seconds)

Set the default timeout for operations.

戻り値の型:

None

パラメータ:

timeout_seconds (float)

Args:

timeout_seconds: New timeout value in seconds

Raises:

ValueError: If timeout_seconds is not positive

get_agent_subscriptions(agent_id)

Get all active subscriptions for an agent.

戻り値の型:

list[MessageSubscription]

パラメータ:

agent_id (str)

Args:

agent_id: Agent identifier

Returns:

List of active subscriptions

Raises:

ValueError: If agent_id is not registered

get_message_queue_size(agent_id)

Get the current size of an agent's message queue.

戻り値の型:

int

パラメータ:

agent_id (str)

Args:

agent_id: Agent identifier

Returns:

Number of pending messages

Raises:

ValueError: If agent_id is not registered

gunn.facades.rl module

RL-style facade interface for multi-agent simulation.

This module provides an RL-style interface that wraps the Orchestrator functionality, allowing developers to interact with the simulation using familiar RL patterns like observe() and step() methods.

class gunn.facades.rl.RLFacade(orchestrator=None, config=None, world_id='default', timeout_seconds=30.0)

ベースクラス: object

RL-style facade wrapping Orchestrator functionality.

Provides a familiar RL interface with observe() and step() methods while operating on the same underlying event system as other facades.

Requirements addressed: - 5.1: Developers call env.observe(agent_id) to get observations - 5.2: Developers call env.step(agent_id, intent) and receive (Effect, ObservationDelta) tuple - 5.5: Operates on the same underlying event system

パラメータ:

• orchestrator (Orchestrator | None)

• config (OrchestratorConfig | None)

• world_id (str)

• timeout_seconds (float)

async initialize()

Initialize the underlying orchestrator.

戻り値の型:

None

async register_agent(agent_id, policy)

Register an agent with the simulation.

戻り値の型:

AgentHandle

パラメータ:

• agent_id (str)

• policy (ObservationPolicy)

Args:

agent_id: Unique identifier for the agent policy: Observation policy for this agent

Returns:

AgentHandle for the registered agent

Raises:

ValueError: If agent_id is invalid or already registered RuntimeError: If maximum agents exceeded

async observe(agent_id)

Get current observations for an agent.

This method implements requirement 5.1: developers call env.observe(agent_id) to get observations.

戻り値の型:

ObservationDelta

パラメータ:

agent_id (str)

Args:

agent_id: Agent identifier

Returns:

Current observation delta for the agent

Raises:

ValueError: If agent_id is not registered TimeoutError: If observation retrieval times out RuntimeError: If agent handle is not available

Requirements addressed: - 5.1: WHEN using RL facade THEN developers SHALL call env.observe(agent_id) to get observations

async step(agent_id, intent)

Execute a step with an intent and return the effect and observation.

This method implements requirement 5.2: developers call env.step(agent_id, intent) and receive (Effect, ObservationDelta) tuple.

戻り値の型:

tuple[Effect, ObservationDelta]

パラメータ:

• agent_id (str)

• intent (Intent)

Args:

agent_id: Agent identifier intent: Intent to execute

Returns:

Tuple of (Effect, ObservationDelta) representing the action result

Raises:

ValueError: If agent_id is not registered or intent is invalid StaleContextError: If intent context is stale QuotaExceededError: If agent quota is exceeded BackpressureError: If backpressure limits are exceeded ValidationError: If intent validation fails TimeoutError: If step execution times out

Requirements addressed: - 5.2: WHEN using RL facade THEN developers SHALL call env.step(agent_id, intent) and receive (Effect, ObservationDelta) tuple

async shutdown()

Shutdown the RL facade and clean up resources.

Cancels any pending step operations and shuts down the orchestrator.

戻り値の型:

None

get_orchestrator()

Get the underlying orchestrator instance.

戻り値の型:

Orchestrator

Returns:

The orchestrator instance used by this facade

Requirements addressed: - 5.5: Both facades operate on the same underlying event system

set_timeout(timeout_seconds)

Set the default timeout for operations.

戻り値の型:

None

パラメータ:

timeout_seconds (float)

Args:

timeout_seconds: New timeout value in seconds

Raises:

ValueError: If timeout_seconds is not positive

async get_agent_view_seq(agent_id)

Get the current view sequence for an agent.

戻り値の型:

int

パラメータ:

agent_id (str)

Args:

agent_id: Agent identifier

Returns:

Current view sequence number

Raises:

ValueError: If agent_id is not registered

async cancel_agent_step(agent_id)

Cancel any pending step operation for an agent.

戻り値の型:

bool

パラメータ:

agent_id (str)

Args:

agent_id: Agent identifier

Returns:

True if a step was cancelled, False if no step was pending

Raises:

ValueError: If agent_id is not registered

Module contents

class gunn.facades.MessageFacade(orchestrator=None, config=None, world_id='default', timeout_seconds=30.0)

ベースクラス: object

Message-oriented facade wrapping Orchestrator functionality.

Provides an event-driven interface with emit() for broadcasting and subscription-based message delivery while operating on the same underlying event system as other facades.

Requirements addressed: - 5.3: Developers call env.emit() to broadcast events through ObservationPolicy filtering - 5.4: Agents receive messages according to their observation policies - 5.5: Operates on the same underlying event system

パラメータ:

• orchestrator (Orchestrator | None)

• config (OrchestratorConfig | None)

• world_id (str)

• timeout_seconds (float)

async emit(message_type, payload, source_id, schema_version='1.0.0')

Broadcast an event through observation policies.

This method implements requirement 5.3: developers call env.emit() to broadcast events through ObservationPolicy filtering.

戻り値の型:

None

パラメータ:

• message_type (str)

• payload (dict[str, Any])

• source_id (str)

• schema_version (str)

Args:

message_type: Type of message being emitted payload: Message payload data source_id: Identifier of the message source schema_version: Schema version for the message

Raises:

ValueError: If message_type or source_id is invalid BackpressureError: If backpressure limits are exceeded ValidationError: If message validation fails TimeoutError: If emission times out

Requirements addressed: - 5.3: WHEN using message facade THEN developers SHALL call env.emit() to broadcast events through ObservationPolicy filtering

get_agent_subscriptions(agent_id)

Get all active subscriptions for an agent.

戻り値の型:

list[MessageSubscription]

パラメータ:

agent_id (str)

Args:

agent_id: Agent identifier

Returns:

List of active subscriptions

Raises:

ValueError: If agent_id is not registered

get_message_queue_size(agent_id)

Get the current size of an agent's message queue.

戻り値の型:

int

パラメータ:

agent_id (str)

Args:

agent_id: Agent identifier

Returns:

Number of pending messages

Raises:

ValueError: If agent_id is not registered

async get_messages(agent_id, timeout=None)

Get pending messages for an agent.

戻り値の型:

list[dict[str, Any]]

パラメータ:

• agent_id (str)

• timeout (float | None)

Args:

agent_id: Agent identifier timeout: Optional timeout for waiting for messages

Returns:

List of pending messages

Raises:

ValueError: If agent_id is not registered TimeoutError: If timeout is exceeded

get_orchestrator()

Get the underlying orchestrator instance.

戻り値の型:

Orchestrator

Returns:

The orchestrator instance used by this facade

Requirements addressed: - 5.5: Both facades operate on the same underlying event system

async initialize()

Initialize the underlying orchestrator and start message delivery.

戻り値の型:

None

async register_agent(agent_id, policy)

Register an agent with the simulation.

戻り値の型:

None

パラメータ:

• agent_id (str)

• policy (ObservationPolicy)

Args:

agent_id: Unique identifier for the agent policy: Observation policy for this agent

Raises:

ValueError: If agent_id is invalid or already registered RuntimeError: If maximum agents exceeded

set_timeout(timeout_seconds)

Set the default timeout for operations.

戻り値の型:

None

パラメータ:

timeout_seconds (float)

Args:

timeout_seconds: New timeout value in seconds

Raises:

ValueError: If timeout_seconds is not positive

async shutdown()

Shutdown the message facade and clean up resources.

Cancels all delivery tasks and shuts down the orchestrator.

戻り値の型:

None

async subscribe(agent_id, message_types=None, handler=None)

Subscribe an agent to specific message types.

This method implements requirement 5.4: agents receive messages according to their observation policies.

戻り値の型:

MessageSubscription

パラメータ:

• agent_id (str)

• message_types (set[str] | None)

• handler (Callable[[str, dict[str, Any]], None] | Callable[[str, dict[str, Any]], Any] | None)

Args:

agent_id: Agent identifier message_types: Set of message types to subscribe to (None = all types) handler: Optional message handler function

Returns:

MessageSubscription object for managing the subscription

Raises:

ValueError: If agent_id is not registered

Requirements addressed: - 5.4: WHEN using message facade THEN agents SHALL receive messages according to their observation policies

async unsubscribe(subscription)

Remove a message subscription.

戻り値の型:

None

パラメータ:

subscription (MessageSubscription)

Args:

subscription: Subscription to remove

async wait_for_message(agent_id, message_type=None, timeout=None)

Wait for a specific message for an agent.

戻り値の型:

dict[str, Any]

パラメータ:

• agent_id (str)

• message_type (str | None)

• timeout (float | None)

Args:

agent_id: Agent identifier message_type: Optional specific message type to wait for timeout: Optional timeout for waiting

Returns:

The received message

Raises:

ValueError: If agent_id is not registered TimeoutError: If timeout is exceeded

class gunn.facades.RLFacade(orchestrator=None, config=None, world_id='default', timeout_seconds=30.0)

ベースクラス: object

RL-style facade wrapping Orchestrator functionality.

Provides a familiar RL interface with observe() and step() methods while operating on the same underlying event system as other facades.

Requirements addressed: - 5.1: Developers call env.observe(agent_id) to get observations - 5.2: Developers call env.step(agent_id, intent) and receive (Effect, ObservationDelta) tuple - 5.5: Operates on the same underlying event system

パラメータ:

• orchestrator (Orchestrator | None)

• config (OrchestratorConfig | None)

• world_id (str)

• timeout_seconds (float)

async cancel_agent_step(agent_id)

Cancel any pending step operation for an agent.

戻り値の型:

bool

パラメータ:

agent_id (str)

Args:

agent_id: Agent identifier

Returns:

True if a step was cancelled, False if no step was pending

Raises:

ValueError: If agent_id is not registered

async get_agent_view_seq(agent_id)

Get the current view sequence for an agent.

戻り値の型:

int

パラメータ:

agent_id (str)

Args:

agent_id: Agent identifier

Returns:

Current view sequence number

Raises:

ValueError: If agent_id is not registered

get_orchestrator()

Get the underlying orchestrator instance.

戻り値の型:

Orchestrator

Returns:

The orchestrator instance used by this facade

Requirements addressed: - 5.5: Both facades operate on the same underlying event system

async initialize()

Initialize the underlying orchestrator.

戻り値の型:

None

async observe(agent_id)

Get current observations for an agent.

This method implements requirement 5.1: developers call env.observe(agent_id) to get observations.

戻り値の型:

ObservationDelta

パラメータ:

agent_id (str)

Args:

agent_id: Agent identifier

Returns:

Current observation delta for the agent

Raises:

ValueError: If agent_id is not registered TimeoutError: If observation retrieval times out RuntimeError: If agent handle is not available

Requirements addressed: - 5.1: WHEN using RL facade THEN developers SHALL call env.observe(agent_id) to get observations

async register_agent(agent_id, policy)

Register an agent with the simulation.

戻り値の型:

AgentHandle

パラメータ:

• agent_id (str)

• policy (ObservationPolicy)

Args:

agent_id: Unique identifier for the agent policy: Observation policy for this agent

Returns:

AgentHandle for the registered agent

Raises:

ValueError: If agent_id is invalid or already registered RuntimeError: If maximum agents exceeded

set_timeout(timeout_seconds)

Set the default timeout for operations.

戻り値の型:

None

パラメータ:

timeout_seconds (float)

Args:

timeout_seconds: New timeout value in seconds

Raises:

ValueError: If timeout_seconds is not positive

async shutdown()

Shutdown the RL facade and clean up resources.

Cancels any pending step operations and shuts down the orchestrator.

戻り値の型:

None

async step(agent_id, intent)

Execute a step with an intent and return the effect and observation.

This method implements requirement 5.2: developers call env.step(agent_id, intent) and receive (Effect, ObservationDelta) tuple.

戻り値の型:

tuple[Effect, ObservationDelta]

パラメータ:

• agent_id (str)

• intent (Intent)

Args:

agent_id: Agent identifier intent: Intent to execute

Returns:

Tuple of (Effect, ObservationDelta) representing the action result

Raises:

ValueError: If agent_id is not registered or intent is invalid StaleContextError: If intent context is stale QuotaExceededError: If agent quota is exceeded BackpressureError: If backpressure limits are exceeded ValidationError: If intent validation fails TimeoutError: If step execution times out

Requirements addressed: - 5.2: WHEN using RL facade THEN developers SHALL call env.step(agent_id, intent) and receive (Effect, ObservationDelta) tuple