agentmark-sdk 0.1.0__py3-none-any.whl

agentmark_sdk/__init__.py

@@ -0,0 +1,71 @@
+"""AgentMark SDK for Python.
+
+Provides OpenTelemetry-based tracing and observability for AI applications.
+
+Example:
+    from agentmark_sdk import AgentMarkSDK, span, SpanOptions
+
+    # Initialize the SDK
+    sdk = AgentMarkSDK(api_key="sk-...", app_id="app_123")
+    sdk.init_tracing()
+
+    # Create a span around an operation
+    result = await span(
+        SpanOptions(name="my-operation", user_id="user-1"),
+        my_async_function,
+    )
+
+    # Auto-capture IO with decorator
+    from agentmark_sdk import observe, SpanKind
+
+    @observe(kind=SpanKind.TOOL)
+    async def my_tool(query: str) -> dict:
+        return {"result": "data"}
+
+    # Submit a score
+    await sdk.score(
+        resource_id=result.trace_id,
+        name="accuracy",
+        score=0.95,
+    )
+"""
+
+from .config import (
+    AGENTMARK_KEY,
+    AGENTMARK_SCORE_ENDPOINT,
+    AGENTMARK_TRACE_ENDPOINT,
+    DEFAULT_BASE_URL,
+    METADATA_KEY,
+)
+from .decorator import SpanKind, observe
+from .sampler import AgentmarkSampler
+from .sdk import AgentMarkSDK
+from .serialize import serialize_value
+from .trace import SpanContext, SpanOptions, SpanResult, span, span_context, span_context_sync
+
+__all__ = [
+    # SDK
+    "AgentMarkSDK",
+    # Span utilities
+    "span",
+    "span_context",
+    "span_context_sync",
+    "observe",
+    "SpanOptions",
+    "SpanContext",
+    "SpanResult",
+    # Span kinds
+    "SpanKind",
+    # Serialization
+    "serialize_value",
+    # Sampler
+    "AgentmarkSampler",
+    # Config
+    "AGENTMARK_KEY",
+    "METADATA_KEY",
+    "AGENTMARK_TRACE_ENDPOINT",
+    "AGENTMARK_SCORE_ENDPOINT",
+    "DEFAULT_BASE_URL",
+]
+
+__version__ = "0.1.0"

agentmark_sdk/config.py

@@ -0,0 +1,12 @@
+"""Configuration constants for AgentMark SDK."""
+
+# API Endpoints
+AGENTMARK_TRACE_ENDPOINT = "v1/traces"
+AGENTMARK_SCORE_ENDPOINT = "v1/score"
+
+# Default base URL
+DEFAULT_BASE_URL = "https://api.agentmark.co"
+
+# Span attribute prefixes
+AGENTMARK_KEY = "agentmark"
+METADATA_KEY = "agentmark.metadata"

agentmark_sdk/decorator.py

