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

agent_first_data-0.13.1/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: agent-first-data
+Version: 0.13.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
+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`, `build_cli_error`, `build_cli_version`, and `cli_handle_version_or_continue`.
+
+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.
+- Use `cli_handle_version_or_continue()` before argument parsing so bare `--version` stays conventional and `--version --output json|yaml|plain` stays structured.
+
+## 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.1/README.md

@@ -0,0 +1,47 @@
+# 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`, `build_cli_error`, `build_cli_version`, and `cli_handle_version_or_continue`.
+
+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.
+- Use `cli_handle_version_or_continue()` before argument parsing so bare `--version` stays conventional and `--version --output json|yaml|plain` stays structured.
+
+## 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.1}/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 (
@@ -41,6 +42,9 @@ from agent_first_data.cli import (
     cli_output,
     cli_output_with_options,
     build_cli_error,
+    build_cli_version,
+    cli_render_version,
+    cli_handle_version_or_continue,
 )
 
 from agent_first_data.skill import (
@@ -74,14 +78,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",
@@ -94,6 +99,9 @@ __all__ = [
     "cli_output",
     "cli_output_with_options",
     "build_cli_error",
+    "build_cli_version",
+    "cli_render_version",
+    "cli_handle_version_or_continue",
     "SkillSpec",
     "SkillAction",
     "SkillScope",

{agent_first_data-0.12.2 → agent_first_data-0.13.1}/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.1}/agent_first_data/cli.py

@@ -7,6 +7,7 @@ from typing import Any
 
 from agent_first_data.format import (
     OutputOptions,
+    build_json,
     output_json,
     output_json_with_options,
     output_yaml,
@@ -93,27 +94,96 @@ def cli_output_with_options(
     return output_json_with_options(value, output_options)
 
 
+def build_cli_version(version: str) -> dict:
+    """Build a standard CLI version value."""
+    return build_json("version", {"version": version})
+
+
+def cli_render_version(
+    name: str,
+    version: str,
+    format: OutputFormat | None = None,
+) -> str:
+    """Render CLI version output.
+
+    Pass an OutputFormat for AFDATA JSON/YAML/plain. Pass None to preserve
+    conventional "<name> <version>" text.
+    """
+    rendered = (
+        f"{name} {version}" if format is None else cli_output(build_cli_version(version), format)
+    )
+    return rendered.rstrip("\n") + "\n"
+
+
+def cli_handle_version_or_continue(
+    raw_args: list[str],
+    name: str,
+    version: str,
+    default_output: OutputFormat | None = None,
+    output_flag: str = "--output",
+    allow_output_format: bool = True,
+) -> str | None:
+    """Render version output if --version/-V is present; otherwise return None.
+
+    Raises ValueError for malformed version requests, for example
+    ``--version --output xml``. The caller should convert that to a CLI error
+    with ``build_cli_error``.
+    """
+    version_requested = False
+    output_format: OutputFormat | None = None
+    output_error: ValueError | None = None
+
+    i = 0
+    while i < len(raw_args):
+        arg = raw_args[i]
+        if arg == "--":
+            break
+        if arg in ("--version", "-V"):
+            version_requested = True
+            i += 1
+            continue
+        if allow_output_format and (arg == output_flag or arg.startswith(f"{output_flag}=")):
+            value: str | None
+            if arg.startswith(f"{output_flag}="):
+                value = arg.split("=", 1)[1]
+                step = 1
+            elif i + 1 < len(raw_args) and not raw_args[i + 1].startswith("-"):
+                value = raw_args[i + 1]
+                step = 2
+            else:
+                value = None
+                step = 1
+            if value is None:
+                output_error = ValueError(
+                    f"missing value for {output_flag}: expected json, yaml, or plain"
+                )
+            else:
+                try:
+                    output_format = cli_parse_output(value)
+                except ValueError as e:
+                    output_error = e
+            i += step
+            continue
+        i += 1
+
+    if not version_requested:
+        return None
+    if output_error is not None:
+        raise output_error
+    return cli_render_version(
+        name,
+        version,
+        output_format if allow_output_format and output_format is not None else default_output,
+    )
+
+
 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.
     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