agent-first-data 0.12.2__tar.gz → 0.13.0__tar.gz

agent_first_data-0.13.0/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: agent-first-data
+Version: 0.13.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 for Python
+
+```bash
+pip install agent-first-data
+```
+
+```python
+from agent_first_data import output_json, output_plain
+
+value = {
+    "code": "ok",
+    "result": {
+        "api_key_secret": "sk-123",
+        "latency_ms": 1280,
+        "db_url": "postgres://user:p@ss@db/app?token_secret=abc",
+    },
+}
+
+print(output_json(value))
+print(output_plain(value))
+```
+
+Useful names use Python casing: `output_json`, `output_yaml`, `output_plain`, `output_json_with_options`, `redacted_value`, `redact_secrets_in_place`, `redact_url_secrets`, `parse_size`, `normalize_utc_offset`, `cli_parse_output`, `cli_output`, and `build_cli_error`.
+
+Logging is available through `init_logging_json`, `init_logging_plain`, `init_logging_yaml`, `span`, and `get_logger`.
+
+```python
+from agent_first_data import init_logging_json
+
+init_logging_json("INFO", secret_names=("authorization",))
+```
+
+## Behavior Notes
+
+- Default redaction replaces every `_secret` or configured secret-name subtree with `***`, including objects and arrays.
+- `_url` fields scrub userinfo passwords and secret-named query parameters; surrounding whitespace is trimmed and internal whitespace redacts the whole field.
+- YAML/plain quote and escape keys as well as values, sort by UTF-16 code unit order, and render nested objects in arrays as canonical JSON.
+- Logging records use `code: "log"` plus a separate `level` field, so error-level logs are not terminal protocol errors.
+- `build_cli_error(message, hint?)` returns `{code:"error", error: message, hint?}` only.
+
+## Reference
+
+- Full convention and API groups: [../docs/overview.md](../docs/overview.md)
+- Formal cross-language contract: [../spec/agent-first-data.md](../spec/agent-first-data.md)
+- Conformance fixtures: [../spec/fixtures](../spec/fixtures)
+- Agent skill: [../skills/agent-first-data.md](../skills/agent-first-data.md)

agent_first_data-0.13.0/README.md

@@ -0,0 +1,46 @@
+# Agent-First Data for Python
+
+```bash
+pip install agent-first-data
+```
+
+```python
+from agent_first_data import output_json, output_plain
+
+value = {
+    "code": "ok",
+    "result": {
+        "api_key_secret": "sk-123",
+        "latency_ms": 1280,
+        "db_url": "postgres://user:p@ss@db/app?token_secret=abc",
+    },
+}
+
+print(output_json(value))
+print(output_plain(value))
+```
+
+Useful names use Python casing: `output_json`, `output_yaml`, `output_plain`, `output_json_with_options`, `redacted_value`, `redact_secrets_in_place`, `redact_url_secrets`, `parse_size`, `normalize_utc_offset`, `cli_parse_output`, `cli_output`, and `build_cli_error`.
+
+Logging is available through `init_logging_json`, `init_logging_plain`, `init_logging_yaml`, `span`, and `get_logger`.
+
+```python
+from agent_first_data import init_logging_json
+
+init_logging_json("INFO", secret_names=("authorization",))
+```
+
+## Behavior Notes
+
+- Default redaction replaces every `_secret` or configured secret-name subtree with `***`, including objects and arrays.
+- `_url` fields scrub userinfo passwords and secret-named query parameters; surrounding whitespace is trimmed and internal whitespace redacts the whole field.
+- YAML/plain quote and escape keys as well as values, sort by UTF-16 code unit order, and render nested objects in arrays as canonical JSON.
+- Logging records use `code: "log"` plus a separate `level` field, so error-level logs are not terminal protocol errors.
+- `build_cli_error(message, hint?)` returns `{code:"error", error: message, hint?}` only.
+
+## Reference
+
+- Full convention and API groups: [../docs/overview.md](../docs/overview.md)
+- Formal cross-language contract: [../spec/agent-first-data.md](../spec/agent-first-data.md)
+- Conformance fixtures: [../spec/fixtures](../spec/fixtures)
+- Agent skill: [../skills/agent-first-data.md](../skills/agent-first-data.md)

