Skip to content

graflo.architecture.schema.context.rank

Ranking vertex types by how useful they are to an agent orienting itself.

Local signals only — degree, identity policy, property count, index presence, hop distance from a seed. No embeddings and no corpus statistics: semantic ranking is the server's business (it has the index), core stays dependency-free.

Attributes

IDENTITY_MODE_STRENGTH = {'natural': 1.0, 'hash': 0.75, 'assigned': 0.5, 'blank': 0.1} module-attribute

Classes

RankingWeights

Bases: ConfigBaseModel

Relative weight of each local signal. Weights need not sum to 1.

Source code in graflo/architecture/schema/context/rank.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
class RankingWeights(ConfigBaseModel):
    """Relative weight of each local signal. Weights need not sum to 1."""

    hop_decay: float = PydanticField(
        default=0.55,
        description="Score multiplier per hop of distance from the nearest seed.",
        gt=0.0,
        le=1.0,
    )
    degree: float = PydanticField(
        default=0.20, description="Weight of normalized incident-edge count.", ge=0.0
    )
    identity: float = PydanticField(
        default=0.15, description="Weight of identity-mode strength.", ge=0.0
    )
    properties: float = PydanticField(
        default=0.10, description="Weight of log-scaled property count.", ge=0.0
    )
    indexed: float = PydanticField(
        default=0.10,
        description="Weight of secondary-index presence (cheap to filter on).",
        ge=0.0,
    )

Attributes

degree = PydanticField(default=0.2, description='Weight of normalized incident-edge count.', ge=0.0) class-attribute instance-attribute
hop_decay = PydanticField(default=0.55, description='Score multiplier per hop of distance from the nearest seed.', gt=0.0, le=1.0) class-attribute instance-attribute
identity = PydanticField(default=0.15, description='Weight of identity-mode strength.', ge=0.0) class-attribute instance-attribute
indexed = PydanticField(default=0.1, description='Weight of secondary-index presence (cheap to filter on).', ge=0.0) class-attribute instance-attribute
properties = PydanticField(default=0.1, description='Weight of log-scaled property count.', ge=0.0) class-attribute instance-attribute

VertexSignals

Bases: ConfigBaseModel

Per-vertex-type ranking inputs and the score derived from them.

Source code in graflo/architecture/schema/context/rank.py 
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
class VertexSignals(ConfigBaseModel):
    """Per-vertex-type ranking inputs and the score derived from them."""

    name: str = PydanticField(..., description="Vertex type name.")
    hop_distance: int | None = PydanticField(
        default=None,
        description="Hops from the nearest seed; None when unreachable.",
    )
    degree: int = PydanticField(..., description="Incident edges (out + in).")
    identity_mode: str = PydanticField(
        ..., description="One of natural / hash / assigned / blank."
    )
    property_count: int = PydanticField(..., description="Declared property count.")
    has_secondary_index: bool = PydanticField(
        ..., description="Whether db_profile declares a secondary index for this type."
    )
    score: float = PydanticField(..., description="Composite rank; higher is better.")

Attributes

degree = PydanticField(..., description='Incident edges (out + in).') class-attribute instance-attribute
has_secondary_index = PydanticField(..., description='Whether db_profile declares a secondary index for this type.') class-attribute instance-attribute
hop_distance = PydanticField(default=None, description='Hops from the nearest seed; None when unreachable.') class-attribute instance-attribute
identity_mode = PydanticField(..., description='One of natural / hash / assigned / blank.') class-attribute instance-attribute
name = PydanticField(..., description='Vertex type name.') class-attribute instance-attribute
property_count = PydanticField(..., description='Declared property count.') class-attribute instance-attribute
score = PydanticField(..., description='Composite rank; higher is better.') class-attribute instance-attribute

Functions:

score_vertices(graph, seeds=(), *, weights=None, max_hops=3, direction=EdgeDirection.ANY)

Rank every vertex type in graph, highest score first.

With no seeds, ranking is seed-independent (structure only) and answers "what are the important types here" — which is what the orientation card needs. With seeds, hop distance dominates and answers "what is near what I asked about".

Ties break by vertex name ascending. This is not cosmetic: without a total order the elision report is not reproducible across runs, and the budget tests become flaky.

Source code in graflo/architecture/schema/context/rank.py 
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
def score_vertices(
    graph: SchemaGraph,
    seeds: Sequence[str] = (),
    *,
    weights: RankingWeights | None = None,
    max_hops: int = 3,
    direction: EdgeDirection = EdgeDirection.ANY,
) -> list[VertexSignals]:
    """Rank every vertex type in *graph*, highest score first.

    With no *seeds*, ranking is seed-independent (structure only) and answers
    "what are the important types here" — which is what the orientation card
    needs. With seeds, hop distance dominates and answers "what is near what I
    asked about".

    Ties break by vertex name ascending. This is not cosmetic: without a total
    order the elision report is not reproducible across runs, and the budget tests
    become flaky.
    """
    weights = weights or RankingWeights()
    schema = graph.schema
    vertex_config = schema.core_schema.vertex_config
    db_profile = schema.db_profile

    distances = neighborhood_distances(graph, seeds, hops=max_hops, direction=direction)

    degrees = {name: graph.degree(name) for name in graph.vertex_types}
    max_degree = max(degrees.values(), default=0)
    property_counts = {
        name: len(vertex_config[name].property_names) for name in graph.vertex_types
    }
    max_properties = max(property_counts.values(), default=0)

    signals: list[VertexSignals] = []
    for name in sorted(graph.vertex_types):
        vertex = vertex_config[name]
        hop_distance = distances.get(name) if seeds else None
        degree = degrees[name]
        property_count = property_counts[name]
        has_index = bool(db_profile.vertex_secondary_indexes(name))

        structural = (
            weights.degree * (degree / max_degree if max_degree else 0.0)
            + weights.identity * IDENTITY_MODE_STRENGTH.get(vertex.identity_mode, 0.5)
            + weights.properties
            * (
                math.log1p(property_count) / math.log1p(max_properties)
                if max_properties
                else 0.0
            )
            + weights.indexed * (1.0 if has_index else 0.0)
        )
        if not seeds:
            score = structural
        elif hop_distance is None:
            score = 0.0
        else:
            score = (weights.hop_decay**hop_distance) + structural

        signals.append(
            VertexSignals(
                name=name,
                hop_distance=hop_distance,
                degree=degree,
                identity_mode=vertex.identity_mode,
                property_count=property_count,
                has_secondary_index=has_index,
                score=score,
            )
        )

    signals.sort(key=lambda item: (-item.score, item.name))
    return signals