agnt5 0.2.8a10__cp310-abi3-manylinux_2_34_x86_64.whl

agnt5/tracing.py

@@ -0,0 +1,196 @@
+"""
+User-facing tracing API for AGNT5 SDK.
+
+Provides decorators and context managers for instrumenting Python code with
+OpenTelemetry spans. All spans are created via Rust FFI and exported through
+the centralized Rust OpenTelemetry system.
+
+Example:
+    ```python
+    from agnt5.tracing import span
+
+    @span("my_operation")
+    async def my_function(ctx, data):
+        # Your code here
+        return result
+
+    # Or use context manager
+    from agnt5.tracing import span_context
+
+    async def process():
+        with span_context("processing", user_id="123") as s:
+            data = await fetch_data()
+            s.set_attribute("records", str(len(data)))
+            return data
+    ```
+"""
+
+import functools
+import inspect
+from contextlib import contextmanager
+from typing import Any, Callable, Dict, Optional
+
+from ._core import create_span as _create_span
+
+
+def span(
+    name: Optional[str] = None,
+    component_type: str = "function",
+    runtime_context: Optional[Any] = None,
+    **attributes: str
+):
+    """
+    Decorator to automatically create spans for functions.
+
+    Args:
+        name: Span name (defaults to function name)
+        component_type: Component type (default: "function")
+        runtime_context: Optional RuntimeContext for trace linking
+        **attributes: Additional span attributes
+
+    Example:
+        ```python
+        @span("fetch_user_data", user_type="premium")
+        async def fetch_user(user_id: str):
+            return await db.get_user(user_id)
+        ```
+    """
+    def decorator(func: Callable) -> Callable:
+        span_name = name or func.__name__
+
+        if inspect.iscoroutinefunction(func):
+            @functools.wraps(func)
+            async def async_wrapper(*args, **kwargs):
+                # Try to extract runtime_context from first arg if it's a Context
+                ctx = runtime_context
+                if ctx is None and args:
+                    from .context import Context
+                    if isinstance(args[0], Context):
+                        ctx = args[0]._runtime_context
+
+                with _create_span(span_name, component_type, ctx, attributes) as s:
+                    try:
+                        result = await func(*args, **kwargs)
+                        # Span automatically marked as OK on success
+                        return result
+                    except Exception as e:
+                        # Exception automatically recorded by PySpan.__exit__
+                        raise
+            return async_wrapper
+        else:
+            @functools.wraps(func)
+            def sync_wrapper(*args, **kwargs):
+                # Try to extract runtime_context from first arg if it's a Context
+                ctx = runtime_context
+                if ctx is None and args:
+                    from .context import Context
+                    if isinstance(args[0], Context):
+                        ctx = args[0]._runtime_context
+
+                with _create_span(span_name, component_type, ctx, attributes) as s:
+                    try:
+                        result = func(*args, **kwargs)
+                        return result
+                    except Exception as e:
+                        raise
+            return sync_wrapper
+
+    return decorator
+
+
+@contextmanager
+def span_context(
+    name: str,
+    component_type: str = "operation",
+    runtime_context: Optional[Any] = None,
+    **attributes: str
+):
+    """
+    Context manager for creating spans around code blocks.
+
+    Args:
+        name: Span name
+        component_type: Component type (default: "operation")
+        runtime_context: Optional RuntimeContext for trace linking
+        **attributes: Span attributes
+
+    Yields:
+        PySpan object with set_attribute() and record_exception() methods
+
+    Example:
+        ```python
+        with span_context("db_query", runtime_context=ctx._runtime_context, table="users") as s:
+            results = query_database()
+            s.set_attribute("result_count", str(len(results)))
+        ```
+    """
+    s = _create_span(name, component_type, runtime_context, attributes)
+    try:
+        yield s
+        # Context manager automatically calls s.__exit__ which sets status
+    except Exception as e:
+        # Exception will be recorded by __exit__
+        raise
+    finally:
+        # PySpan's __exit__ is called automatically when context ends
+        pass
+
+
+def create_task_span(name: str, runtime_context: Optional[Any] = None, **attributes: str):
+    """
+    Create a span for task execution.
+
+    Args:
+        name: Task name
+        runtime_context: Optional RuntimeContext for trace linking
+        **attributes: Task attributes
+
+    Returns:
+        PySpan object to use as context manager
+
+    Example:
+        ```python
+        with create_task_span("process_data", runtime_context=ctx._runtime_context, batch_size="100") as s:
+            result = await process()
+        ```
+    """
+    return _create_span(name, "task", runtime_context, attributes)
+
+
+def create_workflow_span(name: str, runtime_context: Optional[Any] = None, **attributes: str):
+    """
+    Create a span for workflow execution.
+
+    Args:
+        name: Workflow name
+        runtime_context: Optional RuntimeContext for trace linking
+        **attributes: Workflow attributes
+
+    Returns:
+        PySpan object to use as context manager
+    """
+    return _create_span(name, "workflow", runtime_context, attributes)
+
+
+def create_agent_span(name: str, runtime_context: Optional[Any] = None, **attributes: str):
+    """
+    Create a span for agent execution.
+
+    Args:
+        name: Agent name
+        runtime_context: Optional RuntimeContext for trace linking
+        **attributes: Agent attributes
+
+    Returns:
+        PySpan object to use as context manager
+    """
+    return _create_span(name, "agent", runtime_context, attributes)
+
+
+__all__ = [
+    "span",
+    "span_context",
+    "create_task_span",
+    "create_workflow_span",
+    "create_agent_span",
+]

