a2ea-py 0.1.0__py3-none-any.whl

a2ea/__init__.py

@@ -0,0 +1,11 @@
+"""Official Python SDK for the A2EA telemetry platform."""
+
+from .client import A2EAClient, get_default_client, set_default_client
+from .decorators import track
+
+__all__ = [
+    "A2EAClient",
+    "get_default_client",
+    "set_default_client",
+    "track",
+]

a2ea/client.py

@@ -0,0 +1,223 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import logging
+import os
+import queue
+import socket
+import threading
+import time
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+import requests
+
+LOGGER = logging.getLogger("a2ea.sdk")
+
+_DEFAULT_CLIENT: "A2EAClient | None" = None
+
+
+@dataclass
+class TelemetryJob:
+    event: dict[str, Any]
+    task_type: str
+    attempt: int = 0
+
+
+def set_default_client(client: "A2EAClient") -> None:
+    global _DEFAULT_CLIENT
+    _DEFAULT_CLIENT = client
+
+
+def get_default_client() -> "A2EAClient | None":
+    return _DEFAULT_CLIENT
+
+
+def _default_base_url() -> str:
+    return os.getenv("A2EA_BASE_URL", "https://aimodularity.com")
+
+
+def _default_agent_id() -> str:
+    hostname = socket.gethostname().replace(".", "-")
+    return f"agent_{hostname}_{os.getpid()}"
+
+
+class A2EAClient:
+    """Production-ready Python client for A2EA telemetry submission.
+
+    The client signs telemetry locally with the workspace API key, queues delivery in a
+    background thread, retries transient failures, and keeps a fallback buffer when the
+    transport path is unavailable.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        request_timeout: float = 5.0,
+        max_retries: int = 5,
+        retry_backoff_base_seconds: float = 0.75,
+        max_retry_delay_seconds: float = 30.0,
+        auto_set_default: bool = True,
+    ) -> None:
+        if not api_key or not api_key.strip():
+            raise ValueError("api_key is required")
+
+        self.base_url = (base_url or _default_base_url()).rstrip("/")
+        self.agent_id = agent_id or _default_agent_id()
+        self.api_key = api_key.strip()
+        self.signing_secret = self.api_key.encode("utf-8")
+        self.signing_key_id = "workspace-api-key"
+        self.request_timeout = request_timeout
+        self.max_retries = max_retries
+        self.retry_backoff_base_seconds = retry_backoff_base_seconds
+        self.max_retry_delay_seconds = max_retry_delay_seconds
+        self.session = requests.Session()
+        self._queue: "queue.Queue[TelemetryJob]" = queue.Queue()
+        self._fallback_buffer: list[dict[str, Any]] = []
+        self._worker = threading.Thread(target=self._worker_loop, name="a2ea-worker", daemon=True)
+        self._worker.start()
+
+        if auto_set_default:
+            set_default_client(self)
+
+    def track_agent(self, *, task_type: str, agent_name: Optional[str] = None):
+        from .decorators import track
+
+        return track(agent_name=agent_name or self.agent_id, task_type=task_type, client=self)
+
+    def send_telemetry(
+        self,
+        task_type: str,
+        duration_ms: int,
+        outcome: str,
+        *,
+        event_id: Optional[str] = None,
+        timestamp: Optional[str] = None,
+    ) -> Optional[str]:
+        event = self._build_event(
+            task_type=task_type,
+            duration_ms=duration_ms,
+            outcome=outcome,
+            event_id=event_id,
+            timestamp=timestamp,
+        )
+        self._queue.put(TelemetryJob(event=event, task_type=task_type))
+        return event["eventId"]
+
+    def get_local_fallback_buffer(self) -> list[dict[str, Any]]:
+        return list(self._fallback_buffer)
+
+    def flush(self, timeout: Optional[float] = None) -> None:
+        start = time.time()
+        while self._queue.unfinished_tasks:
+          if timeout is not None and (time.time() - start) > timeout:
+              raise TimeoutError("A2EA telemetry queue did not flush before timeout")
+          time.sleep(0.05)
+
+    def close(self) -> None:
+        self.session.close()
+
+    def _worker_loop(self) -> None:
+        while True:
+            job = self._queue.get()
+            try:
+                self._ship_event(job.event, job.task_type)
+            except Exception as exc:  # pragma: no cover - intentional silent fallback boundary
+                LOGGER.warning(
+                    "A2EA telemetry transport failed for %s (attempt %s/%s): %s",
+                    job.event.get("eventId"),
+                    job.attempt + 1,
+                    self.max_retries,
+                    exc,
+                )
+                self._handle_retry(job)
+            finally:
+                self._queue.task_done()
+
+    def _handle_retry(self, job: TelemetryJob) -> None:
+        next_attempt = job.attempt + 1
+        if next_attempt > self.max_retries:
+            LOGGER.warning(
+                "A2EA telemetry event %s exhausted retries; retaining in local fallback buffer",
+                job.event.get("eventId"),
+            )
+            self._fallback_buffer.append(job.event)
+            return
+
+        delay = min(self.retry_backoff_base_seconds * (2 ** job.attempt), self.max_retry_delay_seconds)
+        timer = threading.Timer(
+            delay,
+            lambda: self._queue.put(TelemetryJob(event=job.event, task_type=job.task_type, attempt=next_attempt)),
+        )
+        timer.daemon = True
+        timer.start()
+
+    def _ship_event(self, event: dict[str, Any], task_type: str) -> None:
+        payload = {
+            "taskType": task_type,
+            "telemetry": [event],
+        }
+
+        response = self.session.post(
+            f"{self.base_url}/api/v1/telemetry/score",
+            json=payload,
+            timeout=self.request_timeout,
+            headers={
+                "X-A2EA-API-Key": self.api_key,
+                "Content-Type": "application/json",
+            },
+        )
+        if response.status_code >= 300:
+            raise RuntimeError(f"telemetry score request failed with status {response.status_code}: {response.text}")
+
+    def _build_event(
+        self,
+        *,
+        task_type: str,
+        duration_ms: int,
+        outcome: str,
+        event_id: Optional[str],
+        timestamp: Optional[str],
+    ) -> dict[str, Any]:
+        normalized_outcome = "failure" if outcome == "failure" else "success"
+        event = {
+            "eventId": event_id or f"evt_{uuid.uuid4().hex}",
+            "agentId": self.agent_id,
+            "timestamp": timestamp or datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+            "durationMs": int(duration_ms),
+            "taskType": task_type,
+            "outcome": normalized_outcome,
+        }
+        signature = self._sign_payload(event)
+        event["verification"] = {
+            "keyId": self.signing_key_id,
+            "algorithm": "hmac_sha256",
+            "signature": signature,
+        }
+        return event
+
+    def _sign_payload(self, event: dict[str, Any]) -> str:
+        canonical = self._canonical_event_payload(event)
+        return hmac.new(self.signing_secret, canonical.encode("utf-8"), hashlib.sha256).hexdigest()
+
+    @staticmethod
+    def _canonical_event_payload(event: dict[str, Any]) -> str:
+        timestamp_value = str(event["timestamp"])
+        if timestamp_value.endswith("Z"):
+            timestamp_value = timestamp_value.replace("Z", "+00:00")
+        timestamp = datetime.fromisoformat(timestamp_value).astimezone(timezone.utc).isoformat()
+
+        return (
+            f"event_id={event['eventId']}|"
+            f"agent_id={event['agentId']}|"
+            f"timestamp={timestamp}|"
+            f"duration_ms={event['durationMs']}|"
+            f"task_type={event['taskType']}|"
+            f"outcome={event['outcome']}"
+        )

a2ea/decorators.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from functools import wraps
+from typing import Any, Callable, Optional, TypeVar
+
+from .client import get_default_client
+
+LOGGER = logging.getLogger("a2ea.sdk")
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def track(*, agent_name: Optional[str] = None, task_type: str, client=None) -> Callable[[F], F]:
+    """Framework-agnostic telemetry wrapper.
+
+    Captures only execution timing and success/failure metadata. It does not inspect
+    function arguments or private model payloads.
+    """
+
+    def decorator(func: F) -> F:
+        if asyncio.iscoroutinefunction(func):
+
+            @wraps(func)
+            async def async_wrapper(*args: Any, **kwargs: Any):
+                started = time.perf_counter()
+                selected_client = client or get_default_client()
+                try:
+                    result = await func(*args, **kwargs)
+                    if selected_client:
+                        selected_client.send_telemetry(
+                            task_type=task_type,
+                            duration_ms=int((time.perf_counter() - started) * 1000),
+                            outcome="success",
+                        )
+                    return result
+                except Exception:
+                    if selected_client:
+                        try:
+                            selected_client.send_telemetry(
+                                task_type=task_type,
+                                duration_ms=int((time.perf_counter() - started) * 1000),
+                                outcome="failure",
+                            )
+                        except Exception as exc:  # pragma: no cover
+                            LOGGER.warning("A2EA async telemetry fallback failed for %s: %s", agent_name or task_type, exc)
+                    raise
+
+            return async_wrapper  # type: ignore[return-value]
+
+        @wraps(func)
+        def sync_wrapper(*args: Any, **kwargs: Any):
+            started = time.perf_counter()
+            selected_client = client or get_default_client()
+            try:
+                result = func(*args, **kwargs)
+                if selected_client:
+                    selected_client.send_telemetry(
+                        task_type=task_type,
+                        duration_ms=int((time.perf_counter() - started) * 1000),
+                        outcome="success",
+                    )
+                return result
+            except Exception:
+                if selected_client:
+                    try:
+                        selected_client.send_telemetry(
+                            task_type=task_type,
+                            duration_ms=int((time.perf_counter() - started) * 1000),
+                            outcome="failure",
+                        )
+                    except Exception as exc:  # pragma: no cover
+                        LOGGER.warning("A2EA sync telemetry fallback failed for %s: %s", agent_name or task_type, exc)
+                raise
+
+        return sync_wrapper  # type: ignore[return-value]
+
+    return decorator

a2ea_py-0.1.0.dist-info/METADATA

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: a2ea-py
+Version: 0.1.0
+Summary: Official Python client for the A2EA telemetry and attribution platform.
+Author: AI Blockchain Ventures
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+
+# a2ea-py
+
+Official Python SDK for sending A2EA telemetry to the backend.
+
+## Install
+
+```bash
+pip install a2ea-py
+```
+
+## Quickstart
+
+```python
+from a2ea import A2EAClient
+
+client = A2EAClient(
+    api_key="your X-A2EA-API-Key"
+)
+
+
+@client.track_agent(task_type="data_processing")
+def run_agent(payload):
+    return process(payload)
+```
+
+### Optional configuration
+
+- `base_url`
+  - Defaults to `https://aimodularity.com`
+  - Set this when testing locally against `http://127.0.0.1:4080`
+- `agent_id`
+  - Optional override if you want to assign a fixed agent identifier instead of the default host/process-based value
+
+Example for local development:
+
+```python
+from a2ea import A2EAClient
+
+client = A2EAClient(
+    api_key="your X-A2EA-API-Key",
+    base_url="http://127.0.0.1:4080",
+    agent_id="agent_pipeline_014",
+)
+```
+
+## What the client sends
+
+Each tracked function call produces:
+
+- `eventId`
+- `agentId`
+- `timestamp`
+- `durationMs`
+- `taskType`
+- `outcome`
+- `verification`
+
+The verification payload is signed locally with HMAC-SHA256 using the workspace API key so the backend can verify the telemetry envelope.
+
+## Reliability behavior
+
+- submission runs in a background thread
+- transient failures are retried with backoff
+- exhausted events are retained in a local fallback buffer
+
+## Local package test commands
+
+```bash
+python -m unittest discover tests
+python -m build
+pip install dist/a2ea_py-0.1.0-py3-none-any.whl
+```

a2ea_py-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+a2ea/__init__.py,sha256=-NaIVonjIwfexKJBn_ebOjP6aA4ZyAWTD5pGhpF8SAo,259
+a2ea/client.py,sha256=81aRoHEM90a763yKJnmUAZTDLcfpNz3KzXucIEytdAM,7481
+a2ea/decorators.py,sha256=9rrX9BngkaaS4awgG3e2aKDUR2r36W-0kK2Nsq30fW8,3127
+a2ea_py-0.1.0.dist-info/METADATA,sha256=yVG1USUeYqugrjxUTrWn4XuiOSMsFivumglzIjWtous,1780
+a2ea_py-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+a2ea_py-0.1.0.dist-info/top_level.txt,sha256=dZP6uZHNRs2dE5AMlwt4JmDlVSAVh_Mj08ZVaRlcLqI,5
+a2ea_py-0.1.0.dist-info/RECORD,,

a2ea_py-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

a2ea_py-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+a2ea