@@ -0,0 +1,182 @@
+"""Decorator-based tracing for automatic IO capture.
+
+Provides the @observe decorator that auto-captures function arguments
+as span input and return values as span output.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from enum import Enum
+from typing import Any, Callable, TypeVar, overload
+
+from opentelemetry import trace as otel_trace
+from opentelemetry.trace import StatusCode
+
+from .config import AGENTMARK_KEY
+from .serialize import serialize_value
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+# Attribute keys matching the gen_ai semantic conventions used by the adapter
+INPUT_KEY = "gen_ai.request.input"
+OUTPUT_KEY = "gen_ai.response.output"
+SPAN_KIND_KEY = f"{AGENTMARK_KEY}.span.kind"
+
+
+class SpanKind(str, Enum):
+    """Span kind for categorizing observed operations."""
+
+    FUNCTION = "function"
+    LLM = "llm"
+    TOOL = "tool"
+
+
+def _capture_inputs(
+    fn: Callable[..., Any],
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+    process_inputs: Callable[[dict[str, Any]], dict[str, Any]] | None,
+) -> str | None:
+    """Capture function arguments as a serialized input string."""
+    try:
+        sig = inspect.signature(fn)
+        bound = sig.bind(*args, **kwargs)
+        bound.apply_defaults()
+        inputs = dict(bound.arguments)
+    except (TypeError, ValueError):
+        # Fallback if signature binding fails
+        inputs = {"args": list(args), "kwargs": kwargs} if kwargs else {"args": list(args)}
+
+    if process_inputs is not None:
+        # Pass raw args (including self) to custom processor
+        inputs = process_inputs(inputs)
+    # Exclude self/cls for methods (after process_inputs so it can access self)
+    inputs.pop("self", None)
+    inputs.pop("cls", None)
+
+    return serialize_value(inputs)
+
+
+def _capture_output(
+    result: Any,
+    process_outputs: Callable[[Any], Any] | None,
+) -> str | None:
+    """Capture function return value as a serialized output string."""
+    output = result
+    if process_outputs is not None:
+        output = process_outputs(output)
+    return serialize_value(output)
+
+
+@overload
+def observe(_fn: F) -> F: ...
+
+
+@overload
+def observe(
+    _fn: None = None,
+    *,
+    name: str | None = None,
+    kind: SpanKind = SpanKind.FUNCTION,
+    capture_input: bool = True,
+    capture_output: bool = True,
+    process_inputs: Callable[[dict[str, Any]], dict[str, Any]] | None = None,
+    process_outputs: Callable[[Any], Any] | None = None,
+) -> Callable[[F], F]: ...
+
+
+def observe(
+    _fn: F | None = None,
+    *,
+    name: str | None = None,
+    kind: SpanKind = SpanKind.FUNCTION,
+    capture_input: bool = True,
+    capture_output: bool = True,
+    process_inputs: Callable[[dict[str, Any]], dict[str, Any]] | None = None,
+    process_outputs: Callable[[Any], Any] | None = None,
+) -> F | Callable[[F], F]:
+    """Decorator that auto-captures function IO as span attributes.
+
+    Supports both @observe and @observe() syntax, sync and async functions.
+
+    Args:
+        name: Custom span name. Defaults to the function name.
+        kind: Span kind for categorization. Defaults to SpanKind.FUNCTION.
+        capture_input: Whether to capture function args as input. Default True.
+        capture_output: Whether to capture return value as output. Default True.
+        process_inputs: Optional transform applied to inputs before serialization.
+        process_outputs: Optional transform applied to output before serialization.
+
+    Example:
+        @observe
+        async def my_function(item_type: str) -> dict:
+            return {"result": "data"}
+
+        @observe(name="custom-name", kind=SpanKind.TOOL)
+        async def call_api(query: str) -> dict:
+            ...
+
+        @observe(process_inputs=lambda inputs: {k: v for k, v in inputs.items() if k != "api_key"})
+        async def call_api(api_key: str, query: str) -> dict:
+            ...
+    """
+
+    def decorator(fn: F) -> F:
+        span_name = name or fn.__name__
+
+        @functools.wraps(fn)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+            tracer = otel_trace.get_tracer("agentmark")
+            with tracer.start_as_current_span(span_name) as span:
+                span.set_attribute(SPAN_KIND_KEY, kind.value)
+
+                if capture_input:
+                    input_str = _capture_inputs(fn, args, kwargs, process_inputs)
+                    if input_str is not None:
+                        span.set_attribute(INPUT_KEY, input_str)
+
+                try:
+                    result = await fn(*args, **kwargs)
+                    if capture_output:
+                        output_str = _capture_output(result, process_outputs)
+                        if output_str is not None:
+                            span.set_attribute(OUTPUT_KEY, output_str)
+                    span.set_status(StatusCode.OK)
+                    return result
+                except Exception as e:
+                    span.set_status(StatusCode.ERROR, str(e))
+                    raise
+
+        @functools.wraps(fn)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            tracer = otel_trace.get_tracer("agentmark")
+            with tracer.start_as_current_span(span_name) as span:
+                span.set_attribute(SPAN_KIND_KEY, kind.value)
+
+                if capture_input:
+                    input_str = _capture_inputs(fn, args, kwargs, process_inputs)
+                    if input_str is not None:
+                        span.set_attribute(INPUT_KEY, input_str)
+
+                try:
+                    result = fn(*args, **kwargs)
+                    if capture_output:
+                        output_str = _capture_output(result, process_outputs)
+                        if output_str is not None:
+                            span.set_attribute(OUTPUT_KEY, output_str)
+                    span.set_status(StatusCode.OK)
+                    return result
+                except Exception as e:
+                    span.set_status(StatusCode.ERROR, str(e))
+                    raise
+
+        if inspect.iscoroutinefunction(fn):
+            return async_wrapper  # type: ignore[return-value]
+        return sync_wrapper  # type: ignore[return-value]
+
+    # Support both @observe and @observe() syntax
+    if _fn is not None:
+        return decorator(_fn)
+    return decorator  # type: ignore[return-value]

agentmark_sdk/sampler.py

@@ -0,0 +1,60 @@
+"""Custom sampler for AgentMark traces."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Sequence
+
+from opentelemetry.context import Context
+from opentelemetry.sdk.trace.sampling import (
+    Decision,
+    Sampler,
+    SamplingResult,
+)
+from opentelemetry.trace import Link, SpanKind
+from opentelemetry.util.types import Attributes
+
+# Span attributes that indicate internal framework spans to filter out
+FILTERED_ATTRIBUTE_KEYS = ["next.span_name", "next.clientComponentLoadCount"]
+
+
+class AgentmarkSampler(Sampler):
+    """Custom sampler that filters out internal framework spans.
+
+    This sampler drops spans that have attributes indicating they are
+    internal framework spans (e.g., Next.js internals) that would add
+    noise to traces without providing useful debugging information.
+    """
+
+    def should_sample(
+        self,
+        parent_context: Context | None,
+        trace_id: int,
+        name: str,
+        kind: SpanKind | None = None,
+        attributes: Attributes | None = None,
+        links: Sequence[Link] | None = None,
+    ) -> SamplingResult:
+        """Determine whether to sample this span.
+
+        Args:
+            parent_context: The parent context (if any).
+            trace_id: The trace ID.
+            name: The span name.
+            kind: The span kind.
+            attributes: Span attributes.
+            links: Span links.
+
+        Returns:
+            SamplingResult indicating whether to record/sample.
+        """
+        # Check if any filtered attribute keys are present
+        if attributes:
+            for key in FILTERED_ATTRIBUTE_KEYS:
+                if key in attributes:
+                    return SamplingResult(Decision.DROP)
+
+        return SamplingResult(Decision.RECORD_AND_SAMPLE)
+
+    def get_description(self) -> str:
+        """Return a description of this sampler."""
+        return "AgentmarkSampler"

