Compiler

Compilation

compile

Compiler — translate a Society graph into per-agent execution contexts.

The compiler is the bridge between the declarative graph and the runtime. It produces system prompts, filtered context, and tool schemas for each agent based on graph topology and edge semantics.

Key functions: - tools_for(edge, agent) — physically remove disallowed tools - compile(society) — initial compilation pass for all agents - compile_for_event(...) — per-event prompt assembly with budget management

AgentContext(agent, system_prompt, tools, visible_artifacts) dataclass

Initial compilation result for one agent.

Produced by compile() before any events are processed.

CompiledPrompt(system, context=list(), event_description='', tools=list(), total_tokens=0) dataclass

Per-event compilation result ready for LLM consumption.

Produced by compile_for_event().

tools_for(edge, agent)

Filter agent's tools based on edge type and role.

Physically removes disallowed tools from the schema so the LLM cannot invoke them. Custom tools (not in any known category) always pass through.

compile(society)

Initial compilation pass — produce base contexts for all agents.

Validates the topology, then builds system prompts and tool sets for each agent based on their edges.

Parameters:

Name	Type	Description	Default
society	Society	The society graph to compile.	required

Returns:

Type	Description
dict[str, AgentContext]	Mapping of agent name → AgentContext.

compile_for_event(agent, event_type, active_edge, society, artifacts=None, events=None, budget=4000, tokenizer=None)

Build a prompt for an agent centered on a specific event and edge.

The active edge gets priority for context budget. Background edges fill remaining budget in order.

Parameters:

Name	Type	Description	Default
agent	Agent	The agent to compile for.	required
event_type	str	Type of the incoming event (e.g. "review_requested").	required
active_edge	Edge | GroupEdge	The edge the event arrived on.	required
society	Society	The full society graph.	required
artifacts	dict[str, str] | None	Artifact name → content mapping.	None
events	list[dict[str, Any]] | None	Event history as list of dicts.	None
budget	int	Total token budget for context.	4000
tokenizer	Tokenizer | None	Token counter.	None

Returns:

Type	Description
CompiledPrompt	CompiledPrompt ready for LLM consumption.

Validation

validation

Topology validation — verify a society graph is well-formed before compilation.

Runs structural checks on the graph topology: - No disconnected agents - Every cycle has a termination bound - Competition edges have resolve strategies - Artifact references are consistent

validate_topology(society)

Run all topology checks on a society. Raises on first error.

Errors

errors

Compiler error types raised during topology validation.

CompilerError

Bases: Exception

Base class for all compiler errors.

UnboundedCycleError

Bases: CompilerError

Raised when a cycle has no termination bound (max_rounds or timeout).

DisconnectedAgentError

Bases: CompilerError

Raised when an agent has no edges in the society.

MissingResolveError

Bases: CompilerError

Raised when a Competition edge lacks a resolve strategy.

ArtifactFlowError

Bases: CompilerError

Raised when an artifact is consumed but never produced upstream.

Prompts

prompts

Prompt generation — build system prompts from edge type semantics.

Translates the society graph into natural language instructions for each agent based on their role, edge types, and relationships.

agent_role_on_edge(agent, edge)

Determine the semantic role of an agent on an edge.

generate_system_prompt(agent, edge)

Generate a system prompt for an agent based on edge type semantics.

The prompt includes: - Agent identity (role, instructions) - Edge type semantics (what the agent should do) - Peer relationships

Context

context

Context filtering — visibility matrix for agent prompt assembly.

Determines what each agent can see based on edge type semantics. Implements the visibility rules from the design doc §7.5.

ContextEntry(type, content, source, token_count=0) dataclass

A single block of context included in an agent's prompt.

Attributes:

Name	Type	Description
type	str	Category — "artifact", "event", "edge_summary", "instruction".
content	str	The actual text content.
source	str	Origin identifier (artifact name, edge id, etc.).
token_count	int	Approximate token count of content.

FilteredContext(entries=list(), total_tokens=0) dataclass

The filtered context an agent should see for a specific edge.

Attributes:

Name	Type	Description
entries	list[ContextEntry]	Ordered list of context blocks.
total_tokens	int	Sum of all entry token counts.

VisibilityRules(see_artifacts=True, see_peer_events=True, see_feedback_only=False, cooperate_aspects=None) dataclass

What an agent can see on a specific edge.

Attributes:

Name	Type	Description
see_artifacts	bool	Whether the agent can see artifact content.
see_peer_events	bool	Whether the agent can see peer's event history.
see_feedback_only	bool	If True, only feedback events are visible (not peer's full work log).
cooperate_aspects	list[str] | None	If set, only peer events tagged with an aspect matching one of these values are visible. Used by Coopetition edges to hide competitive-aspect events.

visibility_for(agent, edge)

Determine visibility rules for an agent on an edge.

filter_context(agent, edge, artifacts=None, events=None, budget=4000, tokenizer=None)

Build filtered context for an agent on a specific edge.

Parameters:

Name	Type	Description	Default
agent	Agent	The agent to build context for.	required
edge	Edge | GroupEdge	The active edge.	required
artifacts	dict[str, str] | None	Artifact name → content mapping.	None
events	list[dict[str, Any]] | None	Event history as list of dicts with at least type, agent, and content keys.	None
budget	int	Maximum token budget for context.	4000
tokenizer	Tokenizer | None	Token counter. Defaults to CharApproxTokenizer.	None

Returns:

Type	Description
FilteredContext	FilteredContext with entries the agent should see.