phronesis-framework 0.1.0__py3-none-any.whl

phronesis/__init__.py

@@ -0,0 +1,38 @@
+"""Phronesis: opinionated framework for building AI agents."""
+
+from __future__ import annotations
+
+import logging as _logging
+
+from ._internal.logging import (
+    configure_logging,
+    get_logger,
+    get_logger_with_context,
+)
+from ._internal.logging.constants import PHRONESIS_LOGGER_PREFIX as _ROOT
+from .context.context import Context
+from .tools.decorator import tool
+from .tools.discover import discover
+from .tools.effects import ToolEffect
+from .tools.errors import ToolError
+from .tools.registry import tool_scope
+
+__version__ = "0.1.0"
+
+# Defensive: prevent stdlib "no handlers" warnings when the consumer has not
+# configured logging. Users opt in by calling `configure_logging()` or by
+# attaching their own handler to the `phronesis` logger.
+_logging.getLogger(_ROOT).addHandler(_logging.NullHandler())
+
+__all__ = [
+    "Context",
+    "ToolEffect",
+    "ToolError",
+    "__version__",
+    "configure_logging",
+    "discover",
+    "get_logger",
+    "get_logger_with_context",
+    "tool",
+    "tool_scope",
+]

phronesis/_internal/__init__.py

@@ -0,0 +1 @@
+"""Internal utilities. Not part of the public Phronesis API."""

phronesis/_internal/concurrency/__init__.py

@@ -0,0 +1,18 @@
+"""Concurrency utilities: thread offloading and concurrent task execution."""
+
+from __future__ import annotations
+
+from .exceptions import ConcurrencyError, PartialFailureError
+from .executor import run_sync
+from .gather import gather_all
+from .policies import BestEffortPolicy, FailFastPolicy, GatherPolicy
+
+__all__ = [
+    "BestEffortPolicy",
+    "ConcurrencyError",
+    "FailFastPolicy",
+    "GatherPolicy",
+    "PartialFailureError",
+    "gather_all",
+    "run_sync",
+]

phronesis/_internal/concurrency/exceptions.py

@@ -0,0 +1,39 @@
+"""Concurrency-specific exceptions."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class ConcurrencyError(Exception):
+    """Base class for concurrency-related errors raised by the framework."""
+
+
+class PartialFailureError(ConcurrencyError):
+    """Some tasks in a best-effort gather failed.
+
+    Successful values and exceptions are kept in the original task order:
+    if task ``i`` succeeded, ``results[i]`` is its value and
+    ``exceptions[i]`` is ``None``; if it failed, ``results[i]`` is ``None``
+    and ``exceptions[i]`` is the captured exception.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        results: list[Any],
+        exceptions: list[BaseException | None],
+    ) -> None:
+        super().__init__(message)
+
+        self.results = results
+        self.exceptions = exceptions
+
+    @property
+    def failed_count(self) -> int:
+        return sum(1 for exc in self.exceptions if exc is not None)
+
+    @property
+    def successful_count(self) -> int:
+        return len(self.exceptions) - self.failed_count

phronesis/_internal/concurrency/executor.py

