✨ Give Graph.metadata a schema

[elinscott]

Stacked on #180 (removes graph_type); review the commits after it.

TL;DR

from node_graph import Graph
from node_graph.graph import GraphMetadata
from pydantic import ConfigDict

class StrictMetadata(GraphMetadata, total=False):
    __pydantic_config__ = ConfigDict(extra="forbid")
    my_key: int

class StrictGraph(Graph):
    _metadata_schema = StrictMetadata

StrictGraph(name="g", metadata={"my_key": 1})        # fine
StrictGraph(name="g", metadata={"my_key": "one"})    # ValueError: my_key: Input should be a valid integer
StrictGraph(name="g", metadata={"typo_key": 1})      # ValueError: typo_key: Extra inputs are not permitted

Problem

Graph.metadata has no schema: any key a caller passes at construction is silently accepted, stored, and round-tripped, whether or not anything downstream ever reads it.

• Fine for Graph itself, whose own reserved keys are few and well known.
• Bad for downstream aiida-workgraph: WorkGraph also uses metadata to carry AiiDA's own process-launch keys (label, description, ...), and inheriting node-graph's schema-less dict meant an AiiDA user writing the obvious WorkGraph(name, metadata={'label': ...}) got silently the wrong metadata — accepted without complaint, stored as graph bookkeeping, and never properly passed on as AiiDA metadata (metadata means two different things, and the constructor accepts the wrong one silently aiidateam/aiida-workgraph#812).

node-graph isn't at fault for not knowing what label means to AiiDA, but without a schema that declares which keys Graph itself reserves, a downstream subclass has no way to distinguish "this key is mine" from "this key is a typo" either, so it can't validate an extended metadata schema.

Changes

The schema

GraphMetadata is a total=False TypedDict naming the keys Graph writes for its own serialization bookkeeping, and what each one holds. It carries extra="allow", so a bare Graph keeps behaving as it does today for callers who stash arbitrary keys — but a declared key still has to hold the right thing.

from typing import Any, Dict, TypedDict
from pydantic import ConfigDict
from node_graph import Graph

class GraphMetadata(TypedDict, total=False):
    __pydantic_config__ = ConfigDict(extra="allow", strict=True)

    graph_class: Dict[str, Any]
    definition: Dict[str, Any]

Graph(name="g", metadata={"anything": 1})                # ✅ unknown key, kept
Graph(name="g", metadata={"graph_class": "not a dict"})  # ❌ ValueError

strict=True refuses type coercion, not just unknown keys: a declared field holding a value of the wrong type is rejected rather than converted (a bool field given "yes" or 1, an int field given a numeral spelled as a string).

Narrowing in a subclass

A subclass declares its own schema by inheriting a wider TypedDict from GraphMetadata and pointing _metadata_schema at it. extra="forbid" on that TypedDict is what turns a typo into an error; the schema and the strictness travel together, so there is one thing to declare rather than two.

from typing import Optional
from pydantic import ConfigDict
from node_graph import Graph
from node_graph.graph import GraphMetadata

# Simplified for illustration: aiida-workgraph's real WorkGraphMetadata composes
# GraphMetadata with a second base, EngineLaunchMetadata, carrying AiiDA's own
# process-launch keys (see aiida-workgraph's `unified-metadata` branch).
class WorkGraphMetadata(GraphMetadata, total=False):
    __pydantic_config__ = ConfigDict(extra="forbid")
    pk: Optional[int]

class WorkGraph(Graph):
    _metadata_schema = WorkGraphMetadata

Validated at the boundaries, not on every mutation

metadata is a plain dict — no custom dict class, no setter that checks, nothing to keep in step. Graph.validate_metadata() runs a cached TypeAdapter and returns a validated copy, and it is called at three seams: construction, from_dict(), and get_metadata(), whose result to_dict() writes. So a stray key set after construction is not refused at the line that sets it; it is refused the moment the graph is serialized.

ng = StrictGraph(name="g", metadata={"my_key": 1})  # continuing StrictGraph from the TL;DR above
ng.metadata["typo_key"] = 1      # quiet (but would be flagged by typechecking)
ng.to_dict()                     # ❌ ValueError: typo_key: Extra inputs are not permitted

Graph.metadata is new here too: a plain property over _metadata, so downstream code and subclasses stop reaching for a private name.

Reconstruction validates like construction

from_dict() runs the same check, naming the graph it could not load. For a validating subclass this is a deliberate break: a serialized graph carrying a key outside the current declared set (schema drift, or a stray key from an older version) now raises on load instead of loading silently, and affected data needs that key stripped before it will load again.

clean = StrictGraph(name="g", metadata={"my_key": 1})
data = clean.to_dict()
data["metadata"]["worker_name"] = "localhost"   # written by no current code
StrictGraph.from_dict(data)   # ❌ ValueError: Invalid metadata for graph 'g'. Valid keys: [...]. worker_name: Extra inputs are not permitted

Upstream

Paired with aiidateam/aiida-workgraph's unified-metadata branch, which composes GraphMetadata with AiiDA's own process-launch port names (introspected from WorkGraphEngine's spec) and forbids extras. That PR implements the wiring half of #812; this is the schema primitive it's built on.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.78%. Comparing base (8d85e61) to head (488da15).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #181      +/-   ##
==========================================
+ Coverage   89.68%   89.78%   +0.10%     
==========================================
  Files          81       81              
  Lines        8984     9073      +89     
==========================================
+ Hits         8057     8146      +89     
  Misses        927      927              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.