{agent_first_data-0.12.2 → agent_first_data-0.13.0}/agent_first_data/__init__.py

@@ -15,14 +15,15 @@ from agent_first_data.format import (
     output_yaml_with_options,
     output_plain,
     output_plain_with_options,
-    internal_redact_secrets,
-    internal_redact_secrets_with_options,
+    redact_secrets_in_place,
+    redact_secrets_in_place_with_options,
     redacted_value,
     redacted_value_with,
     redacted_value_with_options,
     redact_url_secrets,
     redact_url_secrets_with_options,
     parse_size,
+    normalize_utc_offset,
 )
 
 from agent_first_data.afdata_logging import (
@@ -74,14 +75,15 @@ __all__ = [
     "output_yaml_with_options",
     "output_plain",
     "output_plain_with_options",
-    "internal_redact_secrets",
-    "internal_redact_secrets_with_options",
+    "redact_secrets_in_place",
+    "redact_secrets_in_place_with_options",
     "redacted_value",
     "redacted_value_with",
     "redacted_value_with_options",
     "redact_url_secrets",
     "redact_url_secrets_with_options",
     "parse_size",
+    "normalize_utc_offset",
     "AfdataHandler",
     "init_logging_json",
     "init_logging_plain",

{agent_first_data-0.12.2 → agent_first_data-0.13.0}/agent_first_data/afdata_logging.py

@@ -21,13 +21,19 @@ Usage:
 import logging
 import sys
 from contextvars import ContextVar, Token
-from typing import Any
+from typing import Any, Sequence
 
-from agent_first_data.format import output_json, output_plain, output_yaml
+from agent_first_data.format import (
+    OutputOptions,
+    RedactionOptions,
+    output_json_with_options,
+    output_plain_with_options,
+    output_yaml_with_options,
+)
 
 _span_fields: ContextVar[dict[str, Any]] = ContextVar("afdata_span", default={})
 
-_LEVEL_TO_CODE = {
+_LEVEL_TO_NAME = {
     "CRITICAL": "error",
     "ERROR": "error",
     "WARNING": "warn",
@@ -44,17 +50,24 @@ class AfdataHandler(logging.Handler):
     Formats output using the library's own output_json/output_plain/output_yaml.
     """
 
-    def __init__(self, format: str = "json") -> None:
+    def __init__(
+        self,
+        format: str = "json",
+        redaction: RedactionOptions | None = None,
+        secret_names: Sequence[str] | None = None,
+    ) -> None:
         super().__init__()
         if format not in ("json", "plain", "yaml"):
             raise ValueError(f"Unknown format: {format!r}, expected json/plain/yaml")
         self._format = format
+        self._redaction = _redaction_options(redaction, secret_names)
 
     def emit(self, record: logging.LogRecord) -> None:
         entry: dict[str, Any] = {
             "timestamp_epoch_ms": int(record.created * 1000),
             "message": record.getMessage(),
-            "target": record.name,
+            "code": "log",
+            "level": _LEVEL_TO_NAME.get(record.levelname, "info"),
         }
 
         # Span fields (from contextvars, async-safe)
@@ -62,26 +75,23 @@ class AfdataHandler(logging.Handler):
         if span_data:
             entry.update(span_data)
 
-        # Event fields (passed via extra= in logging calls)
-        has_code = False
+        # Event fields (passed via extra= in logging calls). The protocol code
+        # is always "log"; use event for business categorization.
         extra = getattr(record, "_afdata_fields", None)
         if extra:
             for k, v in extra.items():
                 if k == "code":
-                    has_code = True
+                    continue
                 entry[k] = v
 
-        # Default code from level
-        if not has_code:
-            entry["code"] = _LEVEL_TO_CODE.get(record.levelname, "info")
-
-        # Format using the library's own output functions
+        # Format using the library's own output functions.
+        options = OutputOptions(redaction=self._redaction)
         if self._format == "plain":
-            line = output_plain(entry)
+            line = output_plain_with_options(entry, options)
         elif self._format == "yaml":
-            line = output_yaml(entry)
+            line = output_yaml_with_options(entry, options)
         else:
-            line = output_json(entry)
+            line = output_json_with_options(entry, options)
 
         sys.stdout.write(line + "\n")
         sys.stdout.flush()
@@ -100,26 +110,56 @@ class _AfdataLoggerAdapter(logging.LoggerAdapter):
         return msg, kwargs
 
 
-def _init_with_format(format: str, level: str = "INFO") -> None:
-    handler = AfdataHandler(format=format)
+def _redaction_options(
+    redaction: RedactionOptions | None,
+    secret_names: Sequence[str] | None,
+) -> RedactionOptions:
+    if redaction is not None and secret_names is not None:
+        raise ValueError("Pass either redaction or secret_names, not both")
+    if redaction is not None:
+        return redaction
+    if secret_names is not None:
+        return RedactionOptions(secret_names=tuple(secret_names))
+    return RedactionOptions()
+
+
+def _init_with_format(
+    format: str,
+    level: str = "INFO",
+    redaction: RedactionOptions | None = None,
+    secret_names: Sequence[str] | None = None,
+) -> None:
+    handler = AfdataHandler(format=format, redaction=redaction, secret_names=secret_names)
     root = logging.getLogger()
     root.handlers = [handler]
     root.setLevel(getattr(logging, level.upper(), logging.INFO))
 
 
-def init_json(level: str = "INFO") -> None:
+def init_json(
+    level: str = "INFO",
+    redaction: RedactionOptions | None = None,
+    secret_names: Sequence[str] | None = None,
+) -> None:
     """Initialize the root logger with AFDATA JSON output to stdout."""
-    _init_with_format("json", level)
+    _init_with_format("json", level, redaction=redaction, secret_names=secret_names)
 
 
-def init_plain(level: str = "INFO") -> None:
+def init_plain(
+    level: str = "INFO",
+    redaction: RedactionOptions | None = None,
+    secret_names: Sequence[str] | None = None,
+) -> None:
     """Initialize the root logger with AFDATA plain/logfmt output to stdout."""
-    _init_with_format("plain", level)
+    _init_with_format("plain", level, redaction=redaction, secret_names=secret_names)
 
 
-def init_yaml(level: str = "INFO") -> None:
+def init_yaml(
+    level: str = "INFO",
+    redaction: RedactionOptions | None = None,
+    secret_names: Sequence[str] | None = None,
+) -> None:
     """Initialize the root logger with AFDATA YAML output to stdout."""
-    _init_with_format("yaml", level)
+    _init_with_format("yaml", level, redaction=redaction, secret_names=secret_names)
 
 
 def get_logger(name: str, **fields: Any) -> logging.LoggerAdapter:

{agent_first_data-0.12.2 → agent_first_data-0.13.0}/agent_first_data/cli.py

@@ -98,22 +98,8 @@ def build_cli_error(message: str, hint: str | None = None) -> dict:
 
     Use when argument parsing fails or a flag value is invalid.
     Print with output_json and exit with code 2.
-
-    >>> v = build_cli_error("--output: invalid value 'xml'")
-    >>> v["code"]
-    'error'
-    >>> v["error_code"]
-    'invalid_request'
-    >>> v["retryable"]
-    False
     """
-    m: dict = {
-        "code": "error",
-        "error_code": "invalid_request",
-        "error": message,
-        "retryable": False,
-        "trace": {"duration_ms": 0},
-    }
+    m: dict = {"code": "error", "error": message}
     if hint is not None:
         m["hint"] = hint
     return m