polyapi-python 0.3.19.dev4__py3-none-any.whl → 0.3.20__py3-none-any.whl

polyapi/__init__.py

@@ -1,25 +1,36 @@
 import copy
+import importlib
 import os
-import sys
 from contextvars import ContextVar, Token
 from dataclasses import dataclass
-from typing import Any, Dict, Literal, Optional, overload
+from types import ModuleType
+from typing import TYPE_CHECKING, Any, Dict, Literal, Optional, overload
 
 import truststore
 from typing_extensions import TypedDict
 
-from .cli_constants import CLI_COMMANDS
-
 truststore.inject_into_ssl()
 
 __all__ = ["poly"]
 
+if TYPE_CHECKING:
+    poly: ModuleType
+
 
-if len(sys.argv) > 1 and sys.argv[1] not in CLI_COMMANDS:
+def _load_generated_poly() -> ModuleType:
     currdir = os.path.dirname(os.path.abspath(__file__))
     if not os.path.isdir(os.path.join(currdir, "poly")):
-        print("No 'poly' found. Please run 'python3 -m polyapi generate' to generate the 'poly' library for your tenant.")
-        sys.exit(1)
+        raise ModuleNotFoundError(
+            "No 'poly' found. Please run 'python3 -m polyapi generate' "
+            "to generate the 'poly' library for your tenant."
+        )
+    return importlib.import_module(".poly", __name__)
+
+
+def __getattr__(name: str) -> ModuleType:
+    if name == "poly":
+        return _load_generated_poly()
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 
 class PolyCustomDict(TypedDict, total=False):

polyapi/ai_function.py

@@ -0,0 +1,96 @@
+from typing import Any, Dict, List, Tuple, cast
+
+from polyapi.typedefs import PropertySpecification, PropertyType
+from polyapi.utils import add_type_import_path, parse_arguments, get_type_and_def, return_type_already_defined_in_args, rewrite_arg_name
+
+AI_DEFS_TEMPLATE = """
+from typing import List, Dict, Any, TypedDict, Callable
+{args_def}
+{return_type_def}
+"""
+
+AI_FUNCTION_TEMPLATE = """
+def {function_name}(
+{args}
+) -> {return_type_name}:
+    \"""{function_description}
+
+    Function ID: {function_id}
+    \"""
+    resp = execute("{function_type}", "{function_id}", {data})
+    try:
+        return {return_action}
+    except:
+        return resp.text  # type: ignore # fallback for debugging
+
+
+async def {function_name}_async(
+{args}
+) -> {return_type_name}:
+    \"""{function_description}
+
+    Function ID: {function_id}
+    \"""
+    resp = await execute_async("{function_type}", "{function_id}", {data})
+    try:
+        return {return_action}
+    except:
+        return resp.text  # type: ignore # fallback for debugging
+
+
+"""
+
+
+def render_ai_function(
+    function_type: str,
+    function_name: str,
+    function_id: str,
+    function_description: str,
+    arguments: List[PropertySpecification],
+    return_type: Dict[str, Any],
+) -> Tuple[str, str]:
+    arg_names = [a["name"] for a in arguments]
+    args, args_def = parse_arguments(function_name, arguments)
+    return_type_name, return_type_def = get_type_and_def(cast(PropertyType, return_type), "ReturnType")
+
+    if return_type_def and return_type_already_defined_in_args(return_type_name, args_def):
+        return_type_def = ""
+
+    data = "{" + ", ".join([f"'{arg}': {rewrite_arg_name(arg)}" for arg in arg_names]) + "}"
+    func_type_defs = AI_DEFS_TEMPLATE.format(
+        args_def=args_def,
+        return_type_def=return_type_def,
+    )
+    func_str = AI_FUNCTION_TEMPLATE.format(
+        return_type_name=_normalize_return_type_for_annotation(function_name, return_type_name),
+        function_type="ai",
+        function_name=function_name,
+        function_id=function_id,
+        function_description=function_description.replace('"', "'"),
+        args=args,
+        return_action=_get_ai_return_action(return_type_name),
+        data=data,
+    )
+    return func_str, func_type_defs
+
+
+def _normalize_return_type_for_annotation(function_name: str, return_type_name: str) -> str:
+    if return_type_name == "ReturnType":
+        return "ReturnType"
+    return add_type_import_path(function_name, return_type_name)
+
+
+def _get_ai_return_action(return_type_name: str) -> str:
+    normalized_type = return_type_name.replace(" ", "")
+
+    if normalized_type in {"str", "Optional[str]"}:
+        return_action = "resp.text"
+    elif "|" in normalized_type:
+        union_parts = {part for part in normalized_type.split("|") if part}
+        if union_parts == {"str", "None"}:
+            return_action = "resp.text"
+        else:
+            return_action = "resp.json()"
+    else:
+        return_action = "resp.json()"
+    return return_action

