@spec apply_meta_dsl(t(), atom(), any()) :: %{
  optional(:state_updates) => map(),
  optional(:world_model_updates) => map(),
  optional(:goal_update) => goal_function(),
  optional(:meta_dsl_updates) => map()
}

Applies meta-DSL constructs for self-reflection and modification.

Executes meta-language constructs that allow objects to reason about and modify their own behavior, state, and goals. This is a core capability for autonomous self-improvement and adaptation.

Parameters

• object - The object to apply meta-DSL construct to
• construct - Meta-DSL construct to execute:
  • :define - Define new attributes or capabilities
  • :goal - Modify objective functions
  • :belief - Update world model beliefs
  • :infer - Perform inference on current knowledge
  • :decide - Make decisions based on current state
  • :learn - Process learning experiences
  • :refine - Adjust learning parameters
• args - Arguments specific to the construct

Returns

Map containing updates to be applied:

• :state_updates - Updates to object state
• :world_model_updates - Updates to world model
• :goal_update - New goal function
• :meta_dsl_updates - Updates to meta-DSL state

Examples

# Define a new attribute
# iex> result = Object.apply_meta_dsl(object, :define, {:confidence, 0.8})
# iex> result.state_updates
%{confidence: 0.8}

# Update beliefs through inference
# iex> inference_data = %{observations: [%{light: :on}], priors: %{light: :off}}
# iex> Object.apply_meta_dsl(object, :infer, inference_data)
%{world_model_updates: %{beliefs: %{light: :on}}, ...}

# Make a decision
# iex> context = %{options: [:explore, :exploit], current_reward: 0.5}
# iex> Object.apply_meta_dsl(object, :decide, context)
%{state_updates: %{last_action: :explore}, ...}

Meta-DSL Constructs

Each construct implements specific self-modification capabilities:

• DEFINE: Create new state variables or capabilities
• GOAL: Modify or replace objective functions
• BELIEF: Update world model through reasoning
• INFER: Bayesian inference on observations
• DECIDE: Goal-directed decision making
• LEARN: Experience-based learning
• REFINE: Meta-learning parameter adjustment

@spec create_subtype(
  object_subtype(),
  keyword()
) :: t()

Creates a specialized object subtype.

Factory function for creating objects with specialized behaviors and capabilities based on their intended role in the system. Each subtype comes with predefined methods, state structure, and behavioral patterns.

Parameters

• subtype - Object subtype to create:
  • :ai_agent - AI reasoning and learning agent
  • :human_client - Human user interaction interface
  • :sensor_object - Environmental sensing and data collection
  • :actuator_object - Physical action and control
  • :coordinator_object - Multi-object coordination and management
• opts - Additional options passed to subtype constructor

Returns

Specialized object with subtype-specific capabilities.

Subtype Characteristics

AI Agent

• Methods: [:learn, :reason, :plan, :execute, :adapt, :self_modify]
• Capabilities: Advanced reasoning, meta-learning, adaptation
• Use cases: Autonomous decision making, complex problem solving

Human Client

• Methods: [:communicate, :provide_feedback, :request_service]
• Capabilities: Natural language interface, preference learning
• Use cases: Human-AI collaboration, user interfaces

Sensor Object

• Methods: [:sense, :calibrate, :filter_noise, :transmit_data]
• Capabilities: Environmental monitoring, data preprocessing
• Use cases: IoT sensors, monitoring systems

Actuator Object

• Methods: [:execute_action, :queue_action, :calibrate_motion, :monitor_wear]
• Capabilities: Physical control, motion planning, safety monitoring
• Use cases: Robotics, industrial control, automation

Coordinator Object

• Methods: [:coordinate, :resolve_conflicts, :allocate_resources, :monitor_performance]
• Capabilities: Multi-agent coordination, resource management
• Use cases: System orchestration, resource allocation

Examples

# Create an AI agent with advanced capabilities
# iex> agent = Object.create_subtype(:ai_agent, 
...>   id: "reasoning_agent",
...>   state: %{intelligence_level: :advanced}
...> )
# iex> agent.subtype
:ai_agent
# iex> :reason in agent.methods
true