agentmark_sdk/sdk.py

@@ -0,0 +1,252 @@
+"""AgentMark SDK main class."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+from opentelemetry import trace as otel_trace
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor, SimpleSpanProcessor
+
+from .config import (
+    AGENTMARK_SCORE_ENDPOINT,
+    AGENTMARK_TRACE_ENDPOINT,
+    DEFAULT_BASE_URL,
+)
+from .sampler import AgentmarkSampler
+
+
+class AgentMarkSDK:
+    """AgentMark SDK for Python.
+
+    Provides OpenTelemetry tracing initialization and score submission.
+
+    Example:
+        sdk = AgentMarkSDK(api_key="sk-...", app_id="app_123")
+        sdk.init_tracing()
+
+        # Use span() function from the SDK
+        from agentmark_sdk import span, SpanOptions
+        result = await span(
+            SpanOptions(name="my-operation"),
+            my_async_function,
+        )
+
+        # Submit a score
+        await sdk.score(
+            resource_id=result.trace_id,
+            name="accuracy",
+            score=0.95,
+            label="good",
+            reason="Response matched expected output",
+        )
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        app_id: str,
+        base_url: str = DEFAULT_BASE_URL,
+    ) -> None:
+        """Initialize the SDK.
+
+        Args:
+            api_key: AgentMark API key.
+            app_id: AgentMark application ID.
+            base_url: Base URL for the AgentMark API.
+        """
+        self._api_key = api_key
+        self._app_id = app_id
+        self._base_url = base_url.rstrip("/")
+        self._tracer_provider: TracerProvider | None = None
+
+    @property
+    def api_key(self) -> str:
+        """Get the API key."""
+        return self._api_key
+
+    @property
+    def app_id(self) -> str:
+        """Get the application ID."""
+        return self._app_id
+
+    @property
+    def base_url(self) -> str:
+        """Get the base URL."""
+        return self._base_url
+
+    def init_tracing(self, disable_batch: bool = False) -> TracerProvider:
+        """Initialize OpenTelemetry tracing with AgentMark exporter.
+
+        Call this once at application startup.
+
+        Args:
+            disable_batch: If True, use SimpleSpanProcessor (immediate export).
+                If False (default), use BatchSpanProcessor for better performance.
+
+        Returns:
+            The configured TracerProvider.
+
+        Example:
+            sdk = AgentMarkSDK(api_key="sk-...", app_id="app_123")
+            provider = sdk.init_tracing()
+        """
+        exporter_url = f"{self._base_url}/{AGENTMARK_TRACE_ENDPOINT}"
+
+        exporter = OTLPSpanExporter(
+            endpoint=exporter_url,
+            headers={
+                "Authorization": self._api_key,
+                "X-Agentmark-App-Id": self._app_id,
+            },
+        )
+
+        processor: SimpleSpanProcessor | BatchSpanProcessor
+        if disable_batch:
+            processor = SimpleSpanProcessor(exporter)
+        else:
+            processor = BatchSpanProcessor(exporter)
+
+        resource = Resource.create(
+            {
+                "service.name": "agentmark-client",
+                "agentmark.app_id": self._app_id,
+            }
+        )
+
+        provider = TracerProvider(
+            resource=resource,
+            sampler=AgentmarkSampler(),
+        )
+        provider.add_span_processor(processor)
+
+        otel_trace.set_tracer_provider(provider)
+        self._tracer_provider = provider
+
+        return provider
+
+    async def score(
+        self,
+        resource_id: str,
+        name: str,
+        score: float,
+        label: str | None = None,
+        reason: str | None = None,
+        type: str | None = None,
+    ) -> dict[str, Any]:
+        """Submit a score for a trace/span.
+
+        Args:
+            resource_id: The trace or span ID to score.
+            name: Name of the score metric (e.g., "accuracy", "relevance").
+            score: Numeric score value (typically 0.0-1.0).
+            label: Optional label (e.g., "good", "bad", "neutral").
+            reason: Optional explanation for the score.
+            type: Optional score type identifier.
+
+        Returns:
+            Response data from the API.
+
+        Raises:
+            Exception: If the API request fails.
+
+        Example:
+            await sdk.score(
+                resource_id="abc123",
+                name="accuracy",
+                score=0.95,
+                label="good",
+                reason="Response matched expected",
+            )
+        """
+        url = f"{self._base_url}/{AGENTMARK_SCORE_ENDPOINT}"
+
+        payload: dict[str, Any] = {
+            "resourceId": resource_id,
+            "name": name,
+            "score": score,
+        }
+        if label is not None:
+            payload["label"] = label
+        if reason is not None:
+            payload["reason"] = reason
+        if type is not None:
+            payload["type"] = type
+
+        async with httpx.AsyncClient() as client:
+            response = await client.post(
+                url,
+                json=payload,
+                headers={
+                    "Content-Type": "application/json",
+                    "Authorization": self._api_key,
+                    "X-Agentmark-App-Id": self._app_id,
+                },
+            )
+
+            if response.is_success:
+                data = response.json()
+                return data.get("data", {})
+
+            error_data = response.json()
+            raise Exception(error_data.get("error", "Unknown error"))
+
+    def score_sync(
+        self,
+        resource_id: str,
+        name: str,
+        score: float,
+        label: str | None = None,
+        reason: str | None = None,
+        type: str | None = None,
+    ) -> dict[str, Any]:
+        """Submit a score for a trace/span (synchronous version).
+
+        Args:
+            resource_id: The trace or span ID to score.
+            name: Name of the score metric.
+            score: Numeric score value.
+            label: Optional label.
+            reason: Optional explanation.
+            type: Optional score type.
+
+        Returns:
+            Response data from the API.
+
+        Raises:
+            Exception: If the API request fails.
+        """
+        url = f"{self._base_url}/{AGENTMARK_SCORE_ENDPOINT}"
+
+        payload: dict[str, Any] = {
+            "resourceId": resource_id,
+            "name": name,
+            "score": score,
+        }
+        if label is not None:
+            payload["label"] = label
+        if reason is not None:
+            payload["reason"] = reason
+        if type is not None:
+            payload["type"] = type
+
+        with httpx.Client() as client:
+            response = client.post(
+                url,
+                json=payload,
+                headers={
+                    "Content-Type": "application/json",
+                    "Authorization": self._api_key,
+                    "X-Agentmark-App-Id": self._app_id,
+                },
+            )
+
+            if response.is_success:
+                data = response.json()
+                return data.get("data", {})
+
+            error_data = response.json()
+            raise Exception(error_data.get("error", "Unknown error"))