polyapi/generate.py

@@ -17,6 +17,7 @@ from .webhook import render_webhook_handle
 from .typedefs import PropertySpecification, SchemaSpecDto, SpecificationDto, VariableSpecDto, TableSpecDto
 from .api import render_api_function
 from .server import render_server_function
+from .ai_function import render_ai_function
 from .utils import add_import_to_init, get_auth_headers, init_the_init, print_green, to_func_namespace, to_type_module_alias
 from .variables import generate_variables
 from .poly_tables import generate_tables
@@ -29,6 +30,7 @@ SUPPORTED_FUNCTION_TYPES = {
     "customFunction",  # client function - this is badly named in /specs atm
     "serverFunction",
     "webhookHandle",
+    "aiFunction",
 }
 
 SUPPORTED_TYPES = SUPPORTED_FUNCTION_TYPES | {"serverVariable", "schema", "snippet", "table"}
@@ -51,7 +53,7 @@ def get_specs(contexts: Optional[List[str]] = None, names: Optional[List[str]] =
     params: Any = {"noTypes": str(no_types).lower()}
 
     if contexts:
-        params["contexts"] = contexts
+        params["contexts"] = ",".join(contexts)
     
     if names:
         params["names"] = names
@@ -98,7 +100,7 @@ def resolve_poly_refs(obj, schema_index):
 def replace_poly_refs_in_functions(specs: List[SpecificationDto], schema_index):
     spec_idxs_to_remove = []
     for idx, spec in enumerate(specs):
-        if spec.get("type") in ("apiFunction", "customFunction", "serverFunction"):
+        if spec.get("type") in ("apiFunction", "customFunction", "serverFunction", "aiFunction"):
             func = spec.get("function")
             if func:
                 try:
@@ -501,6 +503,15 @@ def render_spec(spec: SpecificationDto) -> Tuple[str, str]:
             arguments,
             return_type,
         )
+    elif function_type == "aiFunction":
+        func_str, func_type_defs = render_ai_function(
+            function_type,
+            function_name,
+            function_id,
+            function_description,
+            arguments,
+            return_type,
+        )
 
     if X_POLY_REF_WARNING in func_type_defs:
         # this indicates that jsonschema_gentypes has detected an x-poly-ref

polyapi/http_client.py

@@ -1,83 +1,414 @@
 import asyncio
+import logging
+import os
+import threading
 import httpx
 
+logger = logging.getLogger("poly")
+
+# Connx pool + timeout defaults for the shared clients.
+# All overridable via POLY_HTTP_* env vars so operators can tune limits or
+# opt into timeouts without editing callers. Empty / "none" parses to None (unbounded).
+
+
+def _env_opt_int(name: str, default: "int | None") -> "int | None":
+    raw = os.environ.get(name)
+    if raw is None:
+        return default
+    raw = raw.strip()
+    return None if raw == "" or raw.lower() in ("none", "null") else int(raw)
+
+
+def _env_opt_float(name: str, default: "float | None") -> "float | None":
+    raw = os.environ.get(name)
+    if raw is None:
+        return default
+    raw = raw.strip()
+    return None if raw == "" or raw.lower() in ("none", "null") else float(raw)
+
+
+def _build_limits() -> httpx.Limits:
+    return httpx.Limits(
+        max_connections=_env_opt_int("POLY_HTTP_MAX_CONNECTIONS", 200),
+        max_keepalive_connections=_env_opt_int("POLY_HTTP_MAX_KEEPALIVE_CONNECTIONS", None),
+        keepalive_expiry=_env_opt_float("POLY_HTTP_KEEPALIVE_EXPIRY", 30.0),
+    )
+
+
+def _build_timeout() -> httpx.Timeout:
+    # Default to the SDK's original unbounded timeout; bound per-phase only via env.
+    return httpx.Timeout(
+        connect=_env_opt_float("POLY_HTTP_CONNECT_TIMEOUT", None),
+        read=_env_opt_float("POLY_HTTP_READ_TIMEOUT", None),
+        write=_env_opt_float("POLY_HTTP_WRITE_TIMEOUT", None),
+        pool=_env_opt_float("POLY_HTTP_POOL_TIMEOUT", None),
+    )
+
+
+def _close_deadline() -> "float | None":
+    # Bound pool teardown so one wedged socket cannot hang invocation exit.
+    # None (POLY_HTTP_CLOSE_TIMEOUT=none) restores the old unbounded wait.
+    return _env_opt_float("POLY_HTTP_CLOSE_TIMEOUT", 5.0)
+
+
+# Import-time snapshot for reference/config surface. Clients re-read env at creation
+DEFAULT_LIMITS = _build_limits()
+DEFAULT_TIMEOUT = _build_timeout()
+# PID that owns the clients below; a fork resets it
+_owner_pid: int = os.getpid()
 _sync_client: httpx.Client | None = None