# Create a sensor with specific configuration
# iex> sensor = Object.create_subtype(:sensor_object,
...>   id: "temp_sensor",
...>   state: %{sensor_type: :temperature, accuracy: 0.98}
...> )
# iex> :calibrate in sensor.methods
true

Customization

All subtypes can be further customized:

• Add additional methods
• Modify state structure
• Override default behaviors
• Extend capabilities

@spec embed(t(), pos_integer()) :: [float()]

Generates an embedding representation of the object.

Creates a dense vector representation of the object that captures its essential characteristics. This embedding can be used for similarity calculations, clustering, and machine learning applications.

Parameters

• object - The object to embed
• dimension - Embedding vector dimension (default: 64)

Returns

List of floats representing the object in the embedding space. Values are normalized to the range [-1, 1].

Embedding Strategy

The embedding is based on:

• Object state hash for state information
• Methods hash for capability information
• Deterministic random generation for reproducibility

Examples

# Generate 64-dimensional embedding
# iex> embedding = Object.embed(object)
# iex> length(embedding)
64
# iex> Enum.all?(embedding, fn x -> x >= -1 and x <= 1 end)
true

# Custom dimension
# iex> small_embed = Object.embed(object, 8)
# iex> length(small_embed)
8

Use Cases

• Similarity Search: Find similar objects efficiently
• Clustering: Group objects by embedded characteristics
• Visualization: Project objects to 2D/3D for analysis
• Machine Learning: Features for ML models

Properties

• Deterministic: Same object always produces same embedding
• Stable: Small object changes produce small embedding changes
• Distributed: Similar objects have similar embeddings

@spec evaluate_goal(t()) :: number()

Evaluates the object's goal function against current state.

Computes how well the object's current state satisfies its objectives by applying the goal function to the current state. This is used for decision-making and learning signal generation.

Parameters

• object - The object whose goal to evaluate

Returns

Numerical goal satisfaction score. Higher values indicate better goal achievement.

Examples

# Object with energy maximization goal
# iex> object = Object.new(state: %{energy: 80})
# iex> Object.evaluate_goal(object)
80

# Custom goal function
# iex> goal_fn = fn state -> state.x + state.y end
# iex> object = Object.new(state: %{x: 3, y: 4}, goal: goal_fn)
# iex> Object.evaluate_goal(object)
7

Goal Function Types

• Maximization: Maximize sum of numeric state values (default)
• Distance: Minimize distance to target state
• Composite: Weighted combination of multiple objectives
• Learned: Evolved through meta-learning processes

@spec execute_method(t(), method_name(), [any()]) ::
  {:ok, t()} | {:error, atom() | tuple()}

Executes a method on the object with comprehensive error handling and resource protection.

Invokes the specified method with given arguments, ensuring the method is available and the system has sufficient resources. All method executions are protected by circuit breakers and retry logic to ensure system stability.

Parameters