agentmark_sdk/serialize.py

@@ -0,0 +1,33 @@
+"""Serialization utilities for observed function IO capture."""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+from typing import Any
+
+MAX_SERIALIZE_LENGTH = 1_000_000
+
+
+def serialize_value(value: Any, max_length: int = MAX_SERIALIZE_LENGTH) -> str:
+    """Serialize a value to a JSON string for span attributes.
+
+    Serialization chain:
+      1. Pydantic model → .model_dump() → JSON
+      2. Dataclass → dataclasses.asdict() → JSON
+      3. Dict/list/primitive → JSON directly
+      4. Fallback → str(obj)
+
+    Truncated to max_length characters.
+    """
+    try:
+        if hasattr(value, "model_dump"):
+            serialized = json.dumps(value.model_dump(), default=str)
+        elif dataclasses.is_dataclass(value) and not isinstance(value, type):
+            serialized = json.dumps(dataclasses.asdict(value), default=str)
+        else:
+            serialized = json.dumps(value, default=str)
+    except (TypeError, ValueError, OverflowError):
+        serialized = str(value)
+
+    return serialized[:max_length]

agentmark_sdk/trace.py

@@ -0,0 +1,331 @@
+"""Tracing utilities for AgentMark SDK.
+
+Provides the trace() function for wrapping operations with OpenTelemetry spans.
+"""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from dataclasses import dataclass, field
+from typing import Any, AsyncIterator, Callable, Generic, TypeVar
+
+from opentelemetry import trace as otel_trace
+from opentelemetry.trace import Span, SpanKind, StatusCode, Tracer
+from opentelemetry.util.types import Attributes
+
+from .config import AGENTMARK_KEY, METADATA_KEY
+
+T = TypeVar("T")
+
+
+@dataclass
+class TraceOptions:
+    """Options for creating a trace.
+
+    Attributes:
+        name: Name of the trace/span.
+        metadata: Additional metadata key-value pairs.
+        session_id: Session identifier for grouping traces.
+        session_name: Human-readable session name.
+        user_id: User identifier.
+        dataset_run_id: Dataset run identifier (for experiments).
+        dataset_run_name: Dataset run name (for experiments).
+        dataset_item_name: Dataset item name (for experiments).
+        dataset_expected_output: Expected output for dataset item.
+    """
+
+    name: str
+    metadata: dict[str, str] | None = None
+    session_id: str | None = None
+    session_name: str | None = None
+    user_id: str | None = None
+    prompt_name: str | None = None
+    dataset_run_id: str | None = None
+    dataset_run_name: str | None = None
+    dataset_item_name: str | None = None
+    dataset_expected_output: str | None = None
+    dataset_input: str | None = None
+    dataset_path: str | None = None
+
+
+@dataclass
+class TraceContext:
+    """Context passed to traced functions.
+
+    Provides access to trace information and methods for adding
+    attributes, events, and child spans.
+
+    Attributes:
+        trace_id: The trace ID in hex format.
+        span_id: The span ID in hex format.
+    """
+
+    trace_id: str
+    span_id: str
+    _span: Span = field(repr=False)
+    _tracer: Tracer = field(repr=False)
+
+    def set_attribute(self, key: str, value: str | int | float | bool) -> None:
+        """Set an attribute on this span.
+
+        Args:
+            key: Attribute key.
+            value: Attribute value.
+        """
+        self._span.set_attribute(key, value)
+
+    def set_input(self, data: dict[str, Any]) -> None:
+        """Record input data on this span."""
+        from .serialize import serialize_value
+
+        self._span.set_attribute(
+            f"{AGENTMARK_KEY}.input", serialize_value(data),
+        )
+
+    def set_output(self, data: dict[str, Any]) -> None:
+        """Record output data on this span."""
+        from .serialize import serialize_value
+
+        self._span.set_attribute(
+            f"{AGENTMARK_KEY}.output", serialize_value(data),
+        )
+
+    def add_event(
+        self, name: str, attributes: dict[str, Any] | None = None
+    ) -> None:
+        """Add an event to this span.
+
+        Args:
+            name: Event name.
+            attributes: Optional event attributes.
+        """
+        self._span.add_event(name, attributes or {})
+
+    @asynccontextmanager
+    async def span(
+        self, name: str, metadata: dict[str, str] | None = None
+    ) -> AsyncIterator[TraceContext]:
+        """Create a child span within this trace.
+
+        Args:
+            name: Child span name.
+            metadata: Optional metadata for the child span.
+
+        Yields:
+            TraceContext for the child span.
+        """
+        with self._tracer.start_as_current_span(name) as child_span:
+            if metadata:
+                for key, value in metadata.items():
+                    child_span.set_attribute(f"{METADATA_KEY}.{key}", value)
+
+            span_ctx = child_span.get_span_context()
+            child_ctx = TraceContext(
+                trace_id=self.trace_id,  # Same trace ID
+                span_id=format(span_ctx.span_id, "016x"),
+                _span=child_span,
+                _tracer=self._tracer,
+            )
+            try:
+                yield child_ctx
+                child_span.set_status(StatusCode.OK)
+            except Exception as e:
+                child_span.set_status(StatusCode.ERROR, str(e))
+                raise
+
+
+@dataclass
+class TraceResult(Generic[T]):
+    """Result from trace execution.
+
+    Attributes:
+        result: The result of the traced function.
+        trace_id: The trace ID for correlation.
+    """
+
+    result: T
+    trace_id: str
+
+
+def _set_agentmark_attributes(span: Span, options: TraceOptions) -> None:
+    """Set AgentMark-specific attributes on a span.
+
+    Args:
+        span: The span to set attributes on.
+        options: Trace options containing attribute values.
+    """
+    span.set_attribute(f"{AGENTMARK_KEY}.trace_name", options.name)
+
+    if options.session_id:
+        span.set_attribute(f"{AGENTMARK_KEY}.session_id", options.session_id)
+    if options.session_name:
+        span.set_attribute(f"{AGENTMARK_KEY}.session_name", options.session_name)
+    if options.user_id:
+        span.set_attribute(f"{AGENTMARK_KEY}.user_id", options.user_id)
+    if options.prompt_name:
+        span.set_attribute(f"{AGENTMARK_KEY}.prompt_name", options.prompt_name)
+    if options.dataset_run_id:
+        span.set_attribute(f"{AGENTMARK_KEY}.dataset_run_id", options.dataset_run_id)
+    if options.dataset_run_name:
+        span.set_attribute(f"{AGENTMARK_KEY}.dataset_run_name", options.dataset_run_name)
+    if options.dataset_item_name:
+        span.set_attribute(f"{AGENTMARK_KEY}.dataset_item_name", options.dataset_item_name)
+    if options.dataset_expected_output:
+        span.set_attribute(
+            f"{AGENTMARK_KEY}.dataset_expected_output", options.dataset_expected_output
+        )
+    if options.dataset_input:
+        span.set_attribute(f"{AGENTMARK_KEY}.dataset_input", options.dataset_input)
+    if options.dataset_path:
+        span.set_attribute(f"{AGENTMARK_KEY}.dataset_path", options.dataset_path)
+
+    if options.metadata:
+        for key, value in options.metadata.items():
+            span.set_attribute(f"{METADATA_KEY}.{key}", value)
+
+
+async def trace(
+    options: TraceOptions | str,
+    fn: Callable[..., Any],
+    *args: Any,
+    **kwargs: Any,
+) -> TraceResult[Any]:
+    """Start a new trace and execute a function within it.
+
+    Creates a root span, executes the provided function, and returns
+    both the result and the trace ID.
+
+    Args:
+        options: Trace options or just a name string.
+        fn: The async function to execute within the trace.
+        *args: Positional arguments to pass to the function.
+        **kwargs: Keyword arguments to pass to the function.
+
+    Returns:
+        TraceResult containing the function result and trace ID.
+
+    Example:
+        result = await trace(
+            TraceOptions(name="my-operation", user_id="123"),
+            my_async_function,
+            arg1, arg2,
+        )
+        print(f"Result: {result.result}, Trace ID: {result.trace_id}")
+    """
+    if isinstance(options, str):
+        options = TraceOptions(name=options)
+
+    tracer = otel_trace.get_tracer("agentmark")
+
+    with tracer.start_as_current_span(options.name) as span:
+        _set_agentmark_attributes(span, options)
+
+        span_ctx = span.get_span_context()
+        ctx = TraceContext(
+            trace_id=format(span_ctx.trace_id, "032x"),
+            span_id=format(span_ctx.span_id, "016x"),
+            _span=span,
+            _tracer=tracer,
+        )
+
+        try:
+            result = await fn(*args, **kwargs)
+            span.set_status(StatusCode.OK)
+            return TraceResult(result=result, trace_id=ctx.trace_id)
+        except Exception as e:
+            span.set_status(StatusCode.ERROR, str(e))
+            raise
+
+
+@asynccontextmanager
+async def trace_context(
+    options: TraceOptions | str,
+) -> AsyncIterator[TraceContext]:
+    """Create a trace as an async context manager.
+
+    Alternative API for when you want to use a context manager instead
+    of passing a function.
+
+    Args:
+        options: Trace options or just a name string.
+
+    Yields:
+        TraceContext with trace_id, span_id, and utility methods.
+
+    Example:
+        async with trace_context(TraceOptions(name="my-operation")) as ctx:
+            print(f"Trace ID: {ctx.trace_id}")
+            ctx.set_attribute("custom_key", "value")
+            result = await my_async_function()
+    """
+    if isinstance(options, str):
+        options = TraceOptions(name=options)
+
+    tracer = otel_trace.get_tracer("agentmark")
+
+    with tracer.start_as_current_span(options.name) as span:
+        _set_agentmark_attributes(span, options)
+
+        span_ctx = span.get_span_context()
+        ctx = TraceContext(
+            trace_id=format(span_ctx.trace_id, "032x"),
+            span_id=format(span_ctx.span_id, "016x"),
+            _span=span,
+            _tracer=tracer,
+        )
+
+        try:
+            yield ctx
+            span.set_status(StatusCode.OK)
+        except Exception as e:
+            span.set_status(StatusCode.ERROR, str(e))
+            raise
+
+
+# ---------------------------------------------------------------------------
+# Renamed aliases (trace → span rename)
+# ---------------------------------------------------------------------------
+SpanOptions = TraceOptions
+SpanContext = TraceContext
+SpanResult = TraceResult
+span = trace
+span_context = trace_context
+
+
+# ---------------------------------------------------------------------------
+# Sync wrapper for span_context (used by orchestrator in sync code)
+# ---------------------------------------------------------------------------
+from contextlib import contextmanager  # noqa: E402
+
+
+@contextmanager
+def span_context_sync(options: TraceOptions | str):
+    """Synchronous context manager wrapper around span_context.
+
+    Creates an OTEL span without requiring async. The span is started
+    and stopped synchronously; the yielded context has the same API
+    as the async version (set_attribute, add_event, etc.) but without
+    the async child-span helper.
+    """
+    if isinstance(options, str):
+        options = TraceOptions(name=options)
+
+    tracer = otel_trace.get_tracer("agentmark")
+
+    with tracer.start_as_current_span(options.name) as otel_span:
+        _set_agentmark_attributes(otel_span, options)
+
+        span_ctx = otel_span.get_span_context()
+        ctx = TraceContext(
+            trace_id=format(span_ctx.trace_id, "032x"),
+            span_id=format(span_ctx.span_id, "016x"),
+            _span=otel_span,
+            _tracer=tracer,
+        )
+
+        try:
+            yield ctx
+            otel_span.set_status(StatusCode.OK)
+        except Exception as e:
+            otel_span.set_status(StatusCode.ERROR, str(e))
+            raise

