graph-attention-engine
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-engineFor editable development installs:
pip install -e ".[dev]"Related MCP server: coord-mem MCP Server
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
API | Description |
| Scores factor vectors against category and action centroids. |
| Contains the recommendation, confidence, probabilities, and diagnostics. |
| Selects the distance kernel used for scoring. |
| Builds a scorer from named categories, actions, and centroid mappings. |
Oracle
API | Description |
| Protocol for producing independent ground-truth outcomes. |
| Returns outcomes aligned with supplied ground truth. |
| Samples deterministic-seeded Bernoulli outcomes. |
Evaluation
API | Description |
| Defines one scored evaluation case and expected action. |
| Computes expected calibration error. |
| Evaluates a scorer across a scenario collection. |
Judgment
API | Description |
| Converts a scoring result into an explained judgment. |
| Threshold for high-confidence judgments. |
| Threshold for medium-confidence judgments. |
Calibration
API | Description |
| Holds scoring and learning calibration parameters. |
| Computes the deployment-aware conservation threshold. |
Primitives
API | Description |
| Computes scaled dot-product attention and its weights. |
| Computes a numerically stable probability distribution. |
Learning
API | Description |
| Tracks centroids and learning metadata. |
| Describes a validated learning update. |
Convergence
API | Description |
| Reports centroid movement and convergence diagnostics. |
Kernels
API | Description |
| Computes standard squared Euclidean distance. |
| Applies per-factor diagonal weights. |
| Estimates covariance for adaptive distance calculations. |
| Recommends a kernel from observed data properties. |
Persistence
API | Description |
| Saves learning state to JSON. |
| Loads learning state from JSON. |
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.
MCP Server
Graph Attention Engine includes a built-in Model Context Protocol (MCP) server that exposes decision scoring as MCP tools. Any MCP-compatible client (Claude Desktop, Cursor, etc.) can connect and use GAE's cross-graph attention scoring directly.
Install
pip install "graph-attention-engine[mcp]"Usage
# stdio transport (for Claude Desktop, Cursor)
rgi-mcp-server --categories alert_triage,incident_response --actions investigate,escalate --factors severity,confidence,blast_radius
# HTTP transport (for remote/hosted deployments)
rgi-mcp-server --http --port 8080 --categories alert_triage,incident_response --actions investigate,escalate --factors severity,confidence,blast_radiusDocker
docker build -f Dockerfile.mcp -t gae-mcp .
docker run -p 8080:8080 gae-mcpMCP Tools
Tool | Description |
| Score a decision using cross-graph attention and compounding intelligence |
| Retrieve the learning trajectory showing how decisions compound over time |
| Check conservation law compliance and scoring integrity |
Claude Desktop Configuration
Add to your claude_desktop_config.json:
{
"mcpServers": {
"graph-attention-engine": {
"command": "rgi-mcp-server",
"args": ["--categories", "alert_triage,incident_response", "--actions", "investigate,escalate", "--factors", "severity,confidence,blast_radius"]
}
}
}MCP Server
Graph Attention Engine includes a built-in Model Context Protocol (MCP) server that exposes decision scoring as MCP tools. Any MCP-compatible client (Claude Desktop, Cursor, etc.) can connect and use GAE's cross-graph attention scoring directly.
Install
pip install "graph-attention-engine[mcp]"Usage
# stdio transport (for Claude Desktop, Cursor)
rgi-mcp-server --categories alert_triage,incident_response --actions investigate,escalate --factors severity,confidence,blast_radius
# HTTP transport (for remote/hosted deployments)
rgi-mcp-server --http --port 8080 --categories alert_triage,incident_response --actions investigate,escalate --factors severity,confidence,blast_radiusDocker
docker build -f Dockerfile.mcp -t gae-mcp .
docker run -p 8080:8080 gae-mcpMCP Tools
Tool | Description |
| Score a decision using cross-graph attention and compounding intelligence |
| Retrieve the learning trajectory showing how decisions compound over time |
| Check conservation law compliance and scoring integrity |
Claude Desktop Configuration
Add to your claude_desktop_config.json:
{
"mcpServers": {
"graph-attention-engine": {
"command": "rgi-mcp-server",
"args": ["--categories", "alert_triage,incident_response", "--actions", "investigate,escalate", "--factors", "severity,confidence,blast_radius"]
}
}
}Testing
pytest tests/ -vThe current suite contains 1,244 passing tests.
Documentation
License
Apache 2.0. See the LICENSE file.
Available Tools
6 toolsrgi_accuracyRgi AccuracyC
Report verified accuracy and institutional knowledge.
Inputs: no named parameters. Returns: object
rgi_conservationRgi ConservationC
Report Judgment Memory conservation health.
Inputs: no named parameters. Returns: object
rgi_decisionsRgi DecisionsC
Return recent Judgment Memory decisions.
Inputs: limit. Returns: result
rgi_explainRgi ExplainC
Explain the confidence and factors behind a decision.
Inputs: decision_id. Returns: object
rgi_scoreRgi ScoreC
Score a decision and return action probabilities.
Inputs: factors (required), category (required). Returns: object
rgi_verifyRgi VerifyD
Learn from a verified decision outcome.
Inputs: correct, gt_action, decision_id. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
The tools mostly target clearly different operations: scoring, verification learning, decision history, accuracy reporting, conservation health, and explanation. There is minor potential overlap between rgi_score and rgi_explain, and between rgi_accuracy and rgi_conservation as reporting tools, but the descriptions make their roles reasonably distinct.
All tool names use a consistent rgi_ snake_case prefix, which makes the set predictable. The suffix pattern mixes verbs (score, verify, explain) with nouns (conservation, decisions, accuracy), a minor deviation from a pure verb_noun convention.
Six tools is well-scoped for a specialized decision/judgment-memory engine. Each tool appears to serve a distinct function in the scoring, learning, explanation, and reporting lifecycle.
The surface covers the core lifecycle: scoring a decision, learning from verified outcomes, explaining decisions, listing recent decisions, and reporting accuracy and conservation health. Minor gaps may exist, such as retrieving a specific decision by ID or managing/resetting memory, but core workflows are covered.
Maintenance
Related MCP Connectors
AI Reasoning Cache & Consensus Layer with 11 MCP tools via Streamable HTTP.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Persistent memory, hybrid search and a goal graph for AI agents, over stdio or remote HTTP.
Repository knowledge graph MCP server for codebase understanding and debugging.
Related MCP Servers
- FlicenseAqualityDmaintenanceLocal-first MCP graph intelligence server providing RRF hybrid search, multi-hop traversal, source snippets, and rationale nodes for AI agents, without Docker or web UI.5-
- AlicenseNot gradedqualityDmaintenanceMemory-palace graph MCP server for AI agent memory, exposing memory_add / get / like / record_window / walk / retrieve / neighbors / rooms / misshelved / rehome operations over a zero-dependency, append-only, provenance-tracking knowledge graph with decay, PMI-derived adjacency, and spatial coordinates.MIT
- AlicenseNot gradedqualityFmaintenanceEnables AI agents to perform auditable A* reasoning, import world graphs, incorporate physical carrier constraints, and maintain a learning knowledge base through a zero-dependency local MCP stdio service.MIT
- AlicenseAqualityAmaintenanceOfficial MCP server for Algenta, a local-first AI engine powered by Mojo CPU/GPU kernels, 525+ Mojo libraries and 6,000+ compiled functions. Governed data discovery, exact queries, decisions, simulations, persistent decision memory and agent runs with approvals and execution receipts. Runs on your infrastructure. Source: packages/mcp/algenta_mcp. Install: pip install algenta-mcp (stdio).1401Apache 2.0