agenta 0.57.0__py3-none-any.whl → 0.63.2__py3-none-any.whl

agenta/sdk/tracing/exporters.py

@@ -1,4 +1,7 @@
-from typing import Sequence, Dict, List, Optional
+from typing import Sequence, Dict, List, Optional, Any
+from threading import Thread
+from os import environ
+from uuid import UUID
 
 from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
 from opentelemetry.sdk.trace.export import (
@@ -8,18 +11,21 @@ from opentelemetry.sdk.trace.export import (
     ReadableSpan,
 )
 
+from agenta.sdk.utils.constants import TRUTHY
 from agenta.sdk.utils.logging import get_module_logger
 from agenta.sdk.utils.exceptions import suppress
 from agenta.sdk.utils.cache import TTLLRUCache
-from agenta.sdk.context.tracing import (
-    tracing_exporter_context_manager,
-    tracing_exporter_context,
-    TracingExporterContext,
+from agenta.sdk.contexts.tracing import (
+    otlp_context_manager,
+    otlp_context,
+    OTLPContext,
 )
 
 
 log = get_module_logger(__name__)
 
+_ASYNC_EXPORT = environ.get("AGENTA_OTLP_ASYNC_EXPORT", "true").lower() in TRUTHY
+
 
 class InlineTraceExporter(SpanExporter):
     def __init__(
@@ -45,6 +51,8 @@ class InlineTraceExporter(SpanExporter):
 
                 self._registry[trace_id].append(span)
 
+            return
+
     def shutdown(self) -> None:
         self._shutdown = True
 
@@ -84,7 +92,7 @@ class OTLPExporter(OTLPSpanExporter):
         self.credentials = credentials
 
     def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult:
-        grouped_spans: Dict[str, List[str]] = {}
+        grouped_spans: Dict[Optional[str], List[ReadableSpan]] = dict()
 
         for span in spans:
             trace_id = span.get_span_context().trace_id
@@ -94,18 +102,28 @@ class OTLPExporter(OTLPSpanExporter):
                 credentials = self.credentials.get(trace_id)
 
             if credentials not in grouped_spans:
-                grouped_spans[credentials] = []
+                grouped_spans[credentials] = list()
 
             grouped_spans[credentials].append(span)
 
         serialized_spans = []
 
         for credentials, _spans in grouped_spans.items():
-            with tracing_exporter_context_manager(
-                context=TracingExporterContext(
+            with otlp_context_manager(
+                context=OTLPContext(
                     credentials=credentials,
                 )
             ):
+                for _span in _spans:
+                    trace_id = _span.get_span_context().trace_id
+                    span_id = _span.get_span_context().span_id
+
+                    # log.debug(
+                    #     "[SPAN]  [EXPORT]",
+                    #     trace_id=UUID(int=trace_id).hex,
+                    #     span_id=UUID(int=span_id).hex[-16:],
+                    # )
+
                 serialized_spans.append(super().export(_spans))
 
         if all(serialized_spans):
@@ -114,16 +132,48 @@ class OTLPExporter(OTLPSpanExporter):
             return SpanExportResult.FAILURE
 
     def _export(self, serialized_data: bytes, timeout_sec: Optional[float] = None):
-        credentials = tracing_exporter_context.get().credentials
+        try:
+            credentials = otlp_context.get().credentials
+
+            if credentials:
+                self._session.headers.update({"Authorization": credentials})
+
+            def __export():
+                with suppress():
+                    resp = None
+                    if timeout_sec is not None:
+                        resp = super(OTLPExporter, self)._export(
+                            serialized_data,
+                            timeout_sec,
+                        )
+                    else:
+                        resp = super(OTLPExporter, self)._export(
+                            serialized_data,
+                        )
+
+                    # log.debug(
+                    #     "[SPAN] [_EXPORT]",
+                    #     data=serialized_data,
+                    #     resp=resp,
+                    # )
+
+            if _ASYNC_EXPORT is True:
+                # log.debug("[SPAN] [ASYNC.X]", credentials=(credentials is not None))
+                thread = Thread(target=__export, daemon=False)
+                thread.start()
+            else:
+                # log.debug("[SPAN] [ SYNC.X]", credentials=(credentials is not None))
+                return __export()
 
-        if credentials:
-            self._session.headers.update({"Authorization": credentials})
+        except Exception as e:
+            log.error(f"Export failed with error: {e}", exc_info=True)
 
-        with suppress():
-            if timeout_sec is not None:
-                return super()._export(serialized_data, timeout_sec)
-            else:
-                return super()._export(serialized_data)
+        finally:
+
+            class Response:
+                ok = True
+
+            return Response()
 
 
 ConsoleExporter = ConsoleSpanExporter

agenta/sdk/tracing/processors.py

@@ -1,5 +1,7 @@
 from typing import Optional, Dict, List
 from threading import Lock
+from json import dumps
+from uuid import UUID
 
 from opentelemetry.baggage import get_all as get_baggage
 from opentelemetry.context import Context
@@ -9,10 +11,13 @@ from opentelemetry.sdk.trace.export import (
     ReadableSpan,
     BatchSpanProcessor,
 )
+from opentelemetry.trace import SpanContext
 
 from agenta.sdk.utils.logging import get_module_logger
 from agenta.sdk.tracing.conventions import Reference
 
+from agenta.sdk.contexts.tracing import TracingContext
+
 log = get_module_logger(__name__)
 
 
@@ -50,6 +55,15 @@ class TraceProcessor(SpanProcessor):
         span: Span,
         parent_context: Optional[Context] = None,
     ) -> None:
+        trace_id = span.context.trace_id
+        span_id = span.context.span_id
+
+        # log.debug(
+        #     "[SPAN] [START] ",
+        #     trace_id=UUID(int=trace_id).hex,
+        #     span_id=UUID(int=span_id).hex[-16:],
+        # )
+
         for key in self.references.keys():
             span.set_attribute(f"ag.refs.{key}", self.references[key])
 
@@ -61,6 +75,83 @@ class TraceProcessor(SpanProcessor):
                 if _key in [_.value for _ in Reference.__members__.values()]:
                     span.set_attribute(key, baggage[key])
 
+        context = TracingContext.get()
+
+        trace_type = span.attributes.get("trace_type") if span.attributes else None
+
+        context.annotate = (
+            context.annotate
+            or (context.type == "annotation")
+            or (trace_type == "annotation")
+        )
+        context.type = (
+            (str(trace_type) if trace_type else None)
+            or context.type
+            or ("annotation" if context.annotate else "invocation")
+        )
+
+        span.set_attribute("ag.type.tree", context.type)
+
+        if context.flags:
+            for key in context.flags.keys():
+                span.set_attribute(f"ag.flags.{key}", context.flags[key])
+        # if context.tags:
+        #     for key in context.tags.keys():
+        #         span.set_attribute(f"ag.tags.{key}", context.tags[key])
+        # if context.meta:
+        #     span.set_attribute(f"ag.meta.", dumps(context.meta))
+
+        # --- DISTRIBUTED
+        if not self.inline:
+            if context.links:
+                for key, link in context.links.items():
+                    try:
+                        link = link.model_dump(mode="json", exclude_none=True)
+                    except:  # pylint: disable=bare-except
+                        pass
+                    if not isinstance(link, dict):
+                        continue
+                    if not link.get("trace_id") or not link.get("span_id"):
+                        continue
+
+                    span.add_link(
+                        context=SpanContext(
+                            trace_id=int(str(link.get("trace_id")), 16),
+                            span_id=int(str(link.get("span_id")), 16),
+                            is_remote=True,
+                        ),
+                        attributes=dict(
+                            key=str(key),
+                        ),
+                    )
+
+        if context.references:
+            for key, ref in context.references.items():
+                try:
+                    ref = ref.model_dump(mode="json", exclude_none=True)
+                except:  # pylint: disable=bare-except
+                    pass
+                if not isinstance(ref, dict):
+                    continue
+                if not ref.get("id") and not ref.get("slug") and not ref.get("version"):
+                    continue
+
+                if ref.get("id"):
+                    span.set_attribute(
+                        f"ag.refs.{key}.id",
+                        str(ref.get("id")),
+                    )
+                if ref.get("slug"):
+                    span.set_attribute(
+                        f"ag.refs.{key}.slug",
+                        str(ref.get("slug")),
+                    )
+                if ref.get("version"):
+                    span.set_attribute(
+                        f"ag.refs.{key}.version",
+                        str(ref.get("version")),
+                    )
+
         trace_id = span.context.trace_id
         span_id = span.context.span_id
 
@@ -74,6 +165,12 @@ class TraceProcessor(SpanProcessor):
         trace_id = span.context.trace_id
         span_id = span.context.span_id
 
+        # log.debug(
+        #     "[SPAN] [END]   ",
+        #     trace_id=UUID(int=trace_id).hex,
+        #     span_id=UUID(int=span_id).hex[-16:],
+        # )
+
         self._spans.setdefault(trace_id, []).append(span)
         self._registry.setdefault(trace_id, {})
         self._registry[trace_id].pop(span_id, None)

agenta/sdk/tracing/propagation.py

@@ -6,6 +6,8 @@ from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapProp
 from opentelemetry.baggage import set_baggage
 from opentelemetry.context import get_current
 
+from agenta.sdk.contexts.tracing import TracingContext
+
 import agenta as ag
 
 
@@ -72,7 +74,7 @@ def inject(
 
     _context = get_current()
 
-    ctx = ag.sdk.context.tracing.tracing_context.get()
+    ctx = TracingContext.get()
 
     # --- Inject traceparent --- #
     try:

agenta/sdk/tracing/spans.py

@@ -35,6 +35,10 @@ class CustomSpan(Span):  # INHERITANCE FOR TYPING ONLY
 
     ## --- PROXY METHODS --- ##
 
+    @property
+    def name(self) -> str:
+        return self._span.name
+
     def get_span_context(self):
         return self._span.get_span_context()
 

agenta/sdk/tracing/tracing.py

@@ -99,19 +99,6 @@ class Tracing(metaclass=Singleton):
             resource=Resource(attributes={"service.name": "agenta-sdk"})
         )
 
-        # --- INLINE
-        if inline:
-            # TRACE PROCESSORS -- INLINE
-            self.inline = TraceProcessor(
-                InlineExporter(
-                    registry=self.inline_spans,
-                ),
-                references=self.references,
-                inline=inline,
-            )
-            self.tracer_provider.add_span_processor(self.inline)
-        # --- INLINE
-
         # TRACE PROCESSORS -- OTLP
         try:
             log.info("Agenta - OLTP URL: %s", self.otlp_url)
@@ -129,6 +116,19 @@ class Tracing(metaclass=Singleton):
         except:  # pylint: disable=bare-except
             log.warning("Agenta - OLTP unreachable, skipping exports.")
 
+        # --- INLINE
+        if inline:
+            # TRACE PROCESSORS -- INLINE
+            self.inline = TraceProcessor(
+                InlineExporter(
+                    registry=self.inline_spans,
+                ),
+                references=self.references,
+                inline=inline,
+            )
+            self.tracer_provider.add_span_processor(self.inline)
+        # --- INLINE
+
         # GLOBAL TRACER PROVIDER -- INSTRUMENTATION LIBRARIES
         set_tracer_provider(self.tracer_provider)
         # TRACER

agenta/sdk/types.py

@@ -3,7 +3,7 @@ from dataclasses import dataclass
 from typing import List, Union, Optional, Dict, Literal, Any
 
 from pydantic import ConfigDict, BaseModel, HttpUrl
-from pydantic import BaseModel, Field, model_validator
+from pydantic import BaseModel, Field, model_validator, AliasChoices
 
 from starlette.responses import StreamingResponse
 
@@ -71,15 +71,15 @@ class StreamResponse(StreamingResponse):
     ):
         headers = dict(extra_headers or {})
         if version is not None:
-            headers["X-ag-version"] = version
+            headers["x-ag-version"] = version
         if content_type:
-            headers["X-ag-content-type"] = content_type
+            headers["x-ag-content-type"] = content_type
         if tree_id:
-            headers["X-ag-tree-id"] = tree_id
+            headers["x-ag-tree-id"] = tree_id
         if trace_id:
-            headers["X-ag-trace-id"] = trace_id
+            headers["x-ag-trace-id"] = trace_id
         if span_id:
-            headers["X-ag-span-id"] = span_id
+            headers["x-ag-span-id"] = span_id
 
         super().__init__(
             content=content,
@@ -335,7 +335,29 @@ class ContentPartImage(BaseModel):
     image_url: ImageURL
 
 
-ContentPart = Union[ContentPartText, ContentPartImage]
+class FileInput(BaseModel):
+    file_id: Optional[str] = Field(
+        default=None,
+        alias="file_id",
+        validation_alias=AliasChoices("file_id", "fileId"),
+    )
+    file_data: Optional[str] = Field(
+        default=None,
+        alias="file_data",
+        validation_alias=AliasChoices("file_data", "fileData"),
+    )
+    filename: Optional[str] = None
+    format: Optional[str] = None
+
+    model_config = {"populate_by_name": True}
+
+
+class ContentPartFile(BaseModel):
+    type: Literal["file"] = "file"
+    file: FileInput
+
+
+ContentPart = Union[ContentPartText, ContentPartImage, ContentPartFile]
 
 
 class Message(BaseModel):
@@ -387,7 +409,7 @@ class ModelConfig(BaseModel):
     """Configuration for model parameters"""
 
     model: str = MCField(
-        default="gpt-3.5-turbo",
+        default="gpt-4o-mini",
         choices=supported_llm_models,
     )
 
@@ -421,6 +443,14 @@ class ModelConfig(BaseModel):
         le=2.0,
         description="Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far",
     )
+    reasoning_effort: Optional[Literal["none", "low", "medium", "high"]] = Field(
+        default=None,
+        description="Controls the reasoning effort for thinking models. Options: 'none' (cost-optimized, 0 tokens), 'low' (1024 tokens), 'medium' (2048 tokens), 'high' (4096 tokens)",
+        json_schema_extra={
+            "x-parameter": "choice",
+            "enum": ["none", "low", "medium", "high"],
+        },
+    )
     response_format: Optional[ResponseFormat] = Field(
         default=None,
         description="An object specifying the format that the model must output",
@@ -462,6 +492,154 @@ class TemplateFormatError(PromptTemplateError):
         super().__init__(message)
 
 
+import json
+import re
+from typing import Any, Dict, Iterable, Tuple, Optional
+
+# --- Optional dependency: python-jsonpath (provides JSONPath + JSON Pointer) ---
+try:
+    import jsonpath  # ✅ use module API
+    from jsonpath import JSONPointer  # pointer class is fine to use
+except Exception:
+    jsonpath = None
+    JSONPointer = None
+
+# ========= Scheme detection =========
+
+
+def detect_scheme(expr: str) -> str:
+    """Return 'json-path', 'json-pointer', or 'dot-notation' based on the placeholder prefix."""
+    if expr.startswith("$"):
+        return "json-path"
+    if expr.startswith("/"):
+        return "json-pointer"
+    return "dot-notation"
+
+
+# ========= Resolvers =========
+
+
+def resolve_dot_notation(expr: str, data: dict) -> object:
+    if "[" in expr or "]" in expr:
+        raise KeyError(f"Bracket syntax is not supported in dot-notation: {expr!r}")
+
+    # First, check if the expression exists as a literal key (e.g., "topic.story" as a single key)
+    # This allows users to use dots in their variable names without nested access
+    if expr in data:
+        return data[expr]
+
+    # If not found as a literal key, try to parse as dot-notation path
+    cur = data
+    for token in (p for p in expr.split(".") if p):
+        if isinstance(cur, list) and token.isdigit():
+            cur = cur[int(token)]
+        else:
+            if not isinstance(cur, dict):
+                raise KeyError(
+                    f"Cannot access key {token!r} on non-dict while resolving {expr!r}"
+                )
+            if token not in cur:
+                raise KeyError(f"Missing key {token!r} while resolving {expr!r}")
+            cur = cur[token]
+    return cur
+
+
+def resolve_json_path(expr: str, data: dict) -> object:
+    if jsonpath is None:
+        raise ImportError("python-jsonpath is required for json-path ($...)")
+
+    if not (expr == "$" or expr.startswith("$.") or expr.startswith("$[")):
+        raise ValueError(
+            f"Invalid json-path expression {expr!r}. "
+            "Must start with '$', '$.' or '$[' (no implicit normalization)."
+        )
+
+    # Use package-level APIf
+    results = jsonpath.findall(expr, data)  # always returns a list
+    return results[0] if len(results) == 1 else results
+
+
+def resolve_json_pointer(expr: str, data: Dict[str, Any]) -> Any:
+    """Resolve a JSON Pointer; returns a single value."""
+    if JSONPointer is None:
+        raise ImportError("python-jsonpath is required for json-pointer (/...)")
+    return JSONPointer(expr).resolve(data)
+
+
+def resolve_any(expr: str, data: Dict[str, Any]) -> Any:
+    """Dispatch to the right resolver based on detected scheme."""
+    scheme = detect_scheme(expr)
+    if scheme == "json-path":
+        return resolve_json_path(expr, data)
+    if scheme == "json-pointer":
+        return resolve_json_pointer(expr, data)
+    return resolve_dot_notation(expr, data)
+
+
+# ========= Placeholder & coercion helpers =========
+
+_PLACEHOLDER_RE = re.compile(r"\{\{\s*(.*?)\s*\}\}")
+
+
+def extract_placeholders(template: str) -> Iterable[str]:
+    """Yield the inner text of all {{ ... }} occurrences (trimmed)."""
+    for m in _PLACEHOLDER_RE.finditer(template):
+        yield m.group(1).strip()
+
+
+def coerce_to_str(value: Any) -> str:
+    """Pretty stringify values for embedding into templates."""
+    if isinstance(value, (dict, list)):
+        return json.dumps(value, ensure_ascii=False)
+    return str(value)
+
+
+def build_replacements(
+    placeholders: Iterable[str], data: Dict[str, Any]
+) -> Tuple[Dict[str, str], set]:
+    """
+    Resolve all placeholders against data.
+    Returns (replacements, unresolved_placeholders).
+    """
+    replacements: Dict[str, str] = {}
+    unresolved: set = set()
+    for expr in set(placeholders):
+        try:
+            val = resolve_any(expr, data)
+            # Escape backslashes to avoid regex replacement surprises
+            replacements[expr] = coerce_to_str(val).replace("\\", "\\\\")
+        except Exception:
+            unresolved.add(expr)
+    return replacements, unresolved
+
+
+def apply_replacements(template: str, replacements: Dict[str, str]) -> str:
+    """Replace {{ expr }} using a callback to avoid regex-injection issues."""
+
+    def _repl(m: re.Match) -> str:
+        expr = m.group(1).strip()
+        return replacements.get(expr, m.group(0))
+
+    return _PLACEHOLDER_RE.sub(_repl, template)
+
+
+def compute_truly_unreplaced(original: set, rendered: str) -> set:
+    """Only count placeholders that were in the original template and remain."""
+    now = set(extract_placeholders(rendered))
+    return original & now
+
+
+def missing_lib_hints(unreplaced: set) -> Optional[str]:
+    """Suggest installing python-jsonpath if placeholders indicate json-path or json-pointer usage."""
+    if any(expr.startswith("$") or expr.startswith("/") for expr in unreplaced) and (
+        jsonpath is None or JSONPointer is None
+    ):
+        return (
+            "Install python-jsonpath to enable json-path ($...) and json-pointer (/...)"
+        )
+    return None
+
+
 class PromptTemplate(BaseModel):
     """A template for generating prompts with formatting capabilities"""
 
@@ -508,6 +686,7 @@ class PromptTemplate(BaseModel):
         try:
             if self.template_format == "fstring":
                 return content.format(**kwargs)
+
             elif self.template_format == "jinja2":
                 from jinja2 import Template, TemplateError
 
@@ -518,22 +697,33 @@ class PromptTemplate(BaseModel):
                         f"Jinja2 template error in content: '{content}'. Error: {str(e)}",
                         original_error=e,
                     )
+
             elif self.template_format == "curly":
-                import re
+                original_placeholders = set(extract_placeholders(content))
+
+                replacements, _unresolved = build_replacements(
+                    original_placeholders, kwargs
+                )
+
+                result = apply_replacements(content, replacements)
 
-                result = content
-                for key, value in kwargs.items():
-                    result = re.sub(r"\{\{" + key + r"\}\}", str(value), result)
-                if re.search(r"\{\{.*?\}\}", result):
-                    unreplaced = re.findall(r"\{\{(.*?)\}\}", result)
+                truly_unreplaced = compute_truly_unreplaced(
+                    original_placeholders, result
+                )
+                if truly_unreplaced:
+                    hint = missing_lib_hints(truly_unreplaced)
+                    suffix = f" Hint: {hint}" if hint else ""
                     raise TemplateFormatError(
-                        f"Unreplaced variables in curly template: {unreplaced}"
+                        f"Unreplaced variables in curly template: {sorted(truly_unreplaced)}.{suffix}"
                     )
+
                 return result
+
             else:
                 raise TemplateFormatError(
                     f"Unknown template format: {self.template_format}"
                 )
+
         except KeyError as e:
             key = str(e).strip("'")
             raise TemplateFormatError(
@@ -541,7 +731,8 @@ class PromptTemplate(BaseModel):
             )
         except Exception as e:
             raise TemplateFormatError(
-                f"Error formatting template '{content}': {str(e)}", original_error=e
+                f"Error formatting template '{content}': {str(e)}",
+                original_error=e,
             )
 
     def _substitute_variables(self, obj: Any, kwargs: Dict[str, Any]) -> Any:
@@ -616,7 +807,7 @@ class PromptTemplate(BaseModel):
                 )
             )
 
-        new_llm_config = self.llm_config.copy(deep=True)
+        new_llm_config = self.llm_config.model_copy(deep=True)
         if new_llm_config.response_format is not None:
             rf_dict = new_llm_config.response_format.model_dump(by_alias=True)
             substituted = self._substitute_variables(rf_dict, kwargs)
@@ -658,6 +849,9 @@ class PromptTemplate(BaseModel):
         if self.llm_config.presence_penalty is not None:
             kwargs["presence_penalty"] = self.llm_config.presence_penalty
 
+        if self.llm_config.reasoning_effort is not None:
+            kwargs["reasoning_effort"] = self.llm_config.reasoning_effort
+
         if self.llm_config.response_format:
             kwargs["response_format"] = self.llm_config.response_format.dict(
                 by_alias=True

agenta/sdk/utils/cache.py

@@ -5,7 +5,7 @@ from collections import OrderedDict
 from threading import Lock
 
 CACHE_CAPACITY = int(getenv("AGENTA_MIDDLEWARE_CACHE_CAPACITY", "512"))
-CACHE_TTL = int(getenv("AGENTA_MIDDLEWARE_CACHE_TTL", str(5 * 60)))  # 5 minutes
+CACHE_TTL = int(getenv("AGENTA_MIDDLEWARE_CACHE_TTL", str(1 * 60)))  # 1 minutes
 
 
 class TTLLRUCache: