hermes-pmxt 0.3.0__tar.gz

hermes_pmxt-0.3.0/.github/workflows/workflow.yml

@@ -0,0 +1,95 @@
+name: Build and Publish
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package with dev dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Lint
+        run: python -m ruff check hermes_pmxt/ tests/
+
+      - name: Run unit tests
+        run: python -m pytest -q -m unit --tb=short
+
+      - name: Verify import
+        run: python -c "import hermes_pmxt; print('OK v' + hermes_pmxt.__version__)"
+
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Check distributions
+        run: python -m twine check dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

hermes_pmxt-0.3.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+dist/
+*.egg-info/
+.env

hermes_pmxt-0.3.0/LEARNINGS.md

@@ -0,0 +1,111 @@
+# Learnings -- Building hermes-pmxt v0.3.0
+
+Things discovered during upgrade that differ from docs/research.
+
+## pmxt SDK Realities (v2.50.x)
+
+### Version metadata is inconsistent across sources
+- PyPI: `pmxt 2.50.16`
+- Raw Python pyproject.toml in monorepo: `2.18.0`
+- monorepo package.json: `pmxtjs ^2.17.1`
+- Generated pmxt-mcp tools.ts: `2.50.16` (2026-06-18)
+- **Lesson**: Rely on runtime capability detection, not version strings.
+
+### Dual API hosts
+- `api.pmxt.dev` - reads, Router, MCP, venue passthrough
+- `trade.pmxt.dev` - hosted writes + hosted account state
+- Both authenticate with the same `pmxt_api_key`.
+
+### Python SDK has hosted mode built-in
+- `Exchange.__init__()` accepts `pmxt_api_key`, `wallet_address`, `base_url`
+- Auto-resolves base URL: `PMXT_BASE_URL` → `pmxt_api_key` presence → localhost
+- `build_order` + `submit_order` exist natively in Python SDK >= 2.50
+- `call_api(operation_id, params)` exposes raw OpenAPI endpoints
+
+### Router is NOT a separate Python class
+- Router appears as `exchange="router"` target
+- Router methods: `compareMarketPrices`, `fetchMarketMatches`, `fetchArbitrage`, etc.
+- Available via `pmxt_call("methodName", "router", params={...})`
+
+### server.status() returns a dict, not an object
+- Keys: `running`, `pid`, `port`, `version`, `uptime_seconds`, `lock_file`
+- Must use `.get()` not attribute access.
+
+### fetch_market() (singular) doesn't work by ID
+- `exchange.fetch_market(market_id="701486")` throws `PmxtError: Unknown error`
+- **Workaround**: Use `fetch_markets(query=keyword, limit=N)`.
+
+### outcome_id is Very Long
+- Polymarket outcome_ids are 70+ character token IDs
+- Use labels for display, pass IDs as-is for API calls
+
+## pmxt-mcp Design Patterns Worth Adopting
+
+### Auto-generated tool surface
+- PMXT-MCP generates `src/generated/tools.ts` from OpenAPI + method-verbs.json
+- Auto-runs on every PMXT release via GitHub Actions `sync-mcp.yml`
+- hermes-pmxt should adopt: `scripts/sync_pmxt_registry.py`
+
+### Flat agent-friendly schemas
+- Complex params flattened to top-level MCP tool inputs
+- `ArgSpec` metadata for runtime positional reconstruction
+- `flatten: true` flags merged params for cleaner agent UX
+
+### Safety annotations built into tools
+- `readOnlyHint: true` - safe for repeated calls
+- `destructiveHint: true` - requires confirmation
+- `idempotentHint: true` - safe to retry
+- hermes-pmxt mirrors this in registry.py
+
+### Three config modes: hosted / local / custom
+- `PMXT_API_URL` overrides everything
+- `PMXT_API_KEY` → hosted `api.pmxt.dev`
+- Neither → local `http://localhost:3847`
+- hermes-pmxt mirrors this in config.py
+
+### Compact result shaping
+- `verbose=false` (default): compact agent-friendly output
+- `verbose=true`: raw uncompacted
+- Strips market status when active, truncates descriptions
+- hermes-pmxt mirrors this in shaper.py
+
+### Instructions favor events first
+- pmxt-mcp tells agents: "users say 'market', they mean 'event'"
+- Discovery: fetchEvents → drill to markets → outcomes
+
+## Price Scale
+All prices confirmed as 0.0-1.0 (probabilities). Kalshi internally uses 0-100
+but pmxt normalizes to 0-1 in the Python SDK.
+
+## Trade Timestamps
+All timestamps are Unix milliseconds. Divide by 1000 for Python datetime.
+
+## Kalshi Behavior
+- Returns markets with `before`/`not before` label style
+- Read-only without API keys (local sidecar mode)
+- Search is slower than Polymarket
+
+## hermes-pmxt Architecture Decisions (v0.3.0)
+
+### Lazy import over eager import
+- `exchanges.py` uses `_get_pmxt()` lazy getter
+- Package imports cleanly without pmxt installed
+- Only raises ImportError when pmxt functionality is used
+
+### Generated registry over manual wrappers
+- `registry.py` has ~33 tool definitions with safety annotations
+- `pmxt_call()` dispatches to SDK methods with guard rails
+- Handwritten wrappers for common flows only
+
+### confirmed=True gate for destructive ops
+- `createOrder`, `submitOrder`, `cancelOrder` require `confirmed=True`
+- `_require_confirmed()` returns human-readable error when not confirmed
+
+### Runtime status as first troubleshooting step
+- `pmxt_runtime_status()` shows mode, URL, version, sidecar health
+- Works without pmxt installed
+
+### Exchange list with capability detection
+- 17 known exchanges in registry
+- `pmxt_list_exchanges()` reports which are available in installed build
+- Aliases for common naming variants

