feat: Encoder metadata in serialized hugr (#955)

Closes #950.

Adds a `hugr-rs v0.3.0` or a `hugr-py v0.1.0` label to the serialialised
hugrs under the optional `encoder` field.
This should help with debuggability and error reporting in the future,
for now we just ensure that we start adding the labels. The added field
to the schema is backwards-compatible.

I had to add a `__version__` field at the root of the python package.
This is automatically updated by `release-please`, so it shouldn't be
much of an issue.

drive-by: force `poetry update` before generating the schema in `just
update-schema`, to make sure we are using the same pinned pydantic
version as CI.

hugr-py/src/hugr/__init__.py

@@ -2,6 +2,8 @@
 representation.
 """
 
+__version__ = "0.1.0"
+
 
 def it_works() -> str:
     """Return a string to confirm that the package is installed and working."""

hugr-py/src/hugr/serialization/serial_hugr.py

@@ -1,8 +1,9 @@
 from typing import Any, Literal
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 from .ops import NodeID, OpType
+import hugr
 
 Port = tuple[NodeID, int | None]  # (node, offset)
 Edge = tuple[Port, Port]
@@ -14,9 +15,13 @@ class SerialHugr(BaseModel):
     version: Literal["v1"] = "v1"
     nodes: list[OpType]
     edges: list[Edge]
+    encoder: str | None = Field(
+        default=None, description="The name of the encoder used to generate the Hugr."
+    )
 
     def to_json(self) -> str:
         """Return a JSON representation of the Hugr."""
+        self.encoder = f"hugr-py v{hugr.__version__}"
         return self.model_dump_json()
 
     @classmethod

hugr/src/hugr/serialize.rs

@@ -57,6 +57,9 @@ struct SerHugrV1 {
     // match the internal representation.
     #[serde(default)]
     metadata: Vec<serde_json::Value>,
+    /// A metadata field with the package identifier that encoded the HUGR.
+    #[serde(default)]
+    encoder: Option<String>,
 }
 
 /// Errors that can occur while serializing a HUGR.
@@ -175,10 +178,13 @@ impl TryFrom<&Hugr> for SerHugrV1 {
             })
             .collect();
 
+        let encoder = Some(format!("hugr-rs v{}", env!("CARGO_PKG_VERSION")));
+
         Ok(Self {
             nodes,
             edges,
             metadata,
+            encoder,
         })
     }
 }
@@ -190,6 +196,7 @@ impl TryFrom<SerHugrV1> for Hugr {
             nodes,
             edges,
             metadata,
+            ..
         }: SerHugrV1,
     ) -> Result<Self, Self::Error> {
         // Root must be first node

justfile

@@ -48,6 +48,7 @@ shell:
 
 # Update the HUGR schema.
 update-schema:
+    poetry update
     poetry run python scripts/generate_schema.py specification/schema/
 
 

specification/schema/hugr_schema_v1.json

@@ -1772,6 +1772,19 @@
             },
             "title": "Edges",
             "type": "array"
+        },
+        "encoder": {
+            "anyOf": [
+                {
+                    "type": "string"
+                },
+                {
+                    "type": "null"
+                }
+            ],
+            "default": null,
+            "description": "The name of the encoder used to generate the Hugr.",
+            "title": "Encoder"
         }
     },
     "required": [