Society

society

Society — a named, serializable graph of agents and typed edges.

A Society is the top-level container for a Claw agent graph. It provides a builder API for declaring agents and edges, graph query methods for introspection, and serialization for version control and sharing.

Example::

from claw import Society, Agent, Oversight, Delegation

s = Society("pr-review", description="Automated PR review cycle")
pm = Agent("pm", role="dispatcher", model="claude-sonnet")
coder = Agent("coder", role="implementer", model="claude-opus")
reviewer = Agent("reviewer", role="critic", model="claude-sonnet")

s.add(pm, coder, reviewer)
s.connect(pm, coder, Delegation())
s.connect(coder, reviewer, Oversight(max_rounds=3))

Society

Bases: BaseModel

A named, serializable graph of agents and typed edges.

The Society is the central abstraction in Claw SDK. It holds agents (nodes) and edges (typed relationships), and provides a builder API for constructing the graph declaratively.

Parameters:

Name	Type	Description	Default
name		Unique name for this society.	required
description		Human-readable description of the society's purpose.	required
config		Global runtime configuration.	required

agents property

Return all agents in the society.

edges property

Return all binary edges in the society.

group_edges property

Return all group edges in the society.

all_edges property

Return all edges (binary and group) in the society.

model_post_init(__context)

Initialize mutable private state after Pydantic construction.

add(*agents)

Add one or more agents to the society.

Parameters:

Name	Type	Description	Default
agents	Agent	Agents to add.	()

Raises:

Type	Description
ValueError	If an agent with the same name already exists.

connect(source, target, edge_type)

Create a binary edge between two agents.

Both agents are automatically added to the society if not already present.

Parameters:

Name	Type	Description	Default
source	Agent	The originating agent.	required
target	Agent	The receiving agent.	required
edge_type	EdgeType	The edge type defining relationship semantics.	required

Returns:

Type	Description
Edge	The created Edge.

compete(agents, competition)

Create a group Competition edge among multiple agents.

All agents are automatically added to the society if not already present.

Parameters:

Name	Type	Description	Default
agents	list[Agent]	The competing agents.	required
competition	Competition	The Competition edge type with resolve strategy.	required

Returns:

Type	Description
GroupEdge	The created GroupEdge.

Raises:

Type	Description
TypeError	If edge_type is not a Competition.

cooperate(agents, cooperation)

Create a group Cooperation edge among multiple agents.

Parameters:

Name	Type	Description	Default
agents	list[Agent]	The cooperating agents.	required
cooperation	Cooperation	The Cooperation edge type.	required

Returns:

Type	Description
GroupEdge	The created GroupEdge.

Raises:

Type	Description
TypeError	If edge_type is not a Cooperation.

negotiate(agents, coopetition)

Create a group Coopetition edge among multiple agents.

Parameters:

Name	Type	Description	Default
agents	list[Agent]	The negotiating agents.	required
coopetition	Coopetition	The Coopetition edge type.	required

Returns:

Type	Description
GroupEdge	The created GroupEdge.

Raises:

Type	Description
TypeError	If edge_type is not a Coopetition.

get_agent(name)

Look up an agent by name.

Parameters:

Name	Type	Description	Default
name	str	Agent name to look up.	required

Returns:

Type	Description
Agent | None	The Agent, or None if not found.

edges_of(agent)

Return all edges (binary and group) involving an agent.

Parameters:

Name	Type	Description	Default
agent	Agent	The agent to query.	required

Returns:

Type	Description
list[Edge | GroupEdge]	List of edges where the agent is a participant.

edge_between(a, b)

Find a binary edge between two specific agents.

Parameters:

Name	Type	Description	Default
a	Agent	First agent.	required
b	Agent	Second agent.	required

Returns:

Type	Description
Edge | None	The Edge if found, None otherwise. Returns the first match
Edge | None	if multiple edges exist between the same pair.

to_dict()

Serialize the society to a JSON-compatible dictionary.

Returns:

Type	Description
dict[str, Any]	Dictionary representation of the society graph.

to_json()

Serialize the society to a JSON string.

Returns:

Type	Description
str	JSON string representation of the society graph.

from_dict(data) classmethod

Deserialize a society from a dictionary (inverse of to_dict()).

Reconstructs agents, binary edges, and group edges from their serialized representations. Agent references in edges are resolved by name against the reconstructed agent pool.

.. warning:: Security

Do **not** load societies from untrusted sources. A malicious
payload can define agents with arbitrary instructions and tool
access (e.g. ``shell_exec``, ``file_edit``), which will be
executed when the society is run. Only deserialize data you
produced yourself or received from a trusted origin.

Parameters:

Name	Type	Description	Default
data	dict[str, Any]	Dictionary with keys: name, description, agents, edges, group_edges, config.	required

Returns:

Type	Description
Society	A new Society instance.

Raises:

Type	Description
KeyError	If a referenced agent name is not found.
ValueError	If an edge type name is not recognized.

from_json(json_str) classmethod

Deserialize a society from a JSON string.

.. warning:: Security

Do **not** load societies from untrusted sources. See
:meth:`from_dict` for details.

Parameters:

Name	Type	Description	Default
json_str	str	JSON string (as produced by to_json()).	required

Returns:

Type	Description
Society	A new Society instance.