gunn.policies package

Submodules

gunn.policies.observation module

Observation policies for partial observation and view filtering.

This module implements the ObservationPolicy interface that controls what agents can observe in the simulation world, including distance-based filtering, relationship constraints, and efficient observation delta generation using RFC6902 JSON Patch operations.

class gunn.policies.observation.LatencyModel(*args, **kwargs)

ベースクラス: Protocol

Protocol for calculating observation delivery latency.

calculate_delay(from_agent, to_agent, effect)

Calculate delivery delay in seconds for an observation.

戻り値の型:

float

パラメータ:

• from_agent (str)

• to_agent (str)

• effect (Effect)

class gunn.policies.observation.PolicyConfig(**data)

ベースクラス: BaseModel

Configuration for observation policies.

パラメータ:

• distance_limit (float)

• relationship_filter (list[str])

• field_visibility (dict[str, bool])

• max_patch_ops (int)

• include_spatial_index (bool)

• relationship_depth (int)

distance_limit: float

relationship_filter: list[str]

field_visibility: dict[str, bool]

max_patch_ops: int

include_spatial_index: bool

relationship_depth: int

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class gunn.policies.observation.NoLatencyModel

ベースクラス: object

Default latency model with no delay.

calculate_delay(from_agent, to_agent, effect)

Return zero delay for immediate delivery.

戻り値の型:

float

パラメータ:

• from_agent (str)

• to_agent (str)

• effect (Effect)

class gunn.policies.observation.DistanceLatencyModel(base_latency=0.01, distance_factor=0.001)

ベースクラス: object

Latency model based on spatial distance between agents.

パラメータ:

• base_latency (float)

• distance_factor (float)

calculate_delay(from_agent, to_agent, effect)

Calculate latency based on distance between agents.

戻り値の型:

float

パラメータ:

• from_agent (str)

• to_agent (str)

• effect (Effect)

class gunn.policies.observation.ObservationPolicy(config)

ベースクラス: ABC

Abstract base class for observation policies.

Observation policies control what agents can see in the simulation world, including spatial filtering, relationship constraints, and field visibility.

パラメータ:

config (PolicyConfig)

set_latency_model(latency_model)

Set the latency model for observation delivery.

戻り値の型:

None

パラメータ:

latency_model (LatencyModel)

Args:

latency_model: Latency model to use for calculating delays

abstractmethod filter_world_state(world_state, agent_id)

Generate agent's filtered view of the world state.

戻り値の型:

View

パラメータ:

• world_state (WorldState)

• agent_id (str)

Args:

world_state: Complete world state agent_id: Agent requesting the view

Returns:

Filtered view containing only what the agent should see

abstractmethod should_observe_event(effect, agent_id, world_state)

Determine if an agent should observe a specific effect.

戻り値の型:

bool

パラメータ:

• effect (Effect)

• agent_id (str)

• world_state (WorldState)

Args:

effect: Effect that occurred agent_id: Agent to check observation for world_state: Current world state

Returns:

True if agent should observe this effect

calculate_observation_delta(old_view, new_view)

Generate RFC6902 JSON Patch between two views.

戻り値の型:

ObservationDelta

パラメータ:

• old_view (View)

• new_view (View)

Args:

old_view: Previous view state new_view: New view state

Returns:

ObservationDelta with JSON patch operations

Raises:

ValueError: If views are for different agents

class gunn.policies.observation.DefaultObservationPolicy(config)

ベースクラス: ObservationPolicy

Default observation policy with distance and relationship filtering.

This policy implements: - Distance-based spatial filtering - Relationship-based entity filtering - Field-level visibility controls - Stable path generation for JSON patches

パラメータ:

config (PolicyConfig)

filter_world_state(world_state, agent_id)

Generate agent's filtered view with distance and relationship constraints.

戻り値の型:

View

パラメータ:

• world_state (WorldState)

• agent_id (str)

Args:

world_state: Complete world state agent_id: Agent requesting the view

Returns:

Filtered view containing only observable entities and relationships

should_observe_event(effect, agent_id, world_state)

Determine if agent should observe an effect based on policy rules.

戻り値の型:

bool

パラメータ:

• effect (Effect)

• agent_id (str)

• world_state (WorldState)

Args:

effect: Effect that occurred agent_id: Agent to check observation for world_state: Current world state

Returns:

True if agent should observe this effect

class gunn.policies.observation.ConversationObservationPolicy(config)

ベースクラス: ObservationPolicy

Observation policy optimized for conversation scenarios.

This policy is designed for multi-agent conversations where agents should observe speaking events and participant changes, but may have limited spatial awareness.

パラメータ:

config (PolicyConfig)

filter_world_state(world_state, agent_id)

Generate conversation-focused view of the world state.

戻り値の型:

View

パラメータ:

• world_state (WorldState)

• agent_id (str)

Args:

world_state: Complete world state agent_id: Agent requesting the view

Returns:

View focused on conversation participants and recent messages

should_observe_event(effect, agent_id, world_state)

Determine if agent should observe conversation-related effects.

戻り値の型:

bool

パラメータ:

• effect (Effect)

• agent_id (str)

• world_state (WorldState)

Args:

effect: Effect that occurred agent_id: Agent to check observation for world_state: Current world state

Returns:

True if agent should observe this conversation effect

gunn.policies.observation.create_observation_policy(policy_type, config)

Create an observation policy of the specified type.

戻り値の型:

ObservationPolicy

パラメータ:

• policy_type (str)

• config (PolicyConfig)

Args:

policy_type: Type of policy to create ("default" or "conversation") config: Policy configuration

