flyteplugins-agents-hermes 2.5.17__py3-none-any.whl

flyteplugins/agents/hermes/__init__.py

@@ -0,0 +1,19 @@
+"""Hermes agent adapter for Flyte.
+
+Bring your own Hermes agent (the ``hermes-agent`` package's ``AIAgent``) and
+run it durably on Flyte. The adapter provides:
+
+- :func:`tool` — turn a Flyte ``@env.task`` into a Hermes tool that executes as
+  a durable child action (own container/GPU, retries, caching), registered in
+  the Hermes tool registry under the :data:`FLYTE_TOOLSET` toolset.
+- :func:`run_agent` — run the Hermes agent loop inside your task and return the
+  final answer.
+
+Each tool call runs as a durable Flyte child action, and the run timeline is
+rendered into the Flyte task report.
+"""
+
+from ._run import run_agent, run_agent_sync
+from ._tools import FLYTE_TOOLSET, tool
+
+__all__ = ["FLYTE_TOOLSET", "run_agent", "run_agent_sync", "tool"]

flyteplugins/agents/hermes/_memory.py

@@ -0,0 +1,53 @@
+"""Cross-run Hermes memory — a thin bridge over Flyte's keyed ``MemoryStore``.
+
+Hermes keeps conversation state in-memory. This module persists the conversation
+transcript to a durable, keyed :class:`~flyte.ai.agents.memory.MemoryStore` (an
+object-store slot addressed by ``memory_key``) so a later run with the same key
+continues the conversation — across workers and restarts.
+
+The transcript is a plain list of ``{"role": ..., "content": ...}`` turns, stored
+via ``read_json`` / ``write_json``.
+"""
+
+from __future__ import annotations
+
+import typing
+
+from flyte._logging import logger
+from flyteplugins.agents.core import resolve_memory as _resolve_memory
+
+# Path-addressed slot holding the conversation transcript inside the MemoryStore.
+_MEMORY_HISTORY_PATH = "hermes/history.json"
+
+
+async def resolve_memory(memory_key: str | None) -> typing.Any | None:
+    """Resolve a keyed MemoryStore for Hermes cross-run memory, or ``None``.
+
+    Best-effort: returns ``None`` when ``memory_key`` is falsy or no durable
+    store can be resolved, so memory never breaks a run.
+    """
+    if not memory_key:
+        return None
+    return await _resolve_memory(memory_key)
+
+
+async def load_transcript(store: typing.Any) -> list[dict[str, typing.Any]]:
+    """Load the prior conversation transcript (empty list if none)."""
+    if store is None:
+        return []
+    try:
+        return list(await store.read_json.aio(_MEMORY_HISTORY_PATH, []))
+    except Exception:  # pragma: no cover - memory is best-effort, never fatal
+        logger.warning("Could not load Hermes memory; continuing without prior history.")
+        return []
+
+
+async def save_transcript(store: typing.Any, transcript: typing.Sequence[dict[str, typing.Any]]) -> None:
+    """Persist the conversation transcript back to the keyed store."""
+    if store is None:
+        return
+    try:
+        await store.write_json.aio(_MEMORY_HISTORY_PATH, list(transcript))
+        await store.save.aio()
+    except Exception:  # pragma: no cover - memory is best-effort, never fatal
+        logger.warning("Could not persist Hermes memory; continuing.")

flyteplugins/agents/hermes/_run.py

