Skip to content

task_graph__node_link__unique_cycle_size

Program Contract

Program: count(nodes(unique_cycle(graph))); scene=node_link; scope=unique_cycle_size

Candidate set: the visible graph, tree, network, route, matrix, table, node, edge, label, weight, path, and option elements inside the unique_cycle_size objective scope. Operands: visible scene state and prompt-bound operands named by nodes, unique_cycle, graph, node_link, unique_cycle_size. Operation: evaluate count over the candidate set using the visible graph structure, labels, weights, directions, reachability, paths, connectivity, or option-selection constraints encoded in the program expression; generation enforces a unique final answer. Output binding: answer uses the integer schema; the number of nodes on that unique cycle. Annotation witnesses: annotation uses the point_set schema; the point_set of node-center pixel points for all nodes in the unique cycle. Query ids: single.

Reasoning Operations

Families: counting, topology

1) Identity

  1. Domain: graph
  2. Scene: relation
  3. Task id: task_graph__node_link__unique_cycle_size
  4. Objective: count how many labeled nodes lie on the unique cycle of one graph.

2) Scene + task contract

  1. Branch metadata: query_id
  2. query_id: single
  3. Supported scene_variant values: circular, shell, spring, grid_jitter, layered, component_clustered, path_spine, radial_tree
  4. answer_gt.type: integer
  5. annotation_gt.type: point_set
  6. Scene contract:
  7. one single-panel labeled undirected node-link graph per image,
  8. simple unweighted graph only,
  9. no self-loops,
  10. no multi-edges,
  11. the graph is connected and contains exactly one cycle,
  12. node count sampled from 5..10,
  13. visible node labels use one whole-image label format (letters, numbers, or named).
  14. Query contract:
  15. the prompt states The graph contains exactly one cycle. How many nodes are in that cycle?,
  16. answer is the number of nodes on that unique cycle.
  17. Cycle policy:
  18. target_cycle_size is sampled from 3..7,
  19. node count is chosen from the feasible support that can realize the requested cycle size while leaving at least one node outside the cycle,
  20. generation constructs a unicyclic graph by design and verifies that the finalized graph still has exactly one cycle.
  21. Topology variation:
  22. topology_profile values are balanced, low_degree, and hub_heavy,
  23. topology profile affects how trees are attached around the cycle,
  24. graph semantics always come from adjacency, never from layout position.
  25. Layout variation:
  26. scene_variant records the realized graph layout,
  27. requested layout variants are all reusable node-link layouts: circular|shell|spring|grid_jitter|layered|component_clustered|path_spine|radial_tree,
  28. the renderer may fall back to circular when a sampled layout is too cramped for readable node separation.
  29. Visual variation:
  30. one whole-image named node color is sampled from the shared Trace named-color palette,
  31. one whole-image node glyph style is sampled from circle|rounded_square|hexagon,
  32. one whole-image label format is sampled from letters|numbers|named,
  33. one whole-image edge routing style is sampled from straight|mixed_arc,
  34. one whole-image layout transform is sampled from identity|rotate_90|rotate_180|rotate_270|mirror_left_right|mirror_up_down,
  35. these style axes are non-semantic for this task and are recorded in trace metadata.

3) Prompt contract

  1. Bundle: graph_node_link_relation_v1
  2. scene_key: single_graph_relation
  3. task_key: unique_cycle_size_query
  4. Required slots:
  5. scene: object_description
  6. task: question_text
  7. answer output: json_output_contract_answer_only, answer_hint, json_example_answer_only
  8. answer+annotation mode: json_output_contract, annotation_hint, answer_hint, json_example
  9. Modes: answer_only, answer_and_annotation
  10. Answer JSON shape: {"answer":4}
  11. Answer+annotation JSON shape: {"annotation":[[180,220],[310,180],[430,260],[520,340]],"answer":4}
  12. Prompt-facing annotation uses pixel-space node-center points; node labels remain in witness_symbolic.

4) Annotation + trace contract

  1. Prompt-facing annotation is the point_set of node-center pixel points for all nodes in the unique cycle.
  2. The witness set is unordered semantically; the implementation keeps the corresponding labels in witness_symbolic and canonicalizes label order internally for deterministic serialization.
  3. answer_gt.value == len(annotation_gt.value) by construction.
  4. scene_ir.entities stores one node entity per rendered node with:
  5. visible label,
  6. on-cycle flag,
  7. neighbors,
  8. node center,
  9. node bbox.
  10. scene_ir.relations stores one undirected edge relation per graph edge.
  11. projected_annotation includes:
  12. point_set
  13. pixel_point_set
  14. pixel_bbox_set
  15. execution_trace records:
  16. query_id (the concrete public query branch)
  17. scene_variant
  18. target_cycle_size
  19. feasible support distributions for node count / cycle size
  20. topology_profile
  21. requested and realized layout variants
  22. cycle-node labels, cycle basis, and adjacency map

5) Visual policy

  1. Background and post-image noise use the merged graph-domain visual defaults from src/trace_tasks/resources/configs/domains/graph/base.yaml.
  2. Current graph scenes use a single rounded light panel on a light solid background.
  3. Node labels are rendered inside the nodes and stay visually stable across layout, label-format, shape, and color variants.
  4. Layout and styling may vary for readability and diversity, but the prompt never refers to node position, node color, or node shape as the semantic source of truth.

6) Determinism + constraints

  1. Deterministic sampling/rendering from instance_seed.
  2. Answers and annotation come from the same finalized adjacency map and unique-cycle computation.
  3. Unique-answer policy: the sampler targets one explicit cycle size and rejects any graph that is not unicyclic or whose unique cycle has the wrong size.
  4. Reject/resample conditions:
  5. no feasible node-count support for the requested cycle-size target,
  6. failure to realize a connected unicyclic simple graph with the requested support,
  7. more than one cycle or zero cycles after construction,
  8. unreadable layout that cannot keep nodes sufficiently separated.
  9. No semantic auto-relaxation: failures do not weaken the graph, label, or unique-cycle contract.

7) Complexity + tests

  1. Complexity definition/components: topology_reasoning, visual_scan, ambiguity, clutter
  2. Determinism/build tests: tests/test_graph_relation_unique_cycle_size_contracts.py
  3. Behavior/trace/prompt tests: tests/test_graph_relation_unique_cycle_size_tasks.py
  4. Prompt bundle/config tests: tests/test_prompt_system.py, tests/test_scene_config.py