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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.5.0
+Version: 0.6.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
@@ -84,8 +84,8 @@ Build AFDATA protocol structures. Return dict objects for transport payloads.
 # Success (result)
 build_json_ok(result: Any, trace: Any = None) -> dict
 
-# Error (simple message)
-build_json_error(message: str, trace: Any = None) -> dict
+# Error (simple message, optional hint)
+build_json_error(message: str, hint: str = None, trace: Any = None) -> dict
 
 # Generic (any code + fields)
 build_json(code: str, fields: Any, trace: Any = None) -> dict
@@ -118,6 +118,9 @@ response = build_json_ok(
 # Error
 err = build_json_error("user not found", trace={"duration_ms": 5})
 
+# Error with hint
+err_hint = build_json_error("wallet not found", hint="list wallets with: afpay wallet list", trace={"duration_ms": 5})
+
 # Specific error code
 not_found = build_json(
     "not_found",
@@ -204,7 +207,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
-build_cli_error(message: str) -> dict            # {code:"error", error_code:"invalid_request", retryable:False, trace:{duration_ms:0}}
+build_cli_error(message: str, hint: str = None) -> dict  # {code:"error", error_code:"invalid_request", hint?, retryable:False, trace:{duration_ms:0}}
 ```
 
 **Canonical pattern** — parse all flags before doing work, emit JSONL errors to stdout:

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

@@ -75,8 +75,8 @@ Build AFDATA protocol structures. Return dict objects for transport payloads.
 # Success (result)
 build_json_ok(result: Any, trace: Any = None) -> dict
 
-# Error (simple message)
-build_json_error(message: str, trace: Any = None) -> dict
+# Error (simple message, optional hint)
+build_json_error(message: str, hint: str = None, trace: Any = None) -> dict
 
 # Generic (any code + fields)
 build_json(code: str, fields: Any, trace: Any = None) -> dict
@@ -109,6 +109,9 @@ response = build_json_ok(
 # Error
 err = build_json_error("user not found", trace={"duration_ms": 5})
 
+# Error with hint
+err_hint = build_json_error("wallet not found", hint="list wallets with: afpay wallet list", trace={"duration_ms": 5})
+
 # Specific error code
 not_found = build_json(
     "not_found",
@@ -195,7 +198,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
-build_cli_error(message: str) -> dict            # {code:"error", error_code:"invalid_request", retryable:False, trace:{duration_ms:0}}
+build_cli_error(message: str, hint: str = None) -> dict  # {code:"error", error_code:"invalid_request", hint?, retryable:False, trace:{duration_ms:0}}
 ```
 
 **Canonical pattern** — parse all flags before doing work, emit JSONL errors to stdout:

{agent_first_data-0.5.0 → agent_first_data-0.6.0}/agent_first_data/cli.py

@@ -69,7 +69,7 @@ def cli_output(value: Any, format: OutputFormat) -> str:
     return output_json(value)
 
 
-def build_cli_error(message: str) -> dict:
+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.
@@ -83,10 +83,13 @@ def build_cli_error(message: str) -> dict:
     >>> v["retryable"]
     False
     """
-    return {
+    m: dict = {
         "code": "error",
         "error_code": "invalid_request",
         "error": message,
         "retryable": False,
         "trace": {"duration_ms": 0},
     }
+    if hint is not None:
+        m["hint"] = hint
+    return m

{agent_first_data-0.5.0 → agent_first_data-0.6.0}/agent_first_data/format.py

@@ -25,9 +25,11 @@ def build_json_ok(result: Any, trace: Any = None) -> dict:
     return m
 
 
-def build_json_error(message: str, trace: Any = None) -> dict:
-    """Build {code: "error", error: message, trace?}."""
+def build_json_error(message: str, hint: str | None = None, trace: Any = None) -> dict:
+    """Build {code: "error", error: message, hint?, trace?}."""
     m: dict = {"code": "error", "error": message}
+    if hint is not None:
+        m["hint"] = hint
     if trace is not None:
         m["trace"] = trace
     return m

{agent_first_data-0.5.0 → agent_first_data-0.6.0}/agent_first_data.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.5.0
+Version: 0.6.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
@@ -84,8 +84,8 @@ Build AFDATA protocol structures. Return dict objects for transport payloads.
 # Success (result)
 build_json_ok(result: Any, trace: Any = None) -> dict
 
-# Error (simple message)
-build_json_error(message: str, trace: Any = None) -> dict
+# Error (simple message, optional hint)
+build_json_error(message: str, hint: str = None, trace: Any = None) -> dict
 
 # Generic (any code + fields)
 build_json(code: str, fields: Any, trace: Any = None) -> dict
@@ -118,6 +118,9 @@ response = build_json_ok(
 # Error
 err = build_json_error("user not found", trace={"duration_ms": 5})
 
+# Error with hint
+err_hint = build_json_error("wallet not found", hint="list wallets with: afpay wallet list", trace={"duration_ms": 5})
+
 # Specific error code
 not_found = build_json(
     "not_found",
@@ -204,7 +207,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
-build_cli_error(message: str) -> dict            # {code:"error", error_code:"invalid_request", retryable:False, trace:{duration_ms:0}}
+build_cli_error(message: str, hint: str = None) -> dict  # {code:"error", error_code:"invalid_request", hint?, retryable:False, trace:{duration_ms:0}}
 ```
 
 **Canonical pattern** — parse all flags before doing work, emit JSONL errors to stdout:

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

@@ -1,6 +1,6 @@
 [project]
 name = "agent-first-data"
-version = "0.5.0"
+version = "0.6.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.5.0 → agent_first_data-0.6.0}/tests/test_cli.py

@@ -75,6 +75,16 @@ def test_build_cli_error_is_valid_json():
     assert parsed["code"] == "error"
 
 
+def test_build_cli_error_with_hint():
+    v = build_cli_error("bad flag", hint="try --help")
+    assert v["hint"] == "try --help"
+
+
+def test_build_cli_error_without_hint_has_no_hint_key():
+    v = build_cli_error("oops")
+    assert "hint" not in v
+
+
 # ── cli_output ────────────────────────────────────────────────────────────────
 
 def test_cli_output_dispatches_json():

{agent_first_data-0.5.0 → agent_first_data-0.6.0}/tests/test_format.py

@@ -53,7 +53,11 @@ def test_protocol_fixtures():
         elif typ == "error":
             result = build_json_error(args["message"])
         elif typ == "error_trace":
-            result = build_json_error(args["message"], args["trace"])
+            result = build_json_error(args["message"], trace=args["trace"])
+        elif typ == "error_hint":
+            result = build_json_error(args["message"], hint=args.get("hint"))
+        elif typ == "error_hint_trace":
+            result = build_json_error(args["message"], hint=args.get("hint"), trace=args["trace"])
         elif typ == "status":
             result = build_json(args["code"], args.get("fields"))
         else: