surf-agentic-base 0.3.2__tar.gz → 0.3.3__tar.gz

{surf_agentic_base-0.3.2 → surf_agentic_base-0.3.3}/CITATION.cff

@@ -11,7 +11,7 @@ authors:
   - family-names: Podareanu
     given-names: Damian
     affiliation: SURF
-version: 0.3.2
+version: 0.3.3
 date-released: "2026-09-12"
 license: EUPL-1.2
 repository-code: "https://github.com/saradamian/agentic-base"

{surf_agentic_base-0.3.2/src/surf_agentic_base.egg-info → surf_agentic_base-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: surf-agentic-base
-Version: 0.3.2
+Version: 0.3.3
 Summary: Agentic base layer: run provenance, comparison validity, and shared safety primitives.
 Author: SURF
 License-Expression: EUPL-1.2

{surf_agentic_base-0.3.2 → surf_agentic_base-0.3.3}/docs/schemas/OutcomeRunFacet.json

@@ -7,7 +7,7 @@
   "allOf": [{ "$ref": "https://openlineage.io/spec/2-0-2/OpenLineage.json#/$defs/RunFacet" }],
   "properties": {
     "resolved": { "type": ["boolean", "null"], "description": "The outcome, or null when no label has been attached." },
-    "labelSource": { "type": "string", "enum": ["unlabelled", "self_reported", "convenience_verifier", "official_harness", "human"], "description": "Who decided the outcome." },
+    "labelSource": { "type": "string", "enum": ["unlabelled", "self_reported", "convenience_verifier", "official_harness", "benchmark_grader", "human"], "description": "Who decided the outcome." },
     "authority": { "type": "string", "enum": ["none", "diagnostic", "authoritative"], "description": "Whether the label may be cited, independent of its modality." },
     "degraded": { "type": "boolean", "description": "True when the scoring instrument was not working and returned its fail-open default." },
     "instrument": { "type": "string" },
@@ -18,7 +18,8 @@
     "promptTokens": { "type": "integer" },
     "completionTokens": { "type": "integer" },
     "elapsedMs": { "type": "number" },
-    "joules": { "type": "number", "description": "Physical energy, kept apart from tokens and elapsed time because each prices a different thing." }
+    "joules": { "type": "number", "description": "Physical energy, kept apart from tokens and elapsed time because each prices a different thing." },
+    "sourceRunId": { "type": "string", "description": "The producer's own run id. The event's runId is this when it is a UUID and a uuid5 derived from it otherwise." }
   },
   "required": ["labelSource", "authority", "degraded"]
 }

{surf_agentic_base-0.3.2 → surf_agentic_base-0.3.3}/src/agentic_base/domain/outcomes.py

@@ -52,12 +52,19 @@ class LabelSource(str, enum.Enum):
     contrast."""
 
     OFFICIAL_HARNESS = "official_harness"
-    """The benchmark's own authoritative scorer."""
+    """The benchmark's own authoritative scorer, published as such: the SWE-bench harness."""
+
+    BENCHMARK_GRADER = "benchmark_grader"
+    """A benchmark's own grader where the benchmark ships no separate harness: a tau environment
+    reward, a Terminal-Bench grader, an ARE validator. Authoritative for that benchmark, and
+    named apart from the harness because a reader must not assume the SWE-bench calibration."""
 
     HUMAN = "human"
 
 
-CITABLE_LABEL_SOURCES = frozenset({LabelSource.OFFICIAL_HARNESS, LabelSource.HUMAN})
+CITABLE_LABEL_SOURCES = frozenset(
+    {LabelSource.OFFICIAL_HARNESS, LabelSource.BENCHMARK_GRADER, LabelSource.HUMAN}
+)
 """Sources whose labels may be reported as results. Everything else is a diagnostic."""
 
 
