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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.16.0
+Version: 0.16.1
 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

{agent_first_data-0.16.0 → agent_first_data-0.16.1}/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.16.1}/agent_first_data/assets/skills/agent-first-data/references/rules.md

@@ -258,7 +258,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 +298,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.
 

{agent_first_data-0.16.0 → agent_first_data-0.16.1}/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.16.1}/agent_first_data/format.py

@@ -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)
 
 
 # ═══════════════════════════════════════════

{agent_first_data-0.16.0 → agent_first_data-0.16.1}/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.16.1
 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

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

@@ -1,6 +1,6 @@
 [project]
 name = "agent-first-data"
-version = "0.16.0"
+version = "0.16.1"
 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.16.1}/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.16.1}/tests/test_format.py

@@ -107,8 +107,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 +121,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"])
@@ -388,21 +388,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 == {}