@@ -0,0 +1,196 @@
+"""``run_agent`` — run a Hermes (``hermes-agent``) agent on Flyte.
+
+Hermes owns the agent loop: its ``AIAgent`` (the ``run_agent`` top-level module
+of the ``hermes-agent`` package) drives the model and dispatches tools from a
+process-global registry. ``run_agent`` runs that loop inside your ``@env.task``:
+it builds an ``AIAgent`` scoped to exactly the Flyte-task tools you pass (via a
+custom Hermes toolset), drives ``AIAgent.run_conversation`` (a blocking call,
+bridged off the event loop with ``asyncio.to_thread``), and returns the final
+answer. Each tool call runs as a durable Flyte child action (its own
+container/resources, with retries and caching).
+
+Observability: the run timeline is rendered into the Flyte task report.
+
+The adapter minimizes delta between native Hermes code and Flyte integration:
+bring your own pre-configured ``AIAgent`` (with ``enabled_toolsets`` including
+:data:`~flyteplugins.agents.hermes.FLYTE_TOOLSET`) or let ``run_agent`` build
+one from ``tools`` + ``model``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import os
+import re
+import typing
+
+from flyteplugins.agents.core import ReportTimeline, flush_report, sync_variant
+
+from ._memory import load_transcript, resolve_memory, save_transcript
+from ._tools import tool
+
+if typing.TYPE_CHECKING:
+    from run_agent import AIAgent as _AIAgent  # hermes-agent's top-level module
+else:
+    _AIAgent = None
+
+_OPENAI_BASE_URL = "https://api.openai.com/v1"
+
+
+def _coerce_tool(t: typing.Any) -> typing.Any:
+    """Route anything not already Hermes-registered through :func:`tool`."""
+    if getattr(t, "__hermes_registered__", False):
+        return t
+    return tool(t)
+
+
+def _scoped_toolset(agent_name: str, registered: typing.Sequence[typing.Any]) -> str:
+    """Create (or refresh) a Hermes toolset holding exactly this agent's tools.
+
+    :func:`tool` registers every tool under the shared ``FLYTE_TOOLSET``; scoping
+    each built agent to a named subset keeps two agents in one process from
+    seeing each other's tools.
+    """
+    from toolsets import create_custom_toolset  # hermes-agent
+
+    toolset = f"flyte-{re.sub(r'[^A-Za-z0-9_-]+', '-', agent_name).strip('-') or 'agent'}"
+    names = [getattr(t, "__name__", str(t)) for t in registered]
+    create_custom_toolset(toolset, f"Flyte tools for agent {agent_name!r}", tools=names)
+    return toolset
+
+
+async def run_agent(
+    input: str,
+    *,
+    tools: typing.Sequence[typing.Any] = (),
+    model: str | None = None,
+    instructions: str | None = None,
+    agent: typing.Any = None,
+    name: str = "hermes-agent",
+    durable: bool = True,
+    observability: bool = True,
+    memory_key: str | None = None,
+    **agent_kwargs: typing.Any,
+) -> str:
+    """Run a Hermes agent with the given tools and prompt; return the final text.
+
+    Await this from an async task as ``await run_agent(...)``; from a sync task
+    use :func:`run_agent_sync` instead.
+
+    Call this from inside an ``@env.task`` — that task is the durable parent.
+    Within it, each tool call runs as a durable Flyte child action. Give the
+    enclosing task ``retries=...`` for self-healing and ``report=True`` to see
+    the agent timeline.
+
+    Provide either a pre-built ``agent`` (an ``AIAgent`` with its own
+    ``enabled_toolsets``) or ``tools`` + ``model`` to have one built for you.
+
+    Args:
+        input: The user prompt.
+        tools: ``tool``-wrapped tools or bare ``@env.task`` templates.
+        agent: A pre-built Hermes ``AIAgent``. Mutually exclusive with ``tools``.
+        model: Model name for the built agent. Required when ``agent`` is not
+            given (there is no default model).
+        instructions: System prompt. On the builder path this becomes the
+            agent's ``ephemeral_system_prompt``; with a pre-built agent it is
+            passed as this run's ``system_message``.
+        name: Agent name (used for the scoped toolset and observability).
+        durable: Accepted for the shared adapter contract, but currently a
+            no-op for Hermes: ``hermes-agent`` exposes no per-model-turn hook
+            (the model client is buried inside ``AIAgent``), so completed model
+            turns cannot be recorded/replayed via ``flyte.trace`` the way the
+            openai/langchain adapters do. Tool calls are durable regardless —
+            each runs as a Flyte child action with retries and caching — so a
+            retried task still self-heals at tool granularity.
+        observability: Render the run timeline into the Flyte task report.
+        memory_key: Stable id (e.g. a user/thread id) for cross-run memory.
+            When set, conversation history is persisted to a keyed ``MemoryStore``
+            and resumed on a later run with the same key (passed to Hermes as
+            ``conversation_history``).
+        **agent_kwargs: Extra keyword arguments for the built ``AIAgent``
+            (e.g. ``api_key=``, ``base_url=``, ``provider=``,
+            ``max_iterations=``). Only valid on the builder path. When none of
+            ``api_key``/``base_url``/``provider`` are given and
+            ``OPENAI_API_KEY`` is set, the built agent is pointed at OpenAI
+            with that key (Hermes otherwise only reads credentials from its own
+            ``hermes setup`` config, which a fresh container doesn't have).
+
+    Returns:
+        The agent's final output as a string.
+    """
+    timeline = ReportTimeline() if observability else None
+    if timeline is not None:
+        timeline.heading("Hermes agent")
+
+    if agent is not None and tools:
+        raise ValueError("Pass either `agent` (with its own tools) or `tools`, not both.")
+    if agent is not None and agent_kwargs:
+        raise ValueError("`**agent_kwargs` configure the built agent; don't pass them with a pre-built `agent=`.")
+
+    # Cross-run memory: load the prior transcript (if any) and resume the thread.
+    store = await resolve_memory(memory_key)
+    history = await load_transcript(store)
+
+    system_message: str | None = None
+    if agent is None:
+        if model is None:
+            raise ValueError("Provide `model=` when building the agent (or pass a pre-built `agent=`).")
+
+        if _AIAgent is None:
+            from run_agent import AIAgent as _HermesAgent  # hermes-agent's top-level module
+        else:
+            _HermesAgent = _AIAgent
+
+        enabled_toolsets: list[str] = []
+        if tools:
+            registered = [_coerce_tool(t) for t in tools]
+            enabled_toolsets = [_scoped_toolset(name, registered)]
+
+        has_credentials = any(k in agent_kwargs for k in ("api_key", "base_url", "provider"))
+        if not has_credentials and os.environ.get("OPENAI_API_KEY"):
+            agent_kwargs["api_key"] = os.environ["OPENAI_API_KEY"]
+            agent_kwargs["base_url"] = _OPENAI_BASE_URL
+
+        agent = _HermesAgent(
+            model=model,
+            ephemeral_system_prompt=instructions or f"You are a helpful assistant named {name}.",
+            enabled_toolsets=enabled_toolsets,
+            quiet_mode=True,
+            **agent_kwargs,
+        )
+    else:
+        # A pre-built agent keeps its own prompt; explicit instructions ride
+        # along as this run's system message.
+        system_message = instructions
+
+    # Drive the agent. ``run_conversation`` is synchronous (Hermes bridges its
+    # async tool handlers internally), so run it off the event loop;
+    # ``to_thread`` propagates the Flyte task context into the worker thread.
+    call_kwargs: dict[str, typing.Any] = {}
+    if system_message:
+        call_kwargs["system_message"] = system_message
+    if history:
+        call_kwargs["conversation_history"] = list(history)
+
+    result = await asyncio.to_thread(lambda: agent.run_conversation(input, **call_kwargs))
+    if inspect.isawaitable(result):  # tolerate async fakes/wrappers
+        result = await result
+
+    final = result.get("final_response") if isinstance(result, dict) else result
+    final = str(final) if final is not None else ""
+
+    # Persist the updated transcript for the next run with this memory_key.
+    if store is not None:
+        await save_transcript(
+            store,
+            [*history, {"role": "user", "content": input}, {"role": "assistant", "content": final}],
+        )
+
+    if observability:
+        await flush_report()
+
+    return final
+
+
+run_agent_sync = sync_variant(run_agent)

flyteplugins/agents/hermes/_tools.py

@@ -0,0 +1,122 @@
+"""Turn Flyte tasks into Hermes tools that execute as durable actions.
+
+Hermes (the ``hermes-agent`` package) does not accept tool callables on the
+agent object. Tools live in a process-global registry (``tools.registry``),
+keyed by name and grouped into *toolsets*; an ``AIAgent`` exposes whatever its
+``enabled_toolsets`` resolve to. :func:`tool` therefore does two things:
+
+1. wraps the Flyte ``@env.task`` with the shared core wrapper
+   (:func:`flyteplugins.agents.core.tool`) so a call dispatches to
+   ``task.aio()`` — a durable Flyte child action (its own container/resources,
+   with retries and caching) — and the backing task resolves to itself on the
+   worker;
+2. registers that wrapper in the Hermes tool registry under the
+   :data:`FLYTE_TOOLSET` toolset, with an OpenAI-format schema derived from the
+   task via the Flyte type engine.
+
+``run_agent`` then scopes each built agent to exactly the requested tools via a
+custom toolset (see ``_run``); a bring-your-own ``AIAgent`` opts in with
+``enabled_toolsets=[FLYTE_TOOLSET]``.
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+import typing
+from functools import partial
+
+from flyte._task import AsyncFunctionTaskTemplate
+from flyte.models import NativeInterface
+from flyteplugins.agents.core import task_json_schema
+from flyteplugins.agents.core import tool as core_tool
+
+FLYTE_TOOLSET = "flyte"
+"""The Hermes toolset every Flyte ``tool`` registers under."""
+
+
+def tool(
+    func: AsyncFunctionTaskTemplate | typing.Callable | None = None,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+) -> typing.Any:
+    """Convert a Flyte task (or plain callable) into a Hermes tool.
+
+    - For an ``@env.task``: returns the shared core tool wrapper (a plain async
+      function dispatching to the task as a durable Flyte child action, with
+      ``__wrapped_task__`` and the resolver wired), *and* registers it in the
+      Hermes tool registry under :data:`FLYTE_TOOLSET` so an ``AIAgent`` can
+      call it by name. The input schema is derived from the task via the Flyte
+      type engine.
+    - For a plain (sync or async) callable: registers it as an inline Hermes
+      tool, deriving the schema from its signature.
+
+    Usable bare, parametrized, or as a direct call::
+
+        @tool
+        @env.task
+        async def get_weather(city: str) -> str: ...
+    """
+    if func is None:
+        return partial(tool, name=name, description=description)
+
+    wrapper = core_tool(func, name=name, description=description)
+    tool_name = getattr(wrapper, "__name__", None) or type(wrapper).__name__
+
+    if isinstance(func, AsyncFunctionTaskTemplate):
+        desc = (description or func.func.__doc__ or f"Run {tool_name}").strip()
+        parameters = task_json_schema(func)
+    else:
+        desc = (description or getattr(func, "__doc__", None) or f"Run {tool_name}").strip()
+        parameters = NativeInterface.from_callable(func).json_schema
+
+    _register_hermes_tool(tool_name, desc, parameters, wrapper)
+    try:
+        wrapper.__hermes_registered__ = True
+    except (AttributeError, TypeError):  # pragma: no cover - slotted/immutable callable
+        pass
+    return wrapper
+
+
+def _register_hermes_tool(
+    tool_name: str,
+    description: str,
+    parameters: dict[str, typing.Any],
+    wrapper: typing.Callable,
+) -> None:
+    """Register ``wrapper`` in the Hermes tool registry under :data:`FLYTE_TOOLSET`.
+
+    The handler receives the model's arguments as a dict (Hermes dispatches
+    ``handler(args, **context)``) and returns a string for the model. Re-registering
+    the same name replaces the previous entry, so module reloads are safe.
+    """
+    from tools.registry import registry  # hermes-agent's process-global tool registry
+
+    async def _handler(args: dict[str, typing.Any] | None = None, **_: typing.Any) -> str:
+        out = wrapper(**(args or {}))
+        if inspect.isawaitable(out):
+            out = await out
+        return _as_content(out)
+
+    registry.register(
+        name=tool_name,
+        toolset=FLYTE_TOOLSET,
+        schema={
+            "type": "function",
+            "function": {"name": tool_name, "description": description, "parameters": parameters},
+        },
+        handler=_handler,
+        is_async=True,
+        description=description,
+    )
+
+
+def _as_content(result: typing.Any) -> str:
+    """Convert a tool result to a string for the model."""
+    if isinstance(result, str):
+        return result
+    try:
+        return json.dumps(result, default=str)
+    except (TypeError, ValueError):
+        return str(result)

flyteplugins_agents_hermes-2.5.17.dist-info/METADATA

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: flyteplugins-agents-hermes
+Version: 2.5.17
+Summary: Run Hermes agent on Flyte.
+Author-email: Niels Bantilan <niels@union.ai>
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: flyteplugins-agents-core
+Requires-Dist: hermes-agent

flyteplugins_agents_hermes-2.5.17.dist-info/RECORD

@@ -0,0 +1,8 @@
+flyteplugins/agents/hermes/__init__.py,sha256=lDU18HA4WedhsEJ_KKZGRaVVmPXDQVfcHCx-KSbm5Ws,759
+flyteplugins/agents/hermes/_memory.py,sha256=NHTnsdrZ44XhZO2gs6V3mYaaP--fAnhupj1cp1izwMQ,2112
+flyteplugins/agents/hermes/_run.py,sha256=eVfs3YZnmQDYkxC_OunaYrcj_ofyd4Mql9y0uZfb24M,8394
+flyteplugins/agents/hermes/_tools.py,sha256=MnDvPFUh0Tx_mPYjV0TPWyaeveCkREPuwoVKjGkclZE,4594
+flyteplugins_agents_hermes-2.5.17.dist-info/METADATA,sha256=RpbKppFN0p49egiOOT0iQeVR3QBLYDGc_YaG3jORFCI,285
+flyteplugins_agents_hermes-2.5.17.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+flyteplugins_agents_hermes-2.5.17.dist-info/top_level.txt,sha256=cgd779rPu9EsvdtuYgUxNHHgElaQvPn74KhB5XSeMBE,13
+flyteplugins_agents_hermes-2.5.17.dist-info/RECORD,,

flyteplugins_agents_hermes-2.5.17.dist-info/WHEEL

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

flyteplugins_agents_hermes-2.5.17.dist-info/top_level.txt

@@ -0,0 +1 @@
+flyteplugins