hermes_pmxt-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HERMES-PMXT
+
+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_pmxt-0.3.0/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: hermes-pmxt
+Version: 0.3.0
+Summary: Prediction market integration for Hermes Agent -- search, compare, and trade across prediction market exchanges via pmxt
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: pmxt>=2.50.0
+Provides-Extra: dev
+Requires-Dist: pytest-mock>=3.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# hermes-pmxt
+
+Prediction market integration for [Hermes Agent](https://github.com/NousResearch/hermes-agent).
+Search markets, compare prices, detect arbitrage, and trade across prediction market
+exchanges via [pmxt](https://github.com/pmxt-dev/pmxt) (>= 2.50.0).
+
+## What This Is
+
+A Hermes skill + Python toolset that gives any Hermes agent real-time access to prediction
+markets. Instead of hallucinating probabilities, the agent checks actual market prices.
+
+```
+User: "Will Trump win 2028?"
+Agent: *calls pmxt_search + pmxt_quote*
+Agent: "The market implies a 1.9% chance (No: 98.1%). Polymarket is pricing this very low."
+```
+
+## Installation
+
+Install directly with `pip`, matching the one-command style used by Hermes plugins such
+as Mnemosyne. You do not need to clone this repository unless you are developing it.
+
+```bash
+pip install "git+https://github.com/0xharryriddle/hermes-pmxt.git"
+```
+
+For local development from a checkout:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+### Hermes Skill Setup
+
+After installing the package, copy or symlink `skill/SKILL.md` into your Hermes skills
+directory so agents know when and how to use the tools. Example:
+
+```bash
+mkdir -p ~/.hermes/skills/pmxt
+cp skill/SKILL.md ~/.hermes/skills/pmxt/SKILL.md
+```
+
+If your Hermes install supports GitHub-backed skill/plugin installation, point it at
+`https://github.com/0xharryriddle/hermes-pmxt` and enable the `pmxt` skill.
+
+## Modes
+
+hermes-pmxt supports three runtime modes:
+
+| Mode | Config | Behavior |
+|------|--------|----------|
+| **Hosted** | Set `PMXT_API_KEY` | Talks to `https://api.pmxt.dev`. Handles exchange connections, caching, and rate limits automatically. Recommended for most users. |
+| **Custom** | Set `PMXT_API_URL` or `PMXT_BASE_URL` | Points to any PMXT-compatible server. |
+| **Local Sidecar** | No API key/URL set | Assumes PMXT core is running at `http://localhost:3847`. For self-hosting / development. |
+
+Check your current mode:
+```python
+from hermes_pmxt import pmxt_runtime_status
+print(pmxt_runtime_status())
+```
+
+## Quick Start
+
+```python
+from hermes_pmxt import pmxt_search, pmxt_quote, pmxt_runtime_status
+
+# Check status
+print(pmxt_runtime_status())
+
+# Search
+result = pmxt_search("bitcoin", exchange="polymarket", limit=5)
+for m in result["data"]:
+    prices = m.get("outcomes", [])
+    if prices:
+        print(f"{m['title'][:60]}: YES={prices[0]['price']*100:.1f}%")
+
+# Quote
+quote = pmxt_quote("bitcoin reach", exchange="polymarket")
+print(f"YES: {quote['data']['yes_pct']}  NO: {quote['data']['no_pct']}")
+```
+
+## Data Model
+
+```
+  Event (broad topic)
+    └── Market (tradeable question)
+          ├── Outcome "Yes"
+          └── Outcome "No"
+```
+
+When users ask about a topic, start with events (`pmxt_events`), then drill down to
+markets and outcomes.
+
+## Tools
+
+### Discovery & Research
+
+| Function | Auth | Description |
+|----------|------|-------------|
+| `pmxt_search(query, exchange?, limit?, sort?, search_in?, slug?)` | No* | Search markets by keyword |
+| `pmxt_events(query, exchange?, limit?, sort?, search_in?, slug?)` | No* | Search event groups |
+| `pmxt_quote(identifier, exchange)` | No* | Get YES/NO probabilities |
+| `pmxt_order_book(outcome_id, exchange, limit?)` | No* | Order book depth |
+| `pmxt_ohlcv(outcome_id, exchange, resolution?, limit?)` | No* | Price candles |
+| `pmxt_trades(outcome_id, exchange, limit?)` | No* | Recent trades |
+| `pmxt_execution_price(outcome_id, exchange, side, amount)` | No* | Slippage estimate |
+
+### Cross-Venue & Arbitrage
+
+| Function | Auth | Description |
+|----------|------|-------------|
+| `pmxt_compare_market(query, exchanges?, limit?)` | No* | Compare prices across exchanges |
+| `pmxt_arbitrage_scan(query, exchanges?, threshold?)` | No* | Detect arbitrage opportunities |
+| `pmxt_call("compareMarketPrices", "router", ...)` | No* | Native router comparison |
+| `pmxt_call("fetchArbitrage", "router", ...)` | No* | Native arbitrage search |
+| `pmxt_call("fetchHedges", "router", ...)` | No* | Hedging opportunities |
+
+### Portfolio & Account
+
+| Function | Auth | Description |
+|----------|------|-------------|
+| `pmxt_balance(exchange)` | Yes | Account balance |
+| `pmxt_positions(exchange)` | Yes | Open positions |
+| `pmxt_portfolio(exchanges?)` | Yes | Cross-exchange portfolio |
+
+### Trading (All Destructive -- Require Explicit Confirmation)
+
+| Function | Auth | Description |
+|----------|------|-------------|
+| `pmxt_build_order(...)` | Yes | Build/sign order without submitting (SAFE) |
+| `pmxt_submit_order(built, exchange, confirmed=True)` | Yes | Submit a pre-built order |
+| `pmxt_cancel_order(order_id, exchange, confirmed=True)` | Yes | Cancel an open order |
+| `pmxt_order(...)` | Yes | Legacy one-step order (prefer build+submit) |
+
+### Generic API Call
+
+| Function | Auth | Description |
+|----------|------|-------------|
+| `pmxt_call(method, exchange, ...)` | Varies | Generic PMXT API call with safety checks |
+
+### Server & Diagnostics
+
+| Function | Auth | Description |
+|----------|------|-------------|
+| `pmxt_runtime_status()` | No | Full runtime status |
+| `pmxt_list_exchanges()` | No | Known/available exchanges |
+| `pmxt_server_status()` | No | Sidecar diagnostics |
+| `pmxt_server_start()` | No | Start sidecar |
+| `pmxt_server_stop()` | No | Stop sidecar |
+
+\* Read-only tools work without credentials in local sidecar mode. Hosted mode requires `PMXT_API_KEY` for all operations.
+
+## Trading Safety
+
+**Destructive operations (create, submit, cancel orders) require explicit user confirmation.**
+
+```python
+# SAFE: Build order for preview (does NOT place any order)
+built = pmxt_build_order(
+    market_id="market-uuid",
+    outcome="yes",
+    side="buy",
+    order_type="limit",
+    amount=10,
+    price=0.55,
+    exchange="polymarket",
+)
+
+# DESTRUCTIVE: Submit requires confirmed=True
+result = pmxt_submit_order(built, "polymarket", confirmed=True)
+
+# Without confirmed=True:
+result = pmxt_submit_order(built, "polymarket")
+# => {"success": False, "error": "Operation 'submit_order' is destructive..."}
+```
+
+## Supported Exchanges
+
+hermes-pmxt knows about 17 venues including:
+
+- `polymarket` / `polymarket_us`
+- `kalshi` / `kalshi-demo`
+- `limitless`
+- `probable` / `baozi` / `myriad` / `opinion`
+- `metaculus` / `smarkets`
+- `gemini-titan` / `hyperliquid` / `suibets` / `rain`
+- `mock` / `router`
+
+Actual availability depends on the installed `pmxt` build. Run `pmxt_list_exchanges()` to check.
+
+## Environment Variables
+
+```bash
+# Hosted mode (recommended)
+export PMXT_API_KEY="pmxt_live_..."
+export PMXT_WALLET_ADDRESS="0x..."
+export PMXT_PRIVATE_KEY="0x..."
+
+# Custom server
+export PMXT_API_URL="https://your-server.com"
+# or
+export PMXT_BASE_URL="https://your-server.com"
+
+# Venue-specific (self-hosted mode)
+export POLYMARKET_PRIVATE_KEY="0x..."
+export POLYMARKET_PROXY_ADDRESS="0x..."  # Optional
+export KALSHI_API_KEY="..."
+export KALSHI_PRIVATE_KEY="..."
+export LIMITLESS_API_KEY="..."
+export LIMITLESS_PRIVATE_KEY="..."
+export POLYMARKET_US_API_KEY="..."
+export POLYMARKET_US_PRIVATE_KEY="..."
+```
+
+## Project Structure
+
+```
+hermes-pmxt/
+├── hermes_pmxt/
+│   ├── __init__.py          # Public API exports
+│   ├── config.py            # Runtime config and mode detection
+│   ├── exchanges.py         # Exchange initialization + normalization
+│   ├── registry.py          # Tool registry with safety annotations
+│   ├── shaper.py            # Result shaping for LLM context
+│   └── tools.py             # Core tool functions
+├── skill/
+│   └── SKILL.md             # Hermes agent skill instructions
+├── examples/
+│   └── demo.py              # Interactive demo
+├── tests/
+│   ├── conftest.py          # Test path setup
+│   ├── test_exchanges.py    # Exchange wiring unit tests
+│   └── test_tools.py        # Unit + integration tests
+├── pyproject.toml
+└── README.md
+```
+
+## Testing
+
+```bash
+# Unit tests (no pmxt required)
+python3 -m pytest -q -m unit
+
+# All non-destructive tests
+python3 -m pytest -q -m "not trading"
+
+# Integration tests (need pmxt + sidecar/API)
+python3 -m pytest -q -m integration
+```
+
+## License
+
+MIT