apify-hermes-agent-plugin 0.1.0__tar.gz

apify_hermes_agent_plugin-0.1.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.1.0] - 2026-08-11
+
+### Added
+
+- Initial release.
+- `apify_discover` tool — search the Apify Store by keyword, or fetch an Actor's input schema and README by `actor_id`.
+- `apify_start` tool — fire-and-forget batch Actor runs (up to 10 per call).
+- `apify_collect` tool — poll run statuses and return completed dataset results.
+- `hermes apify-setup` CLI command — prompt for (or accept via `--token`) the `APIFY_API_TOKEN` and enable the Apify toolset.

apify_hermes_agent_plugin-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Apify
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

apify_hermes_agent_plugin-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include CHANGELOG.md
+prune tests

apify_hermes_agent_plugin-0.1.0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: apify-hermes-agent-plugin
+Version: 0.1.0
+Summary: Hermes Agent plugin for Apify, the world's largest marketplace for AI tools — discover, run, and collect results from Actors, all from natural language
+Author-email: "Apify Technologies s.r.o." <support@apify.com>
+License: MIT
+Project-URL: Homepage, https://github.com/apify/apify-hermes-agent-plugin
+Project-URL: Source Code, https://github.com/apify/apify-hermes-agent-plugin
+Project-URL: Issue Tracker, https://github.com/apify/apify-hermes-agent-plugin/issues
+Project-URL: Changelog, https://github.com/apify/apify-hermes-agent-plugin/blob/main/CHANGELOG.md
+Project-URL: Hermes Agent, https://hermes-agent.nousresearch.com
+Keywords: apify,hermes,hermes-agent,actor,plugin,ai-tools,automation
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: hermes-agent>=0.15.1
+Requires-Dist: apify-client<4,>=3.0.1
+Provides-Extra: dev
+Requires-Dist: pytest==9.0.2; extra == "dev"
+Requires-Dist: pytest-asyncio==1.3.0; extra == "dev"
+Requires-Dist: ruff<0.17,>=0.15.20; extra == "dev"
+Requires-Dist: ty<0.1,>=0.0.65; extra == "dev"
+Dynamic: license-file
+
+# apify-hermes-agent-plugin
+
+Hermes Agent plugin for [Apify](https://apify.com), the world's largest marketplace for AI tools — discover
+Actors in the Apify Store, start runs, and collect structured results, all from natural language, via
+[Hermes Agent](https://hermes-agent.nousresearch.com).
+
+## Install
+
+    pip install apify-hermes-agent-plugin
+    hermes plugins enable apify
+
+Then run:
+
+    hermes apify-setup
+
+This prompts for your `APIFY_API_TOKEN` (get one at https://apify.com/account/integrations),
+saves it, and enables the Apify Actors toolset for the CLI. Pass `--token <token>` to skip the
+prompt.
+
+## Tools
+
+- `apify_discover` — search the Apify Store by keyword, or fetch an Actor's input schema + README by `actor_id`.
+- `apify_start` — fire-and-forget batch Actor starts (up to 10 per call).
+- `apify_collect` — poll run statuses and return completed dataset results.
+
+## Development
+
+    pip install -e ".[dev]"
+    pytest

apify_hermes_agent_plugin-0.1.0/README.md

@@ -0,0 +1,29 @@
+# apify-hermes-agent-plugin
+
+Hermes Agent plugin for [Apify](https://apify.com), the world's largest marketplace for AI tools — discover
+Actors in the Apify Store, start runs, and collect structured results, all from natural language, via
+[Hermes Agent](https://hermes-agent.nousresearch.com).
+
+## Install
+
+    pip install apify-hermes-agent-plugin
+    hermes plugins enable apify
+
+Then run:
+
+    hermes apify-setup
+
+This prompts for your `APIFY_API_TOKEN` (get one at https://apify.com/account/integrations),
+saves it, and enables the Apify Actors toolset for the CLI. Pass `--token <token>` to skip the
+prompt.
+
+## Tools
+
+- `apify_discover` — search the Apify Store by keyword, or fetch an Actor's input schema + README by `actor_id`.
+- `apify_start` — fire-and-forget batch Actor starts (up to 10 per call).
+- `apify_collect` — poll run statuses and return completed dataset results.
+
+## Development
+
+    pip install -e ".[dev]"
+    pytest

apify_hermes_agent_plugin-0.1.0/pyproject.toml

@@ -0,0 +1,121 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "apify-hermes-agent-plugin"
+version = "0.1.0"
+description = "Hermes Agent plugin for Apify, the world's largest marketplace for AI tools — discover, run, and collect results from Actors, all from natural language"
+authors = [{ name = "Apify Technologies s.r.o.", email = "support@apify.com" }]
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries",
+]
+keywords = ["apify", "hermes", "hermes-agent", "actor", "plugin", "ai-tools", "automation"]
+dependencies = [
+    "hermes-agent>=0.15.1",
+    "apify-client>=3.0.1,<4",
+]
+
+[project.optional-dependencies]
+dev = ["pytest==9.0.2", "pytest-asyncio==1.3.0", "ruff>=0.15.20,<0.17", "ty>=0.0.65,<0.1"]
+
+[project.urls]
+"Homepage" = "https://github.com/apify/apify-hermes-agent-plugin"
+"Source Code" = "https://github.com/apify/apify-hermes-agent-plugin"
+"Issue Tracker" = "https://github.com/apify/apify-hermes-agent-plugin/issues"
+"Changelog" = "https://github.com/apify/apify-hermes-agent-plugin/blob/main/CHANGELOG.md"
+"Hermes Agent" = "https://hermes-agent.nousresearch.com"
+
+[project.entry-points."hermes_agent.plugins"]
+# NOTE: must point at the bare module, not "apify_hermes_agent_plugin:register".
+# hermes-agent's loader (hermes_cli/plugins.py::_load_entrypoint_module) calls
+# ep.load() and then does getattr(result, "register") — it expects a module.
+# Per importlib.metadata semantics, "module:attr" entry points make ep.load()
+# return the attr itself (the register function), not the module, so
+# getattr(register_fn, "register") finds nothing and the plugin silently
+# fails to load ("no register() function"). This diverges from hermes-agent's
+# own plugin docs example (which shows "my_plugin:register") — see
+# https://hermes-agent.nousresearch.com/docs/user-guide/features/plugins.
+apify = "apify_hermes_agent_plugin"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "strict"
+
+[tool.ruff]
+line-length = 120
+include = ["src/**/*.py", "tests/**/*.py"]
+
+[tool.ruff.format]
+quote-style = "single"
+indent-style = "space"
+
+[tool.ruff.lint.flake8-quotes]
+docstring-quotes = "double"
+inline-quotes = "single"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "ANN401",   # `Any` is disallowed — this plugin's whole surface is dynamically-typed SDK
+                # responses (apify-client returns Pydantic models OR dicts depending on call site)
+                # and JSON-schema-validated tool args; `Any` here is accurate, not lazy.
+    "BLE001",   # Do not catch blind exception — every handler must turn arbitrary SDK/network
+                # failures into a JSON error object for the LLM, never let one crash the tool call.
+    "COM812",   # Conflicts with the formatter.
+    "CPY001",   # Missing copyright notice — this is an MIT-licensed package (see LICENSE at the
+                # repo root); per-file copyright headers aren't this project's convention.
+    "D100",     # Missing docstring in public module.
+    "D104",     # Missing docstring in public package.
+    "D107",     # Missing docstring in `__init__`.
+    "D203",     # One blank line required before class docstring.
+    "D213",     # Multi-line docstring summary should start at the second line.
+    "PLC0415",  # Import should be at top-level — deliberate: `tools.py`/`cli.py` re-import
+                # `tools.interrupt.is_interrupted` and hermes_cli internals inside each function
+                # so tests can `monkeypatch.setattr("tools.interrupt.is_interrupted", ...)` and
+                # have it take effect. A module-level import would bind the original function
+                # once at import time and monkeypatching the source module afterwards would not
+                # reach it — see tests/test_tools.py's `not_interrupted` fixture.
+    "PLR0913",  # Too many arguments in function definition.
+    "PLW0603",  # Using `global` — `src/apify_hermes_agent_plugin/client.py`'s two module-level
+                # variables are a deliberate single-client memoization cache; a wrapper class for
+                # two variables would be more ceremony than the pattern it replaces.
+    "EM101",    # Exception must not use a string literal — validation errors are one-off, not reused.
+    "EM102",    # Exception must not use an f-string literal — same reason.
+    "TRY003",   # Avoid specifying long messages outside the exception class — same reason.
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = [
+    "ANN",      # Type annotations on test helpers/mocks add noise, not safety.
+    "ARG001",   # Mocks commonly do not use all arguments.
+    "ARG002",   # Same — pytest fixtures (e.g. an autouse-style mock_client) are commonly
+                # accepted by a test method for their side effect and never referenced in the body.
+    "ARG005",   # Same — monkeypatch stub lambdas commonly ignore their arguments.
+    "D",        # Missing docstrings.
+    "INP001",   # Implicit namespace package — tests/ deliberately has no __init__.py (a pytest
+                # rootdir/import-mode choice), so this rule will always fire here; it's a
+                # permanent ignore, not pending work.
+    "PLR2004",  # Magic value used in comparison.
+    "S101",     # Use of assert detected.
+    "S105",     # Possible hardcoded password — these are fake test tokens.
+    "S106",     # Possible hardcoded password assigned to argument — same reason.
+]
+"src/apify_hermes_agent_plugin/cli.py" = [
+    "T201",     # `print` found — this file *is* the CLI's terminal UI; printing is the point.
+]

apify_hermes_agent_plugin-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

apify_hermes_agent_plugin-0.1.0/src/apify_hermes_agent_plugin/__init__.py

@@ -0,0 +1,45 @@
+"""apify-hermes-agent-plugin — Apify Actor execution tools for Hermes Agent."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from apify_hermes_agent_plugin.cli import apify_setup_command, register_cli
+from apify_hermes_agent_plugin.tools import (
+    _COLLECT_SCHEMA,
+    _DISCOVER_SCHEMA,
+    _START_SCHEMA,
+    _check_token,
+    collect_handler_str,
+    discover_handler_str,
+    start_handler_str,
+)
+
+_TOOLS = (
+    ('apify_discover', _DISCOVER_SCHEMA, discover_handler_str, '🔍', False),
+    ('apify_start', _START_SCHEMA, start_handler_str, '▶️', False),
+    ('apify_collect', _COLLECT_SCHEMA, collect_handler_str, '📦', True),
+)
+
+
+def register(ctx: Any) -> None:
+    """Register the three Apify Actor tools. Called once by the Hermes plugin loader."""
+    for name, schema, handler, emoji, is_async in _TOOLS:
+        ctx.register_tool(
+            name=name,
+            toolset='apify',
+            schema=schema,
+            handler=handler,
+            check_fn=_check_token,
+            requires_env=['APIFY_API_TOKEN'],
+            is_async=is_async,
+            emoji=emoji,
+        )
+
+    ctx.register_cli_command(
+        name='apify-setup',
+        help='Set your Apify API token',
+        setup_fn=register_cli,
+        handler_fn=apify_setup_command,
+        description=('Prompt for (or accept via --token) your APIFY_API_TOKEN and save it to ~/.hermes/.env.'),
+    )

apify_hermes_agent_plugin-0.1.0/src/apify_hermes_agent_plugin/cli.py

@@ -0,0 +1,86 @@
+"""``hermes apify-setup`` — prompt for and save the Apify API token."""
+
+from __future__ import annotations
+
+import getpass
+import sys
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import argparse
+
+_ENV_KEY = 'APIFY_API_TOKEN'
+
+
+def register_cli(parser: argparse.ArgumentParser) -> None:
+    """Wire up ``hermes apify-setup`` argument parsing.
+
+    Called by the Hermes plugin loader with the parser for this subcommand.
+    """
+    parser.add_argument(
+        '--token',
+        default=None,
+        help=("Apify API token (skips the interactive prompt). If omitted, you'll be prompted securely."),
+    )
+
+
+def apify_setup_command(args: argparse.Namespace) -> int:
+    """Prompt for (or accept via --token) the Apify API token and save it."""
+    token = getattr(args, 'token', None)
+    if token is not None:
+        token = token.strip()
+    else:
+        print('Set your Apify API token (get one at https://apify.com/account/integrations).')
+        token = getpass.getpass(f'{_ENV_KEY}: ').strip()
+
+    if not token:
+        print('No token provided — aborted.')
+        sys.exit(1)
+
+    from hermes_cli.config import get_env_path, save_env_value
+
+    save_env_value(_ENV_KEY, token)
+    print(f'Saved {_ENV_KEY} to {get_env_path()}')
+
+    try:
+        _enable_apify_toolset_for_cli()
+        print('Enabled the Apify Actors toolset for the CLI.')
+    except Exception as exc:
+        print(f'Could not auto-enable the Apify Actors toolset ({exc}).')
+        print('Run `hermes tools` and enable it manually.')
+
+    return 0
+
+
+def _enable_apify_toolset_for_cli() -> None:
+    """Add "apify" to the set of toolsets enabled for the "cli" platform.
+
+    Reuses hermes-agent's own config read/merge/save logic (rather than
+    reimplementing it) since it has non-obvious invariants — reconciling
+    agent.disabled_toolsets, preserving MCP server entries, plugin-toolset
+    bookkeeping. These are private hermes_cli internals with no stability
+    guarantee; callers should treat failure here as non-fatal.
+
+    If the "cli" platform has no explicit toolset list yet, resolving and
+    saving it (via ``_get_platform_tools``) would expand the implicit
+    default composite (every default-on toolset, plus MCP servers) into a
+    frozen explicit snapshot — silently opting this user out of any future
+    default-on toolset that ships in a later hermes-agent release. Instead,
+    keep the composite referenced by name (the same "[hermes-cli, spotify]"
+    mixed-config shape ``_get_platform_tools`` already supports for a single
+    explicit opt-in alongside the defaults).
+    """
+    from hermes_cli.config import load_config
+    from hermes_cli.tools_config import PLATFORMS, _get_platform_tools, _save_platform_tools
+
+    config = load_config()
+    existing = (config.get('platform_toolsets') or {}).get('cli')
+
+    if isinstance(existing, list):
+        enabled = _get_platform_tools(config, 'cli')
+    else:
+        default_ts = PLATFORMS.get('cli', {}).get('default_toolset', 'hermes-cli')
+        enabled = {default_ts}
+
+    enabled.add('apify')
+    _save_platform_tools(config, 'cli', enabled)

apify_hermes_agent_plugin-0.1.0/src/apify_hermes_agent_plugin/client.py

@@ -0,0 +1,45 @@
+"""Apify SDK client — token validation and cache."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from apify_client import ApifyClient
+
+# Sent with every request so Apify can attribute traffic to this integration.
+_HERMES_HEADERS = {'x-apify-integration-platform': 'hermes-agent'}
+
+_CLIENT: Any | None = None
+_CLIENT_CONFIG: Any | None = None
+
+
+def check_apify_api_key() -> bool:
+    """Return True when APIFY_API_TOKEN is configured."""
+    return bool(os.getenv('APIFY_API_TOKEN', '').strip())
+
+
+def get_apify_client() -> Any:
+    """Return a cached ApifyClient built from APIFY_API_TOKEN.
+
+    Raises ValueError when the token is not set.
+    """
+    global _CLIENT, _CLIENT_CONFIG
+    api_token = os.getenv('APIFY_API_TOKEN', '').strip()
+    if not api_token:
+        raise ValueError(
+            'Apify tools are not configured. Set APIFY_API_TOKEN (get one at https://apify.com/account/integrations).'
+        )
+    client_config = ('direct', api_token)
+    if _CLIENT is not None and client_config == _CLIENT_CONFIG:
+        return _CLIENT
+    _CLIENT = ApifyClient(token=api_token, headers=_HERMES_HEADERS)
+    _CLIENT_CONFIG = client_config
+    return _CLIENT
+
+
+def _reset_client_for_tests() -> None:
+    """Drop cached client so tests can re-instantiate cleanly."""
+    global _CLIENT, _CLIENT_CONFIG
+    _CLIENT = None
+    _CLIENT_CONFIG = None

apify_hermes_agent_plugin-0.1.0/src/apify_hermes_agent_plugin/tools.py

@@ -0,0 +1,431 @@
+"""Apify Actor execution tools — discover, start, collect."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+_TERMINAL_STATUSES = {'SUCCEEDED', 'FAILED', 'ABORTED', 'TIMED-OUT'}
+_MAX_BATCH_RUNS = 10
+_COLLECT_DEFAULT_LIMIT = 100
+_MAX_CONTENT_CHARS = 50_000
+
+
+def _attr(obj: Any, key: str, default: Any = None) -> Any:
+    """Get attribute or dict key from SDK response objects (apify_client returns either)."""
+    if isinstance(obj, dict):
+        return obj.get(key, default)
+    if obj is not None and hasattr(obj, key):
+        return getattr(obj, key)
+    return default
+
+
+def _get_client() -> Any:
+    from apify_hermes_agent_plugin.client import get_apify_client
+
+    return get_apify_client()
+
+
+def _check_token() -> bool:
+    from apify_hermes_agent_plugin.client import check_apify_api_key
+
+    return check_apify_api_key()
+
+
+# ---------------------------------------------------------------------------
+# Handlers
+# ---------------------------------------------------------------------------
+
+
+def _discover_handler(args: dict[str, Any]) -> dict[str, Any]:
+    from tools.interrupt import is_interrupted
+
+    if is_interrupted():
+        return {'error': 'Interrupted'}
+
+    query = (_attr(args, 'query') or '').strip() or None
+    actor_id = (_attr(args, 'actor_id') or '').strip() or None
+
+    if not query and not actor_id:
+        return {
+            'error': (
+                "Provide exactly one of 'query' (to search the Apify Store) "
+                "or 'actor_id' (to fetch an Actor's input schema)."
+            )
+        }
+
+    client = _get_client()
+    if actor_id:
+        return _discover_actor(client, actor_id)
+    # This is a type-narrowing hint for `ty`, not a `-O`-surviving safety net — it's provably
+    # redundant given the `query`/`actor_id` guard above, so it's fine if stripped.
+    assert query is not None, 'guaranteed by the query/actor_id check above'  # noqa: S101
+    return _discover_store(client, query)
+
+
+def _discover_actor(client: Any, actor_id: str) -> dict[str, Any]:
+    """Fetch a single Actor's input schema and README by ID or username~actor-name."""
+    try:
+        actor_info = client.actor(actor_id).get()
+        if actor_info is None:
+            return {'error': (f"Actor '{actor_id}' not found. Check the ID format: username~actor-name.")}
+
+        input_schema: Any = None
+        readme: Any = None
+
+        build_detail = client.actor(actor_id).default_build().get()
+        if build_detail is not None:
+            # apify-client 3.x returns Pydantic models with snake_case attributes
+            # (e.g. Build.actor_definition, Build.input_schema) — the JSON's
+            # camelCase names only exist as (de)serialization aliases, not as
+            # real attributes, so _attr() must be called with the snake_case name.
+            actor_def = _attr(build_detail, 'actor_definition')
+            raw_schema = _attr(actor_def, 'input')
+            if raw_schema:
+                input_schema = json.dumps(raw_schema)
+            else:
+                fallback = _attr(build_detail, 'input_schema')
+                if fallback:
+                    input_schema = str(fallback)
+
+            raw_readme = _attr(actor_def, 'readme') or _attr(build_detail, 'readme')
+            if raw_readme:
+                readme = str(raw_readme)[:3000]
+
+        username = _attr(actor_info, 'username', '')
+        name = _attr(actor_info, 'name', '')
+        title = _attr(actor_info, 'title', '') or name
+    except Exception as exc:
+        logger.warning('apify_discover schema fetch error for %s: %s', actor_id, exc)
+        return {'error': str(exc)}
+    else:
+        return {
+            'actor_id': f'{username}~{name}',
+            'name': name,
+            'title': title,
+            'username': username,
+            'description': _attr(actor_info, 'description', ''),
+            'input_schema': input_schema,
+            'readme': readme,
+            'tip': (f"Use apify_start with actor_id='{username}~{name}' and an input matching the input_schema above."),
+        }
+
+
+def _discover_store(client: Any, query: str) -> dict[str, Any]:
+    """Search the Apify Store by keyword."""
+    try:
+        result = client.store().list(search=query, limit=10, sort_by='relevance')
+        items = _attr(result, 'items') or []
+        actors: list[dict[str, Any]] = []
+        for item in items:
+            stats = _attr(item, 'stats')
+            name = _attr(item, 'name', '')
+            username = _attr(item, 'username', '')
+            title = _attr(item, 'title') or name
+            desc = (_attr(item, 'description') or '')[:200]
+            # ActorStats.total_runs — see the snake_case note in _discover_actor().
+            run_count = _attr(stats, 'total_runs', 0) or 0
+            actors.append(
+                {
+                    'actor_id': f'{username}~{name}',
+                    'name': name,
+                    'title': title,
+                    'username': username,
+                    'description': desc,
+                    'run_count': run_count,
+                }
+            )
+    except Exception as exc:
+        logger.warning("apify_discover store search error for '%s': %s", query, exc)
+        return {'error': str(exc)}
+    else:
+        return {'actors': actors}
+
+
+def _start_one_run(client: Any, spec: dict[str, Any]) -> dict[str, Any]:
+    actor_id = (spec.get('actor_id') or '').strip()
+    run_input = spec.get('input') or {}
+    label = spec.get('label')
+
+    if not actor_id:
+        return {'_ok': False, 'error': "Missing 'actor_id' in run spec."}
+
+    try:
+        run = client.actor(actor_id).start(run_input=run_input)
+        entry: dict[str, Any] = {
+            'run_id': _attr(run, 'id'),
+            'actor_id': actor_id,
+            'dataset_id': _attr(run, 'default_dataset_id'),
+            'status': _attr(run, 'status'),
+        }
+        if label:
+            entry['label'] = label
+    except Exception as exc:
+        logger.warning('apify_start error for %s: %s', actor_id, exc)
+        err: dict[str, Any] = {'actor_id': actor_id, 'error': str(exc)}
+        if label:
+            err['label'] = label
+        return {'_ok': False, **err}
+    else:
+        return {'_ok': True, **entry}
+
+
+def _start_handler(args: dict[str, Any]) -> dict[str, Any]:
+    from tools.interrupt import is_interrupted
+
+    if is_interrupted():
+        return {'error': 'Interrupted'}
+
+    run_specs = args.get('runs') or []
+    if not run_specs:
+        return {'error': "Provide at least one run spec in 'runs'."}
+    if len(run_specs) > _MAX_BATCH_RUNS:
+        return {'error': f'Batch too large: {len(run_specs)} runs requested, maximum is {_MAX_BATCH_RUNS}.'}
+
+    client = _get_client()
+    started: list[dict[str, Any]] = []
+    errors: list[dict[str, Any]] = []
+
+    for spec in run_specs:
+        from tools.interrupt import is_interrupted
+
+        if is_interrupted():
+            break
+        outcome = _start_one_run(client, spec)
+        ok = outcome.pop('_ok')
+        (started if ok else errors).append(outcome)
+
+    result: dict[str, Any] = {'runs': started}
+    if errors:
+        result['errors'] = errors
+    return result
+
+
+async def _check_run(client: Any, limit: int, ref: dict[str, Any]) -> dict[str, Any]:
+    run_id = ref.get('run_id', '')
+    actor_id = ref.get('actor_id', '')
+    dataset_id = ref.get('dataset_id', '')
+    label = ref.get('label')
+
+    base: dict[str, Any] = {
+        'run_id': run_id,
+        'actor_id': actor_id,
+        'dataset_id': dataset_id,
+    }
+    if label:
+        base['label'] = label
+
+    try:
+        run_info = await asyncio.to_thread(client.run(run_id).get)
+
+        if run_info is None:
+            return {**base, '_type': 'error', 'error': 'Run not found.'}
+
+        status = _attr(run_info, 'status', 'UNKNOWN')
+        base['status'] = status
+
+        if status not in _TERMINAL_STATUSES:
+            return {**base, '_type': 'pending'}
+
+        if status != 'SUCCEEDED':
+            return {**base, '_type': 'error', 'error': f'Run ended with status: {status}'}
+
+        return await _collect_dataset(client, limit, run_id, dataset_id, base)
+
+    except Exception as exc:
+        logger.warning('apify_collect error for run %s: %s', run_id, exc)
+        return {**base, '_type': 'error', 'error': str(exc)}
+
+
+async def _collect_dataset(
+    client: Any, limit: int, run_id: str, dataset_id: str, base: dict[str, Any]
+) -> dict[str, Any]:
+    dataset_result = await asyncio.to_thread(client.dataset(dataset_id).list_items, limit=limit)
+    items = list(_attr(dataset_result, 'items') or [])
+    may_have_more = len(items) == limit
+    if may_have_more:
+        logger.warning(
+            'apify_collect run %s: fetched %d items (hit limit=%d) — '
+            'dataset may have more; re-call with a higher limit if needed',
+            run_id,
+            len(items),
+            limit,
+        )
+    raw = json.dumps(items, indent=2, default=str)
+    if len(raw) > _MAX_CONTENT_CHARS:
+        raw = raw[:_MAX_CONTENT_CHARS] + '\n\n[…truncated]'
+    wrapped = '<<<EXTERNAL_UNTRUSTED_CONTENT>>>\n' + raw + '\n<<<END_EXTERNAL_UNTRUSTED_CONTENT>>>'
+    result: dict[str, Any] = {
+        **base,
+        '_type': 'completed',
+        'result_count': len(items),
+        'data': wrapped,
+    }
+    if may_have_more:
+        result['may_have_more'] = True
+    return result
+
+
+async def _collect_handler(args: dict[str, Any]) -> dict[str, Any]:
+    from tools.interrupt import is_interrupted
+
+    if is_interrupted():
+        return {'error': 'Interrupted'}
+
+    run_refs = args.get('runs') or []
+    if not run_refs:
+        return {'error': "Provide 'runs' array (from apify_start)."}
+
+    limit = int(args.get('limit') or _COLLECT_DEFAULT_LIMIT)
+    client = _get_client()
+
+    raw_results = await asyncio.gather(*[_check_run(client, limit, ref) for ref in run_refs])
+
+    completed: list[dict[str, Any]] = []
+    pending: list[dict[str, Any]] = []
+    errors: list[dict[str, Any]] = []
+
+    for r in raw_results:
+        t = r.pop('_type', 'error')
+        if t == 'pending':
+            pending.append(r)
+        elif t == 'error':
+            errors.append(r)
+        else:
+            completed.append(r)
+
+    return {
+        'all_done': len(pending) == 0,
+        'completed': completed,
+        'pending': pending,
+        'errors': errors,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Schemas
+# ---------------------------------------------------------------------------
+
+_DISCOVER_SCHEMA: dict[str, Any] = {
+    'name': 'apify_discover',
+    'description': (
+        "Search the Apify Store for Actors by keyword, or fetch an Actor's "
+        "input schema and README. Provide 'query' to search, or 'actor_id' "
+        'to inspect a specific Actor. Actor IDs accept either the unique ID '
+        'or the username~actor-name format.'
+    ),
+    'parameters': {
+        'type': 'object',
+        'properties': {
+            'query': {
+                'type': 'string',
+                'description': "Keywords to search the Apify Store (e.g. 'instagram scraper').",
+            },
+            'actor_id': {
+                'type': 'string',
+                'description': (
+                    'Actor ID to fetch its input schema and README — either the '
+                    "unique ID or 'username~actor-name' (e.g. 'apify~google-search-scraper')."
+                ),
+            },
+        },
+    },
+}
+
+_START_SCHEMA: dict[str, Any] = {
+    'name': 'apify_start',
+    'description': (
+        'Start one or more Apify Actor runs. Returns run references immediately '
+        f'(fire-and-forget). Pass the returned run refs to apify_collect to get results. '
+        f'Maximum {_MAX_BATCH_RUNS} runs per call.'
+    ),
+    'parameters': {
+        'type': 'object',
+        'properties': {
+            'runs': {
+                'type': 'array',
+                'description': f'List of Actor runs to start (max {_MAX_BATCH_RUNS}).',
+                'maxItems': _MAX_BATCH_RUNS,
+                'items': {
+                    'type': 'object',
+                    'properties': {
+                        'actor_id': {
+                            'type': 'string',
+                            'description': 'Actor ID (username~actor-name).',
+                        },
+                        'input': {
+                            'type': 'object',
+                            'description': 'Actor input parameters.',
+                        },
+                        'label': {
+                            'type': 'string',
+                            'description': 'Optional label to identify this run in results.',
+                        },
+                    },
+                    'required': ['actor_id'],
+                },
+            },
+        },
+        'required': ['runs'],
+    },
+}
+
+_COLLECT_SCHEMA: dict[str, Any] = {
+    'name': 'apify_collect',
+    'description': (
+        'Poll the status of Apify Actor runs started with apify_start. '
+        'Returns completed results, still-running refs, and errors. '
+        'Re-call with the same run refs until all_done is true.'
+    ),
+    'parameters': {
+        'type': 'object',
+        'properties': {
+            'runs': {
+                'type': 'array',
+                'description': 'Run references returned by apify_start.',
+                'items': {
+                    'type': 'object',
+                    'properties': {
+                        'run_id': {'type': 'string'},
+                        'actor_id': {'type': 'string'},
+                        'dataset_id': {'type': 'string'},
+                        'label': {'type': 'string'},
+                    },
+                    'required': ['run_id', 'actor_id', 'dataset_id'],
+                },
+            },
+            'limit': {
+                'type': 'integer',
+                'description': (
+                    f'Max dataset items to fetch per run (default {_COLLECT_DEFAULT_LIMIT}). '
+                    'Increase if may_have_more is true in a previous response.'
+                ),
+            },
+        },
+        'required': ['runs'],
+    },
+}
+
+
+# ---------------------------------------------------------------------------
+# String-returning wrappers consumed by register(ctx) in __init__.py
+# ---------------------------------------------------------------------------
+
+
+def discover_handler_str(args: dict[str, Any], **_kw: Any) -> str:
+    """String-returning wrapper around `_discover_handler`, for hermes-agent's tool dispatcher."""
+    return json.dumps(_discover_handler(args), default=str)
+
+
+def start_handler_str(args: dict[str, Any], **_kw: Any) -> str:
+    """String-returning wrapper around `_start_handler`, for hermes-agent's tool dispatcher."""
+    return json.dumps(_start_handler(args), default=str)
+
+
+async def collect_handler_str(args: dict[str, Any], **_kw: Any) -> str:
+    """String-returning wrapper around `_collect_handler`, for hermes-agent's tool dispatcher."""
+    return json.dumps(await _collect_handler(args), default=str)

apify_hermes_agent_plugin-0.1.0/src/apify_hermes_agent_plugin.egg-info/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: apify-hermes-agent-plugin
+Version: 0.1.0
+Summary: Hermes Agent plugin for Apify, the world's largest marketplace for AI tools — discover, run, and collect results from Actors, all from natural language
+Author-email: "Apify Technologies s.r.o." <support@apify.com>
+License: MIT
+Project-URL: Homepage, https://github.com/apify/apify-hermes-agent-plugin
+Project-URL: Source Code, https://github.com/apify/apify-hermes-agent-plugin
+Project-URL: Issue Tracker, https://github.com/apify/apify-hermes-agent-plugin/issues
+Project-URL: Changelog, https://github.com/apify/apify-hermes-agent-plugin/blob/main/CHANGELOG.md
+Project-URL: Hermes Agent, https://hermes-agent.nousresearch.com
+Keywords: apify,hermes,hermes-agent,actor,plugin,ai-tools,automation
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: hermes-agent>=0.15.1
+Requires-Dist: apify-client<4,>=3.0.1
+Provides-Extra: dev
+Requires-Dist: pytest==9.0.2; extra == "dev"
+Requires-Dist: pytest-asyncio==1.3.0; extra == "dev"
+Requires-Dist: ruff<0.17,>=0.15.20; extra == "dev"
+Requires-Dist: ty<0.1,>=0.0.65; extra == "dev"
+Dynamic: license-file
+
+# apify-hermes-agent-plugin
+
+Hermes Agent plugin for [Apify](https://apify.com), the world's largest marketplace for AI tools — discover
+Actors in the Apify Store, start runs, and collect structured results, all from natural language, via
+[Hermes Agent](https://hermes-agent.nousresearch.com).
+
+## Install
+
+    pip install apify-hermes-agent-plugin
+    hermes plugins enable apify
+
+Then run:
+
+    hermes apify-setup
+
+This prompts for your `APIFY_API_TOKEN` (get one at https://apify.com/account/integrations),
+saves it, and enables the Apify Actors toolset for the CLI. Pass `--token <token>` to skip the
+prompt.
+
+## Tools
+
+- `apify_discover` — search the Apify Store by keyword, or fetch an Actor's input schema + README by `actor_id`.
+- `apify_start` — fire-and-forget batch Actor starts (up to 10 per call).
+- `apify_collect` — poll run statuses and return completed dataset results.
+
+## Development
+
+    pip install -e ".[dev]"
+    pytest

apify_hermes_agent_plugin-0.1.0/src/apify_hermes_agent_plugin.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+CHANGELOG.md
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+src/apify_hermes_agent_plugin/__init__.py
+src/apify_hermes_agent_plugin/cli.py
+src/apify_hermes_agent_plugin/client.py
+src/apify_hermes_agent_plugin/tools.py
+src/apify_hermes_agent_plugin.egg-info/PKG-INFO
+src/apify_hermes_agent_plugin.egg-info/SOURCES.txt
+src/apify_hermes_agent_plugin.egg-info/dependency_links.txt
+src/apify_hermes_agent_plugin.egg-info/entry_points.txt
+src/apify_hermes_agent_plugin.egg-info/requires.txt
+src/apify_hermes_agent_plugin.egg-info/top_level.txt

apify_hermes_agent_plugin-0.1.0/src/apify_hermes_agent_plugin.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

apify_hermes_agent_plugin-0.1.0/src/apify_hermes_agent_plugin.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[hermes_agent.plugins]
+apify = apify_hermes_agent_plugin

apify_hermes_agent_plugin-0.1.0/src/apify_hermes_agent_plugin.egg-info/requires.txt

@@ -0,0 +1,8 @@
+hermes-agent>=0.15.1
+apify-client<4,>=3.0.1
+
+[dev]
+pytest==9.0.2
+pytest-asyncio==1.3.0
+ruff<0.17,>=0.15.20
+ty<0.1,>=0.0.65

apify_hermes_agent_plugin-0.1.0/src/apify_hermes_agent_plugin.egg-info/top_level.txt

@@ -0,0 +1 @@
+apify_hermes_agent_plugin