agent-first-data 0.3.0__tar.gz → 0.4.0__tar.gz

{agent_first_data-0.3.0 → agent_first_data-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.3.0
+Version: 0.4.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,7 +74,7 @@ Plain: args.input_path=/data/backup.tar.gz code=log event=startup config.max_fil
 
 ## API Reference
 
-Total: **8 public APIs** + **AFDATA logging** (3 protocol builders + 3 output functions + 1 internal + 1 utility)
+Total: **12 public APIs and 1 type** + **AFDATA logging** (3 protocol builders + 3 output functions + 1 internal + 1 utility + 4 CLI helpers + `OutputFormat`)
 
 ### Protocol Builders (returns dict)
 
@@ -187,6 +187,41 @@ assert parse_size("1.5K") == 1536
 assert parse_size("512") == 512
 ```
 
+### CLI Helpers (for tools built on AFDATA)
+
+Shared helpers that prevent flag-parsing drift between CLI tools. Use these instead of reimplementing `--output` and `--log` handling in each tool.
+
+```python
+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}}
+```
+
+**Canonical pattern** — parse all flags before doing work, emit JSONL errors to stdout:
+
+```python
+import sys
+from agent_first_data import (
+    OutputFormat, cli_parse_output, cli_parse_log_filters,
+    cli_output, build_cli_error, output_json,
+)
+
+try:
+    fmt = cli_parse_output(args.output)
+except ValueError as e:
+    print(output_json(build_cli_error(str(e))))
+    sys.exit(2)
+
+log = cli_parse_log_filters(args.log.split(",") if args.log else [])
+# ... do work ...
+print(cli_output(result, fmt))
+```
+
+See `examples/agent_cli.py` for the complete working example (`pytest examples/agent_cli.py`).
+
 ## Usage Examples
 
 ### Example 1: REST API
@@ -276,6 +311,7 @@ result = build_json_ok(
 )
 
 # Print JSONL to stdout (secrets redacted, one JSON object per line)
+# Channel policy: machine-readable protocol/log events must not use stderr.
 print(output_json(result))
 # {"code":"ok","result":{"status":"success"},"trace":{"api_key_secret":"***","duration_ms":250}}
 ```

{agent_first_data-0.3.0 → agent_first_data-0.4.0}/README.md

@@ -65,7 +65,7 @@ Plain: args.input_path=/data/backup.tar.gz code=log event=startup config.max_fil
 
 ## API Reference
 
-Total: **8 public APIs** + **AFDATA logging** (3 protocol builders + 3 output functions + 1 internal + 1 utility)
+Total: **12 public APIs and 1 type** + **AFDATA logging** (3 protocol builders + 3 output functions + 1 internal + 1 utility + 4 CLI helpers + `OutputFormat`)
 
 ### Protocol Builders (returns dict)
 
@@ -178,6 +178,41 @@ assert parse_size("1.5K") == 1536
 assert parse_size("512") == 512
 ```
 
+### CLI Helpers (for tools built on AFDATA)
+
+Shared helpers that prevent flag-parsing drift between CLI tools. Use these instead of reimplementing `--output` and `--log` handling in each tool.
+
+```python
+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}}
+```
+
+**Canonical pattern** — parse all flags before doing work, emit JSONL errors to stdout:
+
+```python
+import sys
+from agent_first_data import (
+    OutputFormat, cli_parse_output, cli_parse_log_filters,
+    cli_output, build_cli_error, output_json,
+)
+
+try:
+    fmt = cli_parse_output(args.output)
+except ValueError as e:
+    print(output_json(build_cli_error(str(e))))
+    sys.exit(2)
+
+log = cli_parse_log_filters(args.log.split(",") if args.log else [])
+# ... do work ...
+print(cli_output(result, fmt))
+```
+
+See `examples/agent_cli.py` for the complete working example (`pytest examples/agent_cli.py`).
+
 ## Usage Examples
 
 ### Example 1: REST API
@@ -267,6 +302,7 @@ result = build_json_ok(
 )
 
 # Print JSONL to stdout (secrets redacted, one JSON object per line)
+# Channel policy: machine-readable protocol/log events must not use stderr.
 print(output_json(result))
 # {"code":"ok","result":{"status":"success"},"trace":{"api_key_secret":"***","duration_ms":250}}
 ```

{agent_first_data-0.3.0 → agent_first_data-0.4.0}/agent_first_data/__init__.py

@@ -21,6 +21,14 @@ from agent_first_data.afdata_logging import (
     span,
 )
 