-_async_client: httpx.AsyncClient | None = None
-_async_client_loop: asyncio.AbstractEventLoop | None = None
+# Coordinate lazy creation, active requests, and shutdown of _sync_client.
+_sync_client_lock = threading.Lock()
+_sync_client_condition = threading.Condition(_sync_client_lock)
+_sync_inflight = 0
+_sync_closing = False
+# One async client per event loop.
+_async_clients: "dict[asyncio.AbstractEventLoop, httpx.AsyncClient]" = {}
+# In-flight request count per async client, so close_async can drain before aclose.
+_async_inflight: "dict[httpx.AsyncClient, int]" = {}
+# Event loops whose close() already wrapped
+_hooked_loops: "set[asyncio.AbstractEventLoop]" = set()
+# Shared close operation per event loop. New requests wait for it so they do not
+# race a replacement client into the pool mid-close.
+_closing_loops: "dict[asyncio.AbstractEventLoop, asyncio.Task[None]]" = {}
 
 
-def _get_sync_client() -> httpx.Client:
+def _after_fork_in_child() -> None:
+    """Reset all shared client state in a forked child
+    """
+    global _owner_pid, _sync_client, _sync_client_lock, _sync_client_condition
+    global _sync_inflight, _sync_closing
+    _sync_client_lock = threading.Lock()
+    _sync_client_condition = threading.Condition(_sync_client_lock)
+    _sync_client = None
+    _sync_inflight = 0
+    _sync_closing = False
+    _async_clients.clear()
+    _async_inflight.clear()
+    _hooked_loops.clear()
+    _closing_loops.clear()
+    _owner_pid = os.getpid()
+
+
+if hasattr(os, "register_at_fork"):
+    os.register_at_fork(after_in_child=_after_fork_in_child)
+
+
+def _reset_if_forked() -> None:
+    """Drop clients inherited across os.fork() so childisolated
+    Clear not close the inherited refs - child makes its own."""
+    global _owner_pid, _sync_client, _sync_client_lock, _sync_client_condition
+    global _sync_inflight, _sync_closing
+    current_pid = os.getpid()
+    if current_pid != _owner_pid:
+        _sync_client_lock = threading.Lock()
+        _sync_client_condition = threading.Condition(_sync_client_lock)
+        _sync_client = None
+        _sync_inflight = 0
+        _sync_closing = False
+        _async_clients.clear()
+        _async_inflight.clear()
+        _hooked_loops.clear()
+        _closing_loops.clear()
+        _owner_pid = current_pid
+
+
+def _get_or_create_sync_client() -> httpx.Client:
     global _sync_client
     if _sync_client is None:
-        _sync_client = httpx.Client(timeout=None)
+        _sync_client = httpx.Client(limits=_build_limits(), timeout=_build_timeout())
     return _sync_client
 
 
