agent-first-data 0.8.0__tar.gz → 0.9.0__tar.gz

{agent_first_data-0.8.0/agent_first_data.egg-info → agent_first_data-0.9.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.8.0
-Summary: Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates for AI agents
+Version: 0.9.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
 Requires-Python: >=3.9
@@ -74,7 +74,7 @@ Plain: args.input_path=/data/backup.tar.gz code=log event=startup config.max_fil
 
 ## API Reference
 
-Total: **15 public APIs and 2 types** + **AFDATA logging** (3 protocol builders + 2 redacted value helpers + 4 output functions + 1 internal + 1 utility + 4 CLI helpers + `OutputFormat` + `RedactionPolicy`)
+Public APIs are grouped by role: protocol builders, redaction helpers, output formatters, internal redaction tools, utility/CLI helpers, types, and AFDATA logging integration.
 
 ### Protocol Builders (returns dict)
 
@@ -91,13 +91,14 @@ build_json_error(message: str, hint: str = None, trace: Any = None) -> dict
 build_json(code: str, fields: Any, trace: Any = None) -> dict
 ```
 
-### Redacted Values (returns Any)
+### Redaction Helpers (returns Any)
 
 Use these before raw HTTP/MCP/SSE serializers that do not call `output_json`.
 
 ```python
 redacted_value(value: Any) -> Any
 redacted_value_with(value: Any, redaction_policy: RedactionPolicy) -> Any
+redacted_value_with_options(value: Any, redaction_options: RedactionOptions) -> Any
 ```
 
 **Use case:** structured protocol payloads (frameworks automatically serialize)
@@ -138,15 +139,18 @@ not_found = build_json(
 )
 ```
 
-### CLI/Log Output (returns str)
+### Output Formatters (returns str)
 
-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.
+Format values for CLI output and logs. `output_json` uses full `_secret` redaction by default. `output_json_with` supports explicit scoped policies. Use `OutputOptions` to pass legacy secret names such as `api_key` or request schema-preserving YAML/plain rendering with `OutputStyle.Raw`.
 
 ```python
 output_json(value: Any) -> str   # Single-line JSON, original keys, for programs/logs
 output_json_with(value: Any, redaction_policy: RedactionPolicy) -> str
+output_json_with_options(value: Any, output_options: OutputOptions) -> str
 output_yaml(value: Any) -> str   # Multi-line YAML, keys stripped, values formatted
+output_yaml_with_options(value: Any, output_options: OutputOptions) -> str
 output_plain(value: Any) -> str  # Single-line logfmt, keys stripped, values formatted
+output_plain_with_options(value: Any, output_options: OutputOptions) -> str
 ```
 
 ```python
@@ -154,8 +158,18 @@ class RedactionPolicy(enum.Enum):
     RedactionTraceOnly = "RedactionTraceOnly"
     RedactionNone = "RedactionNone"
     RedactionStrict = "RedactionStrict"
+
+RedactionOptions(policy: RedactionPolicy | None = None, secret_names: Sequence[str] = ())
+
+class OutputStyle(enum.Enum):
+    Readable = "Readable"
+    Raw = "Raw"
+
+OutputOptions(redaction: RedactionOptions = RedactionOptions(), style: OutputStyle = OutputStyle.Readable)
 ```
 
+Secret names match exact field names at any nesting level; there is no trim, case folding, hyphen/underscore normalization, glob, regex, or substring matching. `OutputOptions` combines `RedactionOptions` with `OutputStyle.Readable` (default suffix stripping and value formatting) or `OutputStyle.Raw` (no suffix stripping or value formatting).
+
 **Example:**
 ```python
 from agent_first_data import *
@@ -188,6 +202,7 @@ print(output_plain(data))
 
 ```python
 internal_redact_secrets(value: Any) -> None  # Manually redact secrets in-place
+internal_redact_secrets_with_options(value: Any, redaction_options: RedactionOptions) -> None
 ```
 
 Most users don't need this. Output functions automatically protect secrets.
@@ -219,6 +234,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
+cli_output_with_options(value: Any, format: OutputFormat, output_options: OutputOptions) -> str
 build_cli_error(message: str, hint: str = None) -> dict  # {code:"error", error_code:"invalid_request", hint?, retryable:False, trace:{duration_ms:0}}
 ```
 

agent_first_data-0.8.0/PKG-INFO → agent_first_data-0.9.0/README.md

@@ -1,12 +1,3 @@
-Metadata-Version: 2.4
-Name: agent-first-data
-Version: 0.8.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/agentfirstkit/agent-first-data
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-
 # agent-first-data
 
 **Agent-First Data (AFDATA)** — Suffix-driven output formatting and protocol templates for AI agents.
@@ -74,7 +65,7 @@ Plain: args.input_path=/data/backup.tar.gz code=log event=startup config.max_fil
 
 ## API Reference
 
-Total: **15 public APIs and 2 types** + **AFDATA logging** (3 protocol builders + 2 redacted value helpers + 4 output functions + 1 internal + 1 utility + 4 CLI helpers + `OutputFormat` + `RedactionPolicy`)
+Public APIs are grouped by role: protocol builders, redaction helpers, output formatters, internal redaction tools, utility/CLI helpers, types, and AFDATA logging integration.
 
 ### Protocol Builders (returns dict)
 
@@ -91,13 +82,14 @@ build_json_error(message: str, hint: str = None, trace: Any = None) -> dict
 build_json(code: str, fields: Any, trace: Any = None) -> dict
 ```
 
-### Redacted Values (returns Any)
+### Redaction Helpers (returns Any)
 
 Use these before raw HTTP/MCP/SSE serializers that do not call `output_json`.
 
 ```python
 redacted_value(value: Any) -> Any
 redacted_value_with(value: Any, redaction_policy: RedactionPolicy) -> Any
+redacted_value_with_options(value: Any, redaction_options: RedactionOptions) -> Any
 ```
 
 **Use case:** structured protocol payloads (frameworks automatically serialize)
@@ -138,15 +130,18 @@ not_found = build_json(
 )
 ```
 
-### CLI/Log Output (returns str)
+### Output Formatters (returns str)
 
-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.
+Format values for CLI output and logs. `output_json` uses full `_secret` redaction by default. `output_json_with` supports explicit scoped policies. Use `OutputOptions` to pass legacy secret names such as `api_key` or request schema-preserving YAML/plain rendering with `OutputStyle.Raw`.
 
 ```python
 output_json(value: Any) -> str   # Single-line JSON, original keys, for programs/logs
 output_json_with(value: Any, redaction_policy: RedactionPolicy) -> str
+output_json_with_options(value: Any, output_options: OutputOptions) -> str
 output_yaml(value: Any) -> str   # Multi-line YAML, keys stripped, values formatted
+output_yaml_with_options(value: Any, output_options: OutputOptions) -> str
 output_plain(value: Any) -> str  # Single-line logfmt, keys stripped, values formatted
+output_plain_with_options(value: Any, output_options: OutputOptions) -> str
 ```
 
 ```python
@@ -154,8 +149,18 @@ class RedactionPolicy(enum.Enum):
     RedactionTraceOnly = "RedactionTraceOnly"
     RedactionNone = "RedactionNone"
     RedactionStrict = "RedactionStrict"
+
+RedactionOptions(policy: RedactionPolicy | None = None, secret_names: Sequence[str] = ())
+
+class OutputStyle(enum.Enum):
+    Readable = "Readable"
+    Raw = "Raw"
+
+OutputOptions(redaction: RedactionOptions = RedactionOptions(), style: OutputStyle = OutputStyle.Readable)
 ```
 
+Secret names match exact field names at any nesting level; there is no trim, case folding, hyphen/underscore normalization, glob, regex, or substring matching. `OutputOptions` combines `RedactionOptions` with `OutputStyle.Readable` (default suffix stripping and value formatting) or `OutputStyle.Raw` (no suffix stripping or value formatting).
+
 **Example:**
 ```python
 from agent_first_data import *
@@ -188,6 +193,7 @@ print(output_plain(data))
 
 ```python
 internal_redact_secrets(value: Any) -> None  # Manually redact secrets in-place
+internal_redact_secrets_with_options(value: Any, redaction_options: RedactionOptions) -> None
 ```
 
 Most users don't need this. Output functions automatically protect secrets.
@@ -219,6 +225,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
+cli_output_with_options(value: Any, format: OutputFormat, output_options: OutputOptions) -> str
 build_cli_error(message: str, hint: str = None) -> dict  # {code:"error", error_code:"invalid_request", hint?, retryable:False, trace:{duration_ms:0}}
 ```
 

{agent_first_data-0.8.0 → agent_first_data-0.9.0}/agent_first_data/__init__.py

@@ -5,13 +5,21 @@ from agent_first_data.format import (
     build_json_error,
     build_json,
     RedactionPolicy,
+    RedactionOptions,
+    OutputStyle,
+    OutputOptions,
     output_json,
     output_json_with,
+    output_json_with_options,
     output_yaml,
+    output_yaml_with_options,
     output_plain,
+    output_plain_with_options,
     internal_redact_secrets,
+    internal_redact_secrets_with_options,
     redacted_value,
     redacted_value_with,
+    redacted_value_with_options,
     parse_size,
 )
 
@@ -30,6 +38,7 @@ from agent_first_data.cli import (
     cli_parse_output,
     cli_parse_log_filters,
     cli_output,
+    cli_output_with_options,
     build_cli_error,
 )
 
@@ -38,13 +47,21 @@ __all__ = [
     "build_json_error",
     "build_json",
     "RedactionPolicy",
+    "RedactionOptions",
+    "OutputStyle",
+    "OutputOptions",
     "output_json",
     "output_json_with",
+    "output_json_with_options",
     "output_yaml",
+    "output_yaml_with_options",
     "output_plain",
+    "output_plain_with_options",
     "internal_redact_secrets",
+    "internal_redact_secrets_with_options",
     "redacted_value",
     "redacted_value_with",
+    "redacted_value_with_options",
     "parse_size",
     "AfdataHandler",
     "AfdataJsonHandler",
@@ -57,5 +74,6 @@ __all__ = [
     "cli_parse_output",
     "cli_parse_log_filters",
     "cli_output",
+    "cli_output_with_options",
     "build_cli_error",
 ]

{agent_first_data-0.8.0 → agent_first_data-0.9.0}/agent_first_data/cli.py

@@ -5,7 +5,15 @@ from __future__ import annotations
 import enum
 from typing import Any
 
-from agent_first_data.format import output_json, output_yaml, output_plain
+from agent_first_data.format import (
+    OutputOptions,
+    output_json,
+    output_json_with_options,
+    output_yaml,
+    output_yaml_with_options,
+    output_plain,
+    output_plain_with_options,
+)
 
 
 class OutputFormat(enum.Enum):
@@ -69,6 +77,22 @@ def cli_output(value: Any, format: OutputFormat) -> str:
     return output_json(value)
 
 
+def cli_output_with_options(
+    value: Any,
+    format: OutputFormat,
+    output_options: OutputOptions,
+) -> str:
+    """Dispatch output formatting with explicit redaction and style.
+
+    JSON ignores OutputStyle and preserves original keys and values after redaction.
+    """
+    if format is OutputFormat.YAML:
+        return output_yaml_with_options(value, output_options)
+    if format is OutputFormat.PLAIN:
+        return output_plain_with_options(value, output_options)
+    return output_json_with_options(value, output_options)
+
+
 def build_cli_error(message: str, hint: str | None = None) -> dict:
     """Build a standard CLI parse error value.
 

{agent_first_data-0.8.0 → agent_first_data-0.9.0}/agent_first_data/format.py

@@ -1,16 +1,18 @@
 """AFDATA output formatting and protocol templates.
 
-11 public APIs and 1 type: protocol builders, redacted value helpers,
-output formatters, redaction, parse_size, and RedactionPolicy.
+16 public APIs and 4 types: protocol builders, redacted value helpers,
+output formatters, redaction, parse_size, RedactionPolicy, RedactionOptions,
+OutputStyle, and OutputOptions.
 """
 
 from __future__ import annotations
 
 import json
 import math
+from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from enum import Enum
-from typing import Any
+from typing import Any, Sequence
 
 
 # ═══════════════════════════════════════════
@@ -55,6 +57,30 @@ class RedactionPolicy(str, Enum):
     RedactionStrict = "RedactionStrict"
 
 
+@dataclass(frozen=True)
+class RedactionOptions:
+    """Redaction options for legacy secret field names."""
+
+    policy: RedactionPolicy | None = None
+    # Exact field-name matches at any nesting level.
+    secret_names: Sequence[str] = ()
+
+
+class OutputStyle(str, Enum):
+    """Rendering style for YAML and plain output."""
+
+    Readable = "Readable"
+    Raw = "Raw"
+
+
+@dataclass(frozen=True)
+class OutputOptions:
+    """Output options combining redaction and rendering style."""
+
+    redaction: RedactionOptions = field(default_factory=RedactionOptions)
+    style: OutputStyle = OutputStyle.Readable
+
+
 def output_json(value: Any) -> str:
     """Format as single-line JSON. Secrets redacted, original keys, raw values."""
     return json.dumps(redacted_value(value), ensure_ascii=False, separators=(",", ":"))
@@ -65,19 +91,44 @@ def output_json_with(value: Any, redaction_policy: RedactionPolicy) -> str:
     return json.dumps(redacted_value_with(value, redaction_policy), ensure_ascii=False, separators=(",", ":"))
 
 
+def output_json_with_options(value: Any, output_options: OutputOptions) -> str:
+    """Format as single-line JSON with explicit output options."""
+    return json.dumps(
+        redacted_value_with_options(value, output_options.redaction),
+        ensure_ascii=False,
+        separators=(",", ":"),
+    )
+
+
 def output_yaml(value: Any) -> str:
     """Format as multi-line YAML. Keys stripped, values formatted, secrets redacted."""
-    value = redacted_value(value)
+    return output_yaml_with_options(value, OutputOptions())
+
+
+def output_yaml_with_options(value: Any, output_options: OutputOptions) -> str:
+    """Format as multi-line YAML with explicit output options."""
+    value = redacted_value_with_options(value, output_options.redaction)
     lines = ["---"]
-    _render_yaml_processed(value, 0, lines)
+    if output_options.style is OutputStyle.Raw:
+        _render_yaml_raw(value, 0, lines)
+    else:
+        _render_yaml_processed(value, 0, lines)
     return "\n".join(lines)
 
 
 def output_plain(value: Any) -> str:
     """Format as single-line logfmt. Keys stripped, values formatted, secrets redacted."""
-    value = redacted_value(value)
+    return output_plain_with_options(value, OutputOptions())
+
+
+def output_plain_with_options(value: Any, output_options: OutputOptions) -> str:
+    """Format as single-line logfmt with explicit output options."""
+    value = redacted_value_with_options(value, output_options.redaction)
     pairs: list[tuple[str, str]] = []
-    _collect_plain_pairs(value, "", pairs)
+    if output_options.style is OutputStyle.Raw:
+        _collect_plain_pairs_raw(value, "", pairs)
+    else:
+        _collect_plain_pairs(value, "", pairs)
     pairs.sort(key=lambda p: p[0].encode("utf-16-be"))
     parts = []
     for k, v in pairs:
@@ -95,6 +146,11 @@ def internal_redact_secrets(value: Any) -> None:
     _redact_secrets(value)
 
 
+def internal_redact_secrets_with_options(value: Any, redaction_options: RedactionOptions) -> None:
+    """Redact secret fields in-place using explicit redaction options."""
+    _apply_redaction_options(value, redaction_options)
+
+
 def redacted_value(value: Any) -> Any:
     """Return a JSON-safe copy with default _secret redaction applied."""
     v = _sanitize_for_json(value)
@@ -109,18 +165,38 @@ def redacted_value_with(value: Any, redaction_policy: RedactionPolicy) -> Any:
     return v
 
 
+def redacted_value_with_options(value: Any, redaction_options: RedactionOptions) -> Any:
+    """Return a JSON-safe copy with explicit redaction options applied."""
+    v = _sanitize_for_json(value)
+    _apply_redaction_options(v, redaction_options)
+    return v
+
+
 def _apply_redaction_policy(value: Any, redaction_policy: RedactionPolicy) -> None:
+    _apply_redaction_policy_with_names(value, redaction_policy, frozenset())
+
+
+def _apply_redaction_options(value: Any, redaction_options: RedactionOptions) -> None:
+    secret_names = _secret_name_set(redaction_options.secret_names)
+    _apply_redaction_policy_with_names(value, redaction_options.policy, secret_names)
+
+
+def _apply_redaction_policy_with_names(
+    value: Any,
+    redaction_policy: RedactionPolicy | None,
+    secret_names: frozenset[str],
+) -> None:
     if redaction_policy == RedactionPolicy.RedactionTraceOnly:
         if isinstance(value, dict) and "trace" in value:
-            _redact_secrets(value["trace"])
+            _redact_secrets(value["trace"], secret_names)
         return
     if redaction_policy == RedactionPolicy.RedactionNone:
         return
     if redaction_policy == RedactionPolicy.RedactionStrict:
-        _redact_secrets_strict(value)
+        _redact_secrets_strict(value, secret_names)
         return
-    # Safety fallback for unknown values.
-    _redact_secrets(value)
+    # Empty/unknown policy falls back to default full redaction.
+    _redact_secrets(value, secret_names)
 
 
 def parse_size(s: str) -> int | None:
@@ -208,31 +284,43 @@ def _sanitize_for_json(value: Any, stack: set[int] | None = None) -> Any:
     return f"<unsupported:{type(value).__name__}>"
 
 
-def _redact_secrets(value: Any) -> None:
+def _secret_name_set(secret_names: Sequence[str]) -> frozenset[str]:
+    return frozenset(secret_names)
+
+
+def _key_has_secret_suffix(key: str) -> bool:
+    return key.endswith("_secret") or key.endswith("_SECRET")
+
+
+def _is_secret_key(key: str, secret_names: frozenset[str]) -> bool:
+    return _key_has_secret_suffix(key) or key in secret_names
+
+
+def _redact_secrets(value: Any, secret_names: frozenset[str] = frozenset()) -> None:
     if isinstance(value, dict):
         for k in list(value.keys()):
-            if k.endswith("_secret") or k.endswith("_SECRET"):
+            if _is_secret_key(k, secret_names):
                 if isinstance(value[k], (dict, list)):
-                    _redact_secrets(value[k])
+                    _redact_secrets(value[k], secret_names)
                 else:
                     value[k] = "***"
             else:
-                _redact_secrets(value[k])
+                _redact_secrets(value[k], secret_names)
     elif isinstance(value, list):
         for item in value:
-            _redact_secrets(item)
+            _redact_secrets(item, secret_names)
 
 
-def _redact_secrets_strict(value: Any) -> None:
+def _redact_secrets_strict(value: Any, secret_names: frozenset[str] = frozenset()) -> None:
     if isinstance(value, dict):
         for k in list(value.keys()):
-            if k.endswith("_secret") or k.endswith("_SECRET"):
+            if _is_secret_key(k, secret_names):
                 value[k] = "***"
             else:
-                _redact_secrets_strict(value[k])
+                _redact_secrets_strict(value[k], secret_names)
     elif isinstance(value, list):
         for item in value:
-            _redact_secrets_strict(item)
+            _redact_secrets_strict(item, secret_names)
 
 
 # ═══════════════════════════════════════════
@@ -546,6 +634,53 @@ def _render_yaml_processed(value: Any, indent: int, lines: list[str]) -> None:
             lines.append(f"{prefix}{display_key}: {_yaml_scalar(v)}")
 
 
+def _render_yaml_raw(value: Any, indent: int, lines: list[str]) -> None:
+    prefix = "  " * indent
+    if isinstance(value, dict):
+        for key in _sorted_object_keys(value):
+            _render_yaml_field_raw(prefix, key, value[key], indent, lines)
+    elif isinstance(value, list):
+        _render_yaml_array_raw(value, indent, lines)
+    else:
+        lines.append(f"{prefix}{_yaml_scalar(value)}")
+
+
+def _render_yaml_field_raw(prefix: str, key: str, value: Any, indent: int, lines: list[str]) -> None:
+    if isinstance(value, dict):
+        if value:
+            lines.append(f"{prefix}{key}:")
+            _render_yaml_raw(value, indent + 1, lines)
+        else:
+            lines.append(f"{prefix}{key}: {{}}")
+    elif isinstance(value, list):
+        if value:
+            lines.append(f"{prefix}{key}:")
+            _render_yaml_array_raw(value, indent + 1, lines)
+        else:
+            lines.append(f"{prefix}{key}: []")
+    else:
+        lines.append(f"{prefix}{key}: {_yaml_scalar(value)}")
+
+
+def _render_yaml_array_raw(arr: list[Any], indent: int, lines: list[str]) -> None:
+    prefix = "  " * indent
+    for item in arr:
+        if isinstance(item, dict):
+            if item:
+                lines.append(f"{prefix}-")
+                _render_yaml_raw(item, indent + 1, lines)
+            else:
+                lines.append(f"{prefix}- {{}}")
+        elif isinstance(item, list):
+            if item:
+                lines.append(f"{prefix}-")
+                _render_yaml_array_raw(item, indent + 1, lines)
+            else:
+                lines.append(f"{prefix}- []")
+        else:
+            lines.append(f"{prefix}- {_yaml_scalar(item)}")
+
+
 def _escape_yaml_str(s: str) -> str:
     return s.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n").replace("\r", "\\r").replace("\t", "\\t")
 
@@ -586,6 +721,23 @@ def _collect_plain_pairs(value: Any, prefix: str, pairs: list[tuple[str, str]])
             pairs.append((full_key, _plain_scalar(v)))
 
 
+def _collect_plain_pairs_raw(value: Any, prefix: str, pairs: list[tuple[str, str]]) -> None:
+    if not isinstance(value, dict):
+        return
+    for key in _sorted_object_keys(value):
+        v = value[key]
+        full_key = f"{prefix}.{key}" if prefix else key
+        if isinstance(v, dict):
+            _collect_plain_pairs_raw(v, full_key, pairs)
+        elif isinstance(v, list):
+            joined = ",".join(_plain_scalar_raw(item) for item in v)
+            pairs.append((full_key, joined))
+        elif v is None:
+            pairs.append((full_key, ""))
+        else:
+            pairs.append((full_key, _plain_scalar(v)))
+
+
 def _plain_scalar(value: Any) -> str:
     if isinstance(value, str):
         return value
@@ -598,6 +750,12 @@ def _plain_scalar(value: Any) -> str:
     return str(value)
 
 
+def _plain_scalar_raw(value: Any) -> str:
+    if isinstance(value, (dict, list)):
+        return json.dumps(value, ensure_ascii=False, separators=(",", ":"), sort_keys=True)
+    return _plain_scalar(value)
+
+
 def _quote_logfmt_value(value: str) -> str:
     if value == "":
         return ""
@@ -612,3 +770,7 @@ def _quote_logfmt_value(value: str) -> str:
         .replace("\t", "\\t")
     )
     return f'"{escaped}"'
+
+
+def _sorted_object_keys(d: dict) -> list[str]:
+    return sorted(d.keys(), key=lambda k: k.encode("utf-16-be"))

agent_first_data-0.8.0/README.md → agent_first_data-0.9.0/agent_first_data.egg-info/PKG-INFO

@@ -1,3 +1,12 @@
+Metadata-Version: 2.4
+Name: agent-first-data
+Version: 0.9.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
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
 # agent-first-data
 
 **Agent-First Data (AFDATA)** — Suffix-driven output formatting and protocol templates for AI agents.
@@ -65,7 +74,7 @@ Plain: args.input_path=/data/backup.tar.gz code=log event=startup config.max_fil
 
 ## API Reference
 
-Total: **15 public APIs and 2 types** + **AFDATA logging** (3 protocol builders + 2 redacted value helpers + 4 output functions + 1 internal + 1 utility + 4 CLI helpers + `OutputFormat` + `RedactionPolicy`)
+Public APIs are grouped by role: protocol builders, redaction helpers, output formatters, internal redaction tools, utility/CLI helpers, types, and AFDATA logging integration.
 
 ### Protocol Builders (returns dict)
 
@@ -82,13 +91,14 @@ build_json_error(message: str, hint: str = None, trace: Any = None) -> dict
 build_json(code: str, fields: Any, trace: Any = None) -> dict
 ```
 
-### Redacted Values (returns Any)
+### Redaction Helpers (returns Any)
 
 Use these before raw HTTP/MCP/SSE serializers that do not call `output_json`.
 
 ```python
 redacted_value(value: Any) -> Any
 redacted_value_with(value: Any, redaction_policy: RedactionPolicy) -> Any
+redacted_value_with_options(value: Any, redaction_options: RedactionOptions) -> Any
 ```
 
 **Use case:** structured protocol payloads (frameworks automatically serialize)
@@ -129,15 +139,18 @@ not_found = build_json(
 )
 ```
 
-### CLI/Log Output (returns str)
+### Output Formatters (returns str)
 
-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.
+Format values for CLI output and logs. `output_json` uses full `_secret` redaction by default. `output_json_with` supports explicit scoped policies. Use `OutputOptions` to pass legacy secret names such as `api_key` or request schema-preserving YAML/plain rendering with `OutputStyle.Raw`.
 
 ```python
 output_json(value: Any) -> str   # Single-line JSON, original keys, for programs/logs
 output_json_with(value: Any, redaction_policy: RedactionPolicy) -> str
+output_json_with_options(value: Any, output_options: OutputOptions) -> str
 output_yaml(value: Any) -> str   # Multi-line YAML, keys stripped, values formatted
+output_yaml_with_options(value: Any, output_options: OutputOptions) -> str
 output_plain(value: Any) -> str  # Single-line logfmt, keys stripped, values formatted
+output_plain_with_options(value: Any, output_options: OutputOptions) -> str
 ```
 
 ```python
@@ -145,8 +158,18 @@ class RedactionPolicy(enum.Enum):
     RedactionTraceOnly = "RedactionTraceOnly"
     RedactionNone = "RedactionNone"
     RedactionStrict = "RedactionStrict"
+
+RedactionOptions(policy: RedactionPolicy | None = None, secret_names: Sequence[str] = ())
+
+class OutputStyle(enum.Enum):
+    Readable = "Readable"
+    Raw = "Raw"
+
+OutputOptions(redaction: RedactionOptions = RedactionOptions(), style: OutputStyle = OutputStyle.Readable)
 ```
 
+Secret names match exact field names at any nesting level; there is no trim, case folding, hyphen/underscore normalization, glob, regex, or substring matching. `OutputOptions` combines `RedactionOptions` with `OutputStyle.Readable` (default suffix stripping and value formatting) or `OutputStyle.Raw` (no suffix stripping or value formatting).
+
 **Example:**
 ```python
 from agent_first_data import *
@@ -179,6 +202,7 @@ print(output_plain(data))
 
 ```python
 internal_redact_secrets(value: Any) -> None  # Manually redact secrets in-place
+internal_redact_secrets_with_options(value: Any, redaction_options: RedactionOptions) -> None
 ```
 
 Most users don't need this. Output functions automatically protect secrets.
@@ -210,6 +234,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
+cli_output_with_options(value: Any, format: OutputFormat, output_options: OutputOptions) -> str
 build_cli_error(message: str, hint: str = None) -> dict  # {code:"error", error_code:"invalid_request", hint?, retryable:False, trace:{duration_ms:0}}
 ```
 

{agent_first_data-0.8.0 → agent_first_data-0.9.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "agent-first-data"
-version = "0.8.0"
-description = "Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates for AI agents"
+version = "0.9.0"
+description = "A naming convention that lets AI agents understand your data without being told what it means."
 license = "MIT"
 readme = "README.md"
 requires-python = ">=3.9"

{agent_first_data-0.8.0 → agent_first_data-0.9.0}/tests/test_cli.py

@@ -2,9 +2,12 @@
 import pytest
 from agent_first_data import (
     OutputFormat,
+    OutputStyle,
+    OutputOptions,
     cli_parse_output,
     cli_parse_log_filters,
     cli_output,
+    cli_output_with_options,
     build_cli_error,
     output_json,
 )
@@ -106,3 +109,14 @@ def test_cli_output_dispatches_plain():
     out = cli_output(v, OutputFormat.PLAIN)
     assert "\n" not in out
     assert "code=ok" in out
+
+
+def test_cli_output_with_options_dispatches_raw_yaml():
+    v = {"size_bytes": 1024}
+    out = cli_output_with_options(
+        v,
+        OutputFormat.YAML,
+        OutputOptions(style=OutputStyle.Raw),
+    )
+    assert "size_bytes: 1024" in out
+    assert "size:" not in out

{agent_first_data-0.8.0 → agent_first_data-0.9.0}/tests/test_format.py

@@ -8,13 +8,21 @@ from agent_first_data import (
     build_json_error,
     build_json,
     RedactionPolicy,
+    RedactionOptions,
+    OutputStyle,
+    OutputOptions,
     internal_redact_secrets,
+    internal_redact_secrets_with_options,
     redacted_value,
     redacted_value_with,
+    redacted_value_with_options,
     output_json,
     output_json_with,
+    output_json_with_options,
     output_yaml,
+    output_yaml_with_options,
     output_plain,
+    output_plain_with_options,
 )
 from agent_first_data.format import (
     _format_bytes_human,
@@ -31,6 +39,12 @@ def _load(name):
         return json.load(f)
 
 
+def _redaction_options(case):
+    opts = case.get("options", {})
+    policy = RedactionPolicy(opts["policy"]) if "policy" in opts else None
+    return RedactionOptions(policy=policy, secret_names=opts.get("secret_names", ()))
+
+
 # --- Redact fixtures ---
 
 
@@ -42,6 +56,31 @@ def test_redact_fixtures():
         assert inp == case["expected"], f"[redact/{name}] got {inp}"
 
 
+def test_redaction_options_fixtures():
+    for case in _load("redaction_options.json"):
+        name = case["name"]
+        options = _redaction_options(case)
+        output_options = OutputOptions(redaction=options, style=OutputStyle.Readable)
+        expected = case["expected"]
+
+        got = redacted_value_with_options(case["input"], options)
+        assert got == expected, f"[redaction_options/{name}] value mismatch: {got}"
+
+        inp = json.loads(json.dumps(case["input"]))
+        internal_redact_secrets_with_options(inp, options)
+        assert inp == expected, f"[redaction_options/{name}] in-place mismatch: {inp}"
+
+        got_json = json.loads(output_json_with_options(case["input"], output_options))
+        assert got_json == expected, f"[redaction_options/{name}] json mismatch: {got_json}"
+
+        if "expected_yaml" in case:
+            got_yaml = output_yaml_with_options(case["input"], output_options)
+            assert got_yaml == case["expected_yaml"], f"[redaction_options/{name}] yaml mismatch: {got_yaml!r}"
+        if "expected_plain" in case:
+            got_plain = output_plain_with_options(case["input"], output_options)
+            assert got_plain == case["expected_plain"], f"[redaction_options/{name}] plain mismatch: {got_plain!r}"
+
+
 # --- Protocol fixtures ---
 
 
@@ -111,6 +150,57 @@ def test_output_format_fixtures():
         assert got_plain == case["expected_plain"], f"[output/{name}] plain mismatch: {got_plain!r}"
 
 
+def test_output_yaml_raw_keeps_suffix_keys_and_structure():
+    options = OutputOptions(
+        redaction=RedactionOptions(policy=RedactionPolicy.RedactionTraceOnly),
+        style=OutputStyle.Raw,
+    )
+    out = output_yaml_with_options(
+        {
+            "code": "result",
+            "rows": [{"api_key_secret": "sk-live-1", "duration_ms": 42}],
+            "trace": {"request_secret": "top-secret"},
+        },
+        options,
+    )
+
+    assert "rows:\n  -" in out
+    assert 'api_key_secret: "sk-live-1"' in out
+    assert "duration_ms: 42" in out
+    assert 'request_secret: "***"' in out
+    assert 'duration: "42ms"' not in out
+
+
+def test_output_plain_raw_keeps_suffix_keys_and_redacts_trace():
+    options = OutputOptions(
+        redaction=RedactionOptions(policy=RedactionPolicy.RedactionTraceOnly),
+        style=OutputStyle.Raw,
+    )
+    out = output_plain_with_options(
+        {
+            "duration_ms": 42,
+            "trace": {"request_secret": "top-secret"},
+        },
+        options,
+    )
+
+    assert "duration_ms=42" in out
+    assert "trace.request_secret=***" in out
+    assert "duration=42ms" not in out
+
+
+def test_output_with_options_defaults_to_readable_style():
+    out = output_yaml_with_options(
+        {"duration_ms": 42},
+        OutputOptions(
+            redaction=RedactionOptions(policy=RedactionPolicy.RedactionNone),
+            style=OutputStyle.Readable,
+        ),
+    )
+    assert 'duration: "42ms"' in out
+    assert "duration_ms:" not in out
+
+
 def test_output_json_exception_field_is_readable():
     out = output_json({"error": Exception("timeout")})
     parsed = json.loads(out)