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

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
 
@@ -21,13 +21,19 @@ def MCField(  # pylint: disable=invalid-name
     default: str,
     choices: Union[List[str], Dict[str, List[str]]],
 ) -> Field:
-    field = Field(default=default, description="ID of the model to use")
+    # Pydantic 2.12+ no longer allows post-creation mutation of field properties
     if isinstance(choices, dict):
-        field.json_schema_extra = {"choices": choices, "x-parameter": "grouped_choice"}
+        json_extra = {"choices": choices, "x-parameter": "grouped_choice"}
     elif isinstance(choices, list):
-        field.json_schema_extra = {"choices": choices, "x-parameter": "choice"}
-
-    return field
+        json_extra = {"choices": choices, "x-parameter": "choice"}
+    else:
+        json_extra = {}
+
+    return Field(
+        default=default,
+        description="ID of the model to use",
+        json_schema_extra=json_extra,
+    )
 
 
 class LLMTokenUsage(BaseModel):
@@ -65,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,
@@ -329,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):
@@ -381,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,
     )
 
@@ -415,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",
@@ -456,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"""
 
@@ -502,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
 
@@ -512,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(
@@ -535,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:
@@ -610,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)
@@ -652,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:

agenta/sdk/utils/client.py

@@ -0,0 +1,38 @@
+import requests
+
+BASE_TIMEOUT = 10
+
+from agenta.sdk.utils.logging import get_module_logger
+
+import agenta as ag
+
+log = get_module_logger(__name__)
+
+
+def authed_api():
+    """
+    Preconfigured requests for authenticated endpoints (supports all methods).
+    """
+
+    api_url = ag.DEFAULT_AGENTA_SINGLETON_INSTANCE.api_url
+    api_key = ag.DEFAULT_AGENTA_SINGLETON_INSTANCE.api_key
+
+    if not api_url or not api_key:
+        log.error("Please call ag.init() first.")
+        log.error("And don't forget to set AGENTA_API_URL and AGENTA_API_KEY.")
+        raise ValueError("API URL and API Key must be set.")
+
+    def _request(method: str, endpoint: str, **kwargs):
+        url = f"{api_url}{endpoint}"
+        headers = kwargs.pop("headers", {})
+        headers.setdefault("Authorization", f"ApiKey {api_key}")
+
+        return requests.request(
+            method=method,
+            url=url,
+            headers=headers,
+            timeout=BASE_TIMEOUT,
+            **kwargs,
+        )
+
+    return _request

agenta/sdk/utils/helpers.py

@@ -20,25 +20,26 @@ def parse_url(url: str) -> str:
         str: The parsed or rewritten URL suitable for the current environment and Docker network mode.
     """
 
-    # Normalize: remove trailing slash and /api suffix
     url = url.rstrip("/")
-    if url.endswith("/api"):
-        url = url[: -len("/api")]
 
-    if "localhost" not in url:
+    if "localhost" not in url and "0.0.0.0" not in url:
         return url
 
-    internal_url = os.getenv("AGENTA_API_INTERNAL_URL")
-    if internal_url:
-        return internal_url
-
     docker_network_mode = os.getenv("DOCKER_NETWORK_MODE")
 
     if docker_network_mode and docker_network_mode.lower() == "bridge":
-        return url.replace("localhost", "host.docker.internal")
-
-    if not docker_network_mode or docker_network_mode.lower() == "host":
+        return url.replace(
+            "localhost",
+            "host.docker.internal",
+        ).replace(
+            "0.0.0.0",
+            "host.docker.internal",
+        )
+
+    if (
+        not docker_network_mode
+        or (docker_network_mode and docker_network_mode.lower()) == "host"
+    ):
         return url
 
-    # For any other network mode, return the URL unchanged
     return url

agenta/sdk/utils/logging.py

@@ -8,15 +8,6 @@ import logging
 import structlog
 from structlog.typing import EventDict, WrappedLogger, Processor
 
-# from datetime import datetime
-# from logging.handlers import RotatingFileHandler
-
-# from opentelemetry.trace import get_current_span
-# from opentelemetry._logs import set_logger_provider
-# from opentelemetry.sdk._logs import LoggingHandler, LoggerProvider
-# from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
-# from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
-
 TRACE_LEVEL = 1
 logging.TRACE = TRACE_LEVEL
 logging.addLevelName(TRACE_LEVEL, "TRACE")
@@ -40,15 +31,6 @@ structlog.stdlib.BoundLogger.trace = bound_logger_trace
 AGENTA_LOG_CONSOLE_ENABLED = os.getenv("AGENTA_LOG_CONSOLE_ENABLED", "true") == "true"
 AGENTA_LOG_CONSOLE_LEVEL = os.getenv("AGENTA_LOG_CONSOLE_LEVEL", "TRACE").upper()
 
