hermes-tweet 0.1.0__tar.gz

hermes_tweet-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Xquik
+
+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.
+

hermes_tweet-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include plugin.yaml
+recursive-include hermes_tweet *.yaml *.json
+recursive-include hermes_tweet/skills *.md
+

hermes_tweet-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: hermes-tweet
+Version: 0.1.0
+Summary: Native Hermes Agent plugin for X automation through Xquik
+Author: Xquik
+License-Expression: MIT
+Project-URL: Homepage, https://xquik.com
+Project-URL: Documentation, https://docs.xquik.com
+Project-URL: Repository, https://github.com/Xquik-dev/hermes-tweet
+Project-URL: Issues, https://github.com/Xquik-dev/hermes-tweet/issues
+Keywords: hermes-agent,hermes-plugin,twitter,x,xquik,tweet,automation,social-media
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Plugins
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<0.29,>=0.27
+Provides-Extra: dev
+Requires-Dist: bandit[toml]>=1.9.2; extra == "dev"
+Requires-Dist: basedpyright>=1.36.0; extra == "dev"
+Requires-Dist: build>=1.3.0; extra == "dev"
+Requires-Dist: pip-audit>=2.9.0; extra == "dev"
+Requires-Dist: PyYAML>=6.0; extra == "dev"
+Requires-Dist: pytest>=8.2; extra == "dev"
+Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
+Requires-Dist: ruff>=0.14.0; extra == "dev"
+Requires-Dist: twine>=6.2.0; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0.12; extra == "dev"
+Dynamic: license-file
+
+# Hermes Tweet
+
+[![CI](https://github.com/Xquik-dev/hermes-tweet/actions/workflows/ci.yml/badge.svg)](https://github.com/Xquik-dev/hermes-tweet/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/hermes-tweet.svg)](https://pypi.org/project/hermes-tweet/)
+[![Python](https://img.shields.io/pypi/pyversions/hermes-tweet.svg)](https://pypi.org/project/hermes-tweet/)
+[![Apify Actor](https://apify.com/actor-badge?actor=xquik/x-tweet-scraper)](https://apify.com/xquik/x-tweet-scraper)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Native [Hermes Agent](https://github.com/NousResearch/hermes-agent) plugin for
+X automation through [Xquik](https://xquik.com).
+
+Hermes Tweet brings X search, account reads, tweet posting, replies, likes,
+retweets, follows, DMs, monitors, webhooks, draws, extraction jobs, media, and
+trend reads into Hermes as structured tools.
+
+Use it when you need a Hermes Agent Twitter plugin, Hermes X automation, social
+media automation for agents, or a native Hermes toolset for X/Twitter.
+
+## Highlights
+
+- Native Hermes plugin with `plugin.yaml` and pip entry point.
+- 99 agent-callable Xquik endpoints generated from OpenAPI.
+- 32 MPP-tagged read endpoints in the bundled catalog.
+- Read and action tools are split for least-privilege operation.
+- Action endpoints are disabled by default.
+- Bundled Hermes skill for agent-facing usage guidance.
+- Slash commands for account status and trends.
+- Strict CI with formatting, linting, type checking, tests, coverage, security
+  scan, dependency audit, and package build checks.
+
+## Install
+
+From a local checkout:
+
+```bash
+pip install -e .
+hermes plugins enable hermes-tweet
+```
+
+For public distribution:
+
+```bash
+pip install hermes-tweet
+hermes plugins enable hermes-tweet
+```
+
+## Configure
+
+Create an API key in the Xquik dashboard, then set:
+
+```bash
+export XQUIK_API_KEY="xq_..."
+```
+
+Optional settings:
+
+```bash
+export XQUIK_BASE_URL="https://xquik.com"
+export HERMES_TWEET_ENABLE_ACTIONS="false"
+```
+
+Action endpoints are disabled unless `HERMES_TWEET_ENABLE_ACTIONS=true`.
+
+## Security Model
+
+Hermes Tweet never accepts credentials through tool arguments. Auth is read from
+environment variables and injected by the plugin at request time.
+
+The plugin blocks dashboard-only admin, billing, credit top-up, support-ticket,
+API-key, and account re-authentication endpoints from the catalog. Private reads
+and write-like endpoints go through `tweet_action`, which is hidden unless
+`HERMES_TWEET_ENABLE_ACTIONS=true`.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `tweet_explore` | Search the bundled Xquik endpoint catalog. No API call. |
+| `tweet_read` | Call catalog-listed read-only endpoints. |
+| `tweet_action` | Call write-like or private endpoints. Disabled by default. |
+
+Use `tweet_explore` first, then call `tweet_read` or `tweet_action` with a
+concrete `/api/v1/...` path.
+
+## Slash Commands
+
+| Command | Purpose |
+| --- | --- |
+| `/xstatus` | Show Xquik account, subscription, and usage status. |
+| `/xtrends` | Show current X trends. |
+
+## Development
+
+Generate the bundled catalog from Xquik OpenAPI:
+
+```bash
+python scripts/build_catalog.py ../xquik/openapi.yaml
+```
+
+Run checks:
+
+```bash
+uv run --python 3.12 --extra dev ruff format --check .
+uv run --python 3.12 --extra dev ruff check .
+uv run --python 3.12 --extra dev basedpyright
+uv run --python 3.12 --extra dev pytest --cov=hermes_tweet --cov=tests --cov-report=term-missing --cov-fail-under=100
+uv run --python 3.12 --extra dev bandit -c pyproject.toml -r hermes_tweet scripts
+uv run --python 3.12 --extra dev pip-audit
+uv run --python 3.12 --extra dev python -m build
+uv run --python 3.12 --extra dev twine check dist/*
+```
+
+For a single local quality gate:
+
+```bash
+uv run --python 3.12 --extra dev ruff format --check . && \
+uv run --python 3.12 --extra dev ruff check . && \
+uv run --python 3.12 --extra dev basedpyright && \
+uv run --python 3.12 --extra dev pytest --cov=hermes_tweet --cov=tests --cov-report=term-missing --cov-fail-under=100 && \
+uv run --python 3.12 --extra dev bandit -c pyproject.toml -r hermes_tweet scripts && \
+uv run --python 3.12 --extra dev pip-audit && \
+uv run --python 3.12 --extra dev python -m build && \
+uv run --python 3.12 --extra dev twine check dist/*
+```
+
+## Relationship To TweetClaw
+
+TweetClaw is the OpenClaw-native npm plugin. Hermes Tweet is the Hermes-native
+Python plugin. Both use the same Xquik API contract.
+
+## Public Repo Metadata
+
+Recommended GitHub description:
+
+> Native Hermes Agent plugin for X/Twitter automation through Xquik.
+
+Recommended topics:
+
+`hermes-agent`, `hermes-plugin`, `hermes`, `twitter`, `x`, `x-api`,
+`x-automation`, `xquik`, `tweet`, `automation`, `social-media`,
+`social-media-automation`, `ai-agent`, `mcp`, `agent-tools`, `twitter-api`,
+`twitter-automation`, `x-twitter`, `apify`, `python`

hermes_tweet-0.1.0/README.md

@@ -0,0 +1,142 @@
+# Hermes Tweet
+
+[![CI](https://github.com/Xquik-dev/hermes-tweet/actions/workflows/ci.yml/badge.svg)](https://github.com/Xquik-dev/hermes-tweet/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/hermes-tweet.svg)](https://pypi.org/project/hermes-tweet/)
+[![Python](https://img.shields.io/pypi/pyversions/hermes-tweet.svg)](https://pypi.org/project/hermes-tweet/)
+[![Apify Actor](https://apify.com/actor-badge?actor=xquik/x-tweet-scraper)](https://apify.com/xquik/x-tweet-scraper)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Native [Hermes Agent](https://github.com/NousResearch/hermes-agent) plugin for
+X automation through [Xquik](https://xquik.com).
+
+Hermes Tweet brings X search, account reads, tweet posting, replies, likes,
+retweets, follows, DMs, monitors, webhooks, draws, extraction jobs, media, and
+trend reads into Hermes as structured tools.
+
+Use it when you need a Hermes Agent Twitter plugin, Hermes X automation, social
+media automation for agents, or a native Hermes toolset for X/Twitter.
+
+## Highlights
+
+- Native Hermes plugin with `plugin.yaml` and pip entry point.
+- 99 agent-callable Xquik endpoints generated from OpenAPI.
+- 32 MPP-tagged read endpoints in the bundled catalog.
+- Read and action tools are split for least-privilege operation.
+- Action endpoints are disabled by default.
+- Bundled Hermes skill for agent-facing usage guidance.
+- Slash commands for account status and trends.
+- Strict CI with formatting, linting, type checking, tests, coverage, security
+  scan, dependency audit, and package build checks.
+
+## Install
+
+From a local checkout:
+
+```bash
+pip install -e .
+hermes plugins enable hermes-tweet
+```
+
+For public distribution:
+
+```bash
+pip install hermes-tweet
+hermes plugins enable hermes-tweet
+```
+
+## Configure
+
+Create an API key in the Xquik dashboard, then set:
+
+```bash
+export XQUIK_API_KEY="xq_..."
+```
+
+Optional settings:
+
+```bash
+export XQUIK_BASE_URL="https://xquik.com"
+export HERMES_TWEET_ENABLE_ACTIONS="false"
+```
+
+Action endpoints are disabled unless `HERMES_TWEET_ENABLE_ACTIONS=true`.
+
+## Security Model
+
+Hermes Tweet never accepts credentials through tool arguments. Auth is read from
+environment variables and injected by the plugin at request time.
+
+The plugin blocks dashboard-only admin, billing, credit top-up, support-ticket,
+API-key, and account re-authentication endpoints from the catalog. Private reads
+and write-like endpoints go through `tweet_action`, which is hidden unless
+`HERMES_TWEET_ENABLE_ACTIONS=true`.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `tweet_explore` | Search the bundled Xquik endpoint catalog. No API call. |
+| `tweet_read` | Call catalog-listed read-only endpoints. |
+| `tweet_action` | Call write-like or private endpoints. Disabled by default. |
+
+Use `tweet_explore` first, then call `tweet_read` or `tweet_action` with a
+concrete `/api/v1/...` path.
+
+## Slash Commands
+
+| Command | Purpose |
+| --- | --- |
+| `/xstatus` | Show Xquik account, subscription, and usage status. |
+| `/xtrends` | Show current X trends. |
+
+## Development
+
+Generate the bundled catalog from Xquik OpenAPI:
+
+```bash
+python scripts/build_catalog.py ../xquik/openapi.yaml
+```
+
+Run checks:
+
+```bash
+uv run --python 3.12 --extra dev ruff format --check .
+uv run --python 3.12 --extra dev ruff check .
+uv run --python 3.12 --extra dev basedpyright
+uv run --python 3.12 --extra dev pytest --cov=hermes_tweet --cov=tests --cov-report=term-missing --cov-fail-under=100
+uv run --python 3.12 --extra dev bandit -c pyproject.toml -r hermes_tweet scripts
+uv run --python 3.12 --extra dev pip-audit
+uv run --python 3.12 --extra dev python -m build
+uv run --python 3.12 --extra dev twine check dist/*
+```
+
+For a single local quality gate:
+
+```bash
+uv run --python 3.12 --extra dev ruff format --check . && \
+uv run --python 3.12 --extra dev ruff check . && \
+uv run --python 3.12 --extra dev basedpyright && \
+uv run --python 3.12 --extra dev pytest --cov=hermes_tweet --cov=tests --cov-report=term-missing --cov-fail-under=100 && \
+uv run --python 3.12 --extra dev bandit -c pyproject.toml -r hermes_tweet scripts && \
+uv run --python 3.12 --extra dev pip-audit && \
+uv run --python 3.12 --extra dev python -m build && \
+uv run --python 3.12 --extra dev twine check dist/*
+```
+
+## Relationship To TweetClaw
+
+TweetClaw is the OpenClaw-native npm plugin. Hermes Tweet is the Hermes-native
+Python plugin. Both use the same Xquik API contract.
+
+## Public Repo Metadata
+
+Recommended GitHub description:
+
+> Native Hermes Agent plugin for X/Twitter automation through Xquik.
+
+Recommended topics:
+
+`hermes-agent`, `hermes-plugin`, `hermes`, `twitter`, `x`, `x-api`,
+`x-automation`, `xquik`, `tweet`, `automation`, `social-media`,
+`social-media-automation`, `ai-agent`, `mcp`, `agent-tools`, `twitter-api`,
+`twitter-automation`, `x-twitter`, `apify`, `python`

hermes_tweet-0.1.0/hermes_tweet/__init__.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import Any
+
+from . import schemas
+from .tools import (
+    action_enabled,
+    call_action,
+    call_read,
+    check_api_available,
+    explore,
+    xstatus,
+    xtrends,
+)
+
+logger = logging.getLogger(__name__)
+
+TOOLSET = "hermes-tweet"
+
+
+def _register_bundled_skills(ctx: Any) -> None:
+    skills_dir = Path(__file__).parent / "skills"
+    for child in sorted(skills_dir.iterdir()):
+        skill_md = child / "SKILL.md"
+        if child.is_dir() and skill_md.exists():
+            ctx.register_skill(child.name, skill_md)
+
+
+def register(ctx: Any) -> None:
+    ctx.register_tool(
+        name="tweet_explore",
+        toolset=TOOLSET,
+        schema=schemas.TWEET_EXPLORE,
+        handler=explore,
+        is_async=False,
+        description="Search the bundled Xquik endpoint catalog.",
+        emoji="🔎",
+    )
+
+    ctx.register_tool(
+        name="tweet_read",
+        toolset=TOOLSET,
+        schema=schemas.TWEET_READ,
+        handler=call_read,
+        check_fn=check_api_available,
+        requires_env=["XQUIK_API_KEY"],
+        is_async=False,
+        description="Call catalog-listed read-only Xquik endpoints.",
+        emoji="📖",
+    )
+
+    ctx.register_tool(
+        name="tweet_action",
+        toolset=TOOLSET,
+        schema=schemas.TWEET_ACTION,
+        handler=call_action,
+        check_fn=action_enabled,
+        requires_env=["XQUIK_API_KEY", "HERMES_TWEET_ENABLE_ACTIONS"],
+        is_async=False,
+        description="Call write-like or private Xquik endpoints.",
+        emoji="✍️",
+    )
+
+    ctx.register_command(
+        "xstatus",
+        handler=xstatus,
+        description="Show Xquik account and usage status",
+    )
+    ctx.register_command("xtrends", handler=xtrends, description="Show current X trends")
+
+    _register_bundled_skills(ctx)
+    logger.info(
+        "Hermes Tweet loaded with actions=%s",
+        os.getenv("HERMES_TWEET_ENABLE_ACTIONS", "false"),
+    )
+
+
+__all__ = ["register"]

hermes_tweet-0.1.0/hermes_tweet/catalog.py

@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from importlib.resources import files
+from typing import Any, cast
+
+DEFAULT_LIMIT = 25
+MAX_LIMIT = 100
+PACKAGE_NAME = "hermes_tweet"
+
+
+@dataclass(frozen=True)
+class Endpoint:
+    category: str
+    free: bool
+    method: str
+    path: str
+    summary: str
+    parameters: tuple[dict[str, Any], ...] = ()
+    response_shape: str | None = None
+    mpp: dict[str, str] | None = None
+    action: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        data: dict[str, Any] = {
+            "category": self.category,
+            "free": self.free,
+            "method": self.method,
+            "path": self.path,
+            "summary": self.summary,
+            "action": self.action,
+        }
+        if self.parameters:
+            data["parameters"] = list(self.parameters)
+        if self.response_shape:
+            data["responseShape"] = self.response_shape
+        if self.mpp:
+            data["mpp"] = self.mpp
+        return data
+
+
+def _load_raw() -> list[dict[str, Any]]:
+    text = files(PACKAGE_NAME).joinpath("catalog_data.json").read_text(encoding="utf-8")
+    data = cast("object", json.loads(text))
+    items = cast("list[object]", data if isinstance(data, list) else [])
+    return [cast("dict[str, Any]", item) for item in items if isinstance(item, dict)]
+
+
+def _tuple_parameters(value: Any) -> tuple[dict[str, Any], ...]:
+    items = cast("list[object]", value if isinstance(value, list) else [])
+    return tuple(cast("dict[str, Any]", item) for item in items if isinstance(item, dict))
+
+
+def _endpoint(item: dict[str, Any]) -> Endpoint:
+    return Endpoint(
+        action=bool(item.get("action")),
+        category=str(item.get("category", "unknown")),
+        free=bool(item.get("free", False)),
+        method=str(item.get("method", "GET")).upper(),
+        mpp=item.get("mpp") if isinstance(item.get("mpp"), dict) else None,
+        parameters=_tuple_parameters(item.get("parameters")),
+        path=str(item.get("path", "")),
+        response_shape=str(item["responseShape"]) if item.get("responseShape") else None,
+        summary=str(item.get("summary", "")),
+    )
+
+
+ENDPOINTS: tuple[Endpoint, ...] = tuple(_endpoint(item) for item in _load_raw())
+
+
+def normalize_method(method: str | None) -> str:
+    return (method or "GET").upper()
+
+
+def normalize_limit(value: Any) -> int:
+    if not isinstance(value, int):
+        return DEFAULT_LIMIT
+    return min(max(value, 1), MAX_LIMIT)
+
+
+def _segments(path: str) -> list[str]:
+    normalized = path.removesuffix("/")
+    return normalized.split("/")
+
+
+def matches_path(template: str, concrete: str) -> bool:
+    if template == concrete:
+        return True
+    template_segments = _segments(template)
+    concrete_segments = _segments(concrete)
+    if len(template_segments) != len(concrete_segments):
+        return False
+    for template_segment, concrete_segment in zip(
+        template_segments, concrete_segments, strict=True
+    ):
+        if template_segment.startswith("{") and template_segment.endswith("}"):
+            if not concrete_segment:
+                return False
+            continue
+        if template_segment.startswith(":"):
+            if not concrete_segment:
+                return False
+            continue
+        if template_segment != concrete_segment:
+            return False
+    return True
+
+
+def find_endpoint(method: str, path: str) -> Endpoint | None:
+    normalized = normalize_method(method)
+    for endpoint in ENDPOINTS:
+        if endpoint.method == normalized and matches_path(endpoint.path, path):
+            return endpoint
+    return None
+
+
+def _matches_query(endpoint: Endpoint, query: str) -> bool:
+    normalized = query.lower()
+    haystack = " ".join(
+        [
+            endpoint.category,
+            endpoint.method,
+            endpoint.path,
+            endpoint.summary,
+            endpoint.response_shape or "",
+            json.dumps(list(endpoint.parameters), ensure_ascii=False),
+        ]
+    ).lower()
+    return normalized in haystack
+
+
+def explore(args: dict[str, Any]) -> list[dict[str, Any]]:
+    method = normalize_method(args.get("method")) if args.get("method") else None
+    category = str(args.get("category", "")).strip().lower()
+    path = str(args.get("path", "")).strip()
+    query = str(args.get("query", "")).strip()
+    limit = normalize_limit(args.get("limit"))
+    include_actions = bool(args.get("include_actions", False))
+
+    endpoints = ENDPOINTS
+    if method:
+        endpoints = tuple(endpoint for endpoint in endpoints if endpoint.method == method)
+    if category:
+        endpoints = tuple(
+            endpoint for endpoint in endpoints if endpoint.category.lower() == category
+        )
+    if path:
+        endpoints = tuple(
+            endpoint
+            for endpoint in endpoints
+            if path in endpoint.path or matches_path(endpoint.path, path)
+        )
+    if query:
+        endpoints = tuple(endpoint for endpoint in endpoints if _matches_query(endpoint, query))
+    if "free" in args:
+        endpoints = tuple(endpoint for endpoint in endpoints if endpoint.free is bool(args["free"]))
+    if "mpp" in args:
+        endpoints = tuple(
+            endpoint for endpoint in endpoints if (endpoint.mpp is not None) is bool(args["mpp"])
+        )
+    if not include_actions:
+        endpoints = tuple(endpoint for endpoint in endpoints if not endpoint.action)
+    return [endpoint.to_dict() for endpoint in endpoints[:limit]]