@@ -0,0 +1,71 @@
+"""Run synchronous callables from async code via a worker thread."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Callable
+from typing import ParamSpec, TypeVar
+
+from ..logging import get_logger
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+_LOGGER_NAME = "phronesis.concurrency"
+
+
+async def run_sync(
+    fn: Callable[P, T],
+    *args: P.args,
+    **kwargs: P.kwargs,
+) -> T:
+    """Run a synchronous callable in a worker thread.
+
+    Wraps :func:`asyncio.to_thread` with structured logging. The
+    callable runs in the default executor.
+
+    Args:
+        fn: The synchronous callable to invoke off the event loop.
+        *args: Positional arguments forwarded to ``fn``.
+        **kwargs: Keyword arguments forwarded to ``fn``.
+
+    Returns:
+        Whatever ``fn`` returns.
+
+    Raises:
+        Exception: Any exception raised by ``fn`` propagates
+            unchanged after a warning log entry.
+    """
+    log = get_logger(_LOGGER_NAME)
+    label = getattr(fn, "__qualname__", repr(fn))
+
+    log.debug("run_sync start", extra={"callable": label})
+
+    started = time.perf_counter()
+
+    try:
+        result = await asyncio.to_thread(fn, *args, **kwargs)
+
+    except Exception as exc:
+        duration_ms = (time.perf_counter() - started) * 1000
+
+        log.warning(
+            "run_sync failed",
+            extra={
+                "callable": label,
+                "duration_ms": duration_ms,
+                "error": str(exc),
+            },
+        )
+
+        raise
+
+    duration_ms = (time.perf_counter() - started) * 1000
+
+    log.debug(
+        "run_sync done",
+        extra={"callable": label, "duration_ms": duration_ms},
+    )
+
+    return result

phronesis/_internal/concurrency/gather.py

@@ -0,0 +1,65 @@
+"""Concurrent execution of awaitables with configurable error policies."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Awaitable
+from typing import TypeVar, cast
+
+from ..logging import get_logger
+from .policies import FailFastPolicy, GatherPolicy
+
+T = TypeVar("T")
+
+_LOGGER_NAME = "phronesis.concurrency"
+
+
+async def gather_all(
+    *awaitables: Awaitable[T],
+    policy: GatherPolicy | None = None,
+) -> list[T]:
+    """Run ``awaitables`` concurrently and reconcile via ``policy``.
+
+    Args:
+        *awaitables: Awaitables scheduled on the running event loop.
+        policy: Error-handling strategy. Defaults to
+            :class:`FailFastPolicy`. Use :class:`BestEffortPolicy` to
+            wait for every task and surface partial failures.
+
+    Returns:
+        Results in input order. For :class:`BestEffortPolicy`, failed
+        slots are replaced with ``None`` before the policy raises.
+
+    Raises:
+        Exception: The first exception raised by any awaitable under
+            :class:`FailFastPolicy`.
+        PartialFailureError: When :class:`BestEffortPolicy` finds at
+            least one failed awaitable.
+    """
+    effective_policy = policy or FailFastPolicy()
+    log = get_logger(_LOGGER_NAME)
+
+    log.debug(
+        "gather_all start",
+        extra={
+            "count": len(awaitables),
+            "policy": type(effective_policy).__name__,
+        },
+    )
+
+    started = time.perf_counter()
+
+    raw = await asyncio.gather(
+        *awaitables,
+        return_exceptions=effective_policy.return_exceptions,
+    )
+
+    duration_ms = (time.perf_counter() - started) * 1000
+
+    log.debug(
+        "gather_all done",
+        extra={"count": len(awaitables), "duration_ms": duration_ms},
+    )
+
+    return cast("list[T]", effective_policy.reconcile(raw))

phronesis/_internal/concurrency/policies.py

@@ -0,0 +1,70 @@
+"""Error-handling policies for concurrent task execution."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from typing import Any
+
+from .exceptions import PartialFailureError
+
+
+class GatherPolicy(ABC):
+    """Strategy for handling exceptions returned by :func:`asyncio.gather`."""
+
+    @property
+    @abstractmethod
+    def return_exceptions(self) -> bool:
+        """Value passed to ``asyncio.gather(return_exceptions=...)``."""
+
+    @abstractmethod
+    def reconcile(self, results: Sequence[Any]) -> list[Any]:
+        """Inspect raw gather output and either return successes or raise."""
+
+
+class FailFastPolicy(GatherPolicy):
+    """Cancel pending tasks and propagate the first exception immediately."""
+
+    @property
+    def return_exceptions(self) -> bool:
+        return False
+
+    def reconcile(self, results: Sequence[Any]) -> list[Any]:
+        # With return_exceptions=False, asyncio.gather already raised on
+        # the first failure, so any sequence we receive is all-successful.
+        return list(results)
+
+
+class BestEffortPolicy(GatherPolicy):
+    """Wait for every task; raise :class:`PartialFailureError` if any failed."""
+
+    @property
+    def return_exceptions(self) -> bool:
+        return True
+
+    def reconcile(self, results: Sequence[Any]) -> list[Any]:
+        successes: list[Any] = []
+        failures: list[BaseException | None] = []
+        any_failed = False
+
+        for item in results:
+            if isinstance(item, BaseException):
+                successes.append(None)
+                failures.append(item)
+                any_failed = True
+
+            else:
+                successes.append(item)
+                failures.append(None)
+
+        if any_failed:
+            failed = sum(1 for exc in failures if exc is not None)
+            total = len(results)
+
+            raise PartialFailureError(
+                f"{failed} of {total} tasks failed",
+                results=successes,
+                exceptions=failures,
+            )
+
+        return successes

phronesis/_internal/http/__init__.py

@@ -0,0 +1,35 @@
+"""Async HTTP client used by every provider via composition."""
+
+from __future__ import annotations
+
+from .client import HttpClient, HttpStreamResponse, configure_http_client
+from .exceptions import (
+    HttpClientError,
+    HttpConnectionError,
+    HttpError,
+    HttpResponseError,
+    HttpServerError,
+    HttpTimeoutError,
+    HttpTransportError,
+)
+from .headers import build_default_headers, redact_sensitive_headers
+from .models import HttpRequest, HttpResponse
+from .timeouts import HttpTimeouts
+
+__all__ = [
+    "HttpClient",
+    "HttpClientError",
+    "HttpConnectionError",
+    "HttpError",
+    "HttpRequest",
+    "HttpResponse",
+    "HttpResponseError",
+    "HttpServerError",
+    "HttpStreamResponse",
+    "HttpTimeoutError",
+    "HttpTimeouts",
+    "HttpTransportError",
+    "build_default_headers",
+    "configure_http_client",
+    "redact_sensitive_headers",
+]