Add RuntimeConfig declared fields + null-skip (proposal 0032) (#78)

* Add RuntimeConfig declared fields + null-skip

Implements proposal 0032 (spec v0.24.0). Three OpenAI-standard
sampling parameters promoted from the extras pass-through to declared
fields on RuntimeConfig: frequency_penalty, presence_penalty, and
stop_sequences. The declared name stop_sequences matches the
OpenTelemetry GenAI semconv (and Anthropic / Gemini wire-key
conventions); the OpenAI-compatible wire mapping translates it to
OpenAI's shorter body key stop on emission, per spec §8.1.

Null-skip is now uniform across all seven declared fields: a field
set to None is omitted from the wire body entirely (no JSON null).
The existing four fields already followed this pattern; the three
new fields extend it.

OTel observer emits gen_ai.request.frequency_penalty,
gen_ai.request.presence_penalty, and gen_ai.request.stop_sequences
on the LLM span when the corresponding RuntimeConfig field is set
(per observability §5.5.2's expanded attribute list).

RuntimeConfig.from_partial(**kwargs) classmethod is a pure Python
ergonomic that drops None-valued kwargs before construction. The
wire layer already null-skips, so this is convenience only.

Spec submodule bumped to v0.24.0; conformance.toml grows entries for
proposals 0031 (langfuse mapping, not-yet) and 0032 (not-yet here,
flips to implemented with since=0.10.0 in the release PR).

Tests: fixture llm-provider/032 and observability/025 pass. Langfuse
fixtures 022-024 deferred in the parser harness until PR 3 ships the
matching directive model.

* Strengthen from_partial drop-Nones test

The is-None assertions on max_tokens and seed weren't load-bearing:
both fields default to None on a base RuntimeConfig, so the test
would have passed even if from_partial forwarded the None kwargs.
Added model_fields_set assertions, which carry only fields the
caller explicitly set during construction, to prove the drop.

Addresses CoPilot PR review feedback on #78.

Author: chris-colinsky

conformance.toml

@@ -29,7 +29,7 @@
 
 [manifest]
 implementation = "openarmature-python"
-spec_pin = "v0.22.1"
+spec_pin = "v0.24.0"
 
 # Status values:
 #   implemented   — shipped behavior matches the proposal's contract
@@ -149,3 +149,15 @@ since = "0.9.0"
 status = "textual-only"
 since = "0.9.0"
 note = "Drain snapshot semantic and timeout-input validation already implemented as part of the proposal 0010 impl PR (v0.9.0); no additional module-level work needed."
+
+# Spec v0.23.0 + v0.24.0 batch (proposals 0031, 0032). Both proposals
+# have impl work landing across the v0.10.0 release cycle; status
+# stays `not-yet` until the release PR flips them to `implemented`
+# with `since = "0.10.0"`. The pinned spec submodule advances ahead
+# of the impl status because newer fixtures need to be visible to
+# the conformance harness as each PR lands.
+[proposals."0031"]
+status = "not-yet"
+
+[proposals."0032"]
+status = "not-yet"

docs/concepts/observability.md

@@ -396,8 +396,9 @@ tools). Emitted alongside the OA namespace:
 - `gen_ai.request.model` / `gen_ai.response.model` — the bound
   model and (when the provider returns one) the more-specific
   identifier in the response body.
-- `gen_ai.request.temperature` / `max_tokens` / `top_p` / `seed`
-  — only emitted for fields the caller actually set; absence on
+- `gen_ai.request.temperature` / `max_tokens` / `top_p` / `seed` /
+  `frequency_penalty` / `presence_penalty` / `stop_sequences` —
+  only emitted for fields the caller actually set; absence on
   the span means "not supplied," distinct from a zero value.
 - `gen_ai.usage.input_tokens` / `output_tokens` — token counts.
 - `gen_ai.response.finish_reasons` — single-element string array.
@@ -429,7 +430,8 @@ This surfaces three attributes:
   with empty content.
 - `openarmature.llm.request.extras` — JSON-encoded `RuntimeConfig`
   extras bag (provider-specific pass-through fields like
-  `frequency_penalty`). Omitted when empty.
+  `repetition_penalty` for vLLM, or `top_k` for HuggingFace
+  endpoints). Omitted when empty.
 
 **Default-off is deliberate.** The payload may contain PII the user
 hasn't audited; opting in is a separate decision from opting into

openarmature-spec

@@ -51,7 +51,7 @@ Specification = "https://github.com/LunarCommand/openarmature-spec"
 openarmature = "openarmature.cli:main"
 
 [tool.openarmature]