agnt5/types.py

@@ -0,0 +1,110 @@
+"""Type definitions and protocols for AGNT5 SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Awaitable, Callable, Dict, List, Optional, Protocol, TypeVar, Union
+
+# Type aliases
+JSON = Union[Dict[str, Any], List[Any], str, int, float, bool, None]
+HandlerFunc = Callable[..., Awaitable[Any]]
+
+T = TypeVar("T")
+
+
+class BackoffType(str, Enum):
+    """Backoff strategy for retry policies."""
+
+    CONSTANT = "constant"
+    LINEAR = "linear"
+    EXPONENTIAL = "exponential"
+
+
+@dataclass
+class RetryPolicy:
+    """Configuration for function retry behavior."""
+
+    max_attempts: int = 3
+    initial_interval_ms: int = 1000
+    max_interval_ms: int = 60000
+
+    def __post_init__(self) -> None:
+        if self.max_attempts < 1:
+            raise ValueError("max_attempts must be at least 1")
+        if self.initial_interval_ms < 0:
+            raise ValueError("initial_interval_ms must be non-negative")
+        if self.max_interval_ms < self.initial_interval_ms:
+            raise ValueError("max_interval_ms must be >= initial_interval_ms")
+
+
+@dataclass
+class BackoffPolicy:
+    """Configuration for retry backoff strategy."""
+
+    type: BackoffType = BackoffType.EXPONENTIAL
+    multiplier: float = 2.0
+
+    def __post_init__(self) -> None:
+        if self.multiplier <= 0:
+            raise ValueError("multiplier must be positive")
+
+
+@dataclass
+class FunctionConfig:
+    """Configuration for a function handler."""
+
+    name: str
+    handler: HandlerFunc
+    retries: Optional[RetryPolicy] = None
+    backoff: Optional[BackoffPolicy] = None
+    input_schema: Optional[Dict[str, Any]] = None
+    output_schema: Optional[Dict[str, Any]] = None
+    metadata: Optional[Dict[str, str]] = None
+
+
+@dataclass
+class WorkflowConfig:
+    """Configuration for a workflow handler."""
+
+    name: str
+    handler: HandlerFunc
+    input_schema: Optional[Dict[str, Any]] = None
+    output_schema: Optional[Dict[str, Any]] = None
+    metadata: Optional[Dict[str, str]] = None
+
+
+class ContextProtocol(Protocol):
+    """Protocol defining the Context interface."""
+
+    @property
+    def run_id(self) -> str:
+        """Workflow/run identifier."""
+        ...
+
+    @property
+    def step_id(self) -> Optional[str]:
+        """Current step identifier."""
+        ...
+
+    @property
+    def attempt(self) -> int:
+        """Retry attempt number."""
+        ...
+
+    @property
+    def component_type(self) -> str:
+        """Component type: 'function', 'entity', 'workflow'."""
+        ...
+
+    async def get(self, key: str, default: Any = None) -> Any:
+        """Get value from state."""
+        ...
+
+    def set(self, key: str, value: Any) -> None:
+        """Set value in state."""
+        ...
+
+    def delete(self, key: str) -> None:
+        """Delete key from state."""
+        ...

agnt5/version.py

@@ -0,0 +1,19 @@
+"""Version information for agnt5 SDK."""
+
+
+def _get_version() -> str:
+    """Get package version from installed metadata.
+
+    This uses importlib.metadata (Python 3.8+) to read the version from
+    the installed package metadata, maintaining pyproject.toml as the
+    single source of truth.
+
+    Returns:
+        Package version string, or "0.0.0+dev" for development installs.
+    """
+    try:
+        from importlib.metadata import version
+        return version("agnt5")
+    except Exception:
+        # Development/editable install fallback
+        return "0.0.0+dev"