+from agent_first_data.cli import (
+    OutputFormat,
+    cli_parse_output,
+    cli_parse_log_filters,
+    cli_output,
+    build_cli_error,
+)
+
 __all__ = [
     "build_json_ok",
     "build_json_error",
@@ -37,4 +45,9 @@ __all__ = [
     "init_logging_yaml",
     "get_logger",
     "span",
+    "OutputFormat",
+    "cli_parse_output",
+    "cli_parse_log_filters",
+    "cli_output",
+    "build_cli_error",
 ]

agent_first_data-0.4.0/agent_first_data/cli.py

@@ -0,0 +1,92 @@
+"""AFDATA CLI helpers — output format parsing, log filter normalization, error building."""
+
+from __future__ import annotations
+
+import enum
+from typing import Any
+
+from agent_first_data.format import output_json, output_yaml, output_plain
+
+
+class OutputFormat(enum.Enum):
+    """Output format for CLI and pipe/MCP modes."""
+
+    JSON = "json"
+    YAML = "yaml"
+    PLAIN = "plain"
+
+
+def cli_parse_output(s: str) -> OutputFormat:
+    """Parse the --output flag value into an OutputFormat.
+
+    Raises ValueError with a message suitable for build_cli_error on unknown values.
+
+    >>> cli_parse_output("json")
+    <OutputFormat.JSON: 'json'>
+    >>> cli_parse_output("xml")
+    Traceback (most recent call last):
+        ...
+    ValueError: invalid --output format 'xml': expected json, yaml, or plain
+    """
+    try:
+        return OutputFormat(s)
+    except ValueError:
+        raise ValueError(
+            f"invalid --output format {s!r}: expected json, yaml, or plain"
+        )
+
+
+def cli_parse_log_filters(entries: list[str]) -> list[str]:
+    """Normalize --log flag entries: trim, lowercase, deduplicate, remove empty.
+
+    Accepts pre-split entries (e.g. after splitting on comma).
+
+    >>> cli_parse_log_filters(["Query", " error ", "query"])
+    ['query', 'error']
+    """
+    out: list[str] = []
+    for entry in entries:
+        s = entry.strip().lower()
+        if s and s not in out:
+            out.append(s)
+    return out
+
+
+def cli_output(value: Any, format: OutputFormat) -> str:
+    """Dispatch output formatting by OutputFormat.
+
+    Equivalent to calling output_json, output_yaml, or output_plain directly.
+
+    >>> import json
+    >>> v = {"code": "ok"}
+    >>> cli_output(v, OutputFormat.JSON).startswith('{"code"')
+    True
+    """
+    if format is OutputFormat.YAML:
+        return output_yaml(value)
+    if format is OutputFormat.PLAIN:
+        return output_plain(value)
+    return output_json(value)
+
+
+def build_cli_error(message: str) -> 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
+    """
+    return {
+        "code": "error",
+        "error_code": "invalid_request",
+        "error": message,
+        "retryable": False,
+        "trace": {"duration_ms": 0},
+    }

{agent_first_data-0.3.0 → agent_first_data-0.4.0}/agent_first_data.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.3.0
+Version: 0.4.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,7 +74,7 @@ Plain: args.input_path=/data/backup.tar.gz code=log event=startup config.max_fil
 
 ## API Reference
 
-Total: **8 public APIs** + **AFDATA logging** (3 protocol builders + 3 output functions + 1 internal + 1 utility)
+Total: **12 public APIs and 1 type** + **AFDATA logging** (3 protocol builders + 3 output functions + 1 internal + 1 utility + 4 CLI helpers + `OutputFormat`)
 
 ### Protocol Builders (returns dict)
 
@@ -187,6 +187,41 @@ assert parse_size("1.5K") == 1536
 assert parse_size("512") == 512
 ```
 
+### CLI Helpers (for tools built on AFDATA)
+
+Shared helpers that prevent flag-parsing drift between CLI tools. Use these instead of reimplementing `--output` and `--log` handling in each tool.
+
+```python
+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}}
+```
+
+**Canonical pattern** — parse all flags before doing work, emit JSONL errors to stdout:
+
+```python
+import sys
+from agent_first_data import (
+    OutputFormat, cli_parse_output, cli_parse_log_filters,
+    cli_output, build_cli_error, output_json,
+)
+
+try:
+    fmt = cli_parse_output(args.output)
+except ValueError as e:
+    print(output_json(build_cli_error(str(e))))
+    sys.exit(2)
+
+log = cli_parse_log_filters(args.log.split(",") if args.log else [])
+# ... do work ...
+print(cli_output(result, fmt))
+```
+
+See `examples/agent_cli.py` for the complete working example (`pytest examples/agent_cli.py`).
+
 ## Usage Examples
 
 ### Example 1: REST API
@@ -276,6 +311,7 @@ result = build_json_ok(
 )
 
 # Print JSONL to stdout (secrets redacted, one JSON object per line)
+# Channel policy: machine-readable protocol/log events must not use stderr.
 print(output_json(result))
 # {"code":"ok","result":{"status":"success"},"trace":{"api_key_secret":"***","duration_ms":250}}
 ```

{agent_first_data-0.3.0 → agent_first_data-0.4.0}/agent_first_data.egg-info/SOURCES.txt

@@ -2,10 +2,13 @@ README.md
 pyproject.toml
 agent_first_data/__init__.py
 agent_first_data/afdata_logging.py
+agent_first_data/cli.py
 agent_first_data/format.py
 agent_first_data.egg-info/PKG-INFO
 agent_first_data.egg-info/SOURCES.txt
 agent_first_data.egg-info/dependency_links.txt
 agent_first_data.egg-info/top_level.txt
 tests/test_afdata_logging.py
-tests/test_format.py
+tests/test_cli.py
+tests/test_format.py
+tests/test_no_stderr_policy.py

{agent_first_data-0.3.0 → agent_first_data-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-first-data"
-version = "0.3.0"
+version = "0.4.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.0/tests/test_cli.py

@@ -0,0 +1,98 @@
+"""Tests for agent_first_data CLI helpers."""
+import pytest
+from agent_first_data import (
+    OutputFormat,
+    cli_parse_output,
+    cli_parse_log_filters,
+    cli_output,
+    build_cli_error,
+    output_json,
+)
+
+
+# ── cli_parse_output ──────────────────────────────────────────────────────────
+
+def test_parse_output_all_formats():
+    assert cli_parse_output("json") is OutputFormat.JSON
+    assert cli_parse_output("yaml") is OutputFormat.YAML
+    assert cli_parse_output("plain") is OutputFormat.PLAIN
+
+
+def test_parse_output_rejects_unknown():
+    with pytest.raises(ValueError):
+        cli_parse_output("xml")
+    with pytest.raises(ValueError):
+        cli_parse_output("JSON")
+    with pytest.raises(ValueError):
+        cli_parse_output("")
+
+
+def test_parse_output_error_contains_value():
+    with pytest.raises(ValueError, match="toml"):
+        cli_parse_output("toml")
+    with pytest.raises(ValueError, match="json"):
+        cli_parse_output("toml")
+
+
+# ── cli_parse_log_filters ─────────────────────────────────────────────────────
+
+def test_parse_log_filters_trims_and_lowercases():
+    assert cli_parse_log_filters(["  Query  ", "ERROR"]) == ["query", "error"]
+
+
+def test_parse_log_filters_deduplicates():
+    assert cli_parse_log_filters(["query", "error", "Query", "query"]) == ["query", "error"]
+
+
+def test_parse_log_filters_removes_empty():
+    assert cli_parse_log_filters(["", "query", "  "]) == ["query"]
+
+
+def test_parse_log_filters_empty_list():
+    assert cli_parse_log_filters([]) == []
+
+
+def test_parse_log_filters_preserves_order():
+    assert cli_parse_log_filters(["startup", "request", "retry"]) == ["startup", "request", "retry"]
+
+
+# ── build_cli_error ───────────────────────────────────────────────────────────
+
+def test_build_cli_error_required_fields():
+    v = build_cli_error("missing --sql")
+    assert v["code"] == "error"
+    assert v["error_code"] == "invalid_request"
+    assert v["error"] == "missing --sql"
+    assert v["retryable"] is False
+    assert v["trace"]["duration_ms"] == 0
+
+
+def test_build_cli_error_is_valid_json():
+    import json
+    v = build_cli_error("oops")
+    s = output_json(v)
+    parsed = json.loads(s)
+    assert parsed["code"] == "error"
+
+
+# ── cli_output ────────────────────────────────────────────────────────────────
+
+def test_cli_output_dispatches_json():
+    v = {"code": "ok", "size_bytes": 1024}
+    out = cli_output(v, OutputFormat.JSON)
+    assert "size_bytes" in out   # json: raw keys, no suffix processing
+    assert "\n" not in out
+
+
+def test_cli_output_dispatches_yaml():
+    v = {"code": "ok", "size_bytes": 1024}
+    out = cli_output(v, OutputFormat.YAML)
+    assert out.startswith("---")
+    assert "size:" in out        # yaml: suffix stripped
+
+
+def test_cli_output_dispatches_plain():
+    v = {"code": "ok"}
+    out = cli_output(v, OutputFormat.PLAIN)
+    assert "\n" not in out
+    assert "code=ok" in out

agent_first_data-0.4.0/tests/test_no_stderr_policy.py

@@ -0,0 +1,23 @@
+"""Policy test: runtime library sources must not emit protocol/log events to stderr."""
+
+from pathlib import Path
+import re
+
+
+DISALLOWED = re.compile(
+    r"\bsys\.stderr\b|\bfile\s*=\s*sys\.stderr\b|\bstderr\.write\s*\(",
+)
+
+
+def test_no_stderr_usage_in_runtime_sources() -> None:
+    root = Path(__file__).resolve().parents[1] / "agent_first_data"
+    files = sorted(root.glob("*.py"))
+    assert files, "no python source files found"
+
+    violations: list[str] = []
+    for path in files:
+        for lineno, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
+            if DISALLOWED.search(line):
+                violations.append(f"{path.name}:{lineno}: {line.strip()}")
+
+    assert not violations, "stderr usage is disallowed:\n" + "\n".join(violations)