• object - The object to execute the method on
• method - Method name (must be in object's methods list)
• args - List of arguments to pass to the method (default: [])

Returns

• {:ok, updated_object} - Method executed successfully
• {:error, reason} - Method execution failed

Error Conditions

• :method_not_available - Method not in object's methods list
• :throttled - System under high load, execution delayed
• :timeout - Method execution exceeded time limit
• :resource_exhausted - Insufficient system resources

Examples

# Execute a learning method
# iex> experience = %{reward: 1.0, action: :move_forward}
# iex> {:ok, updated} = Object.execute_method(object, :learn, [experience])
# iex> updated.state.q_values
%{move_forward: 0.01}

# Execute state update method
# iex> {:ok, updated} = Object.execute_method(object, :update_state, [%{energy: 95}])
# iex> updated.state.energy
95

# Method not available
# iex> Object.execute_method(object, :invalid_method, [])
{:error, :method_not_available}

Resource Protection

• Resource permission checked before execution
• Circuit breakers prevent system overload
• Execution timeouts prevent runaway methods
• Performance monitoring tracks method efficiency

@spec form_interaction_dyad(t(), object_id(), float()) :: t()

Forms an interaction dyad with another object.

Creates a bidirectional interaction relationship with another object, enabling enhanced communication, coordination, and social learning. Dyads are fundamental units of social interaction in the AAOS system.

Parameters

• object - First object in the dyad
• other_object_id - ID of the second object
• compatibility_score - Initial compatibility assessment (0.0-1.0, default: 0.5)

Returns

Updated object with dyad information added to mailbox.

Compatibility Scoring

Compatibility scores guide dyad effectiveness:

• 0.0-0.3 - Low compatibility, limited interaction benefit
• 0.3-0.7 - Moderate compatibility, good for specific tasks
• 0.7-1.0 - High compatibility, excellent collaboration potential

Examples

# Form dyad with high compatibility
# iex> updated = Object.form_interaction_dyad(object, "agent_2", 0.8)
# iex> dyads = Object.Mailbox.get_active_dyads(updated.mailbox)
# iex> map_size(dyads)
1

# Default compatibility
# iex> Object.form_interaction_dyad(object, "sensor_1")
%Object{mailbox: %{interaction_dyads: %{"obj_1-sensor_1" => %{...}}, ...}, ...}

Dyad Benefits

• Enhanced Communication: Priority message routing
• Social Learning: Shared experience and knowledge
• Coordination: Simplified cooperation protocols
• Trust Building: Reputation and reliability tracking

Lifecycle

1. Formation: Initial dyad creation with compatibility assessment
2. Interaction: Regular communication and coordination
3. Evolution: Compatibility adjustment based on outcomes
4. Dissolution: Automatic or manual dyad termination

@spec get_communication_stats(t()) :: %{
  total_messages_sent: non_neg_integer(),
  total_messages_received: non_neg_integer(),
  pending_inbox: non_neg_integer(),
  pending_outbox: non_neg_integer(),
  active_dyads: non_neg_integer(),
  total_dyads: non_neg_integer(),
  history_size: non_neg_integer(),
  uptime: non_neg_integer()
}

Gets the object's mailbox statistics.

Retrieves comprehensive statistics about the object's communication patterns, interaction history, and mailbox performance. Useful for monitoring, debugging, and performance optimization.

Parameters

• object - The object to get statistics for

Returns

Map containing:

• :total_messages_sent - Number of messages sent
• :total_messages_received - Number of messages received
• :pending_inbox - Current inbox message count
• :pending_outbox - Current outbox message count
• :active_dyads - Number of active interaction dyads
• :total_dyads - Total dyads (including inactive)
• :history_size - Current message history size
• :uptime - Object uptime in seconds

Examples

# iex> stats = Object.get_communication_stats(object)
# iex> stats.total_messages_sent
15
# iex> stats.active_dyads
3
# iex> stats.uptime
3600

Monitoring Uses

• Performance: Message throughput and latency
• Health: Mailbox capacity and processing rates
• Social: Interaction patterns and dyad effectiveness
• Debugging: Message flow analysis and error tracking

Performance Metrics

Key performance indicators:

• Messages per second: total_messages / uptime
• Dyad efficiency: active_dyads / total_dyads
• Processing ratio: pending_inbox / total_received

@spec interact(t(), map()) :: t()

Processes an interaction with another object or environment with error protection.

Handles various types of interactions including messages, coordination requests, and environmental events. All interactions are recorded in the object's history for learning and analysis purposes.

Parameters

• object - The object processing the interaction
• interaction - Map describing the interaction with required fields:
  • :type - Type of interaction (atom)
  • Other fields depend on interaction type

Returns

Updated object with interaction recorded in history.

Interaction Types

• :message - Message from another object
• :coordination - Coordination request or response
• :environmental - Environmental event or observation
• :learning - Learning signal or feedback

Examples

# Process a message interaction
# iex> interaction = %{type: :message, from: "agent_2", content: "hello"}
# iex> updated = Object.interact(object, interaction)
# iex> length(updated.interaction_history)
1

# Process coordination request
# iex> coord = %{type: :coordination, action: :form_coalition}
# iex> Object.interact(object, coord)
%Object{interaction_history: [%{type: :coordination, outcome: :success, ...}], ...}

Error Recovery

• Failed interactions are still recorded with error outcomes
• Circuit breaker prevents cascade failures
• Retry logic for transient failures
• Graceful degradation maintains object functionality

@spec learn(t(), map()) :: t()

Implements learning functionality using meta-DSL constructs with error resilience.

Processes learning experiences using reinforcement learning principles, updating the object's internal policies and knowledge. Learning is protected by resource monitoring and circuit breakers to ensure system stability.

Parameters

• object - The object to perform learning on
• experience - Learning experience map containing:
  • :reward - Numerical reward signal
  • :action - Action that was taken
  • Additional context-specific fields

Returns

Updated object with learning applied, or unchanged object if learning failed.

Learning Algorithm

Uses Q-learning with the following update rule:

Q(s,a) = Q(s,a) + α * (r - Q(s,a))

Where:

• α = learning rate
• r = reward
• Q(s,a) = action-value function

Examples

# Learn from positive reward
# iex> exp = %{reward: 1.0, action: :explore, state: %{position: {1, 1}}}
# iex> learned = Object.learn(object, exp)
# iex> learned.state.q_values[:explore]
0.01

# Learn from negative reward
# iex> exp = %{reward: -0.5, action: :retreat}
# iex> Object.learn(object, exp)
%Object{state: %{q_values: %{retreat: -0.005}}, ...}

Resource Management

• Learning requests resource permission before execution
• Exponential backoff retry strategy for failures
• Circuit breaker prevents learning system overload
• Performance monitoring tracks learning effectiveness

@spec new(keyword()) :: t()

Creates a new Object with the specified attributes.

Initializes a complete autonomous object with all AAOS-compliant capabilities including communication, learning, and meta-reasoning. Objects are created with default behaviors that can be customized through the options.

Parameters

• opts - Keyword list of options for object creation:
  • :id - Unique identifier for the object (auto-generated if not provided)
  • :state - Internal state parameters (default: empty map)
  • :methods - Available methods/functions (default: [:update_state, :interact, :learn])
  • :goal - Objective function (default: maximize state values)
  • :world_model - Beliefs about environment (default: empty beliefs)
  • :meta_dsl - Self-descriptive meta-language constructs (auto-initialized)
  • :parameters - Configuration parameters (default: empty map)
  • :subtype - Object specialization type (default: :generic)

Returns

New Object struct with all fields initialized and ready for use.

Examples

# Create a basic sensor object
# iex> Object.new(id: "sensor_1", state: %{readings: [1, 2, 3]})
%Object{id: "sensor_1", state: %{readings: [1, 2, 3]}, ...}

# Create an AI agent with custom goal function
# iex> goal_fn = fn state -> Map.get(state, :performance, 0) end
# iex> Object.new(id: "ai_agent", subtype: :ai_agent, goal: goal_fn)
%Object{id: "ai_agent", subtype: :ai_agent, goal: #Function<...>, ...}

# Create object with specific methods and parameters
# iex> Object.new(
...>   id: "coordinator", 
...>   methods: [:coordinate, :allocate_resources, :monitor],
...>   parameters: %{max_coordination_objects: 10}
...> )
%Object{id: "coordinator", methods: [:coordinate, :allocate_resources, :monitor], ...}

Performance Characteristics

• Object creation: ~0.1ms for basic objects
• Memory usage: ~1KB base + state size
• Mailbox initialization: ~0.05ms
• Meta-DSL setup: ~0.02ms

@spec process_messages(t()) :: {[{map(), term()}], t()}

Processes all messages in the object's mailbox.

Processes all pending messages in the inbox according to priority and type, applying appropriate message handlers and updating object state as needed. This is typically called periodically by the object server.

Parameters

• object - The object whose messages to process

Returns

{processed_messages, updated_object} where:

• processed_messages - List of processed messages with outcomes
• updated_object - Object with updated state and cleared inbox

Processing Order

Messages are processed in priority order:

1. :critical - System-critical messages
2. :high - Important coordination messages
3. :medium - Regular operational messages
4. :low - Background and maintenance messages

Examples

# Process accumulated messages
# {processed, updated} = Object.process_messages(object)
# length(processed) == 3
# length(updated.mailbox.inbox) == 0

# Check processing outcomes
# {[{msg1, result1}, {msg2, result2}], _obj} = Object.process_messages(object)
# result1 == {:coordination_received, %{action: :form_coalition}}

Message Handlers

Each message type has a specific handler:

• :state_update → Update object state
• :coordination → Process coordination request
• :learning_signal → Apply learning update
• :heartbeat → Update connection status
• :negotiation → Handle negotiation step

Performance

• Batch processing for efficiency
• Priority-based ordering prevents starvation
• Bounded processing time prevents blocking
• Error isolation prevents cascade failures

@spec receive_message(t(), map()) :: {:ok, t()} | {:error, atom() | tuple()}

Receives a message into the object's mailbox with error resilience.

Accepts an incoming message into the object's mailbox with comprehensive validation, error recovery, and poison message handling. Messages are processed according to their type and priority.

Parameters

• object - The receiving object
• message - Message to receive with required fields:
  • :id - Unique message identifier
  • :from - Sender object ID
  • :to - Recipient object ID (should match this object)
  • :type - Message type (atom)
  • :content - Message content
  • :timestamp - Message timestamp

Returns

• {:ok, updated_object} - Message received successfully
• {:error, reason} - Message reception failed

Error Conditions

• :malformed_message - Message missing required fields
• :mailbox_full - Mailbox capacity exceeded
• :invalid_timestamp - Message timestamp invalid
• :poison_message - Message failed validation multiple times

Examples

# Receive a valid message
# iex> message = %{
...>   id: "msg_123",
...>   from: "sender_1",
...>   to: object.id,
...>   type: :coordination,
...>   content: %{action: :join_coalition},
...>   timestamp: DateTime.utc_now()
...> }
# iex> {:ok, updated} = Object.receive_message(object, message)
# iex> length(updated.mailbox.inbox)
1