+def _get_sync_client() -> httpx.Client:
+    _reset_if_forked()
+    with _sync_client_condition:
+        while _sync_closing:
+            _sync_client_condition.wait()
+        return _get_or_create_sync_client()
+
+
+def _dispatch_sync(method_name: str, *args, **kwargs) -> httpx.Response:
+    global _sync_inflight
+    _reset_if_forked()
+    with _sync_client_condition:
+        while _sync_closing:
+            _sync_client_condition.wait()
+        client = _get_or_create_sync_client()
+        _sync_inflight += 1
+    try:
+        return getattr(client, method_name)(*args, **kwargs)
+    finally:
+        with _sync_client_condition:
+            _sync_inflight -= 1
+            if _sync_inflight == 0:
+                _sync_client_condition.notify_all()
+
+
+def _retire_async_client(
+    client: httpx.AsyncClient | None,
+    loop: asyncio.AbstractEventLoop | None,
+) -> None:
+    """Best-effort close of an async client whose event loop is being dumped.
+    """
+    if client is None:
+        return
+    try:
+        if loop is not None and loop.is_running():
+            loop.call_soon_threadsafe(lambda: loop.create_task(client.aclose()))
+            logger.debug(f"Scheduled aclose of async client id={id(client)} pid={os.getpid()} loop={id(loop)}")
+        else:
+            loop_closed = None if loop is None else loop.is_closed()
+            logger.debug(f"Dropping async client id={id(client)} pid={os.getpid()} loop={id(loop)} loop_closed={loop_closed}")
+    except Exception:
+        logger.warning(f"Failed to retire async client id={id(client)} pid={os.getpid()} loop={id(loop)}", exc_info=True)
+
+
+def _sweep_dead_loops() -> None:
+    """Wipe clients whose event loop has been closed.
+    """
+    for loop in list(_async_clients):
+        if loop.is_closed():
+            _retire_async_client(_async_clients.pop(loop, None), loop)
+
+
+def _abandon_close_task(
+    close_task: "asyncio.Future[None]",
+    client: httpx.AsyncClient,
+    loop: asyncio.AbstractEventLoop,
+    deadline: "float | None",
+    context: str = "",
+) -> None:
+    """Detach a pool close that blew its deadline.
+
+    The task is cancelled and dropped rather than awaited: waiting for an
+    unresponsive pool to unwind is the stall the deadline exists to prevent.
+    Cancelling is what keeps loop shutdown bounded too, since asyncio.run()
+    tears down by cancelling every task and gathering them; a cancelled close
+    completes there instead of blocking. Whatever stays open is released when
+    the coroutine is collected, and by the OS at exit.
+    """
+    def _swallow(finished: "asyncio.Future[None]") -> None:
+        # Retrieve the result so a late failure is not reported as an
+        # unretrieved task exception.
+        if finished.cancelled():
+            return
+        error = finished.exception()
+        if error is not None:
+            logger.debug(
+                f"Abandoned aclose later failed with {error!r} id={id(client)} "
+                f"pid={os.getpid()} loop={id(loop)}")
+
+    close_task.add_done_callback(_swallow)
+    close_task.cancel()
+    logger.warning(
+        f"aclose exceeded {deadline}s deadline; abandoning pool "
+        f"id={id(client)} pid={os.getpid()} loop={id(loop)}{context}")
+
+
+def _register_loop_close_hook(loop: asyncio.AbstractEventLoop) -> None:
+    """aclose the loop's async client right before the loop is torn down.
+    """
+    if loop in _hooked_loops:
+        return
+    original_close = loop.close
+
+    def _close_with_cleanup(*args, **kwargs):
+        _hooked_loops.discard(loop)
+        cached = _async_clients.pop(loop, None)
+        if cached is not None and not loop.is_closed():
+            deadline = _close_deadline()
+            try:
+                # asyncio.wait returns at the deadline without cancelling, so
+                # loop.close() proceeds even if the pool ignores cancellation.
+                close_task = loop.create_task(cached.aclose())
+                loop.run_until_complete(
+                    asyncio.wait({close_task}, timeout=deadline))
+                if close_task.done():
+                    # Surface real aclose failures, including a TimeoutError
+                    # raised by aclose itself, rather than treating them as
+                    # our deadline.
+                    close_task.result()
+                else:
+                    _abandon_close_task(
+                        close_task, cached, loop, deadline, " on teardown")
+            except Exception:
+                logger.warning(
+                    f"Failed to aclose async client id={id(cached)} pid={os.getpid()} "
+                    f"loop={id(loop)} on teardown", exc_info=True)
+        return original_close(*args, **kwargs)
+
+    try:
+        loop.close = _close_with_cleanup  # type: ignore[method-assign]
+        _hooked_loops.add(loop)
+    except (AttributeError, TypeError):
+        logger.warning(
+            f"Could not hook loop.close pid={os.getpid()} loop={id(loop)}; "
+            "await close_async() before closing this event loop"
+        )
+
+
 def _get_async_client() -> httpx.AsyncClient:
-    global _async_client, _async_client_loop
+    _reset_if_forked()
     current_loop = asyncio.get_running_loop()
