use super::ascii::{AsciiNode, edge_list, render_wire_diagram};
use super::mermaid::topology_mermaid;
use crate::graph::network::Network;
use crate::graph::node::NodeKind;
use crate::graph::topology::Topology;
pub fn topology_markdown(graph: &Topology, net: Option<&Network>) -> String {
let mut out = String::new();
out.push_str(&format!("# Topology #{}\n\n", graph.id));
let hidden_range: Vec<usize> = graph.nodes.iter().filter_map(|n| n.hidden_dim).collect();
let hidden_info = if hidden_range.is_empty() {
"hidden 8".to_string()
} else {
let min = *hidden_range.iter().min().unwrap();
let max = *hidden_range.iter().max().unwrap();
if min == max {
format!("hidden {min}")
} else {
format!("hidden {min}–{max}")
}
};
out.push_str(&format!(
"**{} nodes** · **{} wires** · input {} → {} → output {}\n\n",
graph.nodes.len(),
graph.connections.len(),
graph
.options
.input_dim
.map(|x| x.to_string())
.unwrap_or_else(|| "?".into()),
hidden_info,
graph
.options
.output_dim
.map(|x| x.to_string())
.unwrap_or_else(|| "?".into()),
));
out.push_str("## Nodes\n\n");
if let Some(net) = net {
out.push_str("| ID | Kind | In | Out | Linear | Activation | Combine | Std | Sources |\n");
out.push_str("|----|------|----|-----|--------|------------|---------|-----|---------|\n");
let node_sources = super::graph_utils::build_node_sources(
&net.connections,
&net.nodes.iter().map(|n| n.num_inputs).collect::<Vec<_>>(),
);
for (i, node) in graph.nodes.iter().enumerate() {
let kind = match node.kind {
NodeKind::Input => "Input",
NodeKind::Hidden => "Hidden",
NodeKind::Output => "Output",
};
let act = node.activation;
let combine = node.combine_op.map_or("—".into(), |op| format!("{op}"));
let std = node.standardize.map_or("—".into(), |s| format!("{s}"));
let (in_dim, out_dim) = graph.node_dims().get(i).copied().unwrap_or((0, 0));
let marker = if i == net.output_node { " " } else { "" };
let sources: Vec<String> = node_sources[i]
.iter()
.flatten()
.map(|p| format!("n{}_o{}", p.node, p.index))
.collect();
let src_str = if sources.is_empty() {
"*".into()
} else {
sources.join(", ")
};
out.push_str(&format!(
"| {id} {kind}{marker} | {kind} | {ni} | {no} | {in_dim} → {out_dim} | {act} | {combine} | {std} | {src_str} |\n",
id = i,
ni = node.num_inputs,
no = node.num_outputs,
));
}
} else {
out.push_str("| ID | Kind | In | Out | Activation | Combine | Std | Dims |\n");
out.push_str("|----|------|----|-----|------------|---------|-----|------|\n");
for (node_id, node) in graph.nodes.iter().enumerate() {
let kind = match node.kind {
NodeKind::Input => "Input",
NodeKind::Hidden => "Hidden",
NodeKind::Output => "Output",
};
let act = node.activation;
let combine = node.combine_op.map_or("—".into(), |op| format!("{op}"));
let std = node.standardize.map_or("—".into(), |s| format!("{s}"));
let (in_dim, out_dim) = graph.node_dims().get(node_id).copied().unwrap_or((0, 0));
out.push_str(&format!(
"| {id} | {kind} | {ni} | {no} | {act} | {combine} | {std} | {in_dim}→{out_dim} |\n",
id = node.id,
ni = node.num_inputs,
no = node.num_outputs,
));
}
}
out.push('\n');
out.push_str("## Edges\n\n");
out.push_str("```text\n");
out.push_str(&edge_list(graph));
out.push_str("```\n\n");
out.push_str("## Wiring diagram\n\n");
out.push_str("```text\n");
let node_dims = graph.node_dims();
let nodes: Vec<AsciiNode> = graph
.nodes
.iter()
.enumerate()
.map(|(i, n)| AsciiNode {
id: n.id,
kind: n.kind,
num_inputs: n.num_inputs,
num_outputs: n.num_outputs,
out_dim: node_dims.get(i).map(|&(_, out)| out),
})
.collect();
out.push_str(&render_wire_diagram(&nodes, &graph.connections));
out.push_str("```\n");
out.push_str("\n> **Legend**:\n");
out.push_str("> - I=input H=hidden O=output\n");
out.push_str("> - 0i/4o = input ports / output ports\n");
out.push_str("> - ->dim = output dimension\n");
out.push_str("> - ▶ connected output ◀ connected input * orphaned port\n");
out.push_str("\n## Graph\n\n");
out.push_str(&topology_mermaid(graph));
out.push_str("\n## How to read this\n\n");
out.push_str("| You see | It means | How to reason about it |\n");
out.push_str("|---|---|---|");
out.push_str("\n| **Box border thickness** | the node's `hidden_dim` | A thick border = that node carries a lot of information (wide layer). Thin = narrow layer. Compare borders *within this one net* — they are scaled to this net's min→max dim, not a global scale. |");
out.push_str("\n| **Wire thickness** | hop distance of the connection | A thick wire skips far (e.g. H1 → out, jumping over intermediate layers) — a long-range shortcut. Thin wires connect neighbors. Skip-heavy nets mix features from different depths; neighbor-only nets process locally, layer by layer. |");
out.push_str("\n| **Box label** | `H<id> <activation> <dim>` | The node's id, its activation function, and its width. E.g. `H3 gelu 48` = hidden node 3, GELU, 48 units. |");
out.push_str("\n| **`in <n>` / `out <n>`** | dataset shape | Fixed by the problem: number of features in, classes out. |");
out.push_str("\n| **Nodes table → `Sources`** | which outputs feed each node | `n1_o2, n3_o0` = this node reads output 2 of node 1 and output 0 of node 3. Empty (`*`) = orphaned port (nothing connects there). |");
out.push_str("\n| **Nodes table → `Combine`** | how a node merges its inputs | `Mean`/`Min`/`Max` — what happens when several wires arrive at one box. |");
out.push_str("\n| **Nodes table → `Std`** | per-node standardization | Whether inputs are normalized before combining. |");
out.push_str("\n| **Edge list → `<<<<`** | long jump | Same fact as thick wires, in text form: this connection skips over nodes. |");
out.push_str("\n| **Wiring diagram → `▶ ◀ *`** | port connection state | ▶ = this output is wired somewhere, ◀ = this input receives something, * = orphaned (unused port — often harmless, sometimes a search artifact). |");
out.push_str("\n");
out
}