Skip to content

Add structured summaries for connection groups - #373

Open
rwill128 wants to merge 1 commit into
JackHopkins:mainfrom
rwill128:codex/structured-connection-summaries
Open

Add structured summaries for connection groups#373
rwill128 wants to merge 1 commit into
JackHopkins:mainfrom
rwill128:codex/structured-connection-summaries

Conversation

@rwill128

@rwill128 rwill128 commented Jul 8, 2026

Copy link
Copy Markdown

Problem

When agents use FLE through the MCP/REPL workflow, connect_entities(...) returns rich Python objects such as BeltGroup, PipeGroup, and ElectricityGroup. Those objects are useful interactively, but their default string output is hard for an agent to validate programmatically.

For example, an agent can see that a route exists, but to answer basic questions like these it currently has to inspect attributes manually or parse repr text:

  • how many belts/pipes/poles were placed?
  • where are the route inputs and outputs?
  • which direction does each belt face?
  • is the group working, empty, or blocked/full?
  • what inventory/fluid/power state is visible on the connection?

That makes route validation brittle in agent code and in MCP logs.

Change

This PR adds a non-breaking structured summary method to connection group models:

connection = connect_entities(source, target, Prototype.TransportBelt)
summary = connection.to_connection_dict()

The existing object attributes and __repr__/str(...) behavior are preserved. This only adds an explicit machine-readable representation for agents and tests.

Implemented summaries for:

  • BeltGroup: connection kind, status, aggregate inventory, input/output belts, per-belt positions, directions, lane inventories, source/terminus flags, and belt count
  • PipeGroup: connection kind, status, fluid, per-pipe positions, flow rate, contents, fluidbox IDs, and pipe count
  • ElectricityGroup: connection kind, status, electrical network ID, per-pole positions, flow rates, max flow rate, and pole count
  • WallGroup: entity list and count

Why this shape

This does not add a new MCP tool or change the MCP protocol surface. FLE's MCP interface is already REPL-oriented, so agents receive and manipulate these Python objects inside execute(code). Adding to_connection_dict() gives agents a stable validation surface without breaking existing callers or forcing string parsing.

A separate follow-up could expose similar structured data automatically in MCP responses or add structured failure details for blocked routes. This PR focuses only on successful connection group summaries.

Example

belts = connect_entities(drill.drop_position, inserter.pickup_position, Prototype.TransportBelt)
summary = belts.to_connection_dict()
assert summary["connection_kind"] == "transport"
assert summary["belt_count"] == len(belts.belts)
print(summary["inputs"], summary["outputs"])

Testing

.venv/bin/python -m pytest tests/entities/test_connection_group_summary.py -q
.venv/bin/python -m py_compile fle/env/entities.py tests/entities/test_connection_group_summary.py
git diff --check

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant