axonpush 0.0.1__py3-none-any.whl

axonpush/__init__.py

@@ -0,0 +1,48 @@
+"""AxonPush — Python SDK for real-time event infrastructure for AI agent systems."""
+
+from axonpush._tracing import TraceContext, get_or_create_trace
+from axonpush._version import __version__
+from axonpush.client import AsyncAxonPush, AxonPush
+from axonpush.exceptions import (
+    AuthenticationError,
+    AxonPushError,
+    ForbiddenError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from axonpush.models.apps import App
+from axonpush.models.channels import Channel
+from axonpush.models.events import Event, EventType
+from axonpush.models.traces import TraceListItem, TraceSummary
+from axonpush.models.webhooks import DeliveryStatus, WebhookDelivery, WebhookEndpoint
+
+__all__ = [
+    # Clients
+    "AxonPush",
+    "AsyncAxonPush",
+    # Models
+    "App",
+    "Channel",
+    "DeliveryStatus",
+    "Event",
+    "EventType",
+    "TraceListItem",
+    "TraceSummary",
+    "WebhookDelivery",
+    "WebhookEndpoint",
+    # Tracing
+    "TraceContext",
+    "get_or_create_trace",
+    # Exceptions
+    "AuthenticationError",
+    "AxonPushError",
+    "ForbiddenError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+    "ValidationError",
+    # Meta
+    "__version__",
+]

axonpush/_auth.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+
+class AuthConfig:
+    """Immutable auth configuration. Thread-safe (read-only after construction)."""
+
+    __slots__ = ("api_key", "tenant_id", "base_url")
+
+    def __init__(
+        self,
+        api_key: str,
+        tenant_id: str,
+        base_url: str,
+    ) -> None:
+        self.api_key = api_key
+        self.tenant_id = tenant_id
+        self.base_url = base_url.rstrip("/")
+
+    def headers(self) -> dict[str, str]:
+        return {
+            "X-API-Key": self.api_key,
+            "x-tenant-id": self.tenant_id,
+            "Content-Type": "application/json",
+        }

axonpush/_http.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Any, Dict, Generator, Iterator, Optional
+
+import httpx
+from httpx_sse import EventSource, connect_sse, aconnect_sse
+
+from axonpush._auth import AuthConfig
+from axonpush.exceptions import (
+    AuthenticationError,
+    AxonPushError,
+    ForbiddenError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+_ERROR_MAP: Dict[int, type] = {
+    400: ValidationError,
+    401: AuthenticationError,
+    403: ForbiddenError,
+    404: NotFoundError,
+    429: RateLimitError,
+}
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    if response.is_success:
+        return
+
+    status = response.status_code
+    try:
+        body = response.json()
+        message = body.get("message", response.text)
+        if isinstance(message, list):
+            message = "; ".join(str(m) for m in message)
+    except Exception:
+        message = response.text or f"HTTP {status}"
+
+    if status == 429:
+        retry_after_raw = response.headers.get("Retry-After")
+        retry_after = float(retry_after_raw) if retry_after_raw else None
+        raise RateLimitError(str(message), retry_after=retry_after)
+
+    exc_cls = _ERROR_MAP.get(status)
+    if exc_cls is not None:
+        raise exc_cls(str(message), status_code=status)
+
+    if status >= 500:
+        raise ServerError(str(message), status_code=status)
+
+    raise AxonPushError(str(message), status_code=status)
+
+
+class SyncTransport:
+    """Synchronous HTTP transport backed by httpx.Client."""
+
+    def __init__(self, auth: AuthConfig, timeout: float = 30.0) -> None:
+        self._auth = auth
+        self._client = httpx.Client(
+            base_url=auth.base_url,
+            headers=auth.headers(),
+            timeout=timeout,
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        response = self._client.request(method, path, json=json, params=params)
+        _raise_for_status(response)
+        if not response.content:
+            return None
+        return response.json()
+
+    @contextmanager
+    def stream_sse(
+        self, path: str, params: Optional[Dict[str, Any]] = None
+    ) -> Generator[EventSource, None, None]:
+        with connect_sse(
+            self._client, "GET", path, params=params or {}
+        ) as event_source:
+            yield event_source
+
+    def close(self) -> None:
+        self._client.close()
+
+
+class AsyncTransport:
+    """Asynchronous HTTP transport backed by httpx.AsyncClient."""
+
+    def __init__(self, auth: AuthConfig, timeout: float = 30.0) -> None:
+        self._auth = auth
+        self._client = httpx.AsyncClient(
+            base_url=auth.base_url,
+            headers=auth.headers(),
+            timeout=timeout,
+        )
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        response = await self._client.request(method, path, json=json, params=params)
+        _raise_for_status(response)
+        if not response.content:
+            return None
+        return response.json()
+
+    async def close(self) -> None:
+        await self._client.aclose()

axonpush/_tracing.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import threading
+import uuid
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+
+_current_trace: ContextVar[TraceContext | None] = ContextVar("_current_trace", default=None)
+
+
+@dataclass
+class TraceContext:
+    """Holds a trace_id and generates sequential span IDs.
+
+    Thread-safe via a lock on the span counter.
+    Task-safe via contextvars (each asyncio Task inherits its own copy).
+    """
+
+    trace_id: str = field(default_factory=lambda: f"tr_{uuid.uuid4().hex[:16]}")
+    _span_counter: int = field(default=0, repr=False)
+    _lock: threading.Lock = field(default_factory=threading.Lock, repr=False)
+
+    def next_span_id(self) -> str:
+        with self._lock:
+            self._span_counter += 1
+            return f"sp_{self.trace_id[3:]}_{self._span_counter:04d}"
+
+
+def get_or_create_trace(trace_id: str | None = None) -> TraceContext:
+    """Get the current trace from context, or create a new one.
+
+    If *trace_id* is provided, always creates a fresh context with that ID.
+    If *trace_id* is None and a context already exists, returns it.
+    Otherwise creates a new context with an auto-generated ID.
+    """
+    if trace_id is not None:
+        ctx = TraceContext(trace_id=trace_id)
+        _current_trace.set(ctx)
+        return ctx
+
+    existing = _current_trace.get()
+    if existing is not None:
+        return existing
+
+    ctx = TraceContext()
+    _current_trace.set(ctx)
+    return ctx
+
+
+def current_trace() -> TraceContext | None:
+    """Return the current trace context, or None if not set."""
+    return _current_trace.get()

axonpush/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

axonpush/client.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from axonpush._auth import AuthConfig
+from axonpush._http import AsyncTransport, SyncTransport
+from axonpush.realtime.websocket import AsyncWebSocketClient, WebSocketClient
+from axonpush.resources.apps import AppsResource, AsyncAppsResource
+from axonpush.resources.channels import AsyncChannelsResource, ChannelsResource
+from axonpush.resources.events import AsyncEventsResource, EventsResource
+from axonpush.resources.traces import AsyncTracesResource, TracesResource
+from axonpush.resources.webhooks import AsyncWebhooksResource, WebhooksResource
+
+
+class AxonPush:
+    """Synchronous AxonPush client. Thread-safe.
+
+    Usage::
+
+        with AxonPush(api_key="ak_...", tenant_id="1", base_url="https://...") as client:
+            event = client.events.publish(
+                "web_search", {"query": "AI agents"}, channel_id=1,
+                agent_id="researcher", event_type="agent.tool_call.start",
+            )
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        tenant_id: str,
+        *,
+        base_url: str,
+        timeout: float = 30.0,
+    ) -> None:
+        self._auth = AuthConfig(api_key, tenant_id, base_url)
+        self._transport = SyncTransport(self._auth, timeout)
+
+        self.events = EventsResource(self._transport)
+        self.channels = ChannelsResource(self._transport)
+        self.apps = AppsResource(self._transport)
+        self.webhooks = WebhooksResource(self._transport)
+        self.traces = TracesResource(self._transport)
+
+    def connect_websocket(self) -> WebSocketClient:
+        """Create and connect a Socket.IO WebSocket client."""
+        ws = WebSocketClient(self._auth)
+        ws.connect()
+        return ws
+
+    def close(self) -> None:
+        """Close the underlying HTTP transport."""
+        self._transport.close()
+
+    def __enter__(self) -> AxonPush:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+
+class AsyncAxonPush:
+    """Asynchronous AxonPush client. Task-safe.
+
+    Usage::
+
+        async with AsyncAxonPush(api_key="ak_...", tenant_id="1", base_url="https://...") as client:
+            event = await client.events.publish(
+                "web_search", {"query": "AI agents"}, channel_id=1,
+                agent_id="researcher", event_type="agent.tool_call.start",
+            )
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        tenant_id: str,
+        *,
+        base_url: str,
+        timeout: float = 30.0,
+    ) -> None:
+        self._auth = AuthConfig(api_key, tenant_id, base_url)
+        self._transport = AsyncTransport(self._auth, timeout)
+
+        self.events = AsyncEventsResource(self._transport)
+        self.channels = AsyncChannelsResource(self._transport)
+        self.apps = AsyncAppsResource(self._transport)
+        self.webhooks = AsyncWebhooksResource(self._transport)
+        self.traces = AsyncTracesResource(self._transport)
+
+    async def connect_websocket(self) -> AsyncWebSocketClient:
+        """Create and connect an async Socket.IO WebSocket client."""
+        ws = AsyncWebSocketClient(self._auth)
+        await ws.connect()
+        return ws
+
+    async def close(self) -> None:
+        """Close the underlying HTTP transport."""
+        await self._transport.close()
+
+    async def __aenter__(self) -> AsyncAxonPush:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()

axonpush/exceptions.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+
+class AxonPushError(Exception):
+    """Base exception for all AxonPush SDK errors."""
+
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        self.status_code = status_code
+        super().__init__(message)
+
+
+class AuthenticationError(AxonPushError):
+    """Raised when the API key or JWT token is invalid or missing (HTTP 401)."""
+
+
+class ForbiddenError(AxonPushError):
+    """Raised when the authenticated user lacks permission (HTTP 403)."""
+
+
+class NotFoundError(AxonPushError):
+    """Raised when the requested resource does not exist (HTTP 404)."""
+
+
+class ValidationError(AxonPushError):
+    """Raised when the request body fails validation (HTTP 400)."""
+
+
+class RateLimitError(AxonPushError):
+    """Raised when the rate limit is exceeded (HTTP 429)."""
+
+    def __init__(self, message: str, retry_after: float | None = None) -> None:
+        self.retry_after = retry_after
+        super().__init__(message, status_code=429)
+
+
+class ServerError(AxonPushError):
+    """Raised when the server returns a 5xx error."""

axonpush/integrations/__init__.py

@@ -0,0 +1,7 @@
+# Integrations are lazily imported to avoid requiring optional dependencies.
+# Import them directly:
+#
+#   from axonpush.integrations.langchain import AxonPushCallbackHandler
+#   from axonpush.integrations.openai_agents import AxonPushRunHooks
+#   from axonpush.integrations.anthropic import AxonPushAnthropicTracer
+#   from axonpush.integrations.crewai import AxonPushCrewCallbacks

axonpush/integrations/anthropic.py

@@ -0,0 +1,184 @@
+"""Anthropic/Claude integration for AxonPush.
+
+Requires: ``pip install axonpush[anthropic]``
+
+Unlike LangChain/CrewAI, the Anthropic SDK has no callback hooks. This
+integration wraps ``messages.create()`` calls to automatically emit events
+for tool_use blocks, text responses, and conversation turns.
+
+Usage::
+
+    from axonpush import AxonPush
+    from axonpush.integrations.anthropic import AxonPushAnthropicTracer
+
+    client = AxonPush(api_key="ak_...", tenant_id="1")
+    tracer = AxonPushAnthropicTracer(client, channel_id=1)
+
+    # Sync
+    response = tracer.create_message(
+        anthropic_client,
+        model="claude-sonnet-4-20250514",
+        messages=[{"role": "user", "content": "Hello"}],
+        tools=[...],
+    )
+
+    # Async
+    response = await tracer.acreate_message(async_anthropic_client, ...)
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+try:
+    import anthropic  # noqa: F401 — verify the package is installed
+except ImportError:
+    raise ImportError(
+        "Anthropic integration requires the 'anthropic' extra. "
+        "Install it with: pip install axonpush[anthropic]"
+    ) from None
+
+from axonpush._tracing import get_or_create_trace
+from axonpush.models.events import EventType
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from axonpush.client import AsyncAxonPush, AxonPush
+
+
+class AxonPushAnthropicTracer:
+    """Wraps Anthropic API calls to emit AxonPush trace events."""
+
+    def __init__(
+        self,
+        client: AxonPush | AsyncAxonPush,
+        channel_id: int,
+        *,
+        agent_id: str = "claude",
+        trace_id: Optional[str] = None,
+    ) -> None:
+        self._client = client
+        self._channel_id = channel_id
+        self._agent_id = agent_id
+        self._trace = get_or_create_trace(trace_id)
+
+    def create_message(self, anthropic_client: Any, **kwargs: Any) -> Any:
+        """Wrap a sync ``anthropic_client.messages.create()`` call with tracing."""
+        self._emit_sync(
+            "conversation.turn",
+            EventType.AGENT_START,
+            {
+                "model": kwargs.get("model"),
+                "message_count": len(kwargs.get("messages", [])),
+            },
+        )
+
+        response = anthropic_client.messages.create(**kwargs)
+        self._process_response(response)
+        return response
+
+    async def acreate_message(self, anthropic_client: Any, **kwargs: Any) -> Any:
+        """Wrap an async ``anthropic_client.messages.create()`` call with tracing."""
+        await self._emit_async(
+            "conversation.turn",
+            EventType.AGENT_START,
+            {
+                "model": kwargs.get("model"),
+                "message_count": len(kwargs.get("messages", [])),
+            },
+        )
+
+        response = await anthropic_client.messages.create(**kwargs)
+        await self._aprocess_response(response)
+        return response
+
+    def send_tool_result(self, tool_use_id: str, result: Any) -> None:
+        """Emit a tool_call.end event when you send a tool result back."""
+        self._emit_sync(
+            "tool.result",
+            EventType.AGENT_TOOL_CALL_END,
+            {"tool_use_id": tool_use_id, "result_preview": str(result)[:500]},
+        )
+
+    async def asend_tool_result(self, tool_use_id: str, result: Any) -> None:
+        """Async variant of send_tool_result."""
+        await self._emit_async(
+            "tool.result",
+            EventType.AGENT_TOOL_CALL_END,
+            {"tool_use_id": tool_use_id, "result_preview": str(result)[:500]},
+        )
+
+    # -- Internal --
+
+    def _process_response(self, response: Any) -> None:
+        for block in getattr(response, "content", []):
+            block_type = getattr(block, "type", None)
+            if block_type == "tool_use":
+                self._emit_sync(
+                    f"tool.{block.name}.start",
+                    EventType.AGENT_TOOL_CALL_START,
+                    {
+                        "tool_name": block.name,
+                        "tool_use_id": block.id,
+                        "input": _truncate(block.input),
+                    },
+                )
+            elif block_type == "text":
+                self._emit_sync(
+                    "agent.response",
+                    EventType.AGENT_MESSAGE,
+                    {"text_length": len(block.text)},
+                )
+
+    async def _aprocess_response(self, response: Any) -> None:
+        for block in getattr(response, "content", []):
+            block_type = getattr(block, "type", None)
+            if block_type == "tool_use":
+                await self._emit_async(
+                    f"tool.{block.name}.start",
+                    EventType.AGENT_TOOL_CALL_START,
+                    {
+                        "tool_name": block.name,
+                        "tool_use_id": block.id,
+                        "input": _truncate(block.input),
+                    },
+                )
+            elif block_type == "text":
+                await self._emit_async(
+                    "agent.response",
+                    EventType.AGENT_MESSAGE,
+                    {"text_length": len(block.text)},
+                )
+
+    def _emit_sync(
+        self, identifier: str, event_type: EventType, payload: Dict[str, Any]
+    ) -> None:
+        self._client.events.publish(  # type: ignore[union-attr]
+            identifier=identifier,
+            payload=payload,
+            channel_id=self._channel_id,
+            agent_id=self._agent_id,
+            trace_id=self._trace.trace_id,
+            span_id=self._trace.next_span_id(),
+            event_type=event_type,
+            metadata={"framework": "anthropic"},
+        )
+
+    async def _emit_async(
+        self, identifier: str, event_type: EventType, payload: Dict[str, Any]
+    ) -> None:
+        await self._client.events.publish(  # type: ignore[union-attr]
+            identifier=identifier,
+            payload=payload,
+            channel_id=self._channel_id,
+            agent_id=self._agent_id,
+            trace_id=self._trace.trace_id,
+            span_id=self._trace.next_span_id(),
+            event_type=event_type,
+            metadata={"framework": "anthropic"},
+        )
+
+
+def _truncate(obj: Any, max_len: int = 500) -> Any:
+    s = str(obj)
+    return s[:max_len] if len(s) > max_len else s