Returns:

Configured observation policy instance

Raises:

ValueError: If policy_type is not recognized

Module contents

Observation and validation policies for the Gunn simulation core.

class gunn.policies.ConversationObservationPolicy(config)

ベースクラス: ObservationPolicy

Observation policy optimized for conversation scenarios.

This policy is designed for multi-agent conversations where agents should observe speaking events and participant changes, but may have limited spatial awareness.

パラメータ:

config (PolicyConfig)

filter_world_state(world_state, agent_id)

Generate conversation-focused view of the world state.

戻り値の型:

View

パラメータ:

• world_state (WorldState)

• agent_id (str)

Args:

world_state: Complete world state agent_id: Agent requesting the view

Returns:

View focused on conversation participants and recent messages

should_observe_event(effect, agent_id, world_state)

Determine if agent should observe conversation-related effects.

戻り値の型:

bool

パラメータ:

• effect (Effect)

• agent_id (str)

• world_state (WorldState)

Args:

effect: Effect that occurred agent_id: Agent to check observation for world_state: Current world state

Returns:

True if agent should observe this conversation effect

class gunn.policies.DefaultObservationPolicy(config)

ベースクラス: ObservationPolicy

Default observation policy with distance and relationship filtering.

This policy implements: - Distance-based spatial filtering - Relationship-based entity filtering - Field-level visibility controls - Stable path generation for JSON patches

パラメータ:

config (PolicyConfig)

filter_world_state(world_state, agent_id)

Generate agent's filtered view with distance and relationship constraints.

戻り値の型:

View

パラメータ:

• world_state (WorldState)

• agent_id (str)

Args:

world_state: Complete world state agent_id: Agent requesting the view

Returns:

Filtered view containing only observable entities and relationships

should_observe_event(effect, agent_id, world_state)

Determine if agent should observe an effect based on policy rules.

戻り値の型:

bool

パラメータ:

• effect (Effect)

• agent_id (str)

• world_state (WorldState)

Args:

effect: Effect that occurred agent_id: Agent to check observation for world_state: Current world state

Returns:

True if agent should observe this effect

class gunn.policies.DistanceLatencyModel(base_latency=0.01, distance_factor=0.001)

ベースクラス: object

Latency model based on spatial distance between agents.

パラメータ:

• base_latency (float)

• distance_factor (float)

calculate_delay(from_agent, to_agent, effect)

Calculate latency based on distance between agents.

戻り値の型:

float

パラメータ:

• from_agent (str)

• to_agent (str)

• effect (Effect)

class gunn.policies.LatencyModel(*args, **kwargs)

ベースクラス: Protocol

Protocol for calculating observation delivery latency.

calculate_delay(from_agent, to_agent, effect)

Calculate delivery delay in seconds for an observation.

戻り値の型:

float

パラメータ:

• from_agent (str)

• to_agent (str)

• effect (Effect)

class gunn.policies.NoLatencyModel

ベースクラス: object

Default latency model with no delay.

calculate_delay(from_agent, to_agent, effect)

Return zero delay for immediate delivery.

戻り値の型:

float

パラメータ:

• from_agent (str)

• to_agent (str)

• effect (Effect)

class gunn.policies.ObservationPolicy(config)

ベースクラス: ABC

Abstract base class for observation policies.

Observation policies control what agents can see in the simulation world, including spatial filtering, relationship constraints, and field visibility.

パラメータ:

config (PolicyConfig)

calculate_observation_delta(old_view, new_view)

Generate RFC6902 JSON Patch between two views.

戻り値の型:

ObservationDelta

パラメータ:

• old_view (View)

• new_view (View)

Args:

old_view: Previous view state new_view: New view state

Returns:

ObservationDelta with JSON patch operations

Raises:

ValueError: If views are for different agents

abstractmethod filter_world_state(world_state, agent_id)

Generate agent's filtered view of the world state.

戻り値の型:

View

パラメータ:

• world_state (WorldState)

• agent_id (str)

Args:

world_state: Complete world state agent_id: Agent requesting the view

Returns:

Filtered view containing only what the agent should see

set_latency_model(latency_model)

Set the latency model for observation delivery.

戻り値の型:

None

パラメータ:

latency_model (LatencyModel)

Args:

latency_model: Latency model to use for calculating delays

abstractmethod should_observe_event(effect, agent_id, world_state)

Determine if an agent should observe a specific effect.

戻り値の型:

bool

パラメータ:

• effect (Effect)

• agent_id (str)

• world_state (WorldState)

Args:

effect: Effect that occurred agent_id: Agent to check observation for world_state: Current world state

Returns:

True if agent should observe this effect

class gunn.policies.PolicyConfig(**data)

ベースクラス: BaseModel

Configuration for observation policies.

パラメータ:

• distance_limit (Annotated[float, Ge(ge=0.0)])

• relationship_filter (list[str])

• field_visibility (dict[str, bool])

• max_patch_ops (Annotated[int, Ge(ge=1)])

• include_spatial_index (bool)

• relationship_depth (Annotated[int, Ge(ge=0)])

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

distance_limit: float

relationship_filter: list[str]

field_visibility: dict[str, bool]

max_patch_ops: int

include_spatial_index: bool

relationship_depth: int

gunn.policies.create_observation_policy(policy_type, config)

Create an observation policy of the specified type.

戻り値の型:

ObservationPolicy

パラメータ:

• policy_type (str)

• config (PolicyConfig)

Args:

policy_type: Type of policy to create ("default" or "conversation") config: Policy configuration

Returns:

Configured observation policy instance

Raises:

ValueError: If policy_type is not recognized