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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.4.2
+Version: 0.5.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,11 +74,11 @@ 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)
@@ -91,7 +91,7 @@ build_json_error(message: str, trace: Any = None) -> dict
 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
@@ -128,14 +128,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 *

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

@@ -65,11 +65,11 @@ 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)
@@ -82,7 +82,7 @@ build_json_error(message: str, trace: Any = None) -> dict
 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
@@ -119,14 +119,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 *

{agent_first_data-0.4.2 → agent_first_data-0.5.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.5.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
 
 
@@ -45,16 +46,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 +75,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 +98,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 +151,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.5.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.5.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,11 +74,11 @@ 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)
@@ -91,7 +91,7 @@ build_json_error(message: str, trace: Any = None) -> dict
 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
@@ -128,14 +128,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 *

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

@@ -1,6 +1,6 @@
 [project]
 name = "agent-first-data"
-version = "0.4.2"
+version = "0.5.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.5.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.5.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,
@@ -83,3 +86,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"