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

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.2.3
-Summary: Agent-First Data (AFD) — suffix-driven output formatting and protocol templates for AI agents
+Version: 0.3.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
 Requires-Python: >=3.9
@@ -9,7 +9,7 @@ Description-Content-Type: text/markdown
 
 # agent-first-data
 
-**Agent-First Data (AFD)** — Suffix-driven output formatting and protocol templates for AI agents.
+**Agent-First Data (AFDATA)** — Suffix-driven output formatting and protocol templates for AI agents.
 
 The field name is the schema. Agents read `latency_ms` and know milliseconds, `api_key_secret` and know to redact, no external schema needed.
 
@@ -27,24 +27,39 @@ A backup tool invoked from the CLI — flags, env vars, and config all use the s
 API_KEY_SECRET=sk-1234 cloudback --timeout-s 30 --max-file-size-bytes 10737418240 /data/backup.tar.gz
 ```
 
-The tool reads env vars, flags, and config — all with AFD suffixes — and emits a startup message:
+For CLI diagnostics, enable log categories explicitly:
+
+```bash
+--log startup,request,progress,retry,redirect
+--verbose   # shorthand for all categories
+```
+
+Without these flags, startup diagnostics should stay off by default.
+
+The tool reads env vars, flags, and config — all with AFDATA suffixes — and can emit a startup diagnostic event:
 
 ```python
 from agent_first_data import *
 import os
 
-startup = build_json_startup(
-    {"timeout_s": 30, "max_file_size_bytes": 10737418240},
-    {"input_path": "/data/backup.tar.gz"},
-    {"API_KEY_SECRET": os.environ.get("API_KEY_SECRET")},
+startup = build_json(
+    "log",
+    {
+        "event": "startup",
+        "config": {"timeout_s": 30, "max_file_size_bytes": 10737418240},
+        "args": {"input_path": "/data/backup.tar.gz"},
+        "env": {"API_KEY_SECRET": os.environ.get("API_KEY_SECRET")},
+    },
+    trace=None,
 )
 ```
 
 Three output formats, same data:
 
 ```
-JSON:  {"code":"startup","args":{"input_path":"/data/backup.tar.gz"},"config":{"max_file_size_bytes":10737418240,"timeout_s":30},"env":{"API_KEY_SECRET":"***"}}
-YAML:  code: "startup"
+JSON:  {"code":"log","event":"startup","args":{"input_path":"/data/backup.tar.gz"},"config":{"max_file_size_bytes":10737418240,"timeout_s":30},"env":{"API_KEY_SECRET":"***"}}
+YAML:  code: "log"
+       event: "startup"
        args:
          input_path: "/data/backup.tar.gz"
        config:
@@ -52,23 +67,20 @@ YAML:  code: "startup"
          timeout: "30s"
        env:
          API_KEY: "***"
-Plain: args.input_path=/data/backup.tar.gz code=startup config.max_file_size=10.0GB config.timeout=30s env.API_KEY=***
+Plain: args.input_path=/data/backup.tar.gz code=log event=startup config.max_file_size=10.0GB config.timeout=30s env.API_KEY=***
 ```
 
 `--timeout-s` → `timeout_s` → `timeout: 30s`. `API_KEY_SECRET` → `API_KEY: "***"`. The suffix is the schema.
 
 ## API Reference
 
-Total: **9 public APIs** + **AFD logging** (4 protocol builders + 3 output functions + 1 internal + 1 utility)
+Total: **8 public APIs** + **AFDATA logging** (3 protocol builders + 3 output functions + 1 internal + 1 utility)
 
 ### Protocol Builders (returns dict)
 
-Build AFD protocol structures. Return dict objects for API responses.
+Build AFDATA protocol structures. Return dict objects for API responses.
 
 ```python
-# Startup (configuration)
-build_json_startup(config: Any, args: Any, env: Any) -> dict
-
 # Success (result)
 build_json_ok(result: Any, trace: Any = None) -> dict
 
@@ -86,10 +98,15 @@ build_json(code: str, fields: Any, trace: Any = None) -> dict
 from agent_first_data import *
 
 # Startup
-startup = build_json_startup(
-    {"api_key_secret": "sk-123", "timeout_s": 30},
-    {"config_path": "config.yml"},
-    {"RUST_LOG": "info"},
+startup = build_json(
+    "log",
+    {
+        "event": "startup",
+        "config": {"api_key_secret": "sk-123", "timeout_s": 30},
+        "args": {"config_path": "config.yml"},
+        "env": {"RUST_LOG": "info"},
+    },
+    trace=None,
 )
 
 # Success (always include trace)
@@ -196,14 +213,20 @@ async def get_user(user_id: int):
 from agent_first_data import *
 
 # 1. Startup
-startup = build_json_startup(
-    {"api_key_secret": "sk-sensitive-key", "timeout_s": 30},
-    {"input_path": "data.json"},
-    {"RUST_LOG": "info"},
+startup = build_json(
+    "log",
+    {
+        "event": "startup",
+        "config": {"api_key_secret": "sk-sensitive-key", "timeout_s": 30},
+        "args": {"input_path": "data.json"},
+        "env": {"RUST_LOG": "info"},
+    },
+    trace=None,
 )
 print(output_yaml(startup))
 # ---
-# code: "startup"
+# code: "log"
+# event: "startup"
 # args:
 #   input_path: "data.json"
 # config:
@@ -294,23 +317,23 @@ print(output_plain(data))
 # api_key=*** cache_ttl=3600s count=42 created_at=2025-02-07T00:00:00.000Z file_size=5.0MB payment=50000000msats price=$99.99 request_timeout=5.0s success_rate=95.5% user_name=alice
 ```
 
-## AFD Logging
+## AFDATA Logging
 
-AFD-compliant structured logging via Python's `logging` module. Every log line is formatted using the library's own `output_json`/`output_plain`/`output_yaml` functions. Span fields are carried via `contextvars` (async-safe), automatically flattened into each log line.
+AFDATA-compliant structured logging via Python's `logging` module. Every log line is formatted using the library's own `output_json`/`output_plain`/`output_yaml` functions. Span fields are carried via `contextvars` (async-safe), automatically flattened into each log line.
 
 ### API
 
 ```python
 from agent_first_data import init_logging_json, init_logging_plain, init_logging_yaml
-from agent_first_data.afd_logging import AfdHandler, get_logger, span
+from agent_first_data.afdata_logging import AfdataHandler, get_logger, span
 
-# Convenience initializers — set up the root logger with AFD output to stdout
+# Convenience initializers — set up the root logger with AFDATA output to stdout
 init_logging_json(level="INFO")    # Single-line JSONL (secrets redacted, original keys)
 init_logging_plain(level="INFO")   # Single-line logfmt (keys stripped, values formatted)
 init_logging_yaml(level="INFO")    # Multi-line YAML (keys stripped, values formatted)
 
 # Low-level — create a handler for custom logger stacks
-AfdHandler(format="json")  # format: "json" | "plain" | "yaml"
+AfdataHandler(format="json")  # format: "json" | "plain" | "yaml"
 
 # Logger with default fields (returns logging.LoggerAdapter)
 get_logger(name, **fields)
@@ -391,8 +414,8 @@ The `code` field defaults to the log level. Override with an explicit field:
 from agent_first_data import get_logger
 
 logger = get_logger("myapp")
-logger.info("Server ready", extra={"code": "startup"})
-# {"timestamp_epoch_ms":...,"message":"Server ready","target":"myapp","code":"startup"}
+logger.info("Server ready", extra={"code": "log", "event": "startup"})
+# {"timestamp_epoch_ms":...,"message":"Server ready","target":"myapp","code":"log","event":"startup"}
 ```
 
 ### Output Fields
@@ -410,7 +433,7 @@ Every log line contains:
 
 ### Log Output Formats
 
-All three formats use the library's own output functions, so AFD suffix processing applies to log fields too:
+All three formats use the library's own output functions, so AFDATA suffix processing applies to log fields too:
 
 | Format | Function | Keys | Values | Use case |
 |:-------|:---------|:-----|:-------|:---------|
@@ -440,6 +463,21 @@ All formats automatically redact `_secret` fields.
 - **Currency**: `_msats`, `_sats`, `_btc`, `_usd_cents`, `_eur_cents`, `_jpy`, `_{code}_cents`
 - **Other**: `_percent`, `_secret` (auto-redacted in all formats)
 
+## Repository
+
+This package is part of the [agent-first-data](https://github.com/cmnspore/agent-first-data) repository, which also contains:
+
+- **`spec/`** — Full AFDATA specification with suffix definitions, protocol format rules, and cross-language test fixtures
+- **`skills/`** — AI coding agent skill for working with AFDATA conventions
+
+To run tests, clone the full repository (tests use shared cross-language fixtures from `spec/fixtures/`):
+
+```bash
+git clone https://github.com/cmnspore/agent-first-data
+cd agent-first-data/python
+python -m pytest
+```
+
 ## License
 
 MIT

agent_first_data-0.2.3/PKG-INFO → agent_first_data-0.3.0/README.md

@@ -1,15 +1,6 @@
-Metadata-Version: 2.4
-Name: agent-first-data
-Version: 0.2.3
-Summary: Agent-First Data (AFD) — suffix-driven output formatting and protocol templates for AI agents
-License-Expression: MIT
-Project-URL: Repository, https://github.com/cmnspore/agent-first-data
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-
 # agent-first-data
 
-**Agent-First Data (AFD)** — Suffix-driven output formatting and protocol templates for AI agents.
+**Agent-First Data (AFDATA)** — Suffix-driven output formatting and protocol templates for AI agents.
 
 The field name is the schema. Agents read `latency_ms` and know milliseconds, `api_key_secret` and know to redact, no external schema needed.
 
@@ -27,24 +18,39 @@ A backup tool invoked from the CLI — flags, env vars, and config all use the s
 API_KEY_SECRET=sk-1234 cloudback --timeout-s 30 --max-file-size-bytes 10737418240 /data/backup.tar.gz
 ```
 
-The tool reads env vars, flags, and config — all with AFD suffixes — and emits a startup message:
+For CLI diagnostics, enable log categories explicitly:
+
+```bash
+--log startup,request,progress,retry,redirect
+--verbose   # shorthand for all categories
+```
+
+Without these flags, startup diagnostics should stay off by default.
+
+The tool reads env vars, flags, and config — all with AFDATA suffixes — and can emit a startup diagnostic event:
 
 ```python
 from agent_first_data import *
 import os
 
-startup = build_json_startup(
-    {"timeout_s": 30, "max_file_size_bytes": 10737418240},
-    {"input_path": "/data/backup.tar.gz"},
-    {"API_KEY_SECRET": os.environ.get("API_KEY_SECRET")},
+startup = build_json(
+    "log",
+    {
+        "event": "startup",
+        "config": {"timeout_s": 30, "max_file_size_bytes": 10737418240},
+        "args": {"input_path": "/data/backup.tar.gz"},
+        "env": {"API_KEY_SECRET": os.environ.get("API_KEY_SECRET")},
+    },
+    trace=None,
 )
 ```
 
 Three output formats, same data:
 
 ```
-JSON:  {"code":"startup","args":{"input_path":"/data/backup.tar.gz"},"config":{"max_file_size_bytes":10737418240,"timeout_s":30},"env":{"API_KEY_SECRET":"***"}}
-YAML:  code: "startup"
+JSON:  {"code":"log","event":"startup","args":{"input_path":"/data/backup.tar.gz"},"config":{"max_file_size_bytes":10737418240,"timeout_s":30},"env":{"API_KEY_SECRET":"***"}}
+YAML:  code: "log"
+       event: "startup"
        args:
          input_path: "/data/backup.tar.gz"
        config:
@@ -52,23 +58,20 @@ YAML:  code: "startup"
          timeout: "30s"
        env:
          API_KEY: "***"
-Plain: args.input_path=/data/backup.tar.gz code=startup config.max_file_size=10.0GB config.timeout=30s env.API_KEY=***
+Plain: args.input_path=/data/backup.tar.gz code=log event=startup config.max_file_size=10.0GB config.timeout=30s env.API_KEY=***
 ```
 
 `--timeout-s` → `timeout_s` → `timeout: 30s`. `API_KEY_SECRET` → `API_KEY: "***"`. The suffix is the schema.
 
 ## API Reference
 
-Total: **9 public APIs** + **AFD logging** (4 protocol builders + 3 output functions + 1 internal + 1 utility)
+Total: **8 public APIs** + **AFDATA logging** (3 protocol builders + 3 output functions + 1 internal + 1 utility)
 
 ### Protocol Builders (returns dict)
 
-Build AFD protocol structures. Return dict objects for API responses.
+Build AFDATA protocol structures. Return dict objects for API responses.
 
 ```python
-# Startup (configuration)
-build_json_startup(config: Any, args: Any, env: Any) -> dict
-
 # Success (result)
 build_json_ok(result: Any, trace: Any = None) -> dict
 
@@ -86,10 +89,15 @@ build_json(code: str, fields: Any, trace: Any = None) -> dict
 from agent_first_data import *
 
 # Startup
-startup = build_json_startup(
-    {"api_key_secret": "sk-123", "timeout_s": 30},
-    {"config_path": "config.yml"},
-    {"RUST_LOG": "info"},
+startup = build_json(
+    "log",
+    {
+        "event": "startup",
+        "config": {"api_key_secret": "sk-123", "timeout_s": 30},
+        "args": {"config_path": "config.yml"},
+        "env": {"RUST_LOG": "info"},
+    },
+    trace=None,
 )
 
 # Success (always include trace)
@@ -196,14 +204,20 @@ async def get_user(user_id: int):
 from agent_first_data import *
 
 # 1. Startup
-startup = build_json_startup(
-    {"api_key_secret": "sk-sensitive-key", "timeout_s": 30},
-    {"input_path": "data.json"},
-    {"RUST_LOG": "info"},
+startup = build_json(
+    "log",
+    {
+        "event": "startup",
+        "config": {"api_key_secret": "sk-sensitive-key", "timeout_s": 30},
+        "args": {"input_path": "data.json"},
+        "env": {"RUST_LOG": "info"},
+    },
+    trace=None,
 )
 print(output_yaml(startup))
 # ---
-# code: "startup"
+# code: "log"
+# event: "startup"
 # args:
 #   input_path: "data.json"
 # config:
@@ -294,23 +308,23 @@ print(output_plain(data))
 # api_key=*** cache_ttl=3600s count=42 created_at=2025-02-07T00:00:00.000Z file_size=5.0MB payment=50000000msats price=$99.99 request_timeout=5.0s success_rate=95.5% user_name=alice
 ```
 
-## AFD Logging
+## AFDATA Logging
 
-AFD-compliant structured logging via Python's `logging` module. Every log line is formatted using the library's own `output_json`/`output_plain`/`output_yaml` functions. Span fields are carried via `contextvars` (async-safe), automatically flattened into each log line.
+AFDATA-compliant structured logging via Python's `logging` module. Every log line is formatted using the library's own `output_json`/`output_plain`/`output_yaml` functions. Span fields are carried via `contextvars` (async-safe), automatically flattened into each log line.
 
 ### API
 
 ```python
 from agent_first_data import init_logging_json, init_logging_plain, init_logging_yaml
-from agent_first_data.afd_logging import AfdHandler, get_logger, span
+from agent_first_data.afdata_logging import AfdataHandler, get_logger, span
 
-# Convenience initializers — set up the root logger with AFD output to stdout
+# Convenience initializers — set up the root logger with AFDATA output to stdout
 init_logging_json(level="INFO")    # Single-line JSONL (secrets redacted, original keys)
 init_logging_plain(level="INFO")   # Single-line logfmt (keys stripped, values formatted)
 init_logging_yaml(level="INFO")    # Multi-line YAML (keys stripped, values formatted)
 
 # Low-level — create a handler for custom logger stacks
-AfdHandler(format="json")  # format: "json" | "plain" | "yaml"
+AfdataHandler(format="json")  # format: "json" | "plain" | "yaml"
 
 # Logger with default fields (returns logging.LoggerAdapter)
 get_logger(name, **fields)
@@ -391,8 +405,8 @@ The `code` field defaults to the log level. Override with an explicit field:
 from agent_first_data import get_logger
 
 logger = get_logger("myapp")
-logger.info("Server ready", extra={"code": "startup"})
-# {"timestamp_epoch_ms":...,"message":"Server ready","target":"myapp","code":"startup"}
+logger.info("Server ready", extra={"code": "log", "event": "startup"})
+# {"timestamp_epoch_ms":...,"message":"Server ready","target":"myapp","code":"log","event":"startup"}
 ```
 
 ### Output Fields
@@ -410,7 +424,7 @@ Every log line contains:
 
 ### Log Output Formats
 
-All three formats use the library's own output functions, so AFD suffix processing applies to log fields too:
+All three formats use the library's own output functions, so AFDATA suffix processing applies to log fields too:
 
 | Format | Function | Keys | Values | Use case |
 |:-------|:---------|:-----|:-------|:---------|
@@ -440,6 +454,21 @@ All formats automatically redact `_secret` fields.
 - **Currency**: `_msats`, `_sats`, `_btc`, `_usd_cents`, `_eur_cents`, `_jpy`, `_{code}_cents`
 - **Other**: `_percent`, `_secret` (auto-redacted in all formats)
 
+## Repository
+
+This package is part of the [agent-first-data](https://github.com/cmnspore/agent-first-data) repository, which also contains:
+
+- **`spec/`** — Full AFDATA specification with suffix definitions, protocol format rules, and cross-language test fixtures
+- **`skills/`** — AI coding agent skill for working with AFDATA conventions
+
+To run tests, clone the full repository (tests use shared cross-language fixtures from `spec/fixtures/`):
+
+```bash
+git clone https://github.com/cmnspore/agent-first-data
+cd agent-first-data/python
+python -m pytest
+```
+
 ## License
 
 MIT

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

@@ -1,7 +1,6 @@
-"""Agent-First Data (AFD) — suffix-driven output formatting and protocol templates."""
+"""Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates."""
 
 from agent_first_data.format import (
-    build_json_startup,
     build_json_ok,
     build_json_error,
     build_json,
@@ -12,9 +11,9 @@ from agent_first_data.format import (
     parse_size,
 )
 
-from agent_first_data.afd_logging import (
-    AfdHandler,
-    AfdJsonHandler,
+from agent_first_data.afdata_logging import (
+    AfdataHandler,
+    AfdataJsonHandler,
     init_json as init_logging_json,
     init_plain as init_logging_plain,
     init_yaml as init_logging_yaml,
@@ -23,7 +22,6 @@ from agent_first_data.afd_logging import (
 )
 
 __all__ = [
-    "build_json_startup",
     "build_json_ok",
     "build_json_error",
     "build_json",
@@ -32,8 +30,8 @@ __all__ = [
     "output_plain",
     "internal_redact_secrets",
     "parse_size",
-    "AfdHandler",
-    "AfdJsonHandler",
+    "AfdataHandler",
+    "AfdataJsonHandler",
     "init_logging_json",
     "init_logging_plain",
     "init_logging_yaml",

agent_first_data-0.2.3/agent_first_data/afd_logging.py → agent_first_data-0.3.0/agent_first_data/afdata_logging.py

@@ -1,4 +1,4 @@
-"""AFD-compliant structured logging.
+"""AFDATA-compliant structured logging.
 
 Outputs log events using agent-first-data formatting functions:
 - JSON: single-line JSONL via output_json (secrets redacted, original keys)
@@ -8,7 +8,7 @@ Outputs log events using agent-first-data formatting functions:
 Span fields are carried via contextvars (async-safe).
 
 Usage:
-    from agent_first_data.afd_logging import init_json, init_plain, init_yaml, span
+    from agent_first_data.afdata_logging import init_json, init_plain, init_yaml, span
     import logging
 
     init_json("INFO")   # or init_plain("INFO") or init_yaml("DEBUG")
@@ -25,7 +25,7 @@ from typing import Any
 
 from agent_first_data.format import output_json, output_plain, output_yaml
 
-_span_fields: ContextVar[dict[str, Any]] = ContextVar("afd_span", default={})
+_span_fields: ContextVar[dict[str, Any]] = ContextVar("afdata_span", default={})
 
 _LEVEL_TO_CODE = {
     "CRITICAL": "error",
@@ -38,8 +38,8 @@ _LEVEL_TO_CODE = {
 }
 
 
-class AfdHandler(logging.Handler):
-    """Logging handler that outputs AFD-compliant log lines to stdout.
+class AfdataHandler(logging.Handler):
+    """Logging handler that outputs AFDATA-compliant log lines to stdout.
 
     Formats output using the library's own output_json/output_plain/output_yaml.
     """
@@ -64,7 +64,7 @@ class AfdHandler(logging.Handler):
 
         # Event fields (passed via extra= in logging calls)
         has_code = False
-        extra = getattr(record, "_afd_fields", None)
+        extra = getattr(record, "_afdata_fields", None)
         if extra:
             for k, v in extra.items():
                 if k == "code":
@@ -88,11 +88,11 @@ class AfdHandler(logging.Handler):
 
 
 # Keep old name as alias for backwards compat
-AfdJsonHandler = AfdHandler
+AfdataJsonHandler = AfdataHandler
 
 
-class _AfdLoggerAdapter(logging.LoggerAdapter):
-    """Logger adapter that passes extra fields to AfdHandler."""
+class _AfdataLoggerAdapter(logging.LoggerAdapter):
+    """Logger adapter that passes extra fields to AfdataHandler."""
 
     def process(self, msg: str, kwargs: Any) -> tuple[str, Any]:
         extra = kwargs.get("extra", {})
@@ -100,29 +100,29 @@ class _AfdLoggerAdapter(logging.LoggerAdapter):
             merged = {**self.extra, **extra}
         else:
             merged = extra
-        kwargs["extra"] = {"_afd_fields": merged}
+        kwargs["extra"] = {"_afdata_fields": merged}
         return msg, kwargs
 
 
 def _init_with_format(format: str, level: str = "INFO") -> None:
-    handler = AfdHandler(format=format)
+    handler = AfdataHandler(format=format)
     root = logging.getLogger()
     root.handlers = [handler]
     root.setLevel(getattr(logging, level.upper(), logging.INFO))
 
 
 def init_json(level: str = "INFO") -> None:
-    """Initialize the root logger with AFD JSON output to stdout."""
+    """Initialize the root logger with AFDATA JSON output to stdout."""
     _init_with_format("json", level)
 
 
 def init_plain(level: str = "INFO") -> None:
-    """Initialize the root logger with AFD plain/logfmt output to stdout."""
+    """Initialize the root logger with AFDATA plain/logfmt output to stdout."""
     _init_with_format("plain", level)
 
 
 def init_yaml(level: str = "INFO") -> None:
-    """Initialize the root logger with AFD YAML output to stdout."""
+    """Initialize the root logger with AFDATA YAML output to stdout."""
     _init_with_format("yaml", level)
 
 
@@ -133,7 +133,7 @@ def get_logger(name: str, **fields: Any) -> logging.LoggerAdapter:
     Use for per-module or per-component fields.
     """
     base = logging.getLogger(name)
-    return _AfdLoggerAdapter(base, fields)
+    return _AfdataLoggerAdapter(base, fields)
 
 
 class span:

{agent_first_data-0.2.3 → agent_first_data-0.3.0}/agent_first_data/format.py

@@ -1,6 +1,6 @@
-"""AFD output formatting and protocol templates.
+"""AFDATA output formatting and protocol templates.
 
-9 public APIs: 4 protocol builders + 3 output formatters + 1 redaction + 1 utility.
+8 public APIs: 3 protocol builders + 3 output formatters + 1 redaction + 1 utility.
 """
 
 from __future__ import annotations
@@ -16,11 +16,6 @@ from typing import Any
 # ═══════════════════════════════════════════
 
 
-def build_json_startup(config: Any, args: Any, env: Any) -> dict:
-    """Build {code: "startup", config, args, env}."""
-    return {"code": "startup", "config": config, "args": args, "env": env}
-
-
 def build_json_ok(result: Any, trace: Any = None) -> dict:
     """Build {code: "ok", result, trace?}."""
     m: dict = {"code": "ok", "result": result}

agent_first_data-0.2.3/README.md → agent_first_data-0.3.0/agent_first_data.egg-info/PKG-INFO

@@ -1,6 +1,15 @@
+Metadata-Version: 2.4
+Name: agent-first-data
+Version: 0.3.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
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
 # agent-first-data
 
-**Agent-First Data (AFD)** — Suffix-driven output formatting and protocol templates for AI agents.
+**Agent-First Data (AFDATA)** — Suffix-driven output formatting and protocol templates for AI agents.
 
 The field name is the schema. Agents read `latency_ms` and know milliseconds, `api_key_secret` and know to redact, no external schema needed.
 
@@ -18,24 +27,39 @@ A backup tool invoked from the CLI — flags, env vars, and config all use the s
 API_KEY_SECRET=sk-1234 cloudback --timeout-s 30 --max-file-size-bytes 10737418240 /data/backup.tar.gz
 ```
 
-The tool reads env vars, flags, and config — all with AFD suffixes — and emits a startup message:
+For CLI diagnostics, enable log categories explicitly:
+
+```bash
+--log startup,request,progress,retry,redirect
+--verbose   # shorthand for all categories
+```
+
+Without these flags, startup diagnostics should stay off by default.
+
+The tool reads env vars, flags, and config — all with AFDATA suffixes — and can emit a startup diagnostic event:
 
 ```python
 from agent_first_data import *
 import os
 
-startup = build_json_startup(
-    {"timeout_s": 30, "max_file_size_bytes": 10737418240},
-    {"input_path": "/data/backup.tar.gz"},
-    {"API_KEY_SECRET": os.environ.get("API_KEY_SECRET")},
+startup = build_json(
+    "log",
+    {
+        "event": "startup",
+        "config": {"timeout_s": 30, "max_file_size_bytes": 10737418240},
+        "args": {"input_path": "/data/backup.tar.gz"},
+        "env": {"API_KEY_SECRET": os.environ.get("API_KEY_SECRET")},
+    },
+    trace=None,
 )
 ```
 
 Three output formats, same data:
 
 ```
-JSON:  {"code":"startup","args":{"input_path":"/data/backup.tar.gz"},"config":{"max_file_size_bytes":10737418240,"timeout_s":30},"env":{"API_KEY_SECRET":"***"}}
-YAML:  code: "startup"
+JSON:  {"code":"log","event":"startup","args":{"input_path":"/data/backup.tar.gz"},"config":{"max_file_size_bytes":10737418240,"timeout_s":30},"env":{"API_KEY_SECRET":"***"}}
+YAML:  code: "log"
+       event: "startup"
        args:
          input_path: "/data/backup.tar.gz"
        config:
@@ -43,23 +67,20 @@ YAML:  code: "startup"
          timeout: "30s"
        env:
          API_KEY: "***"
-Plain: args.input_path=/data/backup.tar.gz code=startup config.max_file_size=10.0GB config.timeout=30s env.API_KEY=***
+Plain: args.input_path=/data/backup.tar.gz code=log event=startup config.max_file_size=10.0GB config.timeout=30s env.API_KEY=***
 ```
 
 `--timeout-s` → `timeout_s` → `timeout: 30s`. `API_KEY_SECRET` → `API_KEY: "***"`. The suffix is the schema.
 
 ## API Reference
 
-Total: **9 public APIs** + **AFD logging** (4 protocol builders + 3 output functions + 1 internal + 1 utility)
+Total: **8 public APIs** + **AFDATA logging** (3 protocol builders + 3 output functions + 1 internal + 1 utility)
 
 ### Protocol Builders (returns dict)
 
-Build AFD protocol structures. Return dict objects for API responses.
+Build AFDATA protocol structures. Return dict objects for API responses.
 
 ```python
-# Startup (configuration)
-build_json_startup(config: Any, args: Any, env: Any) -> dict
-
 # Success (result)
 build_json_ok(result: Any, trace: Any = None) -> dict
 
@@ -77,10 +98,15 @@ build_json(code: str, fields: Any, trace: Any = None) -> dict
 from agent_first_data import *
 
 # Startup
-startup = build_json_startup(
-    {"api_key_secret": "sk-123", "timeout_s": 30},
-    {"config_path": "config.yml"},
-    {"RUST_LOG": "info"},
+startup = build_json(
+    "log",
+    {
+        "event": "startup",
+        "config": {"api_key_secret": "sk-123", "timeout_s": 30},
+        "args": {"config_path": "config.yml"},
+        "env": {"RUST_LOG": "info"},
+    },
+    trace=None,
 )
 
 # Success (always include trace)
@@ -187,14 +213,20 @@ async def get_user(user_id: int):
 from agent_first_data import *
 
 # 1. Startup
-startup = build_json_startup(
-    {"api_key_secret": "sk-sensitive-key", "timeout_s": 30},
-    {"input_path": "data.json"},
-    {"RUST_LOG": "info"},
+startup = build_json(
+    "log",
+    {
+        "event": "startup",
+        "config": {"api_key_secret": "sk-sensitive-key", "timeout_s": 30},
+        "args": {"input_path": "data.json"},
+        "env": {"RUST_LOG": "info"},
+    },
+    trace=None,
 )
 print(output_yaml(startup))
 # ---
-# code: "startup"
+# code: "log"
+# event: "startup"
 # args:
 #   input_path: "data.json"
 # config:
@@ -285,23 +317,23 @@ print(output_plain(data))
 # api_key=*** cache_ttl=3600s count=42 created_at=2025-02-07T00:00:00.000Z file_size=5.0MB payment=50000000msats price=$99.99 request_timeout=5.0s success_rate=95.5% user_name=alice
 ```
 
-## AFD Logging
+## AFDATA Logging
 
-AFD-compliant structured logging via Python's `logging` module. Every log line is formatted using the library's own `output_json`/`output_plain`/`output_yaml` functions. Span fields are carried via `contextvars` (async-safe), automatically flattened into each log line.
+AFDATA-compliant structured logging via Python's `logging` module. Every log line is formatted using the library's own `output_json`/`output_plain`/`output_yaml` functions. Span fields are carried via `contextvars` (async-safe), automatically flattened into each log line.
 
 ### API
 
 ```python
 from agent_first_data import init_logging_json, init_logging_plain, init_logging_yaml
-from agent_first_data.afd_logging import AfdHandler, get_logger, span
+from agent_first_data.afdata_logging import AfdataHandler, get_logger, span
 
-# Convenience initializers — set up the root logger with AFD output to stdout
+# Convenience initializers — set up the root logger with AFDATA output to stdout
 init_logging_json(level="INFO")    # Single-line JSONL (secrets redacted, original keys)
 init_logging_plain(level="INFO")   # Single-line logfmt (keys stripped, values formatted)
 init_logging_yaml(level="INFO")    # Multi-line YAML (keys stripped, values formatted)
 
 # Low-level — create a handler for custom logger stacks
-AfdHandler(format="json")  # format: "json" | "plain" | "yaml"
+AfdataHandler(format="json")  # format: "json" | "plain" | "yaml"
 
 # Logger with default fields (returns logging.LoggerAdapter)
 get_logger(name, **fields)
@@ -382,8 +414,8 @@ The `code` field defaults to the log level. Override with an explicit field:
 from agent_first_data import get_logger
 
 logger = get_logger("myapp")
-logger.info("Server ready", extra={"code": "startup"})
-# {"timestamp_epoch_ms":...,"message":"Server ready","target":"myapp","code":"startup"}
+logger.info("Server ready", extra={"code": "log", "event": "startup"})
+# {"timestamp_epoch_ms":...,"message":"Server ready","target":"myapp","code":"log","event":"startup"}
 ```
 
 ### Output Fields
@@ -401,7 +433,7 @@ Every log line contains:
 
 ### Log Output Formats
 
-All three formats use the library's own output functions, so AFD suffix processing applies to log fields too:
+All three formats use the library's own output functions, so AFDATA suffix processing applies to log fields too:
 
 | Format | Function | Keys | Values | Use case |
 |:-------|:---------|:-----|:-------|:---------|
@@ -431,6 +463,21 @@ All formats automatically redact `_secret` fields.
 - **Currency**: `_msats`, `_sats`, `_btc`, `_usd_cents`, `_eur_cents`, `_jpy`, `_{code}_cents`
 - **Other**: `_percent`, `_secret` (auto-redacted in all formats)
 
+## Repository
+
+This package is part of the [agent-first-data](https://github.com/cmnspore/agent-first-data) repository, which also contains:
+
+- **`spec/`** — Full AFDATA specification with suffix definitions, protocol format rules, and cross-language test fixtures
+- **`skills/`** — AI coding agent skill for working with AFDATA conventions
+
+To run tests, clone the full repository (tests use shared cross-language fixtures from `spec/fixtures/`):
+
+```bash
+git clone https://github.com/cmnspore/agent-first-data
+cd agent-first-data/python
+python -m pytest
+```
+
 ## License
 
 MIT

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

@@ -1,11 +1,11 @@
 README.md
 pyproject.toml
 agent_first_data/__init__.py
-agent_first_data/afd_logging.py
+agent_first_data/afdata_logging.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_afd_logging.py
+tests/test_afdata_logging.py
 tests/test_format.py

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

@@ -1,7 +1,7 @@
 [project]
 name = "agent-first-data"
-version = "0.2.3"
-description = "Agent-First Data (AFD) — suffix-driven output formatting and protocol templates for AI agents"
+version = "0.3.0"
+description = "Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates for AI agents"
 license = "MIT"
 readme = "README.md"
 requires-python = ">=3.9"

agent_first_data-0.2.3/tests/test_afd_logging.py → agent_first_data-0.3.0/tests/test_afdata_logging.py

@@ -1,4 +1,4 @@
-"""Tests for AFD logging module."""
+"""Tests for AFDATA logging module."""
 
 import json
 import logging
@@ -6,7 +6,7 @@ import sys
 from io import StringIO
 from unittest.mock import patch
 
-from agent_first_data.afd_logging import AfdHandler, AfdJsonHandler, init_json, init_plain, init_yaml, span, get_logger
+from agent_first_data.afdata_logging import AfdataHandler, AfdataJsonHandler, init_json, init_plain, init_yaml, span, get_logger
 
 
 def capture_log(fn):
@@ -20,9 +20,9 @@ def capture_log(fn):
 
 
 def make_logger(name="test"):
-    """Create a fresh logger with AfdJsonHandler."""
+    """Create a fresh logger with AfdataJsonHandler."""
     logger = logging.getLogger(name)
-    logger.handlers = [AfdJsonHandler()]
+    logger.handlers = [AfdataJsonHandler()]
     logger.setLevel(logging.DEBUG)
     return logger
 
@@ -108,15 +108,16 @@ class TestCodeOverride:
         logger = make_logger("test_code")
         adapter = get_logger("test_code")
 
-        m = capture_log(lambda: adapter.info("ready", extra={"code": "startup"}))
-        assert m["code"] == "startup"
+        m = capture_log(lambda: adapter.info("ready", extra={"code": "log", "event": "startup"}))
+        assert m["code"] == "log"
+        assert m["event"] == "startup"
 
 
 class TestGetLogger:
     def test_default_fields(self):
-        # Ensure root logger has AfdJsonHandler
+        # Ensure root logger has AfdataJsonHandler
         root = logging.getLogger()
-        root.handlers = [AfdJsonHandler()]
+        root.handlers = [AfdataJsonHandler()]
         root.setLevel(logging.DEBUG)
 
         adapter = get_logger("test_adapter", component="myservice")
@@ -137,7 +138,7 @@ def capture_raw(fn):
 class TestPlainFormat:
     def test_plain_output(self):
         logger = logging.getLogger("test_plain")
-        logger.handlers = [AfdHandler(format="plain")]
+        logger.handlers = [AfdataHandler(format="plain")]
         logger.setLevel(logging.DEBUG)
 
         output = capture_raw(lambda: logger.info("hello"))
@@ -157,7 +158,7 @@ class TestPlainFormat:
 class TestYamlFormat:
     def test_yaml_output(self):
         logger = logging.getLogger("test_yaml")
-        logger.handlers = [AfdHandler(format="yaml")]
+        logger.handlers = [AfdataHandler(format="yaml")]
         logger.setLevel(logging.DEBUG)
 
         output = capture_raw(lambda: logger.info("hello"))

{agent_first_data-0.2.3 → agent_first_data-0.3.0}/tests/test_format.py

@@ -1,10 +1,9 @@
-"""Tests for AFD output formatting — driven by shared spec/fixtures."""
+"""Tests for AFDATA output formatting — driven by shared spec/fixtures."""
 
 import json
 import os
 
 from agent_first_data import (
-    build_json_startup,
     build_json_ok,
     build_json_error,
     build_json,
@@ -52,8 +51,6 @@ def test_protocol_fixtures():
             result = build_json_error(args["message"])
         elif typ == "error_trace":
             result = build_json_error(args["message"], args["trace"])
-        elif typ == "startup":
-            result = build_json_startup(args["config"], args["args"], args["env"])
         elif typ == "status":
             result = build_json(args["code"], args.get("fields"))
         else: