agentmark-sdk 0.1.0__tar.gz

agentmark_sdk-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+node_modules
+dist
+.specs
+.turbo
+.yarn/install-state.gz
+.yarn/releases/*
+.yalc
+yalc.lock
+.env
+*storybook.log
+storybook-static
+tmp-dev*/
+.claude
+
+# Nx
+.nx/cache/
+.nx/workspace-data/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+*.egg-info/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+# AgentMark local development config (contains webhook secrets)
+.agentmark/dev-config.json
+
+# Speckit
+specs/
+.specify/

agentmark_sdk-0.1.0/PKG-INFO

@@ -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/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@agentmark-ai/sdk-python",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "postinstall": "node ../../scripts/setup-python-venv.js -e \".[dev]\"",
+    "test": "node ../../scripts/run-venv.js pytest",
+    "test:watch": "node ../../scripts/run-venv.js pytest --watch",
+    "lint": "node ../../scripts/run-venv.js ruff check src tests || echo Skipping lint: venv not set up",
+    "lint:fix": "node ../../scripts/run-venv.js ruff check --fix src tests",
+    "typecheck": "node ../../scripts/run-venv.js mypy src --strict",
+    "format": "node ../../scripts/run-venv.js ruff format src tests",
+    "clean": "shx rm -rf .venv dist *.egg-info .pytest_cache .mypy_cache .ruff_cache"
+  }
+}

agentmark_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "agentmark-sdk"
+version = "0.1.0"
+description = "AgentMark SDK for Python - Tracing and Observability"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "AgentMark", email = "support@agentmark.co" }]
+keywords = ["agentmark", "llm", "tracing", "observability", "opentelemetry"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "opentelemetry-api>=1.20",
+    "opentelemetry-sdk>=1.20",
+    "opentelemetry-exporter-otlp-proto-http>=1.20",
+    "httpx>=0.25",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "mypy>=1.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentmark_sdk"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+addopts = "-v --tb=short"
+
+[tool.mypy]
+strict = true
+python_version = "3.10"

agentmark_sdk-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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"