topos.graphs.base

Representation Protocol

Defines the contract that all program representations must satisfy.

In the topos of programs, a program can be viewed through multiple lenses: its AST structure, its dependency graph, its control-flow graph, etc. Each lens is a representation – a distinct categorical object that captures different structural invariants of the same morphism.

Every representation can produce a dictionary of metric values. These metrics are routed through representation-specific evaluation sections and ultimately aggregated by the lattice into a single verdict.

class topos.graphs.base.Representation(*args, **kwargs)

Bases: Protocol

Protocol that all program representations must implement.

A representation is a structural view of a program (AST, dependency graph, CFG, …) that can be measured along its own metric axes.

name

A unique identifier for this representation type (e.g. "ast", "mdg").

property name

property dimension

The quality axis this representation measures.

Representations with the same dimension are aggregated together within a single dimension verdict via lattice meet. Representations with different dimensions are reported separately and never collapsed into each other.

Standard dimension names:

"structural" — internal code structure (AST-based) "coupling" — architectural positioning (dependency-graph)

metrics()

Compute all metric values for this representation.

Returns:

A dictionary mapping metric names to their raw float values. Metric names should be namespaced by representation (e.g. "ast.complexity", "mdg.coupling").