agentversion 0.2.0__tar.gz → 0.2.2__tar.gz

{agentversion-0.2.0 → agentversion-0.2.2}/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 > **Package version ≠ spec version.** This file tracks the **package** version. The on-the-wire `spec_version` is independent and frozen at `1.0.0`; a pre-1.0 package can implement a stable 1.0 spec, which is exactly the situation today.
 
+## [0.2.2] - 2026-07-15
+
+### Changed
+- **`behavioral_policy` re-scoped as a generic versioned policy-document surface** (docs only).
+  The surface previously described itself as bound to skillevaluation's conversation-mode
+  `policy_check` state machine; that eval mode was removed (skillevaluation ADR-0007), so the
+  docstrings + `spec/behavioral-policy.md` now define it document-agnostically: `policy_hash` is a
+  hash of *any* bound policy artifact (refund rules, a safety guardrail set, an escalation SOP…),
+  a rule change diffs **breaking**, an unchanged `policy_hash` is non-breaking. **No code or schema
+  change**: the `BehavioralPolicy` model still carries `objection_threshold`/`concede_events`/
+  `always_forbidden` (now documented as optional, illustrative, back-compat rule fields), the
+  `_BEHAVIORAL_POLICY_RULE_FIELDS` diff logic is byte-identical, and every frozen hash-vector +
+  the 406-test suite are unchanged. `spec_version` unchanged (1.0.0).
+
+## [0.2.1] - 2026-06-24
+
+### Fixed
+- **`contract_from_components` now emits the `behavioral_policy` and
+  `environment` surfaces.** 0.2.0 added the models, surface keys, and diff
+  classifiers, but the shared flat-components → contract assembler silently
+  dropped both — so a producer (the DecimalAI SDK / the platform) could never
+  actually populate them from components. They are now assembled verbatim from
+  each component's `schema_json`. Additive-only: a manifest that doesn't declare
+  them is unchanged (same `overall_hash`).
+- **`tool_calling_mode` and `runtime_version` are now lifted to `model_runtime`
+  top level** (not buried in `model_config_hash`), so a `tool_calling_mode`
+  change is classified **breaking** by the diff as intended, and
+  `runtime_version` participates in `model_runtime` severity.
+
+The DecimalAI SDK exporter (`ManifestSnapshot.to_agentversion`) was edited
+byte-identically and is pinned to this assembly by its conformance test.
+`SPEC_VERSION` is unchanged (1.0.0) — these surfaces were already in the spec.
+
 ## [0.2.0] - 2026-06-24
 
 ### Added

