agent-first-data 0.26.2__tar.gz → 0.27.0__tar.gz

{agent_first_data-0.26.2 → agent_first_data-0.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.26.2
+Version: 0.27.0
 Summary: A naming convention that lets AI agents understand your data without being told what it means, plus a CLI and library for reading and safely editing structured JSON, TOML, YAML, dotenv, and INI documents.
 License-Expression: MIT
 Project-URL: Repository, https://github.com/agentfirstkit/agent-first-data
@@ -28,7 +28,7 @@ print(render(value, OutputFormat.JSON))
 print(render(value, OutputFormat.PLAIN))
 ```
 
-Useful names use Python casing: `render` (the single value x format x options -> str entry point; takes an `OutputFormat` and an optional keyword-only `options=`), `redacted_value`, `redact_url_secrets`, `redact_argv`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `is_valid_rfc3339`, `is_valid_bcp47`, `cli_parse_output`, `build_cli_error`, `build_cli_version`, `cli_handle_version_or_continue`, `decode_protocol_event`.
+Useful names use Python casing: `render` (the single value x format x options -> str entry point; takes an `OutputFormat` and an optional keyword-only `options=`), `redacted_value`, `redact_url_secrets`, `redact_argv`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `is_valid_rfc3339`, `is_valid_bcp47`, `cli_parse_output`, `build_cli_error`, `build_cli_version`, `decode_protocol_event`.
 
 ## Behavior Notes
 
@@ -37,7 +37,7 @@ Useful names use Python casing: `render` (the single value x format x options ->
 - YAML keeps original keys and values (structure-preserving, like JSON), sorting keys by UTF-16 code unit order and quoting/escaping unsafe keys and string scalars. Plain strips formatting suffixes, formats values, sorts the same way, and renders nested objects/arrays as canonical JSON.
 - Logging records use `kind:"log"` with a nested `log` payload and a separate `level` field, so error-level logs are not terminal protocol errors.
 - `build_cli_error(message, hint?)` returns a strict-ready CLI error with `error.retryable:false` and `trace:{}`.
-- Use `cli_handle_version_or_continue()` before argument parsing so `--version` always answers with a structured protocol-v1 `kind:"result"` version event. An explicit `--output` wins; pass the command's normal output as `default_format` (JSON when omitted), plus its value-taking global flag names.
+- Do not add a raw version/help pre-parser. Until the Python `CliSpec` compiler lands, applications should keep lifecycle parsing in their own parser rather than claim AFDATA closed-world help compatibility.
 
 ## Reference
 

{agent_first_data-0.26.2 → agent_first_data-0.27.0}/README.md

@@ -19,7 +19,7 @@ print(render(value, OutputFormat.JSON))
 print(render(value, OutputFormat.PLAIN))
 ```
 
-Useful names use Python casing: `render` (the single value x format x options -> str entry point; takes an `OutputFormat` and an optional keyword-only `options=`), `redacted_value`, `redact_url_secrets`, `redact_argv`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `is_valid_rfc3339`, `is_valid_bcp47`, `cli_parse_output`, `build_cli_error`, `build_cli_version`, `cli_handle_version_or_continue`, `decode_protocol_event`.
+Useful names use Python casing: `render` (the single value x format x options -> str entry point; takes an `OutputFormat` and an optional keyword-only `options=`), `redacted_value`, `redact_url_secrets`, `redact_argv`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `is_valid_rfc3339`, `is_valid_bcp47`, `cli_parse_output`, `build_cli_error`, `build_cli_version`, `decode_protocol_event`.
 
 ## Behavior Notes
 
@@ -28,7 +28,7 @@ Useful names use Python casing: `render` (the single value x format x options ->
 - YAML keeps original keys and values (structure-preserving, like JSON), sorting keys by UTF-16 code unit order and quoting/escaping unsafe keys and string scalars. Plain strips formatting suffixes, formats values, sorts the same way, and renders nested objects/arrays as canonical JSON.
 - Logging records use `kind:"log"` with a nested `log` payload and a separate `level` field, so error-level logs are not terminal protocol errors.
 - `build_cli_error(message, hint?)` returns a strict-ready CLI error with `error.retryable:false` and `trace:{}`.
-- Use `cli_handle_version_or_continue()` before argument parsing so `--version` always answers with a structured protocol-v1 `kind:"result"` version event. An explicit `--output` wins; pass the command's normal output as `default_format` (JSON when omitted), plus its value-taking global flag names.
+- Do not add a raw version/help pre-parser. Until the Python `CliSpec` compiler lands, applications should keep lifecycle parsing in their own parser rather than claim AFDATA closed-world help compatibility.
 
 ## Reference
 

{agent_first_data-0.26.2 → agent_first_data-0.27.0}/agent_first_data/__init__.py

@@ -44,7 +44,6 @@ from agent_first_data.cli import (
     build_cli_error,
     build_cli_version,
     cli_render_version,
-    cli_handle_version_or_continue,
 )
 
 __all__ = [
@@ -88,5 +87,4 @@ __all__ = [
     "build_cli_error",
     "build_cli_version",
     "cli_render_version",
-    "cli_handle_version_or_continue",
 ]

agent_first_data-0.27.0/agent_first_data/assets/cli-help-v2.schema.json

@@ -0,0 +1,115 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentfirstkit.org/schemas/agent-first-data/cli-help-v2.schema.json",
+  "title": "AFDATA CLI help v2 event",
+  "description": "One command's complete invocation help, carried by an AFDATA result event. Domain outcomes, side effects, and runtime error catalogs remain in the owning tool's documentation.",
+  "type": "object",
+  "required": [
+    "kind",
+    "result",
+    "trace"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "kind": {
+      "const": "result"
+    },
+    "result": {
+      "type": "object",
+      "required": [
+        "code",
+        "help"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "code": {
+          "const": "help"
+        },
+        "help": {
+          "$ref": "#/$defs/help"
+        }
+      }
+    },
+    "trace": {
+      "type": "object"
+    }
+  },
+  "$defs": {
+    "oneLine": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[^\\n\\r]+$"
+    },
+    "nonEmptyStringMap": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "help": {
+      "type": "object",
+      "required": [
+        "schema",
+        "command_path"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "schema": {
+          "const": "cli-help-v2"
+        },
+        "command_path": {
+          "$ref": "#/$defs/oneLine"
+        },
+        "about": {
+          "$ref": "#/$defs/oneLine"
+        },
+        "shapes": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/shape"
+          },
+          "description": "Every legal shape of this command, each complete. Help answers in one round trip; a second level could only pay off by omitting the optional arguments, which would then be undiscoverable."
+        },
+        "subcommands": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/oneLine"
+          }
+        },
+        "notes": {
+          "$ref": "#/$defs/nonEmptyStringMap",
+          "description": "Argument meanings. Arguments belong to the command rather than to one shape, so they are stated once."
+        },
+        "defaults": {
+          "type": "object",
+          "minProperties": 1,
+          "additionalProperties": true
+        }
+      }
+    },
+    "shape": {
+      "type": "object",
+      "required": [
+        "id",
+        "usage"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/oneLine"
+        },
+        "about": {
+          "$ref": "#/$defs/oneLine",
+          "description": "How this shape differs from its siblings. Absent when the command has only one shape, because its own description already covers it."
+        },
+        "usage": {
+          "$ref": "#/$defs/oneLine"
+        }
+      }
+    }
+  }
+}