-    if _async_client is None or _async_client_loop is not current_loop:
-        _async_client = httpx.AsyncClient(timeout=None)
-        _async_client_loop = current_loop
-    return _async_client
+    client = _async_clients.get(current_loop)
+    if client is None:
+        _sweep_dead_loops()
+        limits = _build_limits()
+        client = httpx.AsyncClient(limits=limits, timeout=_build_timeout())
+        _async_clients[current_loop] = client
+        _register_loop_close_hook(current_loop)
+        logger.debug(
+            f"Created async client id={id(client)} pid={os.getpid()} loop={id(current_loop)} "
+            f"max_connections={limits.max_connections} "
+            f"max_keepalive={limits.max_keepalive_connections} "
+            f"keepalive_expiry={limits.keepalive_expiry}"
+        )
+    return client
+
+
+async def _dispatch_async(method_name: str, *args, **kwargs) -> httpx.Response:
+    # If a shutdown is closing this loop's client, wait so a replacement is not
+    # published mid-close. The shutdown caller owns any close error.
+    closing = _closing_loops.get(asyncio.get_running_loop())
+    if closing is not None:
+        try:
+            await asyncio.shield(closing)
+        except Exception:
+            pass
+    # Track in-flight requests per client so close_async can drain before aclose.
+    client = _get_async_client()
+    _async_inflight[client] = _async_inflight.get(client, 0) + 1
+    try:
+        return await getattr(client, method_name)(*args, **kwargs)
+    finally:
+        remaining = _async_inflight.get(client, 1) - 1
+        if remaining <= 0:
+            _async_inflight.pop(client, None)
+        else:
+            _async_inflight[client] = remaining
+
+
+async def _drain_inflight(client: httpx.AsyncClient) -> None:
+    # Preserve the SDK's unbounded request behavior during shutdown. The shared
+    # close operation retains ownership until every active request finishes.
+    while _async_inflight.get(client, 0) > 0:
+        await asyncio.sleep(0.05)
+
+
+async def _wait_for_close_task(close_task: "asyncio.Task[None]") -> None:
+    """Wait for shared cleanup before propagating caller cancellation."""
+    caller_cancelled = False
+    while not close_task.done():
+        try:
+            await asyncio.shield(close_task)
+        except asyncio.CancelledError:
+            caller_cancelled = True
+    close_task.result()
+    if caller_cancelled:
+        raise asyncio.CancelledError()
+
+
+async def _close_clients_for_loop(
+    current_loop: asyncio.AbstractEventLoop,
+) -> None:
+    """Close shared clients while retaining ownership through completion."""
+    try:
+        await asyncio.to_thread(close)
+        client = _async_clients.get(current_loop)
+        if client is None:
+            return
+
+        await _drain_inflight(client)
+        deadline = _close_deadline()
+        close_task = asyncio.ensure_future(client.aclose())
+        try:
+            # asyncio.wait returns at the deadline without cancelling the
+            # close, so the bound holds even when the pool never processes
+            # cancellation. wait_for would block on that unwind instead.
+            await asyncio.wait({close_task}, timeout=deadline)
+            if close_task.done():
+                # Real aclose errors, including a TimeoutError raised by aclose
+                # itself, still propagate to the close_async caller.
+                close_task.result()
+            else:
+                _abandon_close_task(close_task, client, current_loop, deadline)
+        finally:
+            if _async_clients.get(current_loop) is client:
+                _async_clients.pop(current_loop, None)
+            _async_inflight.pop(client, None)
+    finally:
+        if _closing_loops.get(current_loop) is asyncio.current_task():
+            _closing_loops.pop(current_loop, None)
+        _sweep_dead_loops()
 
 
 def post(url, **kwargs) -> httpx.Response:
-    return _get_sync_client().post(url, **kwargs)
+    return _dispatch_sync("post", url, **kwargs)
 
 
 async def async_post(url, **kwargs) -> httpx.Response:
-    return await _get_async_client().post(url, **kwargs)
+    return await _dispatch_async("post", url, **kwargs)
 
 
 def get(url, **kwargs) -> httpx.Response:
-    return _get_sync_client().get(url, **kwargs)
+    return _dispatch_sync("get", url, **kwargs)
 
 
 async def async_get(url, **kwargs) -> httpx.Response:
