Graph Attention Engine (GAE)

Graph Attention Engine is a standalone, NumPy-only scoring engine that implements Cross-Graph Attention for domain-independent decision systems. It is pure Python and requires no database, network access, or event loop. GAE is licensed under Apache 2.0.

Install

Install the published package:

pip install graph-attention-engine

For editable development installs:

pip install -e ".[dev]"

Quick Start

Scaled dot-product attention

import numpy as np
from gae import scaled_dot_product_attention

rng = np.random.default_rng(7)
Q = rng.normal(size=(4, 8))
K = rng.normal(size=(6, 8))
V = rng.normal(size=(6, 16))

out, weights = scaled_dot_product_attention(Q, K, V)

assert out.shape == (4, 16)
assert weights.shape == (4, 6)

Profile scoring

ProfileScorer compares a factor vector with category-specific action centroids. The convenience factory accepts named categories and actions:

import numpy as np
from gae import ProfileScorer, build_profile_scorer

categories = ["routine", "critical"]
actions = ["accept", "review", "escalate"]

# Shape: (2 categories, 3 actions, 4 factors)
mu = np.array(
    [
        [
            [0.2, 0.2, 0.1, 0.2],
            [0.5, 0.4, 0.5, 0.4],
            [0.8, 0.8, 0.9, 0.8],
        ],
        [
            [0.1, 0.2, 0.2, 0.1],
            [0.5, 0.6, 0.5, 0.6],
            [0.9, 0.9, 0.8, 0.9],
        ],
    ],
    dtype=np.float64,
)

centroids = {
    category: {
        action: mu[category_index, action_index].tolist()
        for action_index, action in enumerate(actions)
    }
    for category_index, category in enumerate(categories)
}

scorer: ProfileScorer = build_profile_scorer(
    categories=categories,
    actions=actions,
    centroids=centroids,
    n_factors=4,
)
result = scorer.score(np.array([0.85, 0.90, 0.80, 0.90]), category_index=1)

print(result.action_index)
print(result.confidence)
print(result.probabilities)

The returned ScoringResult contains the recommended action_index, action_name, calibrated confidence, full probabilities, distances, entropy, and confidence gap.

Core API

Core Scoring

Oracle

Evaluation

Judgment

Calibration

Primitives

Learning

Convergence

Kernels

Persistence

The complete public export list is available in gae/__init__.py.

Conservation Law

GAE checks the constraint alpha * q * V >= theta_min, combining category coverage (alpha), observed quality (q), and verified volume (V). Meeting the threshold provides the operational guarantee that evidence is sufficient to maintain accuracy above the configured boundary; use compute_theta_min to derive the deployment-aware threshold.

Testing

pytest tests/ -v

The current suite contains 1,244 passing tests.

Documentation

• Authoritative design document
• Cross-Graph Attention mathematical foundation
• Dakshineshwari

License

Apache 2.0. See the LICENSE file.