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

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

@@ -11,7 +11,7 @@ authors:
   - family-names: Podareanu
     given-names: Damian
     affiliation: SURF
-version: 0.3.2
+version: 0.3.4
 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.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: surf-agentic-base
-Version: 0.3.2
+Version: 0.3.4
 Summary: Agentic base layer: run provenance, comparison validity, and shared safety primitives.
 Author: SURF
 License-Expression: EUPL-1.2
@@ -59,8 +59,10 @@ Dynamic: license-file
 [![python](https://img.shields.io/badge/python-3.10%20to%203.14-blue.svg)](pyproject.toml)
 [![cite](https://img.shields.io/badge/cite-CITATION.cff-green.svg)](CITATION.cff)
 
-The agentic base layer for SURF: **run provenance, comparison validity, and the shared
-primitives an agent needs**.
+The agentic base layer for SURF: **the record and referee for agent runs, the security
+primitives an agent needs on a shared platform, and the engineering standard that keeps both
+honest**. It is the contracts layer under a set of capability blocks, one per SURF system, that
+live in their own packages; see `docs/architecture/blocks.md`.
 
 It is built on the SURF Developer Platform golden path and adopts the common stack wherever the
 common stack has an answer. It contains only the parts we could not find anywhere else.

{surf_agentic_base-0.3.2 → surf_agentic_base-0.3.4}/README.md

@@ -5,8 +5,10 @@
 [![python](https://img.shields.io/badge/python-3.10%20to%203.14-blue.svg)](pyproject.toml)
 [![cite](https://img.shields.io/badge/cite-CITATION.cff-green.svg)](CITATION.cff)
 
-The agentic base layer for SURF: **run provenance, comparison validity, and the shared
-primitives an agent needs**.
+The agentic base layer for SURF: **the record and referee for agent runs, the security
+primitives an agent needs on a shared platform, and the engineering standard that keeps both
+honest**. It is the contracts layer under a set of capability blocks, one per SURF system, that
+live in their own packages; see `docs/architecture/blocks.md`.
 
 It is built on the SURF Developer Platform golden path and adopts the common stack wherever the
 common stack has an answer. It contains only the parts we could not find anywhere else.

surf_agentic_base-0.3.4/docs/architecture/blocks.md

@@ -0,0 +1,96 @@
+# Blocks: the common capabilities SURF exposes to agents, and where each one lives
+
+SURF intends to offer a set of common building blocks, tools and skills, that an agent can use,
+internally and externally. This page says what a block is, which blocks the existing systems
+imply, how a block composes with others and is adapted by a downstream, and where this
+repository stops. It was checked on 2026-09-13 against the internal Confluence (the NL AI
+Factory architecture, its high-level MLOps design, the design memo of July 2026, the user
+interviews, the SURF Developer Platform overview, the AI-at-SURF product list) and against the
+code that exists in agentic-env, willma2 and the AI4Science prototype.
+
+## Three layers
+
+| layer | what it is | who owns it |
+|---|---|---|
+| **contracts** | what every block stands on: the tool contract, the recording seam, the curated-surface mechanism, the security primitives, the span vocabulary, the run record and the referee. No block lives here | this repository |
+| **blocks** | one per system. An MCP server, a Python client for code that does not want a model in the loop, and the skills that say how to use the system well. Each its own package, each with the owner of the system behind it | the system's team |
+| **catalogue** | where a block is found. Backstage on the SURF Developer Platform internally, the MCP Registry externally; each block ships its own catalogue entry | the platform |
+
+The reason the base is not a block, and no block is in the base: a block imports the contracts,
+and a package that imports something must not also contain it. That is also why the scheduler
+client is not here, whatever the temptation; `boundaries.md` says this repository must not
+submit jobs, and a block that does belongs with the people who run the scheduler.
+
+## The blocks the existing systems imply
+
+The first list had six. Checking it against what SURF runs and what the AI Factory names as its
+common denominators, identity and access, a data plane with object and POSIX tiers, accounting
+and quota, a shared GPU pool, a common home for artifacts, uniform observability, and tenant
+isolation, adds three and sharpens two.
+
+| block | wraps | what exists today | status |
+|---|---|---|---|
+| **hpc** | Slurm on Snellius, LUMI and the AI Factory; a served model on it | agentic-env's slurm_companion, 51 tools, two curated profiles, an SSH backend; three separate slurmrestd clients in willma2, the AI4Science prototype and a stub in `python_slurm_wrapper` | the most duplicated capability at SURF and the one to consolidate, in its own package, once slurmrestd's availability is settled with the operators |
+| **inference** | Willma, the AI Hub back office | an OpenAI-compatible endpoint and nothing published as a block; the model catalogue, serve requests and the Whisper transcription that Research Cloud items already call | a block, because every other block's agent needs a model and the catalogue is the thing to expose |
+| **knowledge** | Confluence today; the SURF knowledge base and the education search portals tomorrow | agentic-env's confluence product, 20 tools, already served over MCP with a curated surface; a separate team is building an MCP server for edusources.nl | the cheapest first extraction, and the proof that two teams' MCP servers can share one catalogue |
+| **software** | EasyBuild and EESSI | agentic-env's easybuild product, 10 tools, with a sandboxed validation backend | ready to extract |
+| **data** | the object stores (Swift, LUMI-O, MinIO on the platform), the POSIX tiers, dCache, iRODS and Yoda, Research Drive, the AI Factory's dataset-as-a-service | the AI4Science prototype's dataset vocabulary; agentic-env's staging scripts for LUMI-O; nothing agent-facing | a block, and the largest gap: an agent that cannot find, stage or cite data does not do research |
+| **artifacts** | the container registry, a model registry, dataset versions and checkpoints | GitLab and Harbor registries on the platform; MLflow named as the registry in the AI Factory design; content-addressed artifacts in agentic-env's lineage | missing. The GPT-NL interview asked for exactly this: a shared versioned store and a common registry |
+| **identity** | SURFconext and SRAM: who you are, which project you belong to, what you may touch | every block needs it and none carries it; the platform's tenancy model | not a block an agent calls; the thing every block's surface is scoped by. Named so it is not forgotten |
+| **accounting** | GPU-seconds, storage, and energy per tenant and per run | Slurm and EAR accounting on Snellius; the AI Factory asks for accounting "the same way however the work was launched"; the run record carries joules beside tokens | a small read-only block, and the one that answers the question a funder asks first |
+| **runs** | the record and the referee | this repository's service and its four-tool server | exists |
+
+Two of the nine are not agent tools at all. Identity is what scopes every surface, and
+accounting is what the platform bills on; they appear because a design that leaves them implicit
+gets them wrong, which the AI Factory memo says in its own words.
+
+## What makes a block composable
+
+- **It speaks MCP and nothing private.** Any agent, any framework, any vendor's client, connects
+  to it. That is the entire composition mechanism, and the field settled it in 2025.
+- **One tool name per capability across backends.** `submit_job` is the same name on Snellius,
+  LUMI and the AI Factory, so telemetry aggregates and a skill written for one transfers to the
+  others. Decision D1.
+- **Surfaces are declared subsets with reasons.** agentic-env's profiles already do this:
+  `hpc-ops` is read-only, `hpc-serve` adds serving, and the full surface stays in-process because
+  a remote shell as the credential owner is not a thing to publish. Internal and external
+  exposure are one block with a different profile and different authentication, never two
+  codebases.
+- **Every block records through the same seam and speaks the same span vocabulary.** A call
+  through the knowledge block and a call through the hpc block land in one trace and one run
+  record, which is what lets the referee judge what an agent did across blocks.
+- **A block's profile maps onto the platform's isolation tier.** The AI Factory distinguishes a
+  community tier, a virtualised tier and an isolated tier for sensitive data. A block published
+  into the isolated tier exposes less, not the same surface behind a stricter login.
+
+## What makes a block derivable
+
+- **Site facts live in configuration, never in code.** Cluster profiles, registry hosts,
+  endpoints, tenant names. The deployment-overlay contract enforces this for the base and applies
+  to a block unchanged: a downstream takes the hpc block and overlays its own cluster profile.
+- **Skills are files next to the block, in the open SKILL.md format**, with the anatomy
+  agentic-env already requires: steps, the rationalisations table, red flags, a verification
+  checklist. A skill for another cluster differs in the profile it names and nothing else.
+- **A template repository derived from this one's standard.** The guards, the ledger, the release
+  path, signed tags and attested wheels. A new block starts from the template and inherits the
+  discipline without inheriting any code.
+
+## What the internal documentation does not yet say
+
+Nothing on the internal Confluence describes an agent-facing layer: no page on MCP, on skills, or
+on agents as a workload, apart from one product line about an MCP server for the education
+portals. The AI Factory's own architecture notes list train, fine-tune and infer as the three
+verbs and have no box for an agent run, which is the gap the design memo of July 2026 calls the
+common denominators without naming agents. This page is therefore the first written statement of
+the layer, and it should move to Confluence once the block owners have read it.
+
+## Order of work
+
+1. Extract the **knowledge** block first. Smallest, already over MCP, needs no scheduler
+   decision, and proves the extraction loop and the template on something that cannot break a
+   cluster.
+2. Settle slurmrestd availability with the Snellius operators, then start the **hpc** block from
+   the `python_slurm_wrapper` stub with willma2's token handling and the AI4Science schemas.
+3. Define the **data** block's surface with the data teams before writing it; find, stage and
+   cite are the three verbs an agent needs, and the systems behind them are theirs.
+4. Leave **identity** and **accounting** as named constraints until a block needs them for real.

{surf_agentic_base-0.3.2 → surf_agentic_base-0.3.4}/docs/architecture/boundaries.md

@@ -72,6 +72,13 @@ No model serving. That is Willma.
 No job submission. That is AI4Science, and the seam between the two is the first piece of work
 worth doing together.
 
+## The blocks are outside, by construction
+
+The capability blocks an agent calls, hpc, inference, knowledge, data, software, artifacts, are
+each their own package with the owner of the system behind them (`blocks.md`). They import this
+repository's contracts; nothing here imports a block. A scheduler client in particular does not
+belong here, because this repository must not submit jobs.
+
 ## Split this repository when, and not before
 
 One package becomes two when someone outside SURF wants the library and does not want the service,

{surf_agentic_base-0.3.2 → surf_agentic_base-0.3.4}/docs/architecture/picture.md

@@ -10,34 +10,35 @@ The mermaid block at the bottom needs a mermaid-capable viewer.
   APPLICATIONS            people's own work, each brings its own agent
   ┌──────────────────┬──────────────────────┬────────────────────┐
   │ agentic-env      │ pipeline triage      │ other SURF teams   │
-  │ experiments      │ a new SURF project   │                    │
+  │ experiments      │ a new SURF project   │ and their agents   │
   └──────────────────┴──────────────────────┴────────────────────┘
                               │
   CONTROL PLANE               │   who may run what, and where
   ┌───────────────────────────▼────────────────────────────────┐
-  │ AI4Science   jobs, tenancy, datasets, orchestration        │
+  │ AI4Science today; the AI Factory's MLOps and meta-scheduler │
   └───────────────────────────┬────────────────────────────────┘
                               │
-  CAPABILITIES                │   one per system, curated surface
-  ┌──────────┬───────┬────────▼──┬──────────┬───────────┐
-  │ runs     │ hpc   │ data      │ software │ knowledge │
-  │ (new)    │       │           │          │           │
-  └──────────┴───┬───┴───────────┴────┬─────┴─────┬─────┘
-                 │                    │           │
-  surf-agentic-base   │  THIS REPOSITORY   │           │
-  ┌──────────────▼────────────────────▼───────────▼────────────┐
-  │ tool contract │ span vocabulary │ recording seam │ prims   │
-  ├────────────────────────────────────────────────────────────┤
-  │ run record · label provenance · validity · epochs · emit   │
-  └────────────────────────────────────────────────────────────┘
+  BLOCKS                      │   one per system, curated surface, own package, own owner
+  ┌───────┬──────────┬──────────┬──────────┬──────┬──────────┬──────────┐
+  │ runs  │ hpc      │inference │knowledge │ data │ software │ artifacts│
+  │ (here)│          │          │          │      │          │          │
+  └───┬───┴────┬─────┴────┬─────┴────┬─────┴──┬───┴────┬─────┴────┬─────┘
+      │  scoped by IDENTITY (SURFconext, SRAM) · billed by ACCOUNTING     │
+      │                    │          │          │        │          │
+  CONTRACTS   │  THIS REPOSITORY   │          │          │        │
+  ┌───────────▼────────────▼──────────▼──────────▼────────▼──────────▼────┐
+  │ tool contract │ recording seam │ curated surfaces │ security │ spans │
+  ├────────────────────────────────────────────────────────────────────────┤
+  │ run record · label provenance · validity · epochs · emitted standards │
+  └────────────────────────────────────────────────────────────────────────┘
 
   ALREADY EXIST, not ours to rebuild
-  ┌────────────┬────────────────┬────────────┬───────────┐
-  │ Willma     │ Slurm clusters │ Confluence │ EasyBuild │
-  │ serves     │ Snellius, LUMI │            │           │
-  │ models     │ AI Factory     │            │           │
-  └────────────┴────────────────┴────────────┴───────────┘
-   each is published as exactly one capability above
+  ┌──────────┬───────────────┬────────────┬───────────┬──────────────────┬──────────────┐
+  │ Willma   │ Slurm         │ Confluence │ EasyBuild │ object stores,   │ registries   │
+  │ serves   │ Snellius,LUMI │ edusources │ EESSI     │ dCache, iRODS,   │ GitLab,      │
+  │ models   │ AI Factory    │            │           │ Yoda, Res. Drive │ Harbor,MLflow│
+  └──────────┴───────────────┴────────────┴───────────┴──────────────────┴──────────────┘
+   each is published as exactly one block above; see blocks.md
 ```
 
 ## Reading it in one paragraph
@@ -46,8 +47,11 @@ The systems at the bottom already exist and are not ours to rebuild. Each is pub
 one capability with a curated, read-only-by-default surface. Those capabilities all stand on the
 same contracts, which is what this repository is. Applications sit on top and bring their own agent.
 
-The only capability with no existing system behind it is **runs**, which is why the record lives
-here and the rest do not.
+The only block with no existing system behind it is **runs**, which is why the record lives here
+and the rest do not. Two things on the picture are not blocks an agent calls: identity scopes
+every surface and accounting bills every run, and both are named because a design that leaves
+them implicit gets them wrong. The full list, with what exists behind each block and the order
+to build them, is in `blocks.md`.
 
 ## What "moving things" would actually mean
 
@@ -87,39 +91,46 @@ flowchart TB
         OTH[other SURF teams]
     end
     subgraph ctrl[Control plane - who may run what and where]
-        AI4[AI4Science]
+        AI4[AI4Science today, the AI Factory MLOps tomorrow]
     end
-    subgraph caps[Capabilities - published to agents]
+    subgraph blocks[Blocks - one per system, curated surface, own owner]
         R[runs]
         H[hpc]
+        I[inference]
+        K[knowledge]
         D[data]
         S[software]
-        K[knowledge]
+        A[artifacts]
+    end
+    subgraph scope[Every block is scoped and billed]
+        ID[identity: SURFconext, SRAM]
+        AC[accounting: GPU-seconds, storage, joules]
     end
-    subgraph base[surf-agentic-base - this repository]
+    subgraph base[Contracts - this repository]
         C1[tool contract]
-        C2[span vocabulary]
-        C3[recording seam]
-        C4[run record and validity and epochs]
-        C6[provenance emission: PROV, OpenLineage, RO-Crate]
-        C5[primitives]
+        C2[recording seam and curated surfaces]
+        C3[security primitives and span vocabulary]
+        C4[run record, validity, epochs, emitted standards]
     end
     subgraph sys[Systems that already exist]
         W[Willma]
         SL[Slurm clusters]
-        CF[Confluence]
-        EB[EasyBuild]
+        CF[Confluence and edusources]
+        EB[EasyBuild and EESSI]
+        ST[object stores, dCache, iRODS, Yoda, Research Drive]
+        RG[GitLab, Harbor, MLflow registries]
     end
-    AE --> caps
-    MW --> caps
-    OTH --> caps
-    AI4 --> caps
-    caps --> base
+    AE --> blocks
+    MW --> blocks
+    OTH --> blocks
+    AI4 --> blocks
+    blocks --> base
+    blocks -.-> scope
     H --> SL
-    H --> W
+    I --> W
     K --> CF
     S --> EB
-    D --> AI4
+    D --> ST
+    A --> RG
     R --> C4
-    R --> C6
 ```

{surf_agentic_base-0.3.2 → surf_agentic_base-0.3.4}/docs/architecture/reuse-ledger.md

@@ -34,7 +34,7 @@ already supported, and already have an owner.
 | secrets | SDP secret management, per its guide | ADOPT. It is the fix for secrets-in-job-scripts |
 | identity and collaboration groups | SURFconext, SRAM | ADOPT |
 | shared model inference | Willma (`research/hpml/willma`, the AI Hub back office) | ADOPT where it serves the model needed |
-| Slurm access from services | `snellius/pyslurm`, `SOIL/slurm-bridge`, Slurm REST | ADOPT. Evaluate both before writing a third |
+| Slurm access from services | slurmrestd, the scheduler's own REST API with a published OpenAPI specification, plus a thin site wrapper. Surveyed 2026-09-13: three hand-written REST clients exist at SURF (willma2, the AI4Science prototype, the `hpml-llms/python_slurm_wrapper` stub) and one SSH backend (agentic-env); `snellius/pyslurm` and `SOIL/slurm-bridge`, named here earlier, could not be found on the GitLab | ADOPT the REST API and generate the client from its specification; the wrapper is one package in the **hpc block**, not this repository (`blocks.md`) |
 | software environments on HPC | EasyBuild (`easybuild-surf`), EESSI | ADOPT |
 
 ## External, where SURF has no internal equivalent

{surf_agentic_base-0.3.2 → surf_agentic_base-0.3.4}/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.4}/mkdocs.yml

@@ -11,6 +11,7 @@ nav:
   - Observability: OBSERVABILITY.md
   - Architecture:
     - The picture: architecture/picture.md
+    - Blocks and layers: architecture/blocks.md
     - Layering: architecture/layering.md
     - Boundaries: architecture/boundaries.md
     - Move plan: architecture/move-plan.md

{surf_agentic_base-0.3.2 → surf_agentic_base-0.3.4}/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.4}/src/agentic_base/provenance/__init__.py

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

{surf_agentic_base-0.3.2 → surf_agentic_base-0.3.4}/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
@@ -13,12 +14,28 @@ from agentic_base.domain.outcomes import RunRecordCreate, authority_of
 if TYPE_CHECKING:
     from openlineage.client.event_v2 import RunEvent
     from prov.model import ProvDocument
+    from rocrate.rocrate import ROCrate
 
 NAMESPACE = "https://github.com/saradamian/agentic-base/ns#"
 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 +160,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 +182,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,21 +201,24 @@ 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=[],
     )
 
 
-def to_process_run_crate(
-    run: RunRecordCreate, run_id: str, created_at: datetime, out_dir: Path
-) -> Path:
-    """A Process Run Crate written to *out_dir*. Returns the metadata file's path.
+def build_process_run_crate(
+    run: RunRecordCreate, run_id: str, created_at: datetime
+) -> ROCrate:
+    """The Process Run Crate as a library object, not yet written anywhere.
 
-    The run is a ``CreateAction`` whose instrument is the software that ran it and whose result
-    is the outcome with its provenance as ``PropertyValue`` entities, which is how the profile
-    says to attach facts the vocabulary does not name.
+    Returned unwritten so a consumer can add its own entities, the files a run produced, the
+    tool activities inside it, a Slurm job, before serialising, the way :func:`to_prov` and
+    :func:`to_openlineage` already hand back a document to extend. The run is a
+    ``CreateAction`` whose instrument is the software that ran it and whose result is the
+    outcome with its provenance as ``PropertyValue`` entities, which is how the profile says to
+    attach facts the vocabulary does not name.
     """
     try:
         from rocrate.model import ContextEntity
@@ -268,5 +290,12 @@ def to_process_run_crate(
     action["object"] = objects
     if results:
         action["result"] = results
-    crate.write(out_dir)
+    return crate
+
+
+def to_process_run_crate(
+    run: RunRecordCreate, run_id: str, created_at: datetime, out_dir: Path
+) -> Path:
+    """:func:`build_process_run_crate`, written to *out_dir*. Returns the metadata file's path."""
+    build_process_run_crate(run, run_id, created_at).write(out_dir)
     return Path(out_dir) / "ro-crate-metadata.json"

{surf_agentic_base-0.3.2 → surf_agentic_base-0.3.4/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.4
 Summary: Agentic base layer: run provenance, comparison validity, and shared safety primitives.
 Author: SURF
 License-Expression: EUPL-1.2
@@ -59,8 +59,10 @@ Dynamic: license-file
 [![python](https://img.shields.io/badge/python-3.10%20to%203.14-blue.svg)](pyproject.toml)
 [![cite](https://img.shields.io/badge/cite-CITATION.cff-green.svg)](CITATION.cff)
 
-The agentic base layer for SURF: **run provenance, comparison validity, and the shared
-primitives an agent needs**.
+The agentic base layer for SURF: **the record and referee for agent runs, the security
+primitives an agent needs on a shared platform, and the engineering standard that keeps both
+honest**. It is the contracts layer under a set of capability blocks, one per SURF system, that
+live in their own packages; see `docs/architecture/blocks.md`.
 
 It is built on the SURF Developer Platform golden path and adopts the common stack wherever the
 common stack has an answer. It contains only the parts we could not find anywhere else.

{surf_agentic_base-0.3.2 → surf_agentic_base-0.3.4}/src/surf_agentic_base.egg-info/SOURCES.txt

@@ -47,6 +47,7 @@ docs/OBSERVABILITY.md
 docs/decisions.md
 docs/include-readme.md
 docs/index.md
+docs/architecture/blocks.md
 docs/architecture/boundaries.md
 docs/architecture/compliance.md
 docs/architecture/deployment-overlay.md

{surf_agentic_base-0.3.2 → surf_agentic_base-0.3.4}/src/surf_agentic_base.egg-info/scm_file_list.json

@@ -42,6 +42,7 @@
     "charts/app/values.yaml",
     "docs/ENGINEERING.md",
     "docs/OBSERVABILITY.md",
+    "docs/architecture/blocks.md",
     "docs/architecture/boundaries.md",
     "docs/architecture/compliance.md",
     "docs/architecture/deployment-overlay.md",

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

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

{surf_agentic_base-0.3.2 → surf_agentic_base-0.3.4}/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.4}/tests/provenance/test_emit.py

@@ -204,3 +204,51 @@ 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"
+    )
+
+
+def test_the_crate_can_be_extended_before_it_is_written(tmp_path) -> None:
+    """A consumer folds its own entities, the files a run produced, onto the base's crate."""
+    from rocrate.rocrate import ROCrate
+
+    from agentic_base.provenance import build_process_run_crate
+
+    crate = build_process_run_crate(_run(), "abc", CREATED)
+    (tmp_path / "patch.diff").write_text("--- a\n+++ b\n")
+    produced = crate.add_file(tmp_path / "patch.diff", properties={"name": "the patch"})
+    action = crate.dereference("#abc")
+    action["result"] = [*action["result"], produced]
+    out = tmp_path / "crate"
+    crate.write(out)
+
+    reloaded = ROCrate(out)
+    results = [r["@id"] for r in reloaded.dereference("#abc")["result"]]
+    assert "patch.diff" in results
+    assert (out / "patch.diff").exists()