-    return await _get_async_client().get(url, **kwargs)
+    return await _dispatch_async("get", url, **kwargs)
 
 
 def patch(url, **kwargs) -> httpx.Response:
-    return _get_sync_client().patch(url, **kwargs)
+    return _dispatch_sync("patch", url, **kwargs)
 
 
 async def async_patch(url, **kwargs) -> httpx.Response:
-    return await _get_async_client().patch(url, **kwargs)
+    return await _dispatch_async("patch", url, **kwargs)
 
 
 def delete(url, **kwargs) -> httpx.Response:
-    return _get_sync_client().delete(url, **kwargs)
+    return _dispatch_sync("delete", url, **kwargs)
 
 
 async def async_delete(url, **kwargs) -> httpx.Response:
-    return await _get_async_client().delete(url, **kwargs)
+    return await _dispatch_async("delete", url, **kwargs)
 
 
 def request(method, url, **kwargs) -> httpx.Response:
-    return _get_sync_client().request(method, url, **kwargs)
+    return _dispatch_sync("request", method, url, **kwargs)
 
 
 async def async_request(method, url, **kwargs) -> httpx.Response:
-    return await _get_async_client().request(method, url, **kwargs)
+    return await _dispatch_async("request", method, url, **kwargs)
 
 
 def close():
-    global _sync_client
-    if _sync_client is not None:
-        _sync_client.close()
-        _sync_client = None
+    global _sync_client, _sync_closing
+    _reset_if_forked()
+    with _sync_client_condition:
+        while _sync_closing:
+            _sync_client_condition.wait()
+        if _sync_client is None:
+            return
+        _sync_closing = True
+        while _sync_inflight > 0:
+            _sync_client_condition.wait()
+        client = _sync_client
+    try:
+        client.close()
+    finally:
+        with _sync_client_condition:
+            if _sync_client is client:
+                _sync_client = None
+            _sync_closing = False
+            _sync_client_condition.notify_all()
 
-async def close_async():
-    global _async_client, _async_client_loop
-    close()
-    client = _async_client
-    client_loop = _async_client_loop
-    _async_client = None
-    _async_client_loop = None
-    if client is None:
-        return
 
+async def close_async():
     current_loop = asyncio.get_running_loop()
-    if client_loop is current_loop:
-        await client.aclose()
+    close_task = _closing_loops.get(current_loop)
+    if close_task is None:
+        close_task = asyncio.create_task(_close_clients_for_loop(current_loop))
+        _closing_loops[current_loop] = close_task
+    await _wait_for_close_task(close_task)

polyapi/typedefs.py

@@ -35,7 +35,7 @@ class SpecificationDto(TypedDict):
     description: str
     # function is none (or function key not present) if this is actually VariableSpecDto
     function: NotRequired[FunctionSpecification | None]
-    type: Literal['apiFunction', 'customFunction', 'serverFunction', 'authFunction', 'webhookHandle', 'serverVariable', 'table']
+    type: Literal['apiFunction', 'customFunction', 'serverFunction', 'authFunction', 'webhookHandle', 'serverVariable', 'table', 'aiFunction']
     code: NotRequired[str]
     language: str
 

polyapi/utils.py

@@ -1,7 +1,7 @@
 import keyword
 import re
 import os
-from urllib.parse import urlparse
+from urllib.parse import unquote, urlparse
 from typing import Tuple, List, Optional, cast
 from colorama import Fore, Style
 from polyapi.constants import BASIC_PYTHON_TYPES
@@ -299,11 +299,29 @@ def _maybe_add_fallback_schema_name(a: PropertySpecification):
     # Handle cases where type might be missing
     if not a.get("type"):
         return
-    
+
     if a["type"].get("kind") == "object" and a["type"].get("schema"):
         schema = a["type"].get("schema", {})
-        if not schema.get("title") and not schema.get("name") and a.get("name"):
-            schema["title"] = a["name"].title()
+        title = schema.get("title") or schema.get("name")
+        if not title and a.get("name"):
+            title = a["name"].title()
+            schema["title"] = title
+
+        reference = schema.get("$ref")
+        definitions = schema.get("definitions")
+        reference_prefix = "#/definitions/"
+        if not isinstance(title, str):
+            return
+        if not isinstance(reference, str) or not reference.startswith(reference_prefix):
+            return
+        if not isinstance(definitions, dict):
+            return
+
+        definition_name = unquote(reference[len(reference_prefix):])
+        definition_name = definition_name.replace("~1", "/").replace("~0", "~")
+        definition = definitions.get(definition_name)
+        if isinstance(definition, dict):
+            definition.setdefault("title", title)
 
 
 def _clean_description(text: str) -> str:

