agent-first-data 0.16.0__tar.gz → 0.17.0__tar.gz

{agent_first_data-0.16.0 → agent_first_data-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.16.0
+Version: 0.17.0
 Summary: A naming convention that lets AI agents understand your data without being told what it means.
 License-Expression: MIT
 Project-URL: Repository, https://github.com/agentfirstkit/agent-first-data
@@ -28,7 +28,7 @@ print(output_json(value))
 print(output_plain(value))
 ```
 
-Useful names use Python casing: `output_json`, `output_yaml`, `output_plain` (each takes an optional keyword-only `options=`), `redacted_value`, `redact_secrets_in_place`, `redact_url_secrets`, `parse_size`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `cli_parse_output`, `cli_output`, `build_cli_error`, `build_cli_version`, `cli_handle_version_or_continue`, `decode_protocol_event`. Skill admin and stream-redirect helpers live in `agent_first_data.skill` and `agent_first_data.stream_redirect` (import the submodule directly).
+Useful names use Python casing: `output_json`, `output_yaml`, `output_plain` (each takes an optional keyword-only `options=`), `redacted_value`, `redact_secrets_in_place`, `redact_url_secrets`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `cli_parse_output`, `cli_output`, `build_cli_error`, `build_cli_version`, `cli_handle_version_or_continue`, `decode_protocol_event`. Skill admin and stream-redirect helpers live in `agent_first_data.skill` and `agent_first_data.stream_redirect` (import the submodule directly).
 
 Logging is available through `init_logging_json`, `init_logging_plain`, `init_logging_yaml`, `span`, and `get_logger`.
 

{agent_first_data-0.16.0 → agent_first_data-0.17.0}/README.md

@@ -19,7 +19,7 @@ print(output_json(value))
 print(output_plain(value))
 ```
 
-Useful names use Python casing: `output_json`, `output_yaml`, `output_plain` (each takes an optional keyword-only `options=`), `redacted_value`, `redact_secrets_in_place`, `redact_url_secrets`, `parse_size`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `cli_parse_output`, `cli_output`, `build_cli_error`, `build_cli_version`, `cli_handle_version_or_continue`, `decode_protocol_event`. Skill admin and stream-redirect helpers live in `agent_first_data.skill` and `agent_first_data.stream_redirect` (import the submodule directly).
+Useful names use Python casing: `output_json`, `output_yaml`, `output_plain` (each takes an optional keyword-only `options=`), `redacted_value`, `redact_secrets_in_place`, `redact_url_secrets`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `cli_parse_output`, `cli_output`, `build_cli_error`, `build_cli_version`, `cli_handle_version_or_continue`, `decode_protocol_event`. Skill admin and stream-redirect helpers live in `agent_first_data.skill` and `agent_first_data.stream_redirect` (import the submodule directly).
 
 Logging is available through `init_logging_json`, `init_logging_plain`, `init_logging_yaml`, `span`, and `get_logger`.
 

{agent_first_data-0.16.0 → agent_first_data-0.17.0}/agent_first_data/__init__.py

@@ -28,8 +28,9 @@ from agent_first_data.format import (
     output_plain,
     redacted_value,
     redact_url_secrets,
-    parse_size,
     normalize_utc_offset,
+    is_valid_bcp47,
+    is_valid_rfc3339,
     is_valid_rfc3339_date,
     is_valid_rfc3339_time,
 )
@@ -75,8 +76,9 @@ __all__ = [
     "output_plain",
     "redacted_value",
     "redact_url_secrets",
-    "parse_size",
     "normalize_utc_offset",
+    "is_valid_bcp47",
+    "is_valid_rfc3339",
     "is_valid_rfc3339_date",
     "is_valid_rfc3339_time",
     "OutputFormat",

{agent_first_data-0.16.0 → agent_first_data-0.17.0}/agent_first_data/assets/protocol-v1.schema.json

@@ -47,13 +47,7 @@
       "type": "object",
       "properties": {
         "kind": {"const": "progress"},
-        "progress": {
-          "type": "object",
-          "properties": {
-            "message": {"type": "string", "minLength": 1}
-          },
-          "additionalProperties": true
-        },
+        "progress": true,
         "trace": {"$ref": "#/$defs/trace"}
       },
       "required": ["kind", "progress"],
@@ -63,18 +57,7 @@
       "type": "object",
       "properties": {
         "kind": {"const": "log"},
-        "log": {
-          "type": "object",
-          "properties": {
-            "message": {"type": "string", "minLength": 1},
-            "level": {"enum": ["debug", "info", "warn", "error"]},
-            "code": false
-          },
-          "not": {
-            "required": ["code"]
-          },
-          "additionalProperties": true
-        },
+        "log": true,
         "trace": {"$ref": "#/$defs/trace"}
       },
       "required": ["kind", "log"],

{agent_first_data-0.16.0 → agent_first_data-0.17.0}/agent_first_data/assets/registry.json

@@ -132,7 +132,7 @@
       "unit": "bcp47_language_tag",
       "formatting": {"strip_key": false, "plain_yaml": "pass_through"},
       "redaction": {"mode": "none"},
-      "constraints": {"string": true}
+      "constraints": {"bcp47": true}
     },
     {
       "suffix": "_utc_offset",
@@ -152,18 +152,9 @@
       "redaction": {"mode": "none"},
       "constraints": {"integer": true, "minimum": 0}
     },
-    {
-      "suffix": "_size",
-      "category": "size",
-      "json_types": ["string"],
-      "unit": "byte_size_input",
-      "formatting": {"strip_key": false, "plain_yaml": "pass_through"},
-      "redaction": {"mode": "none"},
-      "constraints": {"parse_size_units": ["B", "kB", "MB", "GB", "TB", "KiB", "MiB", "GiB", "TiB"]}
-    },
     {
       "suffix": "_percent",
-      "category": "ratio",
+      "category": "percentage",
       "json_types": ["number"],
       "unit": "percent",
       "formatting": {"strip_key": true, "plain_yaml": "append_percent"},

{agent_first_data-0.16.0 → agent_first_data-0.17.0}/agent_first_data/assets/skills/agent-first-data/references/registry.json

@@ -132,7 +132,7 @@
       "unit": "bcp47_language_tag",
       "formatting": {"strip_key": false, "plain_yaml": "pass_through"},
       "redaction": {"mode": "none"},
-      "constraints": {"string": true}
+      "constraints": {"bcp47": true}
     },
     {
       "suffix": "_utc_offset",
@@ -152,18 +152,9 @@
       "redaction": {"mode": "none"},
       "constraints": {"integer": true, "minimum": 0}
     },
-    {
-      "suffix": "_size",
-      "category": "size",
-      "json_types": ["string"],
-      "unit": "byte_size_input",
-      "formatting": {"strip_key": false, "plain_yaml": "pass_through"},
-      "redaction": {"mode": "none"},
-      "constraints": {"parse_size_units": ["B", "kB", "MB", "GB", "TB", "KiB", "MiB", "GiB", "TiB"]}
-    },
     {
       "suffix": "_percent",
-      "category": "ratio",
+      "category": "percentage",
       "json_types": ["number"],
       "unit": "percent",
       "formatting": {"strip_key": true, "plain_yaml": "append_percent"},

{agent_first_data-0.16.0 → agent_first_data-0.17.0}/agent_first_data/assets/skills/agent-first-data/references/rules.md

@@ -37,6 +37,10 @@ The field name is the schema. Always encode units and semantics in the field nam
 | `_epoch_ns` | nanoseconds since Unix epoch as a decimal string | `created_epoch_ns: "1707868800000000000"` |
 | `_rfc3339` | RFC 3339 date-time string | `expires_rfc3339: "2026-02-14T10:30:00Z"` |
 
+Integer vs string is not uniform across siblings: `_epoch_s` and `_epoch_ms` are JSON integers, but `_epoch_ns` is a decimal **string** because nanoseconds exceed the 2⁵³−1 safe-integer range. The same rule applies to large `_sats`/`_msats` (integer when safe, decimal string when not). Writing `_epoch_ns` as a bare JSON number silently loses precision — `afdata lint` rejects it (`suffix_type_mismatch`).
+
+`_rfc3339` needs a **mandatory** offset: `YYYY-MM-DDThh:mm:ss[.fff]` followed by `Z` or `±HH:MM`. A bare `2026-02-14T10:30:00` (no offset), a space instead of `T`, or a trailing IANA name (`...Asia/Shanghai`) is rejected by `afdata lint`. `afdata lint` also type-checks the numeric suffixes (durations `_s`/`_ms`/…, currency `_cents`/`_micro`/`_jpy`) and rejects a `_url` with internal whitespace or bare `user:pass@host` credentials.
+
 ### Strict string formats
 
 | Suffix | Format | Example |
@@ -46,7 +50,7 @@ The field name is the schema. Always encode units and semantics in the field nam
 | `_rfc3339_date` | RFC 3339 full-date string | `invoice_due_rfc3339_date: "2026-06-13"` |
 | `_rfc3339_time` | RFC 3339 partial-time string | `market_open_rfc3339_time: "09:30:00"` |
 
-`*_bcp47` identifies a BCP-47 language tag string. AFDATA does not implement the full BCP-47 registry; tools may validate tags when needed.
+`*_bcp47` identifies a BCP-47 language tag string. AFDATA validates structure (hyphen-separated subtags, 2–3 letter primary language), so the POSIX form `zh_CN` and an over-long primary like `chinese` are rejected; use `zh-CN`. It does not check the IANA registry, so a well-formed-but-unregistered tag like `zz-ZZ` still passes. `is_valid_bcp47` and `afdata lint` apply this check.
 
 `*_utc_offset` identifies a fixed UTC offset. Canonical persisted and structured output values are `"UTC"` or `±HH:MM`, with `HH` in `00..23` and `MM` in `00..59`; zero offsets normalize to `"UTC"`. This is not an IANA timezone name, DST rule, or timezone database field.
 
@@ -63,11 +67,8 @@ Avoid magic string sentinels such as `"auto"` inside strict-format fields. If a
 | Suffix | Example |
 |:-------|:--------|
 | `_bytes` | `payload_bytes: 456789` (non-negative integer) |
-| `_size` | `buffer_size: "10MiB"` or `"10MB"` (config files only, human-readable) |
 
-`_size` parsing requires explicit units: `B`, decimal `kB/MB/GB/TB`, or binary `KiB/MiB/GiB/TiB`. Bare numbers and ambiguous `K/M/G/T` are invalid.
-
-`parse_size("10MiB")` → `10485760`; `parse_size("10MB")` → `10000000`. Returns null for invalid or negative input.
+Byte sizes are always integer `_bytes`, in config and output alike. There is no unit-in-value size string: never write `buffer_size: "10MiB"`. Encode the unit in the key (`buffer_bytes: 10485760`), the same way durations use `timeout_s: 30`.
 
 ### Percentage
 
@@ -75,6 +76,8 @@ Avoid magic string sentinels such as `"auto"` inside strict-format fields. If a
 |:-------|:--------|
 | `_percent` | `cpu_percent: 85` |
 
+Value is in units of percent: `1` = 1%, `0.2` = 0.2%, `85` = 85%. Decimals, negatives, and values >100 are all valid; no fixed range. `%` is exactly 0.01, so `_percent` is never a 0–1 fraction — if the underlying ratio is `0.999`, multiply by 100 and write `success_percent: 99.9`. Writing `0.85` for 85% is a producer-side conversion bug, not a convention ambiguity.
+
 ### Currency
 
 Bitcoin:
@@ -150,7 +153,6 @@ ORM struct fields preserve the suffix: `duration_ms: i64`, not `duration: i64`.
 | `latency: 142` | `latency_ms: 142` | seconds? milliseconds? |
 | `api_key: "sk-..."` | `api_key_secret: "sk-..."` | won't be auto-redacted |
 | `cpu: 85` | `cpu_percent: 85` | 85 what? |
-| `buffer: "10MiB"` | `buffer_size: "10MiB"` | only `_size` gets parsed |
 
 ---
 
@@ -174,7 +176,7 @@ Remove recognized formatting suffix from key. Longest match first, exact lowerca
 4. `_msats`, `_sats`, `_bytes`, `_percent`, `_secret`
 5. `_jpy`, `_ns`, `_us`, `_ms`, `_s`
 
-`_size`, `_bcp47`, `_utc_offset`, `_rfc3339_date`, and `_rfc3339_time` are NOT stripped (pass through). If two keys collide after stripping, both revert to original key AND raw value (no formatting). Redaction runs before collision handling, so fallback never restores a secret.
+`_bcp47`, `_utc_offset`, `_rfc3339_date`, and `_rfc3339_time` are NOT stripped (pass through). If two keys collide after stripping, both revert to original key AND raw value (no formatting). Redaction runs before collision handling, so fallback never restores a secret.
 
 ### Value formatting (YAML and Plain)
 
@@ -184,7 +186,6 @@ Remove recognized formatting suffix from key. Longest match first, exact lowerca
 - `_epoch_ms`/`_epoch_s`/decimal-string `_epoch_ns` → RFC 3339 (negative = pre-1970)
 - `_rfc3339` → pass through
 - `_bytes` → human-readable (`456789` → `446.1KiB`); negative and fractional byte values fall through raw
-- `_size` → pass through
 - `_percent` → append `%`
 - `_msats` → `{n}msats`, `_sats` → `{n}sats`
 - `_usd_cents` → `$X.XX`, `_eur_cents` → `€X.XX`, `_jpy` → `¥X,XXX`, `_{code}_cents` → `X.XX CODE`, `_{code}_micro` → `X.XXXXXX CODE` where `code` is 3-4 ASCII letters
@@ -258,7 +259,7 @@ Startup payload fields are tool-defined; `config` is recommended, while `version
 
 All use `kind` plus the same-named payload and optional `trace`. Do not split protocol events across `stdout` and `stderr`.
 
-Base validators enforce mandatory envelope/error/lifecycle rules. Strict validators additionally require object-valued `trace` on every event, complete log fields (`message`, `level`; `code` field MUST NOT appear in log payload), `retryable` on every error, and a non-empty progress `message`. Use strict validation before claiming compliance with all recommendations.
+Base validators enforce mandatory envelope/error/lifecycle rules. Strict validators additionally require object-valued `trace` on every event and `retryable` on every error. Log and progress payloads remain tool-defined in both profiles. Use strict validation before claiming compliance with all recommendations.
 
 ---
 
@@ -298,11 +299,11 @@ let span = info_span!("request", request_id = %uuid);
 let _guard = span.enter();
 ```
 
-For Go, Python, and TypeScript: emit span fields explicitly in each log event via `.field()` or equivalent event construction.
+For Go, Python, and TypeScript: emit span fields explicitly in each tool-defined log payload.
 
 ### Output fields
 
-Every log line contains `message`, `level` (debug/info/warn/error), plus span fields and event fields. Log payloads MUST NOT contain a `code` field. Do not use the log level as `code`; `code:"error"` is reserved for terminal protocol errors. Projects that need timestamps add them as extension fields (`timestamp_epoch_ms`) via emitter defaults or per-call `.field()`.
+Log payloads have no required or reserved fields. Traditional logging adapters commonly add `message` and `level` (debug/info/warn/error), plus span and event fields, but those names and meanings are adapter conventions rather than AFDATA protocol requirements. Projects that need timestamps add `timestamp_epoch_ms` explicitly.
 
 Log redaction is **by field name** (the same `_secret`/`_url` rule as all output), applied when the line is emitted. Name the secret field — `info!(api_key_secret = %key)` — rather than logging a whole object by its `Debug`/string rendering, which hides the inner field names from redaction. For structured/nested secret-bearing data, build a value, apply redaction through output formatters or redacted_value(), then emit via the standard formatting helpers — do not pass the struct to a `?`/`%`-rendered log field.
 
@@ -340,7 +341,7 @@ Use this checklist when the skill is evaluating a change, not just documenting c
 3. Require secret-bearing values to be named with `_secret` or configured exact secret names before serialization. Do not rely on arbitrary free-text scanning or `Debug`/string-rendered objects.
 4. Run `afdata lint` for JSON/JSONL samples, JSON Schema, MCP schemas, or serialized outputs when available; run `afdata validate` for finite protocol events/streams. If unavailable, report the skipped check.
 5. Before changing an external project's public API, wire format, database schema, or persisted field names, report the compatibility impact and request approval before editing.
-6. Config size values use `_size` suffix (`buffer_size: "10MiB"`, not `buffer: "10MiB"`)
+6. Byte sizes use integer `_bytes` everywhere, config included (`buffer_bytes: 10485760`, never `buffer_size: "10MiB"`)
 7. Environment variables follow `UPPER_SNAKE_CASE` with the same suffixes
 8. One-time CLI output uses `json_log()`/`CliEmitter` + output helpers; long-running services use `afdata_tracing::try_init()` (Rust) to capture via tracing; other languages emit log events explicitly via builders
 9. Database columns use AFDATA suffixes on generic types (`duration_ms INTEGER`, not `duration INTEGER`); native types like `TIMESTAMPTZ` don't need suffixes

{agent_first_data-0.16.0 → agent_first_data-0.17.0}/agent_first_data/cli.py

@@ -168,14 +168,8 @@ class CliEmitter:
         # Apply log fields provider if this is a log event
         if kind == "log" and self._log_fields_provider is not None:
             provider_fields = self._log_fields_provider()
-            if provider_fields:
-                # Check for reserved fields from provider
-                log_payload = envelope.get("log", {})
-                for reserved in ("message", "level", "code"):
-                    if reserved in provider_fields:
-                        raise RuntimeError(
-                            f"log fields provider cannot write reserved field '{reserved}'"
-                        )
+            log_payload = envelope.get("log")
+            if provider_fields and isinstance(log_payload, dict):
                 # Merge provider fields, explicit fields take precedence
                 merged_log = dict(provider_fields)
                 merged_log.update(log_payload)
@@ -211,7 +205,7 @@ class CliEmitter:
         if not message or not isinstance(message, str):
             raise ValueError("message must be a non-empty string")
         # Use the builder to get default trace: {}
-        event = json_progress(message).build()
+        event = json_progress({"message": message}).build()
         self.emit(event)
 
     def emit_log(self, level: LogLevel | str, message: str) -> None:
@@ -220,7 +214,7 @@ class CliEmitter:
             level = LogLevel(level)
         if not message or not isinstance(message, str):
             raise ValueError("message must be a non-empty string")
-        event = json_log(level, message).build()
+        event = json_log({"level": level.value, "message": message}).build()
         self.emit(event)
 
 

{agent_first_data-0.16.0 → agent_first_data-0.17.0}/agent_first_data/format.py

@@ -2,7 +2,7 @@
 
 Protocol builders, value redactors (copy and in-place; cover _secret and
 _url fields), output formatters, URL-string redactors (redact_url_secrets),
-parse_size, normalize_utc_offset, is_valid_rfc3339_date,
+normalize_utc_offset, is_valid_rfc3339_date,
 is_valid_rfc3339_time, RedactionPolicy, OutputStyle, and
 OutputOptions. Each formatter/redactor concept is a single function taking
 a keyword-only ``options`` parameter.
@@ -183,50 +183,11 @@ class ErrorBuilder:
 class ProgressBuilder:
     """Fluent builder for progress events."""
 
-    def __init__(self, message: str) -> None:
-        self._message = message
+    def __init__(self, payload: Any) -> None:
+        self._payload = payload
         self._trace: dict = {}
-        self._fields: dict[str, Any] = {}
         self._errors: list[str] = []
 
-    def field(self, name: str, value: Any) -> ProgressBuilder:
-        """Add a single extension field."""
-        if name == "message":
-            self._errors.append(f"cannot override reserved field '{name}'")
-        else:
-            self._fields[name] = value
-        return self
-
-    def fields(self, mapping: Mapping[str, Any]) -> ProgressBuilder:
-        """Add multiple extension fields from a mapping."""
-        if not isinstance(mapping, Mapping):
-            self._errors.append("fields must be a mapping")
-        else:
-            for k, v in mapping.items():
-                if k == "message":
-                    self._errors.append(f"cannot override reserved field '{k}'")
-                else:
-                    self._fields[k] = v
-        return self
-
-    def extend(self, value: Any) -> ProgressBuilder:
-        """Add extension fields from a dataclass or mapping."""
-        if hasattr(value, "__dataclass_fields__"):
-            from dataclasses import asdict
-            mapping = asdict(value)
-        elif isinstance(value, Mapping):
-            mapping = value
-        else:
-            self._errors.append("extend() requires a dataclass or mapping")
-            return self
-
-        for k, v in mapping.items():
-            if k == "message":
-                self._errors.append(f"cannot override reserved field '{k}'")
-            else:
-                self._fields[k] = v
-        return self
-
     def trace(self, obj: Any) -> ProgressBuilder:
         """Set trace context."""
         if not isinstance(obj, dict):
@@ -239,11 +200,9 @@ class ProgressBuilder:
         """Build and return the Event, raising EventBuildError if there are errors."""
         if self._errors:
             raise EventBuildError("; ".join(self._errors))
-        progress = {"message": self._message}
-        progress.update(self._fields)
         envelope = {
             "kind": "progress",
-            "progress": progress,
+            "progress": self._payload,
             "trace": self._trace,
         }
         return Event(envelope)
@@ -252,53 +211,11 @@ class ProgressBuilder:
 class LogBuilder:
     """Fluent builder for log events."""
 
-    def __init__(self, level: LogLevel | str, message: str) -> None:
-        if isinstance(level, str):
-            level = LogLevel(level)
-        self._level = level
-        self._message = message
+    def __init__(self, payload: Any) -> None:
+        self._payload = payload
         self._trace: dict = {}
-        self._fields: dict[str, Any] = {}
         self._errors: list[str] = []
 
-    def field(self, name: str, value: Any) -> LogBuilder:
-        """Add a single extension field."""
-        if name in ("message", "level", "code"):
-            self._errors.append(f"cannot override reserved field '{name}'")
-        else:
-            self._fields[name] = value
-        return self
-
-    def fields(self, mapping: Mapping[str, Any]) -> LogBuilder:
-        """Add multiple extension fields from a mapping."""
-        if not isinstance(mapping, Mapping):
-            self._errors.append("fields must be a mapping")
-        else:
-            for k, v in mapping.items():
-                if k in ("message", "level", "code"):
-                    self._errors.append(f"cannot override reserved field '{k}'")
-                else:
-                    self._fields[k] = v
-        return self
-
-    def extend(self, value: Any) -> LogBuilder:
-        """Add extension fields from a dataclass or mapping."""
-        if hasattr(value, "__dataclass_fields__"):
-            from dataclasses import asdict
-            mapping = asdict(value)
-        elif isinstance(value, Mapping):
-            mapping = value
-        else:
-            self._errors.append("extend() requires a dataclass or mapping")
-            return self
-
-        for k, v in mapping.items():
-            if k in ("message", "level", "code"):
-                self._errors.append(f"cannot override reserved field '{k}'")
-            else:
-                self._fields[k] = v
-        return self
-
     def trace(self, obj: Any) -> LogBuilder:
         """Set trace context."""
         if not isinstance(obj, dict):
@@ -311,11 +228,9 @@ class LogBuilder:
         """Build and return the Event, raising EventBuildError if there are errors."""
         if self._errors:
             raise EventBuildError("; ".join(self._errors))
-        log = {"level": self._level.value, "message": self._message}
-        log.update(self._fields)
         envelope = {
             "kind": "log",
-            "log": log,
+            "log": self._payload,
             "trace": self._trace,
         }
         return Event(envelope)
@@ -331,23 +246,22 @@ def json_error(code: str, message: str) -> ErrorBuilder:
     return ErrorBuilder(code, message)
 
 
-def json_progress(message: str) -> ProgressBuilder:
+def json_progress(payload: Any) -> ProgressBuilder:
     """Create a fluent progress builder."""
-    return ProgressBuilder(message)
+    return ProgressBuilder(payload)
 
 
-def json_log(level: LogLevel | str, message: str) -> LogBuilder:
+def json_log(payload: Any) -> LogBuilder:
     """Create a fluent log builder."""
-    return LogBuilder(level, message)
+    return LogBuilder(payload)
 
 
 def validate_protocol_event(event: Any, *, strict: bool = True) -> None:
     """Validate one protocol v1 event envelope.
 
     With ``strict=True`` (the default), also enforces the recommended strict
-    protocol profile (required trace, required error.retryable, log/progress
-    message and level rules). Pass ``strict=False`` for the plain, lenient
-    envelope-shape check only.
+    protocol profile (required trace and required error.retryable). Pass
+    ``strict=False`` for the plain, lenient envelope-shape check only.
     """
     if not isinstance(event, dict):
         raise ValueError("event must be a JSON object")
@@ -370,10 +284,6 @@ def validate_protocol_event(event: Any, *, strict: bool = True) -> None:
         raise ValueError("event.trace is required by the strict profile")
     if kind == "error":
         _validate_strict_error_payload(event["error"])
-    elif kind == "log":
-        _validate_strict_log_payload(event["log"])
-    elif kind == "progress":
-        _validate_strict_progress_payload(event["progress"])
 
 
 def _validate_error_payload(error: Any) -> None:
@@ -426,26 +336,6 @@ def _validate_strict_error_payload(error: Any) -> None:
         raise ValueError("event.error.retryable must be a boolean in the strict profile")
 
 
-def _validate_strict_log_payload(log: Any) -> None:
-    if not isinstance(log, dict):
-        raise ValueError("event.log must be a JSON object in the strict profile")
-    if "code" in log:
-        raise ValueError("event.log must not contain 'code' field in the strict profile")
-    _require_non_empty_string(log, "message", "event.log")
-    if "level" not in log:
-        raise ValueError("event.log.level is required by the strict profile")
-    if log.get("level") not in ("debug", "info", "warn", "error"):
-        raise ValueError(
-            "event.log.level must be one of debug, info, warn, error in the strict profile"
-        )
-
-
-def _validate_strict_progress_payload(progress: Any) -> None:
-    if not isinstance(progress, dict):
-        raise ValueError("event.progress must be a JSON object in the strict profile")
-    _require_non_empty_string(progress, "message", "event.progress")
-
-
 def _require_non_empty_string(payload: dict, field: str, path: str) -> None:
     value = payload.get(field)
     if not isinstance(value, str) or value == "":
@@ -487,22 +377,17 @@ class DecodedError:
 
 @dataclass(frozen=True)
 class DecodedProgress:
-    """Decoded protocol v1 progress event. ``fields`` holds extension fields
-    beyond message."""
+    """Decoded protocol v1 progress event."""
 
-    message: str
-    fields: dict[str, Any] = field(default_factory=dict)
+    progress: Any
     trace: dict | None = None
 
 
 @dataclass(frozen=True)
 class DecodedLog:
-    """Decoded protocol v1 log event. ``fields`` holds extension fields
-    beyond level/message."""
+    """Decoded protocol v1 log event."""
 
-    level: LogLevel
-    message: str
-    fields: dict[str, Any] = field(default_factory=dict)
+    log: Any
     trace: dict | None = None
 
 
@@ -544,16 +429,10 @@ def decode_protocol_event(
         )
 
     if kind == "progress":
-        progress = event["progress"]
-        fields = {k: v for k, v in progress.items() if k != "message"}
-        return DecodedProgress(message=progress["message"], fields=fields, trace=trace)
+        return DecodedProgress(progress=event["progress"], trace=trace)
 
     # kind == "log"
-    log = event["log"]
-    fields = {k: v for k, v in log.items() if k not in ("level", "message")}
-    return DecodedLog(
-        level=LogLevel(log["level"]), message=log["message"], fields=fields, trace=trace
-    )
+    return DecodedLog(log=event["log"], trace=trace)
 
 
 # ═══════════════════════════════════════════
@@ -678,58 +557,6 @@ def _apply_redaction_policy_with_context(
     _redact_secrets(value, context)
 
 
-def parse_size(s: str) -> int | None:
-    """Parse a human-readable size string into bytes.
-
-    Accepts numbers followed by explicit units. Decimal units are
-    B/kB/MB/GB/TB; binary units are KiB/MiB/GiB/TiB. Trims whitespace and
-    rejects ambiguous K/M/G/T units.
-    """
-    _multipliers = {
-        "KiB": 1024,
-        "MiB": 1024**2,
-        "GiB": 1024**3,
-        "TiB": 1024**4,
-        "kB": 1000,
-        "MB": 1000**2,
-        "GB": 1000**3,
-        "TB": 1000**4,
-        "B": 1,
-    }
-    _max_safe_integer = (1 << 53) - 1
-    s = s.strip()
-    if not s:
-        return None
-    matched = next(((unit, mult) for unit, mult in _multipliers.items() if s.endswith(unit)), None)
-    if matched is None:
-        return None
-    unit, mult = matched
-    num_str = s[: -len(unit)]
-    if not num_str:
-        return None
-    if not re.fullmatch(r"(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?", num_str):
-        return None
-    try:
-        n = int(num_str)
-        if n < 0:
-            return None
-        if n > _max_safe_integer // mult:
-            return None
-        return n * mult
-    except ValueError:
-        pass
-    try:
-        f = float(num_str)
-        if f < 0 or not math.isfinite(f):
-            return None
-        result = f * mult
-        if not math.isfinite(result) or result > _max_safe_integer:
-            return None
-        return int(result)
-    except (ValueError, OverflowError):
-        return None
-
-
 def normalize_utc_offset(value: str) -> str | None:
     """Normalize a fixed UTC offset string to "UTC" or ±HH:MM.
 
@@ -784,6 +611,64 @@ def is_valid_rfc3339_time(value: str) -> bool:
     return value[8] == "." and len(value) > 9 and value[9:].isdigit()
 
 
+def is_valid_rfc3339(value: str) -> bool:
+    """Return true when value is a complete RFC 3339 date-time.
+
+    Composed from is_valid_rfc3339_date and is_valid_rfc3339_time: a full-date, a
+    T/t separator, a partial-time (with optional fractional seconds), and a
+    mandatory time-offset (Z/z or ±HH:MM with HH in 00..23 and MM in 00..59).
+    The offset is required, so a bare 2026-02-14T10:30:00 is rejected; a space
+    separator is rejected; and a leap second (:60) is rejected, matching
+    is_valid_rfc3339_time. Non-ASCII input is rejected.
+    """
+    if not isinstance(value, str) or len(value) < 20 or not value.isascii():
+        return False
+    if not is_valid_rfc3339_date(value[0:10]):
+        return False
+    if value[10] not in ("T", "t"):
+        return False
+    rest = value[11:]
+    if rest[-1] in ("Z", "z"):
+        partial = rest[:-1]
+    else:
+        if len(rest) < 6 or not _is_rfc3339_numoffset(rest[-6:]):
+            return False
+        partial = rest[:-6]
+    return is_valid_rfc3339_time(partial)
+
+
+def _is_rfc3339_numoffset(offset: str) -> bool:
+    if len(offset) != 6 or offset[0] not in ("+", "-") or offset[3] != ":":
+        return False
+    hours = _parse_ascii_int(offset[1:3])
+    minutes = _parse_ascii_int(offset[4:6])
+    if hours is None or minutes is None:
+        return False
+    return hours <= 23 and minutes <= 59
+
+
+def is_valid_bcp47(value: str) -> bool:
+    """Return true when value is a structurally well-formed BCP 47 language tag.
+
+    A grammar-level check, not a registry lookup: hyphen-separated ASCII-alphanumeric
+    subtags (each 1-8 chars) whose primary subtag is a 2-3 letter language code or the
+    x/i privateuse/grandfathered lead. Rejects the POSIX underscore form (zh_CN), empty
+    or misplaced hyphens, non-ASCII, and out-of-range primaries such as chinese. Does
+    not verify that subtags are registered with IANA.
+    """
+    if not isinstance(value, str) or not value:
+        return False
+    for index, subtag in enumerate(value.split("-")):
+        if not (1 <= len(subtag) <= 8) or not subtag.isascii() or not subtag.isalnum():
+            return False
+        if index == 0:
+            is_language = 2 <= len(subtag) <= 3 and subtag.isalpha()
+            is_special = subtag in ("x", "i")
+            if not is_language and not is_special:
+                return False
+    return True
+
+
 def _parse_utc_offset_body(body: str) -> tuple[int, int] | None:
     if not body:
         return None

{agent_first_data-0.16.0 → agent_first_data-0.17.0}/agent_first_data.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.16.0
+Version: 0.17.0
 Summary: A naming convention that lets AI agents understand your data without being told what it means.
 License-Expression: MIT
 Project-URL: Repository, https://github.com/agentfirstkit/agent-first-data
@@ -28,7 +28,7 @@ print(output_json(value))
 print(output_plain(value))
 ```
 
-Useful names use Python casing: `output_json`, `output_yaml`, `output_plain` (each takes an optional keyword-only `options=`), `redacted_value`, `redact_secrets_in_place`, `redact_url_secrets`, `parse_size`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `cli_parse_output`, `cli_output`, `build_cli_error`, `build_cli_version`, `cli_handle_version_or_continue`, `decode_protocol_event`. Skill admin and stream-redirect helpers live in `agent_first_data.skill` and `agent_first_data.stream_redirect` (import the submodule directly).
+Useful names use Python casing: `output_json`, `output_yaml`, `output_plain` (each takes an optional keyword-only `options=`), `redacted_value`, `redact_secrets_in_place`, `redact_url_secrets`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `cli_parse_output`, `cli_output`, `build_cli_error`, `build_cli_version`, `cli_handle_version_or_continue`, `decode_protocol_event`. Skill admin and stream-redirect helpers live in `agent_first_data.skill` and `agent_first_data.stream_redirect` (import the submodule directly).
 
 Logging is available through `init_logging_json`, `init_logging_plain`, `init_logging_yaml`, `span`, and `get_logger`.
 

{agent_first_data-0.16.0 → agent_first_data-0.17.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-first-data"
-version = "0.16.0"
+version = "0.17.0"
 description = "A naming convention that lets AI agents understand your data without being told what it means."
 license = "MIT"
 readme = "README.md"

{agent_first_data-0.16.0 → agent_first_data-0.17.0}/tests/test_cli.py

@@ -140,7 +140,7 @@ def test_cli_output_dispatches_raw_yaml_with_options():
 def test_cli_emitter_writes_events_and_tracks_terminal():
     writer = StringIO()
     emitter = CliEmitter(writer, OutputFormat.JSON)
-    emitter.emit(json_log(LogLevel.INFO, "startup").build())
+    emitter.emit(json_log({"level": "info", "message": "startup"}).build())
     emitter.emit(json_result({"rows": 2}).build())
     lines = writer.getvalue().splitlines()
     assert len(lines) == 2
@@ -150,7 +150,7 @@ def test_cli_emitter_writes_events_and_tracks_terminal():
 
 def test_cli_emitter_framing_all_formats():
     events = [
-        json_log(LogLevel.INFO, "startup").build(),
+        json_log({"level": "info", "message": "startup"}).build(),
         json_result({"rows": 2}).build(),
     ]
     for fmt in (OutputFormat.JSON, OutputFormat.PLAIN, OutputFormat.YAML):
@@ -238,13 +238,20 @@ def test_cli_emitter_convenience_methods():
 def test_cli_emitter_with_log_fields_provider():
     writer = StringIO()
     def log_fields():
-        return {"source": "test"}
+        return {
+            "source": "test",
+            "code": "cache_miss",
+            "message": "provider default",
+            "level": "debug",
+        }
     emitter = CliEmitter(writer, OutputFormat.JSON, log_fields=log_fields)
     emitter.emit_log(LogLevel.INFO, "test message")
     lines = writer.getvalue().splitlines()
     parsed = json.loads(lines[0])
     assert parsed["log"]["source"] == "test"
+    assert parsed["log"]["code"] == "cache_miss"
     assert parsed["log"]["message"] == "test message"
+    assert parsed["log"]["level"] == "info"
 
 
 # ── version helpers ───────────────────────────────────────────────────────────

{agent_first_data-0.16.0 → agent_first_data-0.17.0}/tests/test_format.py

@@ -28,12 +28,13 @@ from agent_first_data import (
     normalize_utc_offset,
     is_valid_rfc3339_date,
     is_valid_rfc3339_time,
+    is_valid_rfc3339,
+    is_valid_bcp47,
 )
 from agent_first_data.format import (
     _format_bytes_human,
     _format_with_commas,
     _extract_currency_code,
-    parse_size,
 )
 
 FIXTURES_DIR = os.path.join(os.path.dirname(__file__), "..", "..", "spec", "fixtures")
@@ -107,8 +108,8 @@ def _build_protocol_case_event(typ, args):
 
     args vocabulary: "result" (payload), "code"+"message" (error),
     "hint" (-> .hint()), "retryable" (bool -> .retryable_if()),
-    "fields" (object -> .fields()), "trace" (object -> .trace()),
-    "message" alone (progress), "level"+"message" (log).
+    "fields" (object -> .fields()), "trace" (object -> .trace()), and complete
+    progress/log payloads.
     """
     kind = typ.split("_", 1)[0]
 
@@ -121,13 +122,13 @@ def _build_protocol_case_event(typ, args):
         if "retryable" in args:
             builder = builder.retryable_if(args["retryable"])
     elif kind == "progress":
-        builder = json_progress(args["message"])
+        builder = json_progress({"message": args["message"], **args.get("fields", {})})
     elif kind == "log":
-        builder = json_log(LogLevel(args["level"]), args["message"])
+        builder = json_log({"level": args["level"], "message": args["message"], **args.get("fields", {})})
     else:
         raise ValueError(f"unknown fixture type: {typ}")
 
-    if "fields" in args:
+    if "fields" in args and kind not in ("progress", "log"):
         builder = builder.fields(args["fields"])
     if "trace" in args:
         builder = builder.trace(args["trace"])
@@ -205,9 +206,6 @@ def test_helper_fixtures():
             elif name == "extract_currency_code":
                 got = _extract_currency_code(inp)
                 assert got == expected, f"[helpers/{name}({inp!r})] got {got!r}"
-            elif name == "parse_size":
-                got = parse_size(inp)
-                assert got == expected, f"[helpers/{name}({inp!r})] got {got!r}"
             elif name == "normalize_utc_offset":
                 got = normalize_utc_offset(inp)
                 assert got == expected, f"[helpers/{name}({inp!r})] got {got!r}"
@@ -217,6 +215,12 @@ def test_helper_fixtures():
             elif name == "is_valid_rfc3339_time":
                 got = is_valid_rfc3339_time(inp)
                 assert got == expected, f"[helpers/{name}({inp!r})] got {got!r}"
+            elif name == "is_valid_bcp47":
+                got = is_valid_bcp47(inp)
+                assert got == expected, f"[helpers/{name}({inp!r})] got {got!r}"
+            elif name == "is_valid_rfc3339":
+                got = is_valid_rfc3339(inp)
+                assert got == expected, f"[helpers/{name}({inp!r})] got {got!r}"
 
 
 def test_output_format_fixtures():
@@ -388,21 +392,18 @@ def test_decode_protocol_event_error():
 
 
 def test_decode_protocol_event_progress():
-    event = json_progress("halfway").field("percent", 50).build()
+    event = json_progress({"message": "halfway", "percent": 50}).build()
     decoded = decode_protocol_event(output_json(event.to_dict()))
     assert isinstance(decoded, DecodedProgress)
-    assert decoded.message == "halfway"
-    assert decoded.fields == {"percent": 50}
+    assert decoded.progress == {"message": "halfway", "percent": 50}
     assert decoded.trace == {}
 
 
 def test_decode_protocol_event_log():
-    event = json_log(LogLevel.WARN, "slow query").field("duration_ms", 900).build()
+    event = json_log({"level": "warn", "message": "slow query", "duration_ms": 900}).build()
     decoded = decode_protocol_event(output_json(event.to_dict()))
     assert isinstance(decoded, DecodedLog)
-    assert decoded.level == LogLevel.WARN
-    assert decoded.message == "slow query"
-    assert decoded.fields == {"duration_ms": 900}
+    assert decoded.log == {"level": "warn", "message": "slow query", "duration_ms": 900}
     assert decoded.trace == {}