# Invalid message format
# iex> bad_message = %{invalid: true}
# iex> Object.receive_message(object, bad_message)
{:error, {:malformed_message, {:missing_fields, [:id, :from, ...]}}}

Message Processing

• Validation: Format and field validation
• Deduplication: Prevents duplicate message processing
• Priority Ordering: High-priority messages processed first
• Acknowledgments: Automatic ACK for messages requiring confirmation

Resilience Features

• Malformed messages sent to poison message queue
• Transient errors trigger retry logic
• Circuit breaker prevents mailbox overload
• Graceful degradation under resource pressure

@spec receive_message(t(), object_id(), any()) :: t()

Receives a message with explicit from and to parameters.

Alternative interface for receiving messages with explicit sender and recipient specification. This is used by some test scenarios and advanced routing systems.

Parameters

• object - The receiving object
• from_object_id - ID of the sending object
• message_content - Content of the message

Returns

Updated object with message in mailbox

@spec send_message(t(), object_id(), atom(), any(), keyword()) :: t()

Sends a message to another object via the mailbox system with delivery guarantees.

Routes a message through the mailbox and message routing system with comprehensive error handling, delivery guarantees, and dead letter queue fallback for failed deliveries. All messages are tracked for debugging and performance analysis.

Parameters

• object - The sending object
• to_object_id - ID of the recipient object
• message_type - Type of message (atom) for routing and handling
• content - Message content (any term)
• opts - Delivery options:
  • :priority - Message priority (:low, :medium, :high, :critical)
  • :requires_ack - Whether delivery confirmation is required
  • :ttl - Time-to-live in seconds (default: 3600)
  • :retry_count - Number of retry attempts on failure

