agent-first-data 0.4.2__tar.gz → 0.6.0__tar.gz

{agent_first_data-0.4.2 → agent_first_data-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.4.2
+Version: 0.6.0
 Summary: Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates for AI agents
 License-Expression: MIT
 Project-URL: Repository, https://github.com/cmnspore/agent-first-data
@@ -74,24 +74,24 @@ Plain: args.input_path=/data/backup.tar.gz code=log event=startup config.max_fil
 
 ## API Reference
 
-Total: **12 public APIs and 1 type** + **AFDATA logging** (3 protocol builders + 3 output functions + 1 internal + 1 utility + 4 CLI helpers + `OutputFormat`)
+Total: **13 public APIs and 2 types** + **AFDATA logging** (3 protocol builders + 4 output functions + 1 internal + 1 utility + 4 CLI helpers + `OutputFormat` + `RedactionPolicy`)
 
 ### Protocol Builders (returns dict)
 
-Build AFDATA protocol structures. Return dict objects for API responses.
+Build AFDATA protocol structures. Return dict objects for transport payloads.
 
 ```python
 # Success (result)
 build_json_ok(result: Any, trace: Any = None) -> dict
 
-# Error (simple message)
-build_json_error(message: str, trace: Any = None) -> dict
+# Error (simple message, optional hint)
+build_json_error(message: str, hint: str = None, trace: Any = None) -> dict
 
 # Generic (any code + fields)
 build_json(code: str, fields: Any, trace: Any = None) -> dict
 ```
 
-**Use case:** API responses (frameworks like FastAPI automatically serialize)
+**Use case:** structured protocol payloads (frameworks automatically serialize)
 
 **Example:**
 ```python
@@ -118,6 +118,9 @@ response = build_json_ok(
 # Error
 err = build_json_error("user not found", trace={"duration_ms": 5})
 
+# Error with hint
+err_hint = build_json_error("wallet not found", hint="list wallets with: afpay wallet list", trace={"duration_ms": 5})
+
 # Specific error code
 not_found = build_json(
     "not_found",
@@ -128,14 +131,21 @@ not_found = build_json(
 
 ### CLI/Log Output (returns str)
 
-Format values for CLI output and logs. **All formats redact `_secret` fields.** YAML and Plain also strip suffixes from keys and format values for human readability.
+Format values for CLI output and logs. `output_json` uses full `_secret` redaction by default. `output_json_with` supports explicit scoped policies. YAML and Plain always redact `_secret` and apply human-readable formatting.
 
 ```python
 output_json(value: Any) -> str   # Single-line JSON, original keys, for programs/logs
+output_json_with(value: Any, redaction_policy: RedactionPolicy) -> str
 output_yaml(value: Any) -> str   # Multi-line YAML, keys stripped, values formatted
 output_plain(value: Any) -> str  # Single-line logfmt, keys stripped, values formatted
 ```
 
+```python
+class RedactionPolicy(enum.Enum):
+    RedactionTraceOnly = "RedactionTraceOnly"
+    RedactionNone = "RedactionNone"
+```
+
 **Example:**
 ```python
 from agent_first_data import *
@@ -197,7 +207,7 @@ class OutputFormat(enum.Enum):  # JSON="json", YAML="yaml", PLAIN="plain"
 cli_parse_output(s: str) -> OutputFormat         # Parse --output flag; raises ValueError on unknown
 cli_parse_log_filters(entries: list[str]) -> list[str]  # Normalize --log: trim, lowercase, dedup, remove empty
 cli_output(value: Any, format: OutputFormat) -> str     # Dispatch to output_json/yaml/plain
-build_cli_error(message: str) -> dict            # {code:"error", error_code:"invalid_request", retryable:False, trace:{duration_ms:0}}
+build_cli_error(message: str, hint: str = None) -> dict  # {code:"error", error_code:"invalid_request", hint?, retryable:False, trace:{duration_ms:0}}
 ```
 
 **Canonical pattern** — parse all flags before doing work, emit JSONL errors to stdout:

{agent_first_data-0.4.2 → agent_first_data-0.6.0}/README.md

@@ -65,24 +65,24 @@ Plain: args.input_path=/data/backup.tar.gz code=log event=startup config.max_fil
 
 ## API Reference
 
-Total: **12 public APIs and 1 type** + **AFDATA logging** (3 protocol builders + 3 output functions + 1 internal + 1 utility + 4 CLI helpers + `OutputFormat`)
+Total: **13 public APIs and 2 types** + **AFDATA logging** (3 protocol builders + 4 output functions + 1 internal + 1 utility + 4 CLI helpers + `OutputFormat` + `RedactionPolicy`)
 
 ### Protocol Builders (returns dict)
 
-Build AFDATA protocol structures. Return dict objects for API responses.
+Build AFDATA protocol structures. Return dict objects for transport payloads.
 
 ```python
 # Success (result)
 build_json_ok(result: Any, trace: Any = None) -> dict
 
-# Error (simple message)
-build_json_error(message: str, trace: Any = None) -> dict
+# Error (simple message, optional hint)
+build_json_error(message: str, hint: str = None, trace: Any = None) -> dict
 
 # Generic (any code + fields)
 build_json(code: str, fields: Any, trace: Any = None) -> dict
 ```
 
-**Use case:** API responses (frameworks like FastAPI automatically serialize)
+**Use case:** structured protocol payloads (frameworks automatically serialize)
 
 **Example:**
 ```python
@@ -109,6 +109,9 @@ response = build_json_ok(
 # Error
 err = build_json_error("user not found", trace={"duration_ms": 5})
 
+# Error with hint
+err_hint = build_json_error("wallet not found", hint="list wallets with: afpay wallet list", trace={"duration_ms": 5})
+
 # Specific error code
 not_found = build_json(
     "not_found",
@@ -119,14 +122,21 @@ not_found = build_json(
 
 ### CLI/Log Output (returns str)
 
-Format values for CLI output and logs. **All formats redact `_secret` fields.** YAML and Plain also strip suffixes from keys and format values for human readability.
+Format values for CLI output and logs. `output_json` uses full `_secret` redaction by default. `output_json_with` supports explicit scoped policies. YAML and Plain always redact `_secret` and apply human-readable formatting.
 
 ```python
 output_json(value: Any) -> str   # Single-line JSON, original keys, for programs/logs
+output_json_with(value: Any, redaction_policy: RedactionPolicy) -> str
 output_yaml(value: Any) -> str   # Multi-line YAML, keys stripped, values formatted
 output_plain(value: Any) -> str  # Single-line logfmt, keys stripped, values formatted
 ```
 
+```python
+class RedactionPolicy(enum.Enum):
+    RedactionTraceOnly = "RedactionTraceOnly"
+    RedactionNone = "RedactionNone"
+```
+
 **Example:**
 ```python
 from agent_first_data import *
@@ -188,7 +198,7 @@ class OutputFormat(enum.Enum):  # JSON="json", YAML="yaml", PLAIN="plain"
 cli_parse_output(s: str) -> OutputFormat         # Parse --output flag; raises ValueError on unknown
 cli_parse_log_filters(entries: list[str]) -> list[str]  # Normalize --log: trim, lowercase, dedup, remove empty
 cli_output(value: Any, format: OutputFormat) -> str     # Dispatch to output_json/yaml/plain
-build_cli_error(message: str) -> dict            # {code:"error", error_code:"invalid_request", retryable:False, trace:{duration_ms:0}}
+build_cli_error(message: str, hint: str = None) -> dict  # {code:"error", error_code:"invalid_request", hint?, retryable:False, trace:{duration_ms:0}}
 ```
 
 **Canonical pattern** — parse all flags before doing work, emit JSONL errors to stdout:

{agent_first_data-0.4.2 → agent_first_data-0.6.0}/agent_first_data/__init__.py

@@ -4,7 +4,9 @@ from agent_first_data.format import (
     build_json_ok,
     build_json_error,
     build_json,
+    RedactionPolicy,
     output_json,
+    output_json_with,
     output_yaml,
     output_plain,
     internal_redact_secrets,
@@ -33,7 +35,9 @@ __all__ = [
     "build_json_ok",
     "build_json_error",
     "build_json",
+    "RedactionPolicy",
     "output_json",
+    "output_json_with",
     "output_yaml",
     "output_plain",
     "internal_redact_secrets",

{agent_first_data-0.4.2 → agent_first_data-0.6.0}/agent_first_data/cli.py

@@ -69,7 +69,7 @@ def cli_output(value: Any, format: OutputFormat) -> str:
     return output_json(value)
 
 
-def build_cli_error(message: str) -> dict:
+def build_cli_error(message: str, hint: str | None = None) -> dict:
     """Build a standard CLI parse error value.
 
     Use when argument parsing fails or a flag value is invalid.
@@ -83,10 +83,13 @@ def build_cli_error(message: str) -> dict:
     >>> v["retryable"]
     False
     """
-    return {
+    m: dict = {
         "code": "error",
         "error_code": "invalid_request",
         "error": message,
         "retryable": False,
         "trace": {"duration_ms": 0},
     }
+    if hint is not None:
+        m["hint"] = hint
+    return m

{agent_first_data-0.4.2 → agent_first_data-0.6.0}/agent_first_data/format.py

@@ -1,13 +1,14 @@
 """AFDATA output formatting and protocol templates.
 
-8 public APIs: 3 protocol builders + 3 output formatters + 1 redaction + 1 utility.
+9 public APIs and 1 type: 3 protocol builders + 4 output formatters + 1 redaction + 1 utility + RedactionPolicy.
 """
 
 from __future__ import annotations
 
-import copy
 import json
+import math
 from datetime import datetime, timezone
+from enum import Enum
 from typing import Any
 
 
@@ -24,9 +25,11 @@ def build_json_ok(result: Any, trace: Any = None) -> dict:
     return m
 
 
-def build_json_error(message: str, trace: Any = None) -> dict:
-    """Build {code: "error", error: message, trace?}."""
+def build_json_error(message: str, hint: str | None = None, trace: Any = None) -> dict:
+    """Build {code: "error", error: message, hint?, trace?}."""
     m: dict = {"code": "error", "error": message}
+    if hint is not None:
+        m["hint"] = hint
     if trace is not None:
         m["trace"] = trace
     return m
@@ -45,16 +48,28 @@ def build_json(code: str, fields: Any, trace: Any = None) -> dict:
 # Public API: Output Formatters
 # ═══════════════════════════════════════════
 
+class RedactionPolicy(str, Enum):
+    RedactionTraceOnly = "RedactionTraceOnly"
+    RedactionNone = "RedactionNone"
+
 
 def output_json(value: Any) -> str:
     """Format as single-line JSON. Secrets redacted, original keys, raw values."""
-    v = copy.deepcopy(value)
+    v = _sanitize_for_json(value)
     _redact_secrets(v)
     return json.dumps(v, ensure_ascii=False, separators=(",", ":"))
 
 
+def output_json_with(value: Any, redaction_policy: RedactionPolicy) -> str:
+    """Format as single-line JSON with explicit redaction policy."""
+    v = _sanitize_for_json(value)
+    _apply_redaction_policy(v, redaction_policy)
+    return json.dumps(v, ensure_ascii=False, separators=(",", ":"))
+
+
 def output_yaml(value: Any) -> str:
     """Format as multi-line YAML. Keys stripped, values formatted, secrets redacted."""
+    value = _sanitize_for_json(value)
     lines = ["---"]
     _render_yaml_processed(value, 0, lines)
     return "\n".join(lines)
@@ -62,6 +77,7 @@ def output_yaml(value: Any) -> str:
 
 def output_plain(value: Any) -> str:
     """Format as single-line logfmt. Keys stripped, values formatted, secrets redacted."""
+    value = _sanitize_for_json(value)
     pairs: list[tuple[str, str]] = []
     _collect_plain_pairs(value, "", pairs)
     pairs.sort(key=lambda p: p[0].encode("utf-16-be"))
@@ -84,6 +100,17 @@ def internal_redact_secrets(value: Any) -> None:
     _redact_secrets(value)
 
 
+def _apply_redaction_policy(value: Any, redaction_policy: RedactionPolicy) -> None:
+    if redaction_policy == RedactionPolicy.RedactionTraceOnly:
+        if isinstance(value, dict) and "trace" in value:
+            _redact_secrets(value["trace"])
+        return
+    if redaction_policy == RedactionPolicy.RedactionNone:
+        return
+    # Safety fallback for unknown values.
+    _redact_secrets(value)
+
+
 def parse_size(s: str) -> int | None:
     """Parse a human-readable size string into bytes.
 
@@ -126,6 +153,43 @@ def parse_size(s: str) -> int | None:
 # ═══════════════════════════════════════════
 
 
+def _sanitize_for_json(value: Any, stack: set[int] | None = None) -> Any:
+    if stack is None:
+        stack = set()
+
+    if value is None or isinstance(value, (str, bool, int)):
+        return value
+    if isinstance(value, float):
+        if math.isfinite(value):
+            return value
+        return "<unsupported:float>"
+    if isinstance(value, BaseException):
+        return str(value)
+
+    if isinstance(value, dict):
+        obj_id = id(value)
+        if obj_id in stack:
+            return "<unsupported:circular>"
+        stack.add(obj_id)
+        out: dict[str, Any] = {}
+        for k, v in value.items():
+            key = k if isinstance(k, str) else str(k)
+            out[key] = _sanitize_for_json(v, stack)
+        stack.remove(obj_id)
+        return out
+
+    if isinstance(value, (list, tuple)):
+        obj_id = id(value)
+        if obj_id in stack:
+            return "<unsupported:circular>"
+        stack.add(obj_id)
+        out = [_sanitize_for_json(item, stack) for item in value]
+        stack.remove(obj_id)
+        return out
+
+    return f"<unsupported:{type(value).__name__}>"
+
+
 def _redact_secrets(value: Any) -> None:
     if isinstance(value, dict):
         for k in list(value.keys()):

{agent_first_data-0.4.2 → agent_first_data-0.6.0}/agent_first_data.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.4.2
+Version: 0.6.0
 Summary: Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates for AI agents
 License-Expression: MIT
 Project-URL: Repository, https://github.com/cmnspore/agent-first-data
@@ -74,24 +74,24 @@ Plain: args.input_path=/data/backup.tar.gz code=log event=startup config.max_fil
 
 ## API Reference
 
-Total: **12 public APIs and 1 type** + **AFDATA logging** (3 protocol builders + 3 output functions + 1 internal + 1 utility + 4 CLI helpers + `OutputFormat`)
+Total: **13 public APIs and 2 types** + **AFDATA logging** (3 protocol builders + 4 output functions + 1 internal + 1 utility + 4 CLI helpers + `OutputFormat` + `RedactionPolicy`)
 
 ### Protocol Builders (returns dict)
 
-Build AFDATA protocol structures. Return dict objects for API responses.
+Build AFDATA protocol structures. Return dict objects for transport payloads.
 
 ```python
 # Success (result)
 build_json_ok(result: Any, trace: Any = None) -> dict
 
-# Error (simple message)
-build_json_error(message: str, trace: Any = None) -> dict
+# Error (simple message, optional hint)
+build_json_error(message: str, hint: str = None, trace: Any = None) -> dict
 
 # Generic (any code + fields)
 build_json(code: str, fields: Any, trace: Any = None) -> dict
 ```
 
-**Use case:** API responses (frameworks like FastAPI automatically serialize)
+**Use case:** structured protocol payloads (frameworks automatically serialize)
 
 **Example:**
 ```python
@@ -118,6 +118,9 @@ response = build_json_ok(
 # Error
 err = build_json_error("user not found", trace={"duration_ms": 5})
 
+# Error with hint
+err_hint = build_json_error("wallet not found", hint="list wallets with: afpay wallet list", trace={"duration_ms": 5})
+
 # Specific error code
 not_found = build_json(
     "not_found",
@@ -128,14 +131,21 @@ not_found = build_json(
 
 ### CLI/Log Output (returns str)
 
-Format values for CLI output and logs. **All formats redact `_secret` fields.** YAML and Plain also strip suffixes from keys and format values for human readability.
+Format values for CLI output and logs. `output_json` uses full `_secret` redaction by default. `output_json_with` supports explicit scoped policies. YAML and Plain always redact `_secret` and apply human-readable formatting.
 
 ```python
 output_json(value: Any) -> str   # Single-line JSON, original keys, for programs/logs
+output_json_with(value: Any, redaction_policy: RedactionPolicy) -> str
 output_yaml(value: Any) -> str   # Multi-line YAML, keys stripped, values formatted
 output_plain(value: Any) -> str  # Single-line logfmt, keys stripped, values formatted
 ```
 
+```python
+class RedactionPolicy(enum.Enum):
+    RedactionTraceOnly = "RedactionTraceOnly"
+    RedactionNone = "RedactionNone"
+```
+
 **Example:**
 ```python
 from agent_first_data import *
@@ -197,7 +207,7 @@ class OutputFormat(enum.Enum):  # JSON="json", YAML="yaml", PLAIN="plain"
 cli_parse_output(s: str) -> OutputFormat         # Parse --output flag; raises ValueError on unknown
 cli_parse_log_filters(entries: list[str]) -> list[str]  # Normalize --log: trim, lowercase, dedup, remove empty
 cli_output(value: Any, format: OutputFormat) -> str     # Dispatch to output_json/yaml/plain
-build_cli_error(message: str) -> dict            # {code:"error", error_code:"invalid_request", retryable:False, trace:{duration_ms:0}}
+build_cli_error(message: str, hint: str = None) -> dict  # {code:"error", error_code:"invalid_request", hint?, retryable:False, trace:{duration_ms:0}}
 ```
 
 **Canonical pattern** — parse all flags before doing work, emit JSONL errors to stdout:

{agent_first_data-0.4.2 → agent_first_data-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-first-data"
-version = "0.4.2"
+version = "0.6.0"
 description = "Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates for AI agents"
 license = "MIT"
 readme = "README.md"

{agent_first_data-0.4.2 → agent_first_data-0.6.0}/tests/test_afdata_logging.py

@@ -112,6 +112,12 @@ class TestCodeOverride:
         assert m["code"] == "log"
         assert m["event"] == "startup"
 
+    def test_exception_field_is_readable(self):
+        logger = make_logger("test_exc")
+        adapter = get_logger("test_exc")
+        m = capture_log(lambda: adapter.error("request failed", extra={"error": Exception("timeout")}))
+        assert m["error"] == "timeout"
+
 
 class TestGetLogger:
     def test_default_fields(self):

{agent_first_data-0.4.2 → agent_first_data-0.6.0}/tests/test_cli.py

@@ -75,6 +75,16 @@ def test_build_cli_error_is_valid_json():
     assert parsed["code"] == "error"
 
 
+def test_build_cli_error_with_hint():
+    v = build_cli_error("bad flag", hint="try --help")
+    assert v["hint"] == "try --help"
+
+
+def test_build_cli_error_without_hint_has_no_hint_key():
+    v = build_cli_error("oops")
+    assert "hint" not in v
+
+
 # ── cli_output ────────────────────────────────────────────────────────────────
 
 def test_cli_output_dispatches_json():

{agent_first_data-0.4.2 → agent_first_data-0.6.0}/tests/test_format.py

@@ -7,7 +7,10 @@ from agent_first_data import (
     build_json_ok,
     build_json_error,
     build_json,
+    RedactionPolicy,
     internal_redact_secrets,
+    output_json,
+    output_json_with,
 )
 from agent_first_data.format import (
     _format_bytes_human,
@@ -50,7 +53,11 @@ def test_protocol_fixtures():
         elif typ == "error":
             result = build_json_error(args["message"])
         elif typ == "error_trace":
-            result = build_json_error(args["message"], args["trace"])
+            result = build_json_error(args["message"], trace=args["trace"])
+        elif typ == "error_hint":
+            result = build_json_error(args["message"], hint=args.get("hint"))
+        elif typ == "error_hint_trace":
+            result = build_json_error(args["message"], hint=args.get("hint"), trace=args["trace"])
         elif typ == "status":
             result = build_json(args["code"], args.get("fields"))
         else:
@@ -83,3 +90,52 @@ def test_helper_fixtures():
             elif name == "parse_size":
                 got = parse_size(inp)
                 assert got == expected, f"[helpers/{name}({inp!r})] got {got!r}"
+
+
+def test_output_json_exception_field_is_readable():
+    out = output_json({"error": Exception("timeout")})
+    parsed = json.loads(out)
+    assert parsed["error"] == "timeout"
+
+
+def test_output_json_unsupported_value_does_not_leak_secret():
+    class SecretRepr:
+        def __repr__(self) -> str:
+            return "Secret(sk-live-123)"
+
+    out = output_json({"meta": SecretRepr(), "api_key_secret": "sk-live-123"})
+    assert "sk-live-123" not in out
+    parsed = json.loads(out)
+    assert parsed["api_key_secret"] == "***"
+    assert parsed["meta"].startswith("<unsupported:")
+
+
+def test_output_json_circular_reference():
+    v = {}
+    v["self"] = v
+    out = output_json(v)
+    parsed = json.loads(out)
+    assert parsed["self"] == "<unsupported:circular>"
+
+
+def test_output_json_with_trace_only_redacts_only_trace():
+    out = output_json_with(
+        {
+            "code": "ok",
+            "result": {"api_key_secret": "sk-live-123"},
+            "trace": {"request_secret": "top-secret"},
+        },
+        RedactionPolicy.RedactionTraceOnly,
+    )
+    parsed = json.loads(out)
+    assert parsed["trace"]["request_secret"] == "***"
+    assert parsed["result"]["api_key_secret"] == "sk-live-123"
+
+
+def test_output_json_with_none_keeps_secrets():
+    out = output_json_with(
+        {"api_key_secret": "sk-live-123"},
+        RedactionPolicy.RedactionNone,
+    )
+    parsed = json.loads(out)
+    assert parsed["api_key_secret"] == "sk-live-123"