mirascope 2.0.0a6__py3-none-any.whl → 2.0.2__py3-none-any.whl

mirascope/ops/_internal/tracing.py

@@ -11,8 +11,11 @@ from ...llm.calls import AsyncCall, AsyncContextCall, Call, ContextCall
 from ...llm.context import DepsT
 from .protocols import (
     AsyncFunction,
+    AsyncSpanFunction,
     SyncFunction,
+    SyncSpanFunction,
     fn_is_async,
+    fn_wants_span,
 )
 from .traced_calls import (
     TracedAsyncCall,
@@ -24,7 +27,9 @@ from .traced_calls import (
 )
 from .traced_functions import (
     AsyncTracedFunction,
+    AsyncTracedSpanFunction,
     TracedFunction,
+    TracedSpanFunction,
 )
 from .types import P, R
 
@@ -43,7 +48,7 @@ class TraceDecorator:
     """Arbitrary key-value pairs for additional metadata."""
 
     # IMPORTANT: The order of these overloads matters for type inference.
-    # Call type overloads come first, then function overloads.
+    # Call type overloads come first, then span function overloads, then regular functions.
     @overload
     def __call__(  # pyright: ignore[reportOverlappingOverload]
         self,
@@ -76,6 +81,22 @@ class TraceDecorator:
         """Overload for applying decorator to a Call."""
         ...
 
+    @overload
+    def __call__(  # pyright: ignore[reportOverlappingOverload]
+        self,
+        fn: AsyncSpanFunction[P, R],
+    ) -> AsyncTracedSpanFunction[P, R]:
+        """Overload for applying decorator to an async function with span injection."""
+        ...
+
+    @overload
+    def __call__(
+        self,
+        fn: SyncSpanFunction[P, R],
+    ) -> TracedSpanFunction[P, R]:
+        """Overload for applying decorator to a sync function with span injection."""
+        ...
+
     @overload
     def __call__(
         self,
@@ -99,6 +120,8 @@ class TraceDecorator:
             | ContextCall[P, DepsT, FormattableT]
             | AsyncCall[P, FormattableT]
             | Call[P, FormattableT]
+            | AsyncSpanFunction[P, R]
+            | SyncSpanFunction[P, R]
             | AsyncFunction[P, R]
             | SyncFunction[P, R]
         ),
@@ -107,12 +130,21 @@ class TraceDecorator:
         | TracedContextCall[P, DepsT, FormattableT]
         | TracedAsyncCall[P, FormattableT]
         | TracedCall[P, FormattableT]
+        | AsyncTracedSpanFunction[P, R]
+        | TracedSpanFunction[P, R]
         | AsyncTracedFunction[P, R]
         | TracedFunction[P, R]
     ):
         """Applies the decorator to the given function or Call object."""
         if is_call_type(fn):
             return wrap_call(fn=fn, tags=self.tags, metadata=self.metadata)
+        elif fn_wants_span(fn):
+            if fn_is_async(fn):
+                return AsyncTracedSpanFunction(
+                    fn=fn, tags=self.tags, metadata=self.metadata
+                )
+            else:
+                return TracedSpanFunction(fn=fn, tags=self.tags, metadata=self.metadata)
         elif fn_is_async(fn):
             return AsyncTracedFunction(fn=fn, tags=self.tags, metadata=self.metadata)
         else:
@@ -174,6 +206,28 @@ def trace(
     ...
 
 
+@overload
+def trace(  # pyright: ignore[reportOverlappingOverload]
+    __fn: AsyncSpanFunction[P, R],
+    *,
+    tags: None = None,
+    metadata: None = None,
+) -> AsyncTracedSpanFunction[P, R]:
+    """Overload for directly decorating an async function with span injection."""
+    ...
+
+
+@overload
+def trace(
+    __fn: SyncSpanFunction[P, R],
+    *,
+    tags: None = None,
+    metadata: None = None,
+) -> TracedSpanFunction[P, R]:
+    """Overload for directly decorating a sync function with span injection."""
+    ...
+
+
 @overload
 def trace(
     __fn: AsyncFunction[P, R],
@@ -202,6 +256,8 @@ def trace(  # pyright: ignore[reportGeneralTypeIssues]
         | ContextCall[P, DepsT, FormattableT]
         | AsyncCall[P, FormattableT]
         | Call[P, FormattableT]
+        | AsyncSpanFunction[P, R]
+        | SyncSpanFunction[P, R]
         | AsyncFunction[P, R]
         | SyncFunction[P, R]
         | None
@@ -214,6 +270,8 @@ def trace(  # pyright: ignore[reportGeneralTypeIssues]
     | TracedContextCall[P, DepsT, FormattableT]
     | TracedAsyncCall[P, FormattableT]
     | TracedCall[P, FormattableT]
+    | AsyncTracedSpanFunction[P, R]
+    | TracedSpanFunction[P, R]
     | AsyncTracedFunction[P, R]
     | TracedFunction[P, R]
     | TraceDecorator
@@ -227,6 +285,9 @@ def trace(  # pyright: ignore[reportGeneralTypeIssues]
     When decorating an @llm.call function, returns a TracedCall that wraps both
     the call and stream methods with tracing capabilities.
 
+    If the decorated function has `trace_ctx: Span` as its first parameter,
+    the span will be injected automatically and callers should NOT pass it.
+
     Args:
         __fn: The function or Call object to decorate.
         tags: Optional list of string tags to associate with traced executions.
@@ -262,6 +323,17 @@ def trace(  # pyright: ignore[reportGeneralTypeIssues]
         print(trace.result.content)
         print(trace.span_id)
         ```
+
+    Example:
+        ```python
+        @ops.trace
+        def my_fn(trace_ctx: Span, arg: str) -> str:
+            trace_ctx.info(f"Processing: {arg}")
+            return arg.upper()
+
+        # Call without trace_ctx - it's injected automatically
+        result = my_fn("hello")  # Returns "HELLO"
+        ```
     """
     tags = tuple(sorted(set(tags or [])))
     metadata = metadata or {}
@@ -270,6 +342,11 @@ def trace(  # pyright: ignore[reportGeneralTypeIssues]
 
     if is_call_type(__fn):
         return wrap_call(fn=__fn, tags=tags, metadata=metadata)
+    elif fn_wants_span(__fn):
+        if fn_is_async(__fn):
+            return AsyncTracedSpanFunction(fn=__fn, tags=tags, metadata=metadata)
+        else:
+            return TracedSpanFunction(fn=__fn, tags=tags, metadata=metadata)
     elif fn_is_async(__fn):
         return AsyncTracedFunction(fn=__fn, tags=tags, metadata=metadata)
     else:

mirascope/ops/_internal/utils.py

@@ -6,7 +6,7 @@ from typing import Any, TypeAlias
 
 import orjson
 
-from .protocols import P
+from .protocols import P, fn_wants_span
 
 ORJSON_OPTS = (
     orjson.OPT_NON_STR_KEYS
@@ -25,18 +25,56 @@ def json_dumps(obj: Any) -> str:  # noqa: ANN401
     return orjson.dumps(obj, option=ORJSON_OPTS).decode("utf-8")
 
 
+def _is_call_method(fn: Callable[..., Any]) -> bool:
+    """Check if fn is a bound method of a Call object (e.g., Call.call or Call.stream)."""
+    return (
+        hasattr(fn, "__self__") and hasattr(fn.__self__, "prompt")  # pyright: ignore[reportFunctionMemberAccess]
+    )
+
+
+def get_original_fn(fn: Callable[..., Any]) -> Callable[..., Any]:
+    """Get the original unwrapped function.
+
+    Follows the __wrapped__ chain set by copy_function_metadata() to find the
+    original function. Falls back to checking for Call methods for bound methods.
+    """
+    # Follow __wrapped__ chain if available (set by copy_function_metadata)
+    # In practice, get_original_fn is called with original functions or bound methods,
+    # so this loop is defensive code for edge cases like @functools.wraps chains.
+    while hasattr(fn, "__wrapped__"):
+        fn = fn.__wrapped__  # pyright: ignore[reportFunctionMemberAccess] # pragma: no cover
+
+    # Handle bound methods of Call objects (e.g., Call.call or Call.stream)
+    if _is_call_method(fn):
+        prompt = fn.__self__.prompt  # pyright: ignore[reportFunctionMemberAccess]
+        if hasattr(prompt, "fn"):
+            return get_original_fn(prompt.fn)
+
+    return fn
+
+
 def get_qualified_name(fn: Callable[..., Any]) -> str:
     """Return the simplified qualified name of a function.
 
+    If the function is a bound method of a Call object (e.g., Call.call or Call.stream),
+    returns the qualified name of the original decorated function from prompt.fn,
+    suffixed with the method name (e.g., "recommend.call" or "recommend.stream").
+
     If the function is defined locally, return the name after '<locals>.'; otherwise,
     return the last non-empty part after splitting by '.'.
     """
+    # Check if this is a Call method and capture the method name
+    method_suffix = f".{fn.__name__}" if _is_call_method(fn) else ""
+
+    fn = get_original_fn(fn)
     qualified_name = fn.__qualname__
     if "<locals>." in qualified_name:
-        return qualified_name.split("<locals>.")[-1]
+        base_name = qualified_name.split("<locals>.")[-1]
     else:
         parts = [part for part in qualified_name.split(".") if part]
-        return parts[-1] if parts else qualified_name
+        base_name = parts[-1] if parts else qualified_name
+
+    return f"{base_name}{method_suffix}"
 
 
 def extract_arguments(
@@ -44,8 +82,26 @@ def extract_arguments(
     *args: P.args,
     **kwargs: P.kwargs,
 ) -> tuple[dict[str, str], dict[str, Any]]:
-    """Returns a tuple of (arg_types, arg_values) dictionaries from function call."""
+    """Returns a tuple of (arg_types, arg_values) dictionaries from function call.
+
+    If the function is a Call method (e.g., Call.call), uses the original
+    decorated function's signature to get proper parameter names and types.
+
+    If the function has `trace_ctx: Span` as first parameter (detected via
+    fn_wants_span), that parameter is skipped since it's injected by the
+    decorator and shouldn't be recorded in span attributes.
+    """
+    # Use original function signature for Call methods
+    fn = get_original_fn(fn)
     signature = inspect.signature(fn)
+
+    # If function wants span injection, skip the first parameter
+    if fn_wants_span(fn):
+        params = list(signature.parameters.values())
+        if params:
+            remaining_params = params[1:]
+            signature = signature.replace(parameters=remaining_params)
+
     bound_arguments = signature.bind(*args, **kwargs)
     bound_arguments.apply_defaults()
 

mirascope/ops/_internal/versioned_functions.py

@@ -196,7 +196,7 @@ class _BaseVersionedFunction(_BaseTracedFunction[P, R, Any]):
             if self.name:
                 span.set(**{"mirascope.version.name": self.name})
             if self.tags:
-                span.set(**{"mirascope.version.tags": self.tags})
+                span.set(**{"mirascope.version.tags": list(self.tags)})
             if self.metadata:
                 for key, value in self.metadata.items():
                     span.set(**{f"mirascope.version.meta.{key}": value})

{mirascope-2.0.0a6.dist-info → mirascope-2.0.2.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: mirascope
-Version: 2.0.0a6
-Summary: LLM abstractions that aren't obstructions
+Version: 2.0.2
+Summary: Every frontier LLM. One unified interface.
 Project-URL: Homepage, https://mirascope.com
 Project-URL: Documentation, https://mirascope.com/docs/mirascope/v2
 Project-URL: Repository, https://github.com/Mirascope/mirascope/tree/v2
@@ -11,7 +11,7 @@ Author-email: William Bakst <william@mirascope.com>, Dandelion Mané <dandelion@
 Maintainer-email: William Bakst <william@mirascope.com>, Dandelion Mané <dandelion@mirascope.com>
 License: MIT License
         
-        Copyright (c) 2023 Mirascope, Inc.
+        Copyright (c) 2026 Mirascope, Inc.
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
@@ -31,8 +31,8 @@ License: MIT License
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
 License-File: LICENSE
-Keywords: agents,artificial intelligence,developer tools,llm,llm tools,prompt engineering
-Classifier: Development Status :: 3 - Alpha
+Keywords: agents,anthropic,artificial intelligence,context engineering,developer tools,gemini,llm,llm tools,openai,prompt engineering
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
@@ -48,15 +48,16 @@ Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.10
 Requires-Dist: docstring-parser>=0.17.0
 Requires-Dist: httpx>=0.27.0
+Requires-Dist: jiter>=0.7.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: typing-extensions>=4.10.0
 Provides-Extra: all
-Requires-Dist: anthropic<1.0,>=0.75.0; extra == 'all'
-Requires-Dist: google-genai<2,>=1.57.0; extra == 'all'
+Requires-Dist: anthropic<1.0,>=0.76.0; extra == 'all'
+Requires-Dist: google-genai<2,>=1.58.0; extra == 'all'
 Requires-Dist: libcst>=1.8.6; extra == 'all'
 Requires-Dist: mcp<2,>=1.25.0; extra == 'all'
 Requires-Dist: mlx-lm<1,>=0.28.4; extra == 'all'
-Requires-Dist: openai<3,>=2.14.0; extra == 'all'
+Requires-Dist: openai<3,>=2.15.0; extra == 'all'
 Requires-Dist: opentelemetry-api<2,>=1.38.0; extra == 'all'
 Requires-Dist: opentelemetry-exporter-otlp<2,>=1.38.0; extra == 'all'
 Requires-Dist: opentelemetry-instrumentation<1,>=0.59b0; extra == 'all'
@@ -70,11 +71,11 @@ Requires-Dist: pillow<11,>=10.4.0; extra == 'all'
 Requires-Dist: proto-plus>=1.24.0; extra == 'all'
 Requires-Dist: pydantic-settings>=2.12.0; extra == 'all'
 Provides-Extra: anthropic
-Requires-Dist: anthropic<1.0,>=0.75.0; extra == 'anthropic'
+Requires-Dist: anthropic<1.0,>=0.76.0; extra == 'anthropic'
 Provides-Extra: api
 Requires-Dist: pydantic-settings>=2.12.0; extra == 'api'
 Provides-Extra: google
-Requires-Dist: google-genai<2,>=1.57.0; extra == 'google'
+Requires-Dist: google-genai<2,>=1.58.0; extra == 'google'
 Requires-Dist: pillow<11,>=10.4.0; extra == 'google'
 Requires-Dist: proto-plus>=1.24.0; extra == 'google'
 Provides-Extra: mcp
@@ -82,7 +83,7 @@ Requires-Dist: mcp<2,>=1.25.0; extra == 'mcp'
 Provides-Extra: mlx
 Requires-Dist: mlx-lm<1,>=0.28.4; extra == 'mlx'
 Provides-Extra: openai
-Requires-Dist: openai<3,>=2.14.0; extra == 'openai'
+Requires-Dist: openai<3,>=2.15.0; extra == 'openai'
 Provides-Extra: ops
 Requires-Dist: libcst>=1.8.6; extra == 'ops'
 Requires-Dist: opentelemetry-api<2,>=1.38.0; extra == 'ops'