Returns

Updated object with message sent and mailbox updated.

Message Types

Common message types include:

• :state_update - State change notification
• :coordination - Coordination request/response
• :learning_signal - Learning feedback or data
• :heartbeat - Connectivity check
• :negotiation - Negotiation protocol messages

Examples

# Send a coordination request
# iex> updated = Object.send_message(object, "coordinator_1", 
...>   :coordination, %{action: :form_coalition},
...>   priority: :high, requires_ack: true)
# iex> length(updated.mailbox.outbox)
1

# Send learning signal with TTL
# iex> Object.send_message(object, "learner_2",
...>   :learning_signal, %{reward: 1.0}, ttl: 300)
%Object{mailbox: %{outbox: [%{ttl: 300, ...}], ...}, ...}

Delivery Guarantees

• At-least-once: Messages with requires_ack: true
• Best-effort: Regular messages (may be lost under extreme load)
• Dead letter queue: Failed messages are queued for retry
• Circuit breaker: Prevents cascade failures from unreachable objects

Error Handling

• Message validation before sending
• Automatic retry with exponential backoff
• Dead letter queue for persistent failures
• Graceful degradation under resource pressure

@spec similarity(t(), t()) :: float()

Calculates similarity between two objects.

Computes a similarity score between two objects based on their state, methods, and goal functions. This is useful for clustering, coalition formation, and social learning partner selection.

