tangl.story.analysis

Projection and rendering helpers for inspecting StoryTangl graphs as explicit graph views.

These helpers are observational only. They do not participate in traversal or become a second source of truth.

Related design docs

• Conceptual Foundations

• Navigation vs Automatic Redirects

Projected graph model

class ProjectedNode(id: 'str', label: 'str', source_id: 'str | None', source_kind: 'str | None', synthetic: 'bool' = False, origin_node_ids: 'list[str]' = <factory>, attrs: 'dict[str, object]' = <factory>)

class ProjectedEdge(id: 'str', source_id: 'str', target_id: 'str', label: 'str', source_edge_id: 'str | None', source_kind: 'str | None', edge_role: 'str', synthetic: 'bool' = False, origin_edge_ids: 'list[str]' = <factory>, attrs: 'dict[str, object]' = <factory>)

class ProjectedGroup(id: 'str', label: 'str', group_kind: 'str', member_node_ids: 'list[str]', source_id: 'str | None', source_kind: 'str | None', synthetic: 'bool' = False, origin_node_ids: 'list[str]' = <factory>, attrs: 'dict[str, object]' = <factory>)

class ProjectedGraph(nodes: 'list[ProjectedNode]', edges: 'list[ProjectedEdge]', groups: 'list[ProjectedGroup]', _source_nodes_by_id: 'dict[str, Any]' = <factory>, _source_edges_by_id: 'dict[str, Any]' = <factory>, _projected_node_id_by_source_id: 'dict[str, str]' = <factory>, _origin_source_nodes_by_id: 'dict[str, Any]' = <factory>)

Projection APIs

project_story_graph(graph, *, selector=None, node_selector=None, edge_selector=None, processors=())

Project one live StoryGraph into a filtered deterministic graph view.

project_world_graph(world, *, selector=None, node_selector=None, edge_selector=None, processors=(), story_label='projection_inspection')

Project one world by first creating an eager frozen inspection story.

structural_selector()

Return the default structural source-graph selector.

episode_only_selector()

Return one selector limited to episode nodes and traversal edges.

episode_plus_concepts_selector()

Return one selector that adds concept/provider structure to episode views.

Processors

cluster_by_scene()

Return one processor that adds scene cluster groups.

attach_media_preview(media_role=None)

Return one processor that annotates nodes with previewable media paths.

annotate_runtime(ledger, *, include_availability=True)

Return one processor that stamps runtime attrs from one live ledger.

focus_runtime_window(ledger, *, history_steps=6, include_current_successors=True, include_current_predecessors=False)

Return one processor that filters one projection to the active runtime slice.

collapse_linear_chains(*, min_length=2, preserve_visited=False)

Return one processor that collapses eligible linear chains.

mark_runtime_styles()

Return one processor that converts runtime attrs into renderer style attrs.

Rendering

to_dot(projected_graph, *, include_groups=True)

Return one deterministic DOT script for a projected graph.

render_dot(dot_text, *, prog='dot', format='svg')

Render DOT text through a local Graphviz executable.

Compatibility wrappers

build_script_report(bundle_or_world)

Return the phase-1 compatibility block report via live graph projection.

render_basic_svg(report)

Render one phase-1 compatibility report as a deterministic inspection SVG.