@@ -81,6 +88,7 @@ _AUTHORITY: dict[LabelSource, LabelAuthority] = {
     LabelSource.SELF_REPORTED: LabelAuthority.DIAGNOSTIC,
     LabelSource.CONVENIENCE_VERIFIER: LabelAuthority.DIAGNOSTIC,
     LabelSource.OFFICIAL_HARNESS: LabelAuthority.AUTHORITATIVE,
+    LabelSource.BENCHMARK_GRADER: LabelAuthority.AUTHORITATIVE,
     LabelSource.HUMAN: LabelAuthority.AUTHORITATIVE,
 }
 
@@ -89,6 +97,7 @@ _MLFLOW_SOURCE_TYPE: dict[LabelSource, str] = {
     LabelSource.SELF_REPORTED: "LLM_JUDGE",
     LabelSource.CONVENIENCE_VERIFIER: "CODE",
     LabelSource.OFFICIAL_HARNESS: "CODE",
+    LabelSource.BENCHMARK_GRADER: "CODE",
     LabelSource.HUMAN: "HUMAN",
 }
 

{surf_agentic_base-0.3.2 → surf_agentic_base-0.3.3}/src/agentic_base/provenance/__init__.py

@@ -11,6 +11,7 @@ schema file per format under ``docs/schemas``.
 from agentic_base.provenance.emit import (
     OUTCOME_FACET_SCHEMA,
     PROCESS_RUN_CRATE_PROFILE,
+    openlineage_run_id,
     to_openlineage,
     to_process_run_crate,
     to_prov,
@@ -19,6 +20,7 @@ from agentic_base.provenance.emit import (
 __all__ = [
     "OUTCOME_FACET_SCHEMA",
     "PROCESS_RUN_CRATE_PROFILE",
+    "openlineage_run_id",
     "to_openlineage",
     "to_process_run_crate",
     "to_prov",

{surf_agentic_base-0.3.2 → surf_agentic_base-0.3.3}/src/agentic_base/provenance/emit.py

@@ -4,6 +4,7 @@ without the ``provenance`` extra and a caller without it gets one sentence namin
 from __future__ import annotations
 
 import json
+import uuid
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
@@ -19,6 +20,21 @@ PRODUCER = "https://github.com/saradamian/agentic-base"
 OUTCOME_FACET_SCHEMA = "https://github.com/saradamian/agentic-base/blob/main/docs/schemas/OutcomeRunFacet.json"
 PROCESS_RUN_CRATE_PROFILE = "https://w3id.org/ro/wfrun/process/0.5"
 EXTRA = "provenance"
+RUN_ID_NAMESPACE = uuid.uuid5(uuid.NAMESPACE_URL, PRODUCER)
+"""Namespace for deriving an OpenLineage run UUID from a run id that is not one."""
+
+
+def openlineage_run_id(run_id: str) -> str:
+    """The UUID OpenLineage requires for a run, derived when *run_id* is not one.
+
+    PROV and RO-Crate take any string; OpenLineage's ``Run.runId`` must be a UUID and the
+    library fails on anything else. A consumer keying runs by an integer or a slug gets one
+    stable rule here rather than three private ones, and the original id travels in the facet.
+    """
+    try:
+        return str(uuid.UUID(run_id))
+    except ValueError:
+        return str(uuid.uuid5(RUN_ID_NAMESPACE, run_id))
 
 
 def _need(module: str) -> None:
@@ -143,6 +159,7 @@ def to_openlineage(run: RunRecordCreate, run_id: str, created_at: datetime) -> R
         completionTokens: int = 0
         elapsedMs: float = 0.0
         joules: float = 0.0
+        sourceRunId: str = ""
 
         @staticmethod
         def _get_schema() -> str:
@@ -164,6 +181,7 @@ def to_openlineage(run: RunRecordCreate, run_id: str, created_at: datetime) -> R
             completionTokens=run.completion_tokens,
             elapsedMs=run.elapsed_ms,
             joules=run.joules,
+            sourceRunId=run_id,
         ),
     }
     versions = run.component_versions
@@ -182,7 +200,7 @@ def to_openlineage(run: RunRecordCreate, run_id: str, created_at: datetime) -> R
         eventTime=_iso(created_at),
         producer=PRODUCER,
         eventType=state,
-        run=Run(runId=run_id, facets=facets),
+        run=Run(runId=openlineage_run_id(run_id), facets=facets),
         job=Job(namespace=run.tenant, name=run.arm or "(unset)"),
         inputs=inputs,
         outputs=[],

{surf_agentic_base-0.3.2 → surf_agentic_base-0.3.3/src/surf_agentic_base.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: surf-agentic-base
-Version: 0.3.2
+Version: 0.3.3
 Summary: Agentic base layer: run provenance, comparison validity, and shared safety primitives.
 Author: SURF
 License-Expression: EUPL-1.2

{surf_agentic_base-0.3.2 → surf_agentic_base-0.3.3}/src/surf_agentic_base.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.3.2",
+  "tag": "0.3.3",
   "distance": 0,
-  "node": "g374920070a759fc6f8a4924a83529c6f0e66226c",
+  "node": "g975166d0784fe4be5f7e10196ecf812b58a1edae",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-09-12"

{surf_agentic_base-0.3.2 → surf_agentic_base-0.3.3}/tests/domain/test_outcomes.py

@@ -141,3 +141,19 @@ def test_tenant_and_code_revision_have_no_defaults() -> None:
         RunRecordCreate(code_revision="abc123")
     with pytest.raises(ValueError):
         RunRecordCreate(tenant="hpml")
+
+
+def test_a_benchmarks_own_grader_is_authoritative_and_citable() -> None:
+    """tau, Terminal-Bench and ARE ship a grader and no separate harness; their verdict is the
+    benchmark's own, and a consumer must not have to file it as a convenience check."""
+    from agentic_base.domain.outcomes import (
+        CITABLE_LABEL_SOURCES,
+        LabelAuthority,
+        LabelSource,
+        authority_of,
+        mlflow_source_type,
+    )
+
+    assert LabelSource.BENCHMARK_GRADER in CITABLE_LABEL_SOURCES
+    assert authority_of(LabelSource.BENCHMARK_GRADER) is LabelAuthority.AUTHORITATIVE
+    assert mlflow_source_type(LabelSource.BENCHMARK_GRADER) == "CODE"

{surf_agentic_base-0.3.2 → surf_agentic_base-0.3.3}/tests/provenance/test_emit.py

@@ -204,3 +204,31 @@ def test_the_module_imports_without_the_extra_and_names_it_when_called(
 
     with pytest.raises(ImportError, match=r"surf-agentic-base\[provenance\]"):
         module.to_prov(_run(), "abc", CREATED)
+
+
+def test_a_run_id_that_is_not_a_uuid_becomes_a_stable_uuid_and_travels_in_the_facet() -> (
+    None
+):
+    from openlineage.client.serde import Serde
+
+    from agentic_base.provenance import openlineage_run_id
+
+    first = json.loads(Serde.to_json(to_openlineage(_run(), "journal-42", CREATED)))
+    second = json.loads(Serde.to_json(to_openlineage(_run(), "journal-42", CREATED)))
+
+    assert (
+        first["run"]["runId"]
+        == second["run"]["runId"]
+        == openlineage_run_id("journal-42")
+    )
+    assert first["run"]["runId"] != "journal-42"
+    assert first["run"]["facets"]["agenticBaseOutcome"]["sourceRunId"] == "journal-42"
+
+
+def test_a_run_id_that_is_a_uuid_is_kept_as_is() -> None:
+    from agentic_base.provenance import openlineage_run_id
+
+    assert (
+        openlineage_run_id("C5A4B1E0-0000-4000-8000-000000000001")
+        == "c5a4b1e0-0000-4000-8000-000000000001"
+    )