Parameters

• obj1 - First object for comparison
• obj2 - Second object for comparison

Returns

Similarity score between 0.0 (completely different) and 1.0 (identical).

Similarity Metrics

The overall similarity is the average of:

• State similarity: Based on common state variables and their values
• Method similarity: Jaccard similarity of method sets
• Goal similarity: Functional similarity based on sample evaluations

Examples

# Identical objects
# iex> obj1 = Object.new(state: %{x: 1})
# iex> obj2 = Object.new(state: %{x: 1})
# iex> Object.similarity(obj1, obj2)
1.0

# Partially similar objects
# iex> sensor1 = Object.new(methods: [:sense, :transmit])
# iex> sensor2 = Object.new(methods: [:sense, :filter])
# iex> Object.similarity(sensor1, sensor2)  # 50% method overlap
0.67

Use Cases

• Coalition Formation: Find compatible partners
• Social Learning: Identify good imitation targets
• Object Clustering: Group similar objects
• Dyad Formation: Assess interaction compatibility

@spec update_state(t(), object_state()) :: t()

Updates the object's internal state with comprehensive error handling.

Performs a safe merge of the new state with the existing state, validating the update before applying it. If validation fails, the original object is returned unchanged and an error is logged.

Parameters

• object - The object to update
• new_state - Map of state updates to merge into current state

Returns

Updated object with merged state, or unchanged object if validation failed.

Validation Rules

• New state must be a map
• State size cannot exceed 100 entries
• Cannot contain forbidden keys (:internal, :system, :meta)

Examples

# Update sensor readings
# iex> sensor = Object.new(id: "temp_sensor", state: %{temp: 20.0})
# iex> updated = Object.update_state(sensor, %{temp: 22.5, humidity: 65})
# iex> updated.state
%{temp: 22.5, humidity: 65}

# Incremental updates preserve existing state
# iex> agent = Object.new(state: %{energy: 100, position: {0, 0}})
# iex> updated = Object.update_state(agent, %{energy: 95})
# iex> updated.state
%{energy: 95, position: {0, 0}}

Error Handling

• Invalid state formats are rejected and logged
• State size limits prevent memory exhaustion
• Forbidden keys are blocked to maintain system integrity
• All errors are handled gracefully without crashing the object

@spec update_world_model(t(), map()) :: t()

Updates the object's world model based on observations.

Merges new observations into the object's current beliefs about the world. This is a fundamental operation for maintaining accurate environmental knowledge and enabling effective decision-making.

Parameters

• object - The object whose world model to update
• observations - Map of new observations to incorporate

Returns

Updated object with modified world model.

Examples

# Update environmental observations
# iex> obs = %{temperature: 22.5, other_agents: ["agent_2", "agent_3"]}
# iex> updated = Object.update_world_model(object, obs)
# iex> updated.world_model.beliefs.temperature
22.5

# Incremental belief updates
# iex> Object.update_world_model(object, %{light_level: :bright})
%Object{world_model: %{beliefs: %{light_level: :bright}, ...}, ...}

World Model Structure

The world model contains:

• Current beliefs about environmental state
• Uncertainty estimates for each belief
• Historical observations for trend analysis