{polyapi_python-0.3.19.dev4.dist-info → polyapi_python-0.3.20.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: polyapi-python
-Version: 0.3.19.dev4
+Version: 0.3.20
 Summary: The Python SDK for the integration platform PolyAPI
 Author-email: PolyAPI <support@polyapi.io>
 License: MIT License
@@ -84,6 +84,39 @@ POLY_API_KEY='your_key'
 POLY_API_BASE_URL='your_server'  # e.g. na1.polyapi.io
 ```
 
+### HTTP Client Configuration
+
+The SDK reuses one synchronous HTTP client per process and one asynchronous
+client per event loop. New clients read these optional environment variables:
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `POLY_HTTP_MAX_CONNECTIONS` | `200` | Maximum connections per client |
+| `POLY_HTTP_MAX_KEEPALIVE_CONNECTIONS` | `none` | Maximum idle keep-alive connections per client |
+| `POLY_HTTP_KEEPALIVE_EXPIRY` | `30` | Idle keep-alive expiry in seconds |
+| `POLY_HTTP_CONNECT_TIMEOUT` | `none` | Connection timeout in seconds |
+| `POLY_HTTP_READ_TIMEOUT` | `none` | Read timeout in seconds |
+| `POLY_HTTP_WRITE_TIMEOUT` | `none` | Write timeout in seconds |
+| `POLY_HTTP_POOL_TIMEOUT` | `none` | Connection-pool timeout in seconds |
+| `POLY_HTTP_CLOSE_TIMEOUT` | `5` | Deadline in seconds for closing a client's pool |
+
+An empty value, `none`, or `null` means unbounded. Limits are per client, so
+processes with multiple event loops can create one configured pool per loop.
+
+`POLY_HTTP_CLOSE_TIMEOUT` is read at shutdown rather than at client creation.
+It bounds pool teardown so a single unresponsive socket cannot stall shutdown:
+if the deadline passes, the SDK logs a warning, abandons the remaining
+connections to the operating system, and retires the client so it is never
+reused. Set it to `none` to wait indefinitely.
+
+Call `polyapi.http_client.close()` during synchronous shutdown or await
+`polyapi.http_client.close_async()` on each owning event loop during
+asynchronous shutdown. The shutdown functions wait for active SDK requests
+before closing their client. Clients on standard asyncio loops are closed
+automatically when the loop closes. If a custom event-loop implementation
+reports that its close hook could not be installed, explicitly await
+`close_async()` before closing that loop.
+
 ### 3. Test
 
 That's it! Now open up a test file and you can run some code like so:

{polyapi_python-0.3.19.dev4.dist-info → polyapi_python-0.3.20.dist-info}/RECORD

@@ -1,5 +1,6 @@
-polyapi/__init__.py,sha256=vV1N9xtIMtpi4o-2jAI3775LkzRbC9JUo87MAnW9zgo,5201
+polyapi/__init__.py,sha256=oEijoOVghgeEbwqtWK_74QU38HBDt4THXHBbsortJ1w,5505
 polyapi/__main__.py,sha256=V4zhAh_YGxno5f_KSrlkELxcuDh9bR3WSd0n-2r-qQQ,93
+polyapi/ai_function.py,sha256=GvJKpBZFbI11y9JAKTHXMkztbMHZxNTfL37LLbGKmwI,3017
 polyapi/api.py,sha256=CzqX99GekhQJVqAAWlL03hUenIi_5iTln9cWgQzz6Ko,2784
 polyapi/auth.py,sha256=l0pGAoYvEWqa2TMsrM9GS8imXu3GsWvpn4eFPy1vksI,6195
 polyapi/cli.py,sha256=V3586ElV1927u2AhQZAo_4UYKoJPqE8lz6b3_gJfMj0,11918
@@ -12,8 +13,8 @@ polyapi/error_handler.py,sha256=I_e0iz6VM23FLVQWJljxs2NGcl_OODbi43OcbnqBlp8,2398
 polyapi/exceptions.py,sha256=Zh7i7eCUhDuXEdUYjatkLFTeZkrx1BJ1P5ePgbJ9eIY,89
 polyapi/execute.py,sha256=4jLkQely6cM7pNN9pYpGZTbEis-DfwENi5Fl07xSiig,8966
 polyapi/function_cli.py,sha256=gJE72lRvuWnGl6CG9GpqL78TOnUzxVe4kJMvg0PQixw,4493
-polyapi/generate.py,sha256=9B6DbrkBAPWpMVD92ifFYV2JaKNCduMQhqJ4Gm48qq0,22051
-polyapi/http_client.py,sha256=TcoFsIvRcNB9wWJT4YePPWFFY6lX90cdqi7C4jKbqqk,2259
+polyapi/generate.py,sha256=U8JQ_XR2gJI_eYNnmvXReILUxapj95QKoBronqMFkyE,22403
+polyapi/http_client.py,sha256=5N-zWSsjdMCPnrICR45EJWtXtBNyMP42L6Q8_Bh7n1A,15198
 polyapi/parser.py,sha256=t3jJI6g5F7Qg_tirPOzSkQ02VLkSVhnqs9YGapyHx2k,21901
 polyapi/poly_schemas.py,sha256=JGMQbELPFw4V_0nA0o71WJKFTdxjCGoKqJvIid_Y-a4,10759
 polyapi/poly_tables.py,sha256=SlP7ZwqS3nIji2uGR2VJQH6IdddZ832rRItcmoYdIBc,20293
@@ -23,12 +24,12 @@ polyapi/rendered_spec.py,sha256=J2Num7MXnW_mKAe2MSVIL1coWopNYZ-6nNNwQRfseV0,2262
 polyapi/schema.py,sha256=SPO5GDvIE1BjRfJR89vJMEGCXERfEbhNXQm2A05UAOc,6959
 polyapi/server.py,sha256=_14lP4_BmRYMBXwaqXVWmiSTHH3h7ecCHxSalM9UiSc,3049
 polyapi/sync.py,sha256=t0Khh8B5GylxB7KWRP_xvkrvkuyVarSLCOvtmaz7lcc,6766
-polyapi/typedefs.py,sha256=mfll-KrngOW0wzbvDNiIDaDkFMwbsT-MY5y5hzWj9RE,5642
-polyapi/utils.py,sha256=dIkuIlGNsg1USiXNNkUnOtLVzie4mxBCBlTc0YsaXao,15594
+polyapi/typedefs.py,sha256=UeAdyYrgqxrvBRkjisK_xgzQmuTePPvOM74HKf1y0II,5656
+polyapi/utils.py,sha256=LUqTkbb0b7y3gjsOU-WO1LVYaTMyExTGpYjKY8wVKg8,16300
 polyapi/variables.py,sha256=hfSDPGQK6YphNCa9MqE0W88WIFfqCQWgpBDWkExMq-A,7582
 polyapi/webhook.py,sha256=0ceLwHNjNd2Yx_8MX5jOIxiQ5Lwhy2pe81ProAuKon0,5108
-polyapi_python-0.3.19.dev4.dist-info/licenses/LICENSE,sha256=6b_I7aPVp8JXhqQwdw7_B84Ca0S4JGjHj0sr_1VOdB4,1068
-polyapi_python-0.3.19.dev4.dist-info/METADATA,sha256=E2Ot99-wAaduZDv9OUFxzH7cFH3m020ZGT3OcNXj9iM,5898
-polyapi_python-0.3.19.dev4.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-polyapi_python-0.3.19.dev4.dist-info/top_level.txt,sha256=CEFllOnzowci_50RYJac-M54KD2IdAptFsayVVF_f04,8
-polyapi_python-0.3.19.dev4.dist-info/RECORD,,
+polyapi_python-0.3.20.dist-info/licenses/LICENSE,sha256=6b_I7aPVp8JXhqQwdw7_B84Ca0S4JGjHj0sr_1VOdB4,1068
+polyapi_python-0.3.20.dist-info/METADATA,sha256=dk9Wpal3miMVocn7pAkop1yBllU4pA1m3u9k3GtWCz0,7732
+polyapi_python-0.3.20.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+polyapi_python-0.3.20.dist-info/top_level.txt,sha256=CEFllOnzowci_50RYJac-M54KD2IdAptFsayVVF_f04,8
+polyapi_python-0.3.20.dist-info/RECORD,,

{polyapi_python-0.3.19.dev4.dist-info → polyapi_python-0.3.20.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (82.0.1)
+Generator: setuptools (84.0.0)
 Root-Is-Purelib: true
 Tag: py3-none-any