Skip to content

agenticraft_foundation.specifications.mas_mappings

Bidirectional MAS theory mappings — BDI, Joint Intentions, SharedPlans, and Contract Net with formal property preservation.

Classical Multi-Agent Systems (MAS) formal mappings.

Maps classical MAS theories to mesh coordination primitives:

  1. BDI (Belief-Desire-Intention): Beliefs → context state, Desires → task objectives, Intentions → active assignments

  2. Joint Intentions (Cohen & Levesque): Mutual belief → consensus state, Persistent goal → task completion

  3. SharedPlans (Grosz & Kraus): Recipe → task decomposition DAG, Subgroup plans → agent clusters

  4. Contract Net Protocol (Smith 1980): Manager broadcasts CFP → bidders respond → manager awards

Each mapping provides bidirectional transformations between classical MAS concepts and mesh coordination state, with property preservation verification.

References: - Rao & Georgeff (1995) - BDI agents - Cohen & Levesque (1990) - Intention is choice with commitment - Grosz & Kraus (1996) - Collaborative plans - Smith (1980) - Contract Net Protocol

MASTheory

Bases: str, Enum

Classical MAS theories.

BDI = 'bdi' class-attribute instance-attribute

Belief-Desire-Intention architecture

JOINT_INTENTIONS = 'joint_intentions' class-attribute instance-attribute

Cohen & Levesque's Joint Intentions

SHARED_PLANS = 'shared_plans' class-attribute instance-attribute

Grosz & Kraus's SharedPlans

CONTRACT_NET = 'contract_net' class-attribute instance-attribute

Smith's Contract Net Protocol

MeshState dataclass

Representation of mesh coordination state.

Common structure that all MAS mappings convert to/from.

agents = field(default_factory=dict) class-attribute instance-attribute

Agent states: agent_id → {capabilities, assignments, status, ...}

tasks = field(default_factory=dict) class-attribute instance-attribute

Task states: task_id → {objective, status, assigned_agent, ...}

consensus = field(default_factory=dict) class-attribute instance-attribute

Consensus state: {round, decisions, proposed_values, ...}

messages = field(default_factory=list) class-attribute instance-attribute

Message history

BDIState dataclass

BDI agent mental state.

beliefs = field(default_factory=dict) class-attribute instance-attribute

Agent's beliefs about the world

desires = field(default_factory=list) class-attribute instance-attribute

Agent's desires (goals)

intentions = field(default_factory=list) class-attribute instance-attribute

Agent's committed intentions (active plans)

agent_id = '' class-attribute instance-attribute

Owning agent

BDIMapping

Map BDI mental state to/from mesh coordination state.

  • Beliefs → agent context state (world model)
  • Desires → task objectives (unassigned goals)
  • Intentions → active task assignments (committed plans)

to_mesh(bdi_states) staticmethod

Convert BDI states to mesh state.

PARAMETER DESCRIPTION
bdi_states

BDI states keyed by agent_id

TYPE: dict[str, BDIState]

RETURNS DESCRIPTION
MeshState

MeshState representation

from_mesh(mesh) staticmethod

Convert mesh state to BDI states.

PARAMETER DESCRIPTION
mesh

Mesh coordination state

TYPE: MeshState

RETURNS DESCRIPTION
dict[str, BDIState]

BDI states keyed by agent_id

JointIntentionState dataclass

Joint Intention state (Cohen & Levesque).

team = field(default_factory=set) class-attribute instance-attribute

Team members

mutual_beliefs = field(default_factory=dict) class-attribute instance-attribute

Mutually believed facts

persistent_goal = field(default_factory=dict) class-attribute instance-attribute

The persistent goal the team is committed to

joint_commitment = False class-attribute instance-attribute

Whether the team has a joint commitment

goal_status = 'active' class-attribute instance-attribute

Status: active, achieved, impossible, abandoned

JointIntentionMapping

Map Joint Intentions to/from mesh coordination.

  • Mutual belief → consensus state (agreed-upon facts)
  • Persistent goal → task with completion criteria
  • Joint commitment → all agents assigned to same task

to_mesh(ji_state) staticmethod

Convert Joint Intention state to mesh state.

from_mesh(mesh) staticmethod

Convert mesh state to Joint Intention state.

SharedPlanState dataclass

SharedPlans state (Grosz & Kraus).

recipe = field(default_factory=dict) class-attribute instance-attribute

Task decomposition: parent_task → [subtasks]

task_descriptions = field(default_factory=dict) class-attribute instance-attribute

Task descriptions: task_id → description

subgroup_assignments = field(default_factory=dict) class-attribute instance-attribute

Subgroup plans: task_id → assigned agents

partial_plan = True class-attribute instance-attribute

Whether the plan is still being elaborated

SharedPlanMapping

Map SharedPlans to/from mesh coordination.

  • Recipe → task decomposition DAG
  • Subgroup plans → agent cluster assignments

to_mesh(sp_state) staticmethod

Convert SharedPlan state to mesh state.

from_mesh(mesh) staticmethod

Convert mesh state to SharedPlan state.

ContractNetPhase

Bases: str, Enum

Phases of the Contract Net Protocol.

ANNOUNCEMENT = 'announcement' class-attribute instance-attribute

Manager announces task (CFP)

BIDDING = 'bidding' class-attribute instance-attribute

Bidders submit proposals

EVALUATION = 'evaluation' class-attribute instance-attribute

Manager evaluates bids

AWARDING = 'awarding' class-attribute instance-attribute

Manager awards contract

EXECUTION = 'execution' class-attribute instance-attribute

Contractor executes task

REPORTING = 'reporting' class-attribute instance-attribute

Contractor reports results

ContractNetState dataclass

Contract Net Protocol state.

manager = '' class-attribute instance-attribute

Manager agent ID

task = field(default_factory=dict) class-attribute instance-attribute

Task being contracted

phase = ContractNetPhase.ANNOUNCEMENT class-attribute instance-attribute

Current phase

bids = field(default_factory=dict) class-attribute instance-attribute

Bids received: bidder_id → bid details

winner = None class-attribute instance-attribute

Winning bidder

result = None class-attribute instance-attribute

Execution result

ContractNetMapping

Map Contract Net Protocol to/from mesh coordination.

  • Manager broadcasts CFP → task announcement message
  • Bidders respond → agent capability advertisements
  • Manager awards → task assignment

to_mesh(cn_state) staticmethod

Convert Contract Net state to mesh state.

from_mesh(mesh) staticmethod

Convert mesh state to Contract Net state.

verify_mapping_preservation(original_mesh, mapping_to, mapping_from, to_func='to_mesh', from_func='from_mesh')

Verify that a MAS mapping preserves key properties.

Checks: 1. Agent count is preserved 2. Task count is preserved 3. Assignment relationships are preserved

PARAMETER DESCRIPTION
original_mesh

Original mesh state

TYPE: MeshState

mapping_to

Mapping class with from_mesh method

TYPE: Any

mapping_from

Mapping class with to_mesh method

TYPE: Any

to_func

Name of the to_mesh method

TYPE: str DEFAULT: 'to_mesh'

from_func

Name of the from_mesh method

TYPE: str DEFAULT: 'from_mesh'

RETURNS DESCRIPTION
dict[str, Any]

Verification results