-# AGENTA_LOG_OTLP_ENABLED = os.getenv("AGENTA_LOG_OTLP_ENABLED", "false") == "true"
-# AGENTA_LOG_OTLP_LEVEL = os.getenv("AGENTA_LOG_OTLP_LEVEL", "INFO").upper()
-
-# AGENTA_LOG_FILE_ENABLED = os.getenv("AGENTA_LOG_FILE_ENABLED", "true") == "true"
-# AGENTA_LOG_FILE_LEVEL = os.getenv("AGENTA_LOG_FILE_LEVEL", "WARNING").upper()
-# AGENTA_LOG_FILE_BASE = os.getenv("AGENTA_LOG_FILE_PATH", "error")
-# LOG_FILE_DATE = datetime.utcnow().strftime("%Y-%m-%d")
-# AGENTA_LOG_FILE_PATH = f"{AGENTA_LOG_FILE_BASE}-{LOG_FILE_DATE}.log"
-
 # COLORS
 LEVEL_COLORS = {
     "TRACE": "\033[97m",
@@ -88,15 +70,6 @@ def process_positional_args(_, __, event_dict: EventDict) -> EventDict:
     return event_dict
 
 
-# def add_trace_context(_, __, event_dict: EventDict) -> EventDict:
-#     span = get_current_span()
-#     if span and span.get_span_context().is_valid:
-#         ctx = span.get_span_context()
-#         event_dict["TraceId"] = format(ctx.trace_id, "032x")
-#         event_dict["SpanId"] = format(ctx.span_id, "016x")
-#     return event_dict
-
-
 def add_logger_info(
     logger: WrappedLogger, method_name: str, event_dict: EventDict
 ) -> EventDict:
@@ -143,36 +116,9 @@ def colored_console_renderer() -> Processor:
     return render
 
 
-# def plain_renderer() -> Processor:
-#     hidden = {
-#         "SeverityText",
-#         "SeverityNumber",
-#         "MethodName",
-#         "logger_factory",
-#         "LoggerName",
-#         "level",
-#     }
-
-#     def render(_, __, event_dict: EventDict) -> str:
-#         ts = event_dict.pop("Timestamp", "")[:23] + "Z"
-#         level = event_dict.get("level", "")
-#         msg = event_dict.pop("event", "")
-#         padded = f"[{level:<5}]"
-#         logger = f"[{event_dict.pop('logger', '')}]"
-#         extras = " ".join(f"{k}={v}" for k, v in event_dict.items() if k not in hidden)
-#         return f"{ts} {padded} {msg} {logger} {extras}"
-
-#     return render
-
-
-# def json_renderer() -> Processor:
-#     return structlog.processors.JSONRenderer()
-
-
 SHARED_PROCESSORS: list[Processor] = [
     structlog.processors.TimeStamper(fmt="iso", utc=True, key="Timestamp"),
     process_positional_args,
-    # add_trace_context,
     add_logger_info,
     structlog.processors.format_exc_info,
     structlog.processors.dict_tracebacks,
@@ -193,35 +139,29 @@ def create_struct_logger(
     )
 
 
+# Guard against double initialization
+_LOGGING_CONFIGURED = False
+
 # CONFIGURE HANDLERS AND STRUCTLOG LOGGERS
 handlers = []
 loggers = []
 
-if AGENTA_LOG_CONSOLE_ENABLED:
-    h = logging.StreamHandler(sys.stdout)
-    h.setLevel(getattr(logging, AGENTA_LOG_CONSOLE_LEVEL, TRACE_LEVEL))
-    h.setFormatter(logging.Formatter("%(message)s"))
-    logging.getLogger("console").addHandler(h)
-    loggers.append(create_struct_logger([colored_console_renderer()], "console"))
+if AGENTA_LOG_CONSOLE_ENABLED and not _LOGGING_CONFIGURED:
+    _LOGGING_CONFIGURED = True
+
+    # Check if console logger already has handlers (from OSS module)
+    console_logger = logging.getLogger("console")
 
-# if AGENTA_LOG_FILE_ENABLED:
-#     h = RotatingFileHandler(AGENTA_LOG_FILE_PATH, maxBytes=10 * 1024 * 1024, backupCount=5)
-#     h.setLevel(getattr(logging, AGENTA_LOG_FILE_LEVEL, logging.WARNING))
-#     h.setFormatter(logging.Formatter("%(message)s"))
-#     logging.getLogger("file").addHandler(h)
-#     loggers.append(create_struct_logger([plain_renderer()], "file"))
-
-# if AGENTA_LOG_OTLP_ENABLED:
-#     provider = LoggerProvider()
-#     exporter = OTLPLogExporter()
-#     provider.add_log_record_processor(BatchLogRecordProcessor(exporter))
-#     set_logger_provider(provider)
-#     h = LoggingHandler(
-#         level=getattr(logging, AGENTA_LOG_OTLP_LEVEL, logging.INFO), logger_provider=provider
-#     )
-#     h.setFormatter(logging.Formatter("%(message)s"))
-#     logging.getLogger("otel").addHandler(h)
-#     loggers.append(create_struct_logger([json_renderer()], "otel"))
+    if not console_logger.handlers:
+        # Only add handler if it doesn't exist yet
+        h = logging.StreamHandler(sys.stdout)
+        h.setLevel(getattr(logging, AGENTA_LOG_CONSOLE_LEVEL, TRACE_LEVEL))
+        h.setFormatter(logging.Formatter("%(message)s"))
+        console_logger.addHandler(h)
+        console_logger.setLevel(TRACE_LEVEL)
+        console_logger.propagate = False
+
+    loggers.append(create_struct_logger([colored_console_renderer()], "console"))
 
 
 class MultiLogger:

agenta/sdk/utils/references.py

@@ -0,0 +1,23 @@
+from uuid import UUID
+import re
+import unicodedata
+
+
+def get_slug_from_name_and_id(
+    name: str,
+    id: UUID,  # pylint: disable=redefined-builtin
+) -> str:
+    # Normalize Unicode (e.g., é → e)
+    name = unicodedata.normalize("NFKD", name)
+    # Remove non-ASCII characters
+    name = name.encode("ascii", "ignore").decode("ascii")
+    # Lowercase and remove non-word characters except hyphens and spaces
+    name = re.sub(r"[^\w\s-]", "", name.lower())
+    # Replace any sequence of hyphens or whitespace with a single hyphen
+    name = re.sub(r"[-\s]+", "-", name)
+    # Trim leading/trailing hyphens
+    name = name.strip("-")
+    # Last 12 characters of the ID
+    slug = f"{name}-{id.hex[-12:]}"
+
+    return slug.lower()