agent_first_data-0.27.0/agent_first_data/assets/cli-spec-v1.schema.json

@@ -0,0 +1,334 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentfirstkit.org/schemas/agent-first-data/cli-spec-v1.schema.json",
+  "title": "AFDATA closed-world CLI spec v1",
+  "type": "object",
+  "required": [
+    "schema",
+    "name",
+    "version",
+    "lifecycle_output",
+    "commands"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema": {
+      "const": "cli-spec-v1"
+    },
+    "name": {
+      "$ref": "#/$defs/nonEmpty"
+    },
+    "version": {
+      "$ref": "#/$defs/nonEmpty"
+    },
+    "display_name": {
+      "$ref": "#/$defs/nonEmpty",
+      "description": "Human-facing product name, distinct from the binary identity in `name`."
+    },
+    "build": {
+      "$ref": "#/$defs/nonEmpty",
+      "description": "Opaque build identifier, such as a git commit SHA. Its meaning is the host's."
+    },
+    "about": {
+      "$ref": "#/$defs/nonEmpty"
+    },
+    "lifecycle_output": {
+      "$ref": "#/$defs/output"
+    },
+    "commands": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/command"
+      }
+    }
+  },
+  "$defs": {
+    "nonEmpty": {
+      "type": "string",
+      "minLength": 1
+    },
+    "argumentId": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]*$"
+    },
+    "command": {
+      "type": "object",
+      "required": [
+        "command_path",
+        "arguments",
+        "combinations"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "command_path": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]*$"
+          }
+        },
+        "about": {
+          "$ref": "#/$defs/nonEmpty"
+        },
+        "arguments": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/argument"
+          }
+        },
+        "combinations": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/combination"
+          }
+        }
+      }
+    },
+    "argument": {
+      "type": "object",
+      "required": [
+        "argument_id",
+        "syntax",
+        "value_type"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "argument_id": {
+          "$ref": "#/$defs/argumentId"
+        },
+        "syntax": {
+          "oneOf": [
+            {
+              "type": "object",
+              "required": [
+                "kind",
+                "name"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "kind": {
+                  "const": "long"
+                },
+                "name": {
+                  "type": "string",
+                  "pattern": "^--[a-z0-9][a-z0-9-]*$"
+                }
+              }
+            },
+            {
+              "type": "object",
+              "required": [
+                "kind",
+                "index"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "kind": {
+                  "const": "positional"
+                },
+                "index": {
+                  "type": "integer",
+                  "minimum": 0
+                }
+              }
+            }
+          ]
+        },
+        "value_type": {
+          "enum": [
+            "flag",
+            "string",
+            "i64",
+            "finite_f64",
+            "enum",
+            "json"
+          ]
+        },
+        "value_name": {
+          "$ref": "#/$defs/nonEmpty"
+        },
+        "enum_values": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/nonEmpty"
+          }
+        },
+        "default": true,
+        "repeatable": {
+          "const": true
+        },
+        "sensitive": {
+          "type": "boolean",
+          "description": "This argument's value must never be echoed back in help, errors, or logs."
+        },
+        "about": {
+          "$ref": "#/$defs/nonEmpty"
+        }
+      }
+    },
+    "combination": {
+      "type": "object",
+      "required": [
+        "combination_id",
+        "action_id",
+        "output"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "combination_id": {
+          "$ref": "#/$defs/nonEmpty"
+        },
+        "action_id": {
+          "$ref": "#/$defs/nonEmpty"
+        },
+        "about": {
+          "$ref": "#/$defs/nonEmpty"
+        },
+        "fixed": {
+          "type": "object",
+          "additionalProperties": {
+            "oneOf": [
+              {
+                "$ref": "#/$defs/nonEmpty"
+              },
+              {
+                "type": "object",
+                "required": [
+                  "one_of"
+                ],
+                "additionalProperties": false,
+                "properties": {
+                  "one_of": {
+                    "type": "array",
+                    "minItems": 1,
+                    "uniqueItems": true,
+                    "items": {
+                      "$ref": "#/$defs/nonEmpty"
+                    }
+                  }
+                }
+              }
+            ]
+          }
+        },
+        "required": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/argumentId"
+          }
+        },
+        "optional": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/argumentId"
+          }
+        },
+        "output": {
+          "$ref": "#/$defs/output"
+        }
+      }
+    },
+    "fileSinks": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "enum": [
+          "stdout",
+          "stderr"
+        ]
+      }
+    },
+    "output": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": [
+            "kind",
+            "file_sinks"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "const": "raw"
+            },
+            "file_sinks": {
+              "$ref": "#/$defs/fileSinks"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": [
+            "kind",
+            "lifecycle",
+            "formats",
+            "destinations",
+            "default_format",
+            "default_destination",
+            "file_sinks"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "const": "protocol"
+            },
+            "lifecycle": {
+              "enum": [
+                "finite",
+                "stream"
+              ]
+            },
+            "formats": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "enum": [
+                  "json",
+                  "yaml",
+                  "plain"
+                ]
+              }
+            },
+            "destinations": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "enum": [
+                  "split",
+                  "stdout",
+                  "stderr"
+                ]
+              }
+            },
+            "default_format": {
+              "enum": [
+                "json",
+                "yaml",
+                "plain"
+              ]
+            },
+            "default_destination": {
+              "enum": [
+                "split",
+                "stdout",
+                "stderr"
+              ]
+            },
+            "file_sinks": {
+              "$ref": "#/$defs/fileSinks"
+            }
+          }
+        }
+      ]
+    }
+  }
+}

agent_first_data-0.27.0/agent_first_data/assets/protocol-v1.schema.json

@@ -0,0 +1,178 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentfirstkit.org/schemas/agent-first-data/protocol-v1.schema.json",
+  "title": "Agent-First Data Protocol v1 Event (base profile)",
+  "description": "One protocol v1 event. The document root is the BASE profile: the mandatory MUST rules only — envelope shape and error payload requirements. Validate against the root unless you are claiming strict conformance; rejecting a base-conformant event is a false negative. The STRICT profile is `#/$defs/strictEvent`: it additionally requires the two recommendations (an object `trace` on every event, a boolean `error.retryable`). Stream lifecycle — (log | progress)* then exactly one result | error — is not expressible per event; validate a whole stream with `afdata validate` or `validate_protocol_stream`.",
+  "$ref": "#/$defs/event",
+  "$defs": {
+    "event": {
+      "title": "Protocol v1 event, base profile",
+      "description": "Top-level fields are closed: `kind`, the payload field whose name equals `kind`, and an optional `trace`.",
+      "type": "object",
+      "oneOf": [
+        {
+          "$ref": "#/$defs/resultEvent"
+        },
+        {
+          "$ref": "#/$defs/errorEvent"
+        },
+        {
+          "$ref": "#/$defs/progressEvent"
+        },
+        {
+          "$ref": "#/$defs/logEvent"
+        }
+      ]
+    },
+    "strictEvent": {
+      "title": "Protocol v1 event, strict profile",
+      "description": "The base profile plus the recommendations of the spec's `Validation profiles` section. Equivalent to `validate_protocol_event(event, strict = true)`.",
+      "allOf": [
+        {
+          "$ref": "#/$defs/event"
+        },
+        {
+          "$ref": "#/$defs/strictRecommendations"
+        }
+      ]
+    },
+    "strictRecommendations": {
+      "description": "What the strict profile adds on top of the base profile, and nothing else.",
+      "type": "object",
+      "required": [
+        "trace"
+      ],
+      "properties": {
+        "trace": {
+          "$ref": "#/$defs/trace"
+        }
+      },
+      "if": {
+        "type": "object",
+        "properties": {
+          "kind": {
+            "const": "error"
+          }
+        },
+        "required": [
+          "kind"
+        ]
+      },
+      "then": {
+        "properties": {
+          "error": {
+            "type": "object",
+            "required": [
+              "retryable"
+            ],
+            "properties": {
+              "retryable": {
+                "type": "boolean"
+              }
+            }
+          }
+        }
+      }
+    },
+    "trace": {
+      "description": "Execution context. Recommended on every event, required by the strict profile. Its fields are owned by the emitting tool.",
+      "type": "object"
+    },
+    "resultEvent": {
+      "type": "object",
+      "properties": {
+        "kind": {
+          "const": "result"
+        },
+        "result": true,
+        "trace": {
+          "$ref": "#/$defs/trace"
+        }
+      },
+      "required": [
+        "kind",
+        "result"
+      ],
+      "additionalProperties": false
+    },
+    "errorEvent": {
+      "type": "object",
+      "properties": {
+        "kind": {
+          "const": "error"
+        },
+        "error": {
+          "$ref": "#/$defs/errorPayload"
+        },
+        "trace": {
+          "$ref": "#/$defs/trace"
+        }
+      },
+      "required": [
+        "kind",
+        "error"
+      ],
+      "additionalProperties": false
+    },
+    "progressEvent": {
+      "type": "object",
+      "properties": {
+        "kind": {
+          "const": "progress"
+        },
+        "progress": true,
+        "trace": {
+          "$ref": "#/$defs/trace"
+        }
+      },
+      "required": [
+        "kind",
+        "progress"
+      ],
+      "additionalProperties": false
+    },
+    "logEvent": {
+      "type": "object",
+      "properties": {
+        "kind": {
+          "const": "log"
+        },
+        "log": true,
+        "trace": {
+          "$ref": "#/$defs/trace"
+        }
+      },
+      "required": [
+        "kind",
+        "log"
+      ],
+      "additionalProperties": false
+    },
+    "errorPayload": {
+      "description": "Extension fields go directly on this object; there is no `details` wrapper.",
+      "type": "object",
+      "properties": {
+        "code": {
+          "type": "string",
+          "minLength": 1
+        },
+        "message": {
+          "type": "string",
+          "minLength": 1
+        },
+        "hint": {
+          "description": "Actionable remediation. Omit it when there is none.",
+          "type": "string"
+        },
+        "retryable": {
+          "description": "Whether retrying the same call can succeed. Recommended, and left unconstrained by the base profile — the strict profile (`#/$defs/strictEvent`) requires it and requires a boolean."
+        }
+      },
+      "required": [
+        "code",
+        "message"
+      ],
+      "additionalProperties": true
+    }
+  }
+}