{agentversion-0.2.0 → agentversion-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentversion
-Version: 0.2.0
+Version: 0.2.2
 Summary: An open specification for versioning agent runtimes and keeping datasets valid.
 Project-URL: Homepage, https://github.com/decimal-labs/agentversion
 Project-URL: Documentation, https://github.com/decimal-labs/agentversion/tree/main/spec

{agentversion-0.2.0 → agentversion-0.2.2}/agentversion/contract.py

@@ -12,7 +12,8 @@ Each component is a plain dict::
     {
       "component_type":    "tool" | "skill" | "prompt" | "model" | "subagent"
                            | "output_schema" | "workflow" | "guardrail"
-                           | "context_config",
+                           | "context_config" | "behavioral_policy"
+                           | "environment",
       "component_name":    str,
       "component_version": str | None,
       "content_hash":      str | None,   # producer-supplied content fingerprint
@@ -146,6 +147,13 @@ def contract_from_components(components: list[dict[str, Any]]) -> dict[str, Any]
             gen["response_format"] = cfg["response_format"]
         if gen:
             model_runtime["generation_config"] = gen
+        # tool_calling_mode + runtime_version are TOP-LEVEL model_runtime fields
+        # (not under generation_config); the diff classifies a tool_calling_mode
+        # change as breaking. Must stay byte-identical with the SDK exporter.
+        if isinstance(cfg.get("tool_calling_mode"), str):
+            model_runtime["tool_calling_mode"] = cfg["tool_calling_mode"]
+        if isinstance(cfg.get("runtime_version"), str):
+            model_runtime["runtime_version"] = cfg["runtime_version"]
     else:
         model_runtime = {"provider": "unknown", "model": "unknown"}
 
@@ -252,4 +260,15 @@ def contract_from_components(components: list[dict[str, Any]]) -> dict[str, Any]
             ctx["retrieval_config_hash"] = ctx_comps[0]["content_hash"]
         contract["context_config"] = ctx
 
+    # behavioral_policy / environment are single structured surfaces (the surface
+    # IS the config), emitted verbatim from schema_json so hash_manifest hashes
+    # their contents. Must stay byte-identical with the SDK exporter.
+    bp_comps = by_type.get("behavioral_policy", [])
+    if bp_comps:
+        contract["behavioral_policy"] = dict(bp_comps[0].get("schema_json") or {})
+
+    env_comps = by_type.get("environment", [])
+    if env_comps:
+        contract["environment"] = dict(env_comps[0].get("schema_json") or {})
+
     return contract

{agentversion-0.2.0 → agentversion-0.2.2}/agentversion/diff.py

@@ -741,9 +741,9 @@ _BEHAVIORAL_POLICY_RULE_FIELDS = (
 def _adapt_behavioral_policy(old: dict[str, Any], new: dict[str, Any]) -> tuple[
     Literal["breaking", "non_breaking"], Severity, list[str]
 ]:
-    """A change to the multi-turn behavioral policy RULES is BREAKING: it invalidates the conversation-
-    mode eval set and any past traces graded under the old policy. (A bare metadata change with an
-    unchanged ``policy_hash`` is not a rule change.)
+    """A change to the bound behavioral policy RULES is BREAKING: it invalidates any eval set and any
+    past traces graded under the old policy. (A bare metadata change with an unchanged ``policy_hash``
+    is not a rule change.)
 
     Add/remove are asymmetric and handled here so the surface is severitied by its own
     logic in both directions: *introducing* a policy where there was none is additive

{agentversion-0.2.0 → agentversion-0.2.2}/agentversion/manifest.py

@@ -263,25 +263,30 @@ class Environment(BaseModel):
 
 
 class BehavioralPolicy(BaseModel):
-    """Multi-turn BEHAVIORAL-POLICY contract surface.
+    """Versioned BEHAVIORAL-POLICY contract surface.
 
-    The rules a multi-turn agent must hold across turns — e.g. a refund/escalation policy: "deny until
-    the customer objects N times, then escalate; never admit liability". Bound to skillevaluation's
-    conversation-mode ``policy_check`` (the deterministic state machine that grades these rules).
+    Binds the agent to a named policy artifact — the rules it must hold to, e.g. a refund/escalation
+    policy ("deny until the customer objects N times, then escalate; never admit liability"), a safety
+    guardrail set, or an escalation SOP. The surface is document-agnostic: ``policy_hash`` is the stable
+    identity (a hash of whatever policy artifact you bind), and the value carried is opaque to this
+    model.
 
     Why it is a first-class surface: a behavioral policy lives *inside* the prompt, so a prompt-stack
-    hash change is classified ``non_breaking`` — yet flipping the policy (``objection_threshold`` 3 → 1,
-    or removing an ``always_forbidden`` rule) INVALIDATES the conversation-mode eval set and any past
-    traces graded under the old policy. Hoisting the policy to its own surface makes that flip visible
-    and ``breaking`` instead of silently ``keep``. ``policy_hash`` is the stable identity (a hash of the
-    bound ``policy_check`` spec); the rule fields are carried for human-readable diffs. ``extra='allow'``
-    so a richer policy spec round-trips without forking this model.
+    hash change is classified ``non_breaking`` — yet flipping the policy (a threshold 3 → 1, or removing
+    a forbidden rule) INVALIDATES any eval set and any past traces graded under the old policy. Hoisting
+    the policy to its own surface makes that flip visible and ``breaking`` instead of silently ``keep``.
+
+    ``policy_hash`` is the identity; the structured rule fields below are OPTIONAL and carried only for
+    human-readable diffs (a policy artifact needn't populate any of them — ``extra='allow'`` lets a
+    richer or differently-shaped policy spec round-trip without forking this model). They remain on the
+    model for backward compatibility with policies already bound this way.
     """
 
     model_config = ConfigDict(extra="allow")
 
     policy_id: str | None = None
-    policy_hash: str | None = None  # stable hash of the bound policy_check spec (the identity)
+    policy_hash: str | None = None  # stable hash of the bound policy artifact (the identity)
+    # Optional structured rule fields — illustrative, kept for back-compat + human-readable diffs.
     objection_threshold: int | None = None
     concede_events: list[str] | None = None
     always_forbidden: list[str] | None = None

{agentversion-0.2.0 → agentversion-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentversion"
-version = "0.2.0"
+version = "0.2.2"
 description = "An open specification for versioning agent runtimes and keeping datasets valid."
 readme = "README.md"
 license = "Apache-2.0"

agentversion-0.2.2/spec/behavioral-policy.md

@@ -0,0 +1,56 @@
+# `behavioral_policy` surface
+
+A contract surface that binds an agent to a **versioned policy document** — the rules it must hold to.
+The surface is document-agnostic: the policy can be a refund/escalation policy (*"deny refunds and offer
+alternatives; only after the customer has objected ≥3 times, escalate to a human; never concede a refund
+yourself, and never admit liability"*), a safety guardrail set, an escalation SOP, or any other bound
+rule artifact.
+
+## Why it is a first-class surface
+
+A behavioral policy usually lives *inside the system prompt*. Before this surface existed, flipping the
+policy (tightening a threshold, or dropping a forbidden rule) showed up only as a `prompt_stack`
+**hash change**, which the diff classifies **`non_breaking`** → recommended decision **`keep`**. But a
+policy flip **invalidates** any eval set and any past traces that were graded under the old policy.
+Hoisting the policy to its own surface makes that flip **`breaking`** → `replay`/`drop`, instead of
+silently retaining now-wrong data.
+
+The `policy_hash` is the canonical identity — a hash of *whatever policy artifact you bind*. The
+structured rule fields below are optional and carried only for human-readable diffs; the surface does not
+interpret them.
+
+## Shape
+
+```json
+"behavioral_policy": {
+  "policy_id": "refund-escalation",
+  "policy_hash": "sha256:…",          // hash of the bound policy artifact (the identity)
+  "objection_threshold": 3,           // optional structured rule fields — illustrative,
+  "concede_events": ["offered_refund", "escalated"],   // carried for readable diffs only
+  "always_forbidden": ["admits_liability"]
+}
+```
+
+`policy_id` and `policy_hash` are the only load-bearing keys. The structured rule fields
+(`objection_threshold`, `concede_events`, `always_forbidden`) are **optional**, illustrative, and kept
+for backward compatibility with policies already bound this way — a policy artifact needn't populate any
+of them. The model is `extra="allow"`, so a richer or differently-shaped policy spec round-trips without
+forking it.
+
+## Diff semantics
+
+| Transition | Classification | Rationale |
+|---|---|---|
+| rule change (`policy_hash` differs, or any rule field differs) | **breaking** (`major`) | any eval set + past graded traces are now wrong |
+| `policy_hash` unchanged, only metadata (`policy_id`) differs | `non_breaking` (`minor`) | same policy, no rule changed |
+| introduced (absent → present) | `non_breaking` | the old eval set tested no policy; additive |
+| removed (present → absent) | **breaking** (`major`) | past data graded under the policy is now ungoverned |
+
+Reason code: `behavioral_policy_changed`. Configurable per-surface via `CompatibilityPolicy.behavioral_policy`
+(defaults: `on_major` → `drop`).
+
+## Hash-safety
+
+`behavioral_policy` is **optional and omitted by default**. The `overall_hash` is computed only over the
+surfaces actually present in a contract, so adding this surface to the spec does **not** change the hash
+of any existing (policy-less) manifest. The frozen hash-vectors are unchanged.

{agentversion-0.2.0 → agentversion-0.2.2}/tests/test_contract.py

@@ -59,6 +59,67 @@ def test_model_provider_inferred_when_absent():
     assert c["model_runtime"]["provider"] == "anthropic"
 
 
+# ── OSS-1/3/7: new 0.2.0 surfaces (must mirror the SDK exporter) ────────────
+
+def test_model_runtime_lifts_tool_calling_mode_and_runtime_version():
+    """OSS-1: tool_calling_mode + runtime_version are TOP-LEVEL model_runtime
+    fields (not under generation_config), so the diff classifies them."""
+    c = contract_from_components([
+        _comp("model", "default", content_hash="sha256:m",
+              schema_json={"provider": "openai", "model": "gpt-4o",
+                           "tool_calling_mode": "native", "runtime_version": "1.2"}),
+    ])
+    mr = c["model_runtime"]
+    assert mr["tool_calling_mode"] == "native"
+    assert mr["runtime_version"] == "1.2"
+    assert "tool_calling_mode" not in mr.get("generation_config", {})
+
+
+def test_behavioral_policy_surface_assembled():
+    """OSS-3: behavioral_policy is emitted verbatim from its schema_json."""
+    sj = {"policy_id": "refund", "policy_hash": "sha256:p", "objection_threshold": 3,
+          "always_forbidden": ["admit_liability"]}
+    c = contract_from_components([
+        _comp("model", "default", schema_json={"model": "gpt-4o"}),
+        _comp("behavioral_policy", "behavioral_policy", content_hash="sha256:p", schema_json=sj),
+    ])
+    assert c["behavioral_policy"] == sj
+
+
+def test_environment_surface_assembled():
+    """OSS-7: environment is emitted verbatim from its schema_json."""
+    sj = {"deployment_id": "d", "region": "us", "runtime_versions": {"python": "3.12"}}
+    c = contract_from_components([
+        _comp("model", "default", schema_json={"model": "gpt-4o"}),
+        _comp("environment", "environment", content_hash="sha256:e", schema_json=sj),
+    ])
+    assert c["environment"] == sj
+
+
+def test_new_optional_surfaces_absent_when_undeclared():
+    """Additive-only: a model-only contract carries neither new surface, so
+    existing manifests keep their exact prior identity hash."""
+    c = contract_from_components([_comp("model", "default", schema_json={"model": "gpt-4o"})])
+    assert "behavioral_policy" not in c
+    assert "environment" not in c
+
+
+def test_behavioral_policy_participates_in_identity_hash():
+    """Adding behavioral_policy, and changing its policy_hash, each change the
+    canonical jcs-sha256 identity hash."""
+    base = [_comp("model", "default", content_hash="sha256:m",
+                  schema_json={"provider": "openai", "model": "gpt-4o"})]
+    with_p = base + [_comp("behavioral_policy", "behavioral_policy", content_hash="sha256:p",
+                           schema_json={"policy_id": "p", "policy_hash": "sha256:p"})]
+    with_p2 = base + [_comp("behavioral_policy", "behavioral_policy", content_hash="sha256:p2",
+                            schema_json={"policy_id": "p", "policy_hash": "sha256:p2"})]
+    h_base = hash_manifest({"contract": contract_from_components(base)})
+    h_p = hash_manifest({"contract": contract_from_components(with_p)})
+    h_p2 = hash_manifest({"contract": contract_from_components(with_p2)})
+    assert h_base != h_p   # the surface participates in identity
+    assert h_p != h_p2     # a rule change re-versions
+
+
 def test_tool_and_skill_registry_hashes_are_computed():
     c = contract_from_components([
         _comp("tool", "t1", version="1", content_hash="sha256:t1",

agentversion-0.2.0/spec/behavioral-policy.md

@@ -1,51 +0,0 @@
-# `behavioral_policy` surface
-
-A contract surface for a multi-turn agent's **behavioral policy** — the rules it must hold *across
-turns*, e.g. a refund/escalation policy: *"deny refunds and offer alternatives; only after the customer
-has objected ≥3 times, escalate to a human; never concede a refund yourself, and never admit liability."*
-
-## Why it is a first-class surface
-
-A behavioral policy lives *inside the system prompt*. Before this surface existed, flipping the policy
-(`objection_threshold` 3 → 1, or dropping an `always_forbidden` rule) showed up only as a `prompt_stack`
-**hash change**, which the diff classifies **`non_breaking`** → recommended decision **`keep`**. But a
-policy flip **invalidates** the conversation-mode eval set and any past traces that were graded under the
-old policy. Hoisting the policy to its own surface makes that flip **`breaking`** → `replay`/`drop`,
-instead of silently retaining now-wrong data.
-
-This binds directly to [skillevaluation](https://github.com/decimal-labs/skillevaluation)'s
-conversation-mode `policy_check` — the deterministic state machine that grades these same rules. The
-`policy_hash` is the canonical identity (a hash of the bound `policy_check` spec); the rule fields are
-carried for human-readable diffs.
-
-## Shape
-
-```json
-"behavioral_policy": {
-  "policy_id": "refund-escalation",
-  "policy_hash": "sha256:…",          // hash of the bound policy_check spec (the identity)
-  "objection_threshold": 3,
-  "concede_events": ["offered_refund", "escalated"],
-  "always_forbidden": ["admits_liability"]
-}
-```
-
-The model is `extra="allow"`, so a richer policy spec round-trips without forking it.
-
-## Diff semantics
-
-| Transition | Classification | Rationale |
-|---|---|---|
-| rule change (`policy_hash` differs, or any rule field differs) | **breaking** (`major`) | conversation eval set + past graded traces are now wrong |
-| `policy_hash` unchanged, only metadata (`policy_id`) differs | `non_breaking` (`minor`) | same policy, no rule changed |
-| introduced (absent → present) | `non_breaking` | the old eval set tested no policy; additive |
-| removed (present → absent) | **breaking** (`major`) | past data graded under the policy is now ungoverned |
-
-Reason code: `behavioral_policy_changed`. Configurable per-surface via `CompatibilityPolicy.behavioral_policy`
-(defaults: `on_major` → `drop`).
-
-## Hash-safety
-
-`behavioral_policy` is **optional and omitted by default**. The `overall_hash` is computed only over the
-surfaces actually present in a contract, so adding this surface to the spec does **not** change the hash
-of any existing (policy-less) manifest. The frozen hash-vectors are unchanged.