agentmark_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: agentmark-sdk
+Version: 0.1.0
+Summary: AgentMark SDK for Python - Tracing and Observability
+Author-email: AgentMark <support@agentmark.co>
+License: MIT
+Keywords: agentmark,llm,observability,opentelemetry,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25
+Requires-Dist: opentelemetry-api>=1.20
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20
+Requires-Dist: opentelemetry-sdk>=1.20
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'

agentmark_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+agentmark_sdk/__init__.py,sha256=6QecsmFhFtg6H6S7OphsWXzGQLSL9ehMbDI4js_W6Jk,1637
+agentmark_sdk/config.py,sha256=M2oZBF4vQPTMtSiYJtLwQmUdrXGqq55Jcceo8uNXeNY,300
+agentmark_sdk/decorator.py,sha256=Xvb74xFqnxtOjlvLwidSe576Fl4u1vNjpUB7JYBY7mw,6330
+agentmark_sdk/sampler.py,sha256=bXqhw7ma3mINh7TkLneAeyQz4bYwiJj4TLZJpOsHx5E,1897
+agentmark_sdk/sdk.py,sha256=G2jzdWaWIwcjC6lagilgyN4FwnEYp-HpR3ouuLvDxjY,7319
+agentmark_sdk/serialize.py,sha256=OzzMmYpllnxtYh7Cs-n-Dx3jpyeQMv0wPucUQhjz6dc,1053
+agentmark_sdk/trace.py,sha256=_Z-BUlHiPCAhVihTBQ19FTNDAFqeCEq4isMJ7Ebtn3A,10682
+agentmark_sdk-0.1.0.dist-info/METADATA,sha256=YDmXZxeN63AQj9VoBXWwX6GPqb3boOx6Ph1zzNA1pQc,997
+agentmark_sdk-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+agentmark_sdk-0.1.0.dist-info/RECORD,,

agentmark_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any