-spec_version = "0.22.1"
+spec_version = "0.24.0"
 
 [dependency-groups]
 dev = [

pyproject.toml

@@ -1,6 +1,6 @@
 # OpenArmature — Agent documentation
 
-*This is the agent guide bundled with the openarmature Python package, version 0.9.0 (spec v0.22.1). For the full docs site see [openarmature.ai](https://openarmature.ai). For the canonical spec text see [openarmature.org/capabilities](https://openarmature.org/capabilities/). For project-specific conventions for the code you're editing, see the host project's `AGENTS.md` or `CLAUDE.md`.*
+*This is the agent guide bundled with the openarmature Python package, version 0.9.0 (spec v0.24.0). For the full docs site see [openarmature.ai](https://openarmature.ai). For the canonical spec text see [openarmature.org/capabilities](https://openarmature.org/capabilities/). For project-specific conventions for the code you're editing, see the host project's `AGENTS.md` or `CLAUDE.md`.*
 
 ## TL;DR
 
@@ -10,7 +10,7 @@ OpenArmature is a workflow framework for LLM pipelines and tool-calling agents 
 
 ## Capability contracts
 
-_Sourced from openarmature-spec v0.22.1. Each entry below reproduces §1 (Purpose) and §2 (Concepts) of the capability's `spec.md`. For the full spec text (execution model, error semantics, determinism, observer hooks, etc.) see the linked docs site._
+_Sourced from openarmature-spec v0.24.0. Each entry below reproduces §1 (Purpose) and §2 (Concepts) of the capability's `spec.md`. For the full spec text (execution model, error semantics, determinism, observer hooks, etc.) see the linked docs site._
 
 ### Capability: `graph-engine`
 
@@ -274,13 +274,13 @@ The observability capability defines normative mappings from OpenArmature's runt
 well-known external observability backends. The substrate is provider-neutral; the capability is
 where each concrete backend's translation lives.
 
-This first version specifies the **OpenTelemetry** mapping. Future proposals add other backends
-(Langfuse, etc.) as sibling sections of this same spec; the OTel mapping serves as the reference
-shape for cross-backend equivalence.
+This spec defines two concrete backend mappings: the **OpenTelemetry** mapping in §3–§7 and the
+**Langfuse** mapping in §8. Future proposals add additional backends as further sibling sections
+of this same spec; the OTel mapping serves as the reference shape for cross-backend equivalence.
 
 The capability does NOT introduce new graph-engine primitives. It consumes the existing observer
 event stream — `started` events open spans, `completed` events close them. An implementation that
-emits OTel spans is built on top of §6, not into the engine.
+emits OTel spans (or Langfuse observations, per §8) is built on top of §6, not into the engine.
 
 #### 2. Concepts
 
@@ -310,7 +310,8 @@ and is intended to be visible in every backend the implementation emits to. A us
 LLM workflow with both an OTel backend (system traces, logs) and a Langfuse backend
 (LLM-specific traces) uses the `correlation_id` as a join key between them: find a slow request
 in Langfuse, search for its `correlation_id` in OTel logs, and see the surrounding
-infrastructure activity. See §3 (architectural contract) and §5.6 (OTel attribute realization).
+infrastructure activity. See §3 (architectural contract), §5.6 (OTel attribute realization),
+and §8.5 (Langfuse attribute realization).
 
 ### Capability: `prompt-management`
 

src/openarmature/AGENTS.md

@@ -25,4 +25,4 @@
 """
 
 __version__ = "0.9.0"
-__spec_version__ = "0.22.1"
+__spec_version__ = "0.24.0"

src/openarmature/__init__.py

@@ -423,6 +423,11 @@ def _build_request_body(
         if tools:
             body["tools"] = [_tool_to_wire(t) for t in tools]
         if config is not None:
+            # Per spec §6 null-skip: each declared field with value
+            # ``None`` is omitted from the wire body. Same-name keys
+            # for the pre-0032 four; same-name for frequency_penalty /
+            # presence_penalty per §8.1; ``stop_sequences`` renames to
+            # OpenAI's body key ``stop`` per §8.1's only rename.
             if config.temperature is not None:
                 body["temperature"] = config.temperature
             if config.max_tokens is not None:
@@ -431,9 +436,15 @@ def _build_request_body(
                 body["top_p"] = config.top_p
             if config.seed is not None:
                 body["seed"] = config.seed
+            if config.frequency_penalty is not None:
+                body["frequency_penalty"] = config.frequency_penalty
+            if config.presence_penalty is not None:
+                body["presence_penalty"] = config.presence_penalty
+            if config.stop_sequences is not None:
+                body["stop"] = config.stop_sequences
             # Pass-through any provider-specific extras (extra="allow"
-            # on RuntimeConfig); spec §6 permits implementations to
-            # accept additional fields.
+            # on RuntimeConfig); spec §6 mandates implementations MUST
+            # accept and forward undeclared fields untouched.
             extras = config.model_extra or {}
             for k, v in extras.items():
                 body.setdefault(k, v)
@@ -1111,6 +1122,15 @@ def _request_params_from_config(config: RuntimeConfig | None) -> dict[str, Any]:
         out["top_p"] = config.top_p
     if config.seed is not None:
         out["seed"] = config.seed
+    # Three fields promoted in proposal 0032; surfaced under their
+    # cross-vendor declared names so the observer emits
+    # gen_ai.request.{frequency_penalty,presence_penalty,stop_sequences}.
+    if config.frequency_penalty is not None:
+        out["frequency_penalty"] = config.frequency_penalty
+    if config.presence_penalty is not None:
+        out["presence_penalty"] = config.presence_penalty
+    if config.stop_sequences is not None:
+        out["stop_sequences"] = config.stop_sequences
     return out
 
 

src/openarmature/llm/providers/openai.py

@@ -15,8 +15,7 @@
 
 ``RuntimeConfig`` is the optional per-call sampling-parameter record.
 Implementations MAY accept additional provider-specific fields; the
-four declared here (temperature, max_tokens, top_p, seed) are the
-mandated minimum.
+seven declared here are the mandated minimum.
 """
 
 from __future__ import annotations
@@ -107,12 +106,13 @@ class Response(BaseModel):
     response_model: str | None = None
 
 
+# Spec §6 declared-field surface: seven optional fields. Undeclared
+# fields supplied by callers MUST be forwarded to the wire body
+# untouched (extras pass-through); declared fields with value ``None``
+# MUST be omitted from the wire body (null-skip). Both rules are
+# enforced by the §8 wire-format mapping, not by RuntimeConfig itself.
 class RuntimeConfig(BaseModel):
-    """Per-call sampling parameters and budget hints.
-
-    All four fields are optional. Implementations MAY accept
-    additional provider-specific fields; this is the minimum.
-    """
+    """Per-call sampling parameters and budget hints."""
 
     model_config = ConfigDict(extra="allow")
 
@@ -122,6 +122,32 @@ class RuntimeConfig(BaseModel):
     # Per spec §6: setting ``seed`` does NOT guarantee determinism; see
     # §9. Best-effort only, useful for providers that support it.
     seed: int | None = None
+    # Promoted from extras to a declared field in proposal 0032 (spec
+    # v0.24.0). Cross-vendor: OpenAI / Mistral / Cohere accept this
+    # name directly; Anthropic and Gemini map to vendor-specific
+    # equivalents at the wire layer (per §8.2 / §8.3 when those land).
+    frequency_penalty: float | None = None
+    presence_penalty: float | None = None
+    # Declared field name matches the cross-vendor OpenTelemetry GenAI
+    # semconv (``gen_ai.request.stop_sequences``) and Anthropic /
+    # Gemini wire-key conventions. The §8.1 OpenAI-compatible wire
+    # mapping translates ``stop_sequences`` to OpenAI's shorter body
+    # key ``stop`` on emission. OpenAI is the outlier on the shorter
+    # name; the declared layer matches the cross-vendor norm.
+    stop_sequences: list[str] | None = None
+
+    # Pure Python ergonomic, not a spec contract. The wire-layer
+    # null-skip rule already drops ``None``-valued declared fields, so
+    # this helper exists solely to let callers splat a dict whose
+    # entries may be ``None`` without filtering at the call site.
+    @classmethod
+    def from_partial(cls, **kwargs: Any) -> RuntimeConfig:
+        """Construct a config, dropping kwargs whose value is ``None``.
+
+        >>> RuntimeConfig.from_partial(temperature=0.7, top_p=None).top_p is None
+        True
+        """
+        return cls(**{k: v for k, v in kwargs.items() if v is not None})
 
 
 __all__ = [

src/openarmature/llm/response.py

@@ -765,6 +765,17 @@ def _handle_llm_event(self, event: NodeEvent) -> None:
                     attrs["gen_ai.request.top_p"] = request_params["top_p"]
                 if "seed" in request_params:
                     attrs["gen_ai.request.seed"] = request_params["seed"]
+                # Three new request-param attrs from proposal 0032
+                # (spec v0.24.0). The §8.4.3 Langfuse mapping picks
+                # these up by inclusion via the gen_ai.request.* →
+                # generation.modelParameters.<suffix> rule with no
+                # §8 edit.
+                if "frequency_penalty" in request_params:
+                    attrs["gen_ai.request.frequency_penalty"] = request_params["frequency_penalty"]
+                if "presence_penalty" in request_params:
+                    attrs["gen_ai.request.presence_penalty"] = request_params["presence_penalty"]
+                if "stop_sequences" in request_params:
+                    attrs["gen_ai.request.stop_sequences"] = request_params["stop_sequences"]
             # §5.5.1 payload attributes (gated by ``disable_llm_payload``).
             # ``input.messages`` and ``request.extras`` go on the started
             # span; ``output.content`` lands on the completed branch.

src/openarmature/observability/otel/observer.py

@@ -346,6 +346,10 @@ class RuntimeConfigSpec(_AllowExtras):
     max_tokens: int | None = None
     top_p: float | None = None
     seed: int | None = None
+    # Three declared fields promoted by proposal 0032 (spec v0.24.0).
+    frequency_penalty: float | None = None
+    presence_penalty: float | None = None
+    stop_sequences: list[str] | None = None
     extras: dict[str, Any] | None = None