agent-first-data 0.1.0__tar.gz

agent_first_data-0.1.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: agent-first-data
+Version: 0.1.0
+Summary: Agent-First Data (AFD) — suffix-driven output formatting and protocol templates for AI agents
+License-Expression: MIT
+Requires-Python: >=3.9

agent_first_data-0.1.0/agent_first_data/__init__.py

@@ -0,0 +1,29 @@
+"""Agent-First Data (AFD) — suffix-driven output formatting and protocol templates."""
+
+from agent_first_data.format import (
+    OutputFormat,
+    to_yaml,
+    to_plain,
+    redact_secrets,
+    ok,
+    ok_trace,
+    error,
+    error_trace,
+    startup,
+    status,
+    parse_size,
+)
+
+__all__ = [
+    "OutputFormat",
+    "to_yaml",
+    "to_plain",
+    "redact_secrets",
+    "ok",
+    "ok_trace",
+    "error",
+    "error_trace",
+    "startup",
+    "status",
+    "parse_size",
+]

agent_first_data-0.1.0/agent_first_data/format.py

@@ -0,0 +1,352 @@
+"""AFD output formatting: JSON, YAML, plain text with suffix-driven transforms."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+
+
+class OutputFormat(Enum):
+    JSON = "json"
+    YAML = "yaml"
+    PLAIN = "plain"
+
+    def format(self, value: Any) -> str:
+        if self is OutputFormat.JSON:
+            return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+        if self is OutputFormat.YAML:
+            return to_yaml(value)
+        return to_plain(value)
+
+    def format_pretty(self, value: Any) -> str:
+        if self is OutputFormat.JSON:
+            return json.dumps(value, ensure_ascii=False, indent=2)
+        if self is OutputFormat.YAML:
+            return to_yaml(value)
+        return to_plain(value)
+
+
+# ═══════════════════════════════════════════
+# YAML
+# ═══════════════════════════════════════════
+
+
+def to_yaml(value: Any) -> str:
+    lines = ["---"]
+    _render_yaml(value, 0, lines)
+    return "\n".join(lines)
+
+
+def _render_yaml(value: Any, indent: int, lines: list[str]) -> None:
+    prefix = "  " * indent
+    if isinstance(value, dict):
+        for k, v in sorted(value.items(), key=lambda kv: kv[0].encode("utf-16-be")):
+            if isinstance(v, dict):
+                if v:
+                    lines.append(f"{prefix}{k}:")
+                    _render_yaml(v, indent + 1, lines)
+                else:
+                    lines.append(f"{prefix}{k}: {{}}")
+            elif isinstance(v, list):
+                if not v:
+                    lines.append(f"{prefix}{k}: []")
+                else:
+                    lines.append(f"{prefix}{k}:")
+                    for item in v:
+                        if isinstance(item, dict):
+                            lines.append(f"{prefix}  -")
+                            _render_yaml(item, indent + 2, lines)
+                        else:
+                            lines.append(f"{prefix}  - {_yaml_scalar(item)}")
+            else:
+                lines.append(f"{prefix}{k}: {_yaml_scalar(v)}")
+    else:
+        lines.append(f"{prefix}{_yaml_scalar(value)}")
+
+
+def _yaml_scalar(value: Any) -> str:
+    if isinstance(value, str):
+        escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+        escaped = escaped.replace("\n", "\\n").replace("\r", "\\r").replace("\t", "\\t")
+        return f'"{escaped}"'
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return str(value)
+    escaped = str(value).replace('"', '\\"')
+    return f'"{escaped}"'
+
+
+# ═══════════════════════════════════════════
+# Plain
+# ═══════════════════════════════════════════
+
+
+def to_plain(value: Any) -> str:
+    lines: list[str] = []
+    _render_plain(value, 0, lines)
+    return "\n".join(lines)
+
+
+def _render_plain(value: Any, indent: int, lines: list[str]) -> None:
+    prefix = "  " * indent
+    if isinstance(value, dict):
+        for k, v in sorted(value.items(), key=lambda kv: kv[0].encode("utf-16-be")):
+            if isinstance(v, dict):
+                lines.append(f"{prefix}{k}:")
+                _render_plain(v, indent + 1, lines)
+            elif isinstance(v, list):
+                if not v:
+                    lines.append(f"{prefix}{k}: []")
+                elif all(not isinstance(i, (dict, list)) for i in v):
+                    lines.append(f"{prefix}{k}:")
+                    for item in v:
+                        lines.append(f"{prefix}  - {_plain_scalar(item)}")
+                else:
+                    lines.append(f"{prefix}{k}:")
+                    for item in v:
+                        if isinstance(item, dict):
+                            lines.append(f"{prefix}  -")
+                            _render_plain(item, indent + 2, lines)
+                        else:
+                            lines.append(f"{prefix}  - {_plain_scalar(item)}")
+            else:
+                lines.append(f"{prefix}{k}: {_format_plain_field(k, v)}")
+    else:
+        lines.append(f"{prefix}{_plain_scalar(value)}")
+
+
+def _format_plain_field(key: str, value: Any) -> str:
+    lower = key.lower()
+
+    # Secret — always redact
+    if lower.endswith("_secret"):
+        return "***"
+
+    # Timestamps → RFC 3339
+    if lower.endswith("_epoch_ms"):
+        if isinstance(value, int) and not isinstance(value, bool):
+            return _format_rfc3339_ms(value)
+    if lower.endswith("_epoch_s"):
+        if isinstance(value, int) and not isinstance(value, bool):
+            return _format_rfc3339_ms(value * 1000)
+    if lower.endswith("_epoch_ns"):
+        if isinstance(value, int) and not isinstance(value, bool):
+            return _format_rfc3339_ms(value // 1_000_000)
+    if lower.endswith("_rfc3339"):
+        return _plain_scalar(value)
+
+    # Size
+    if lower.endswith("_bytes"):
+        if isinstance(value, int) and not isinstance(value, bool):
+            return _format_bytes_human(value)
+
+    # Percentage
+    if lower.endswith("_percent"):
+        if isinstance(value, (int, float)) and not isinstance(value, bool):
+            return f"{_plain_scalar(value)}%"
+
+    # Currency — Bitcoin
+    if lower.endswith("_msats"):
+        if isinstance(value, (int, float)) and not isinstance(value, bool):
+            return f"{_plain_scalar(value)}msats"
+    if lower.endswith("_sats"):
+        if isinstance(value, (int, float)) and not isinstance(value, bool):
+            return f"{_plain_scalar(value)}sats"
+    if lower.endswith("_btc"):
+        if isinstance(value, (int, float)) and not isinstance(value, bool):
+            return f"{_plain_scalar(value)} BTC"
+
+    # Currency — Fiat with symbol
+    if lower.endswith("_usd_cents"):
+        if isinstance(value, int) and not isinstance(value, bool) and value >= 0:
+            return f"${value // 100}.{value % 100:02d}"
+    if lower.endswith("_eur_cents"):
+        if isinstance(value, int) and not isinstance(value, bool) and value >= 0:
+            return f"\u20ac{value // 100}.{value % 100:02d}"
+    if lower.endswith("_jpy"):
+        if isinstance(value, int) and not isinstance(value, bool) and value >= 0:
+            return f"\u00a5{_format_with_commas(value)}"
+    # Currency — Generic _{code}_cents
+    if lower.endswith("_cents"):
+        code = _extract_currency_code(lower)
+        if code and isinstance(value, int) and not isinstance(value, bool) and value >= 0:
+            return f"{value // 100}.{value % 100:02d} {code.upper()}"
+
+    # Duration — long units
+    if lower.endswith("_minutes"):
+        if isinstance(value, (int, float)) and not isinstance(value, bool):
+            return f"{_plain_scalar(value)} minutes"
+    if lower.endswith("_hours"):
+        if isinstance(value, (int, float)) and not isinstance(value, bool):
+            return f"{_plain_scalar(value)} hours"
+    if lower.endswith("_days"):
+        if isinstance(value, (int, float)) and not isinstance(value, bool):
+            return f"{_plain_scalar(value)} days"
+
+    # Duration — ms
+    if lower.endswith("_ms") and not lower.endswith("_epoch_ms"):
+        if isinstance(value, (int, float)) and not isinstance(value, bool):
+            if value >= 1000:
+                return f"{value / 1000:.2f}s"
+            return f"{_plain_scalar(value)}ms"
+
+    # Duration — ns, us, s
+    if lower.endswith("_ns") and not lower.endswith("_epoch_ns"):
+        if isinstance(value, (int, float)) and not isinstance(value, bool):
+            return f"{_plain_scalar(value)}ns"
+    if lower.endswith("_us"):
+        if isinstance(value, (int, float)) and not isinstance(value, bool):
+            return f"{_plain_scalar(value)}\u03bcs"
+    if lower.endswith("_s") and not lower.endswith("_epoch_s"):
+        if isinstance(value, (int, float)) and not isinstance(value, bool):
+            return f"{_plain_scalar(value)}s"
+
+    return _plain_scalar(value)
+
+
+def _plain_scalar(value: Any) -> str:
+    if isinstance(value, str):
+        return value
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return str(value)
+    return str(value)
+
+
+# ═══════════════════════════════════════════
+# Secret redaction
+# ═══════════════════════════════════════════
+
+
+def redact_secrets(value: Any) -> Any:
+    """Walk a dict/list tree and redact any key ending in '_secret'."""
+    if isinstance(value, dict):
+        for k in value:
+            if k.lower().endswith("_secret") and isinstance(value[k], str):
+                value[k] = "***"
+            redact_secrets(value[k])
+    elif isinstance(value, list):
+        for item in value:
+            redact_secrets(item)
+    return value
+
+
+# ═══════════════════════════════════════════
+# AFD Protocol templates
+# ═══════════════════════════════════════════
+
+
+def ok(result: Any) -> dict:
+    return {"code": "ok", "result": result}
+
+
+def ok_trace(result: Any, trace: Any) -> dict:
+    return {"code": "ok", "result": result, "trace": trace}
+
+
+def error(message: str) -> dict:
+    return {"code": "error", "error": message}
+
+
+def error_trace(message: str, trace: Any) -> dict:
+    return {"code": "error", "error": message, "trace": trace}
+
+
+def startup(config: Any, args: Any, env: Any) -> dict:
+    return {"code": "startup", "config": config, "args": args, "env": env}
+
+
+def status(code: str, fields: dict | None = None) -> dict:
+    result = dict(fields) if fields else {}
+    result["code"] = code
+    return result
+
+
+# ═══════════════════════════════════════════
+# Helpers
+# ═══════════════════════════════════════════
+
+
+def _format_rfc3339_ms(ms: int) -> str:
+    try:
+        dt = datetime.fromtimestamp(ms / 1000, tz=timezone.utc)
+        return dt.strftime("%Y-%m-%dT%H:%M:%S.") + f"{ms % 1000:03d}Z"
+    except (OSError, OverflowError, ValueError):
+        return str(ms)
+
+
+def _format_bytes_human(n: int) -> str:
+    KB = 1024.0
+    MB = KB * 1024
+    GB = MB * 1024
+    TB = GB * 1024
+    sign = "-" if n < 0 else ""
+    b = float(abs(n))
+    if b >= TB:
+        return f"{sign}{b / TB:.1f}TB"
+    if b >= GB:
+        return f"{sign}{b / GB:.1f}GB"
+    if b >= MB:
+        return f"{sign}{b / MB:.1f}MB"
+    if b >= KB:
+        return f"{sign}{b / KB:.1f}KB"
+    return f"{n}B"
+
+
+def _format_with_commas(n: int) -> str:
+    return f"{n:,}"
+
+
+def parse_size(s: str) -> int | None:
+    """Parse a human-readable size string into bytes.
+
+    Accepts bare numbers or numbers followed by a unit letter (B/K/M/G/T).
+    Case-insensitive. Trims whitespace. Returns None for invalid input.
+    """
+    _multipliers = {"b": 1, "k": 1024, "m": 1024**2, "g": 1024**3, "t": 1024**4}
+    s = s.strip()
+    if not s:
+        return None
+    last = s[-1].lower()
+    if last in _multipliers:
+        num_str = s[:-1]
+        mult = _multipliers[last]
+    elif last.isdigit() or last == ".":
+        num_str = s
+        mult = 1
+    else:
+        return None
+    if not num_str:
+        return None
+    try:
+        n = int(num_str)
+        if n < 0:
+            return None
+        return n * mult
+    except ValueError:
+        pass
+    try:
+        f = float(num_str)
+        if f < 0 or f != f:  # NaN check
+            return None
+        return int(f * mult)
+    except (ValueError, OverflowError):
+        return None
+
+
+def _extract_currency_code(key: str) -> str | None:
+    without_cents = key.removesuffix("_cents")
+    if without_cents == key:
+        return None
+    idx = without_cents.rfind("_")
+    if idx < 0:
+        return None
+    return without_cents[idx + 1:]

agent_first_data-0.1.0/agent_first_data.egg-info/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: agent-first-data
+Version: 0.1.0
+Summary: Agent-First Data (AFD) — suffix-driven output formatting and protocol templates for AI agents
+License-Expression: MIT
+Requires-Python: >=3.9

agent_first_data-0.1.0/agent_first_data.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+pyproject.toml
+agent_first_data/__init__.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_format.py

agent_first_data-0.1.0/agent_first_data.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agent_first_data-0.1.0/agent_first_data.egg-info/top_level.txt

@@ -0,0 +1 @@
+agent_first_data

agent_first_data-0.1.0/pyproject.toml

@@ -0,0 +1,11 @@
+[project]
+name = "agent-first-data"
+version = "0.1.0"
+description = "Agent-First Data (AFD) — suffix-driven output formatting and protocol templates for AI agents"
+license = "MIT"
+requires-python = ">=3.9"
+dependencies = []
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"

agent_first_data-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agent_first_data-0.1.0/tests/test_format.py

@@ -0,0 +1,153 @@
+"""Tests for AFD output formatting — driven by shared spec/fixtures."""
+
+import json
+import os
+
+from agent_first_data import (
+    to_yaml,
+    to_plain,
+    redact_secrets,
+    ok,
+    ok_trace,
+    error,
+    error_trace,
+    startup,
+    status,
+    OutputFormat,
+)
+from agent_first_data.format import (
+    _format_bytes_human,
+    _format_with_commas,
+    _extract_currency_code,
+    parse_size,
+)
+
+FIXTURES_DIR = os.path.join(os.path.dirname(__file__), "..", "..", "spec", "fixtures")
+
+
+def _load(name):
+    with open(os.path.join(FIXTURES_DIR, name)) as f:
+        return json.load(f)
+
+
+# --- Plain fixtures ---
+
+
+def test_plain_fixtures():
+    for case in _load("plain.json"):
+        name = case["name"]
+        plain = to_plain(case["input"])
+        for s in case["contains"]:
+            assert s in plain, f"[plain/{name}] expected {s!r} in {plain!r}"
+        for s in case.get("not_contains", []):
+            assert s not in plain, f"[plain/{name}] unexpected {s!r} in {plain!r}"
+
+
+# --- YAML fixtures ---
+
+
+def test_yaml_fixtures():
+    for case in _load("yaml.json"):
+        name = case["name"]
+        yaml = to_yaml(case["input"])
+        if "starts_with" in case:
+            assert yaml.startswith(case["starts_with"]), f"[yaml/{name}] starts_with failed"
+        for s in case.get("contains", []):
+            assert s in yaml, f"[yaml/{name}] expected {s!r} in {yaml!r}"
+
+
+# --- Redact fixtures ---
+
+
+def test_redact_fixtures():
+    for case in _load("redact.json"):
+        name = case["name"]
+        inp = json.loads(json.dumps(case["input"]))  # deep copy
+        redact_secrets(inp)
+        assert inp == case["expected"], f"[redact/{name}] got {inp}"
+
+
+# --- Protocol fixtures ---
+
+
+def test_protocol_fixtures():
+    for case in _load("protocol.json"):
+        name = case["name"]
+        typ = case["type"]
+        args = case["args"]
+        if typ == "ok":
+            result = ok(args["result"])
+        elif typ == "ok_trace":
+            result = ok_trace(args["result"], args["trace"])
+        elif typ == "error":
+            result = error(args["message"])
+        elif typ == "error_trace":
+            result = error_trace(args["message"], args["trace"])
+        elif typ == "startup":
+            result = startup(args["config"], args["args"], args["env"])
+        elif typ == "status":
+            result = status(args["code"], args.get("fields"))
+        else:
+            raise ValueError(f"unknown type: {typ}")
+
+        if "expected" in case:
+            assert result == case["expected"], f"[protocol/{name}] got {result}"
+        if "expected_contains" in case:
+            for k, v in case["expected_contains"].items():
+                assert result[k] == v, f"[protocol/{name}] key {k}: got {result.get(k)}"
+
+
+# --- Exact fixtures ---
+
+
+def test_exact_fixtures():
+    for case in _load("exact.json"):
+        name = case["name"]
+        fmt = case["format"]
+        expected = case["expected"]
+        if fmt == "plain":
+            got = to_plain(case["input"])
+        elif fmt == "yaml":
+            got = to_yaml(case["input"])
+        else:
+            raise ValueError(f"unknown format: {fmt}")
+        assert got == expected, f"[exact/{name}]\ngot:  {got!r}\nwant: {expected!r}"
+
+
+# --- Helper fixtures ---
+
+
+def test_helper_fixtures():
+    for case in _load("helpers.json"):
+        name = case["name"]
+        for tc in case["cases"]:
+            inp, expected = tc
+            if name == "format_bytes_human":
+                got = _format_bytes_human(inp)
+                assert got == expected, f"[helpers/{name}({inp})] got {got!r}"
+            elif name == "format_with_commas":
+                got = _format_with_commas(inp)
+                assert got == expected, f"[helpers/{name}({inp})] got {got!r}"
+            elif name == "extract_currency_code":
+                got = _extract_currency_code(inp)
+                assert got == expected, f"[helpers/{name}({inp!r})] got {got!r}"
+            elif name == "parse_size":
+                got = parse_size(inp)
+                assert got == expected, f"[helpers/{name}({inp!r})] got {got!r}"
+
+
+# --- OutputFormat (not in fixtures — format-specific) ---
+
+
+def test_output_format_json():
+    assert OutputFormat.JSON.format({"status": "ok"}) == '{"status":"ok"}'
+
+
+def test_output_format_yaml():
+    out = OutputFormat.YAML.format({"status": "ok"})
+    assert out.startswith("---\n")
+    assert 'status: "ok"' in out
+
+
+def test_output_format_plain():
+    assert OutputFormat.PLAIN.format({"status": "ok"}) == "status: ok"