better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/python-library.md

@@ -0,0 +1,333 @@
+---
+sidebar_position: 5
+title: "Using Hermes as a Python Library"
+description: "Embed AIAgent in your own Python scripts, web apps, or automation pipelines — no CLI required"
+---
+
+# Using Hermes as a Python Library
+
+Hermes isn't just a CLI tool. You can import `AIAgent` directly and use it programmatically in your own Python scripts, web applications, or automation pipelines. This guide shows you how.
+
+---
+
+## Installation
+
+Clone Hermes and create its supported editable development environment:
+
+```bash
+git clone https://github.com/NousResearch/hermes-agent.git
+cd hermes-agent
+uv sync
+```
+
+Run your application with `uv run python your_app.py` from that checkout. Hermes does not publish a supported wheel or source distribution for `requirements.txt` installs.
+
+:::tip
+The same environment variables used by the CLI are required when using Hermes as a library. At minimum, set `OPENROUTER_API_KEY` (or `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` if using direct provider access).
+:::
+
+---
+
+## Basic Usage
+
+The simplest way to use Hermes is the `chat()` method — pass a message, get a string back:
+
+```python
+from run_agent import AIAgent
+
+agent = AIAgent(
+    model="anthropic/claude-sonnet-4.6",
+    quiet_mode=True,
+)
+response = agent.chat("What is the capital of France?")
+print(response)
+```
+
+`chat()` handles the full conversation loop internally — tool calls, retries, everything — and returns just the final text response.
+
+:::warning
+Always set `quiet_mode=True` when embedding Hermes in your own code. Without it, the agent prints CLI spinners, progress indicators, and other terminal output that will clutter your application's output.
+:::
+
+---
+
+## Full Conversation Control
+
+For more control over the conversation, use `run_conversation()` directly. It returns a dictionary with the full response, message history, and metadata:
+
+```python
+agent = AIAgent(
+    model="anthropic/claude-sonnet-4.6",
+    quiet_mode=True,
+)
+
+result = agent.run_conversation(
+    user_message="Search for recent Python 3.13 features",
+    task_id="my-task-1",
+)
+
+print(result["final_response"])
+print(f"Messages exchanged: {len(result['messages'])}")
+```
+
+The returned dictionary contains:
+- **`final_response`** — The agent's final text reply
+- **`messages`** — The complete message history (system, user, assistant, tool calls)
+
+(The `task_id` you pass in is stored on the agent instance for VM isolation but isn't echoed back in the return dict.)
+
+You can also pass a custom system message that overrides the ephemeral system prompt for that call:
+
+```python
+result = agent.run_conversation(
+    user_message="Explain quicksort",
+    system_message="You are a computer science tutor. Use simple analogies.",
+)
+```
+
+---
+
+## Configuring Tools
+
+Control which toolsets the agent has access to using `enabled_toolsets` or `disabled_toolsets`:
+
+```python
+# Only enable web tools (browsing, search)
+agent = AIAgent(
+    model="anthropic/claude-sonnet-4.6",
+    enabled_toolsets=["web"],
+    quiet_mode=True,
+)
+
+# Enable everything except terminal access
+agent = AIAgent(
+    model="anthropic/claude-sonnet-4.6",
+    disabled_toolsets=["terminal"],
+    quiet_mode=True,
+)
+```
+
+:::tip
+Use `enabled_toolsets` when you want a minimal, locked-down agent (e.g., only web search for a research bot). Use `disabled_toolsets` when you want most capabilities but need to restrict specific ones (e.g., no terminal access in a shared environment).
+:::
+
+---
+
+## Multi-turn Conversations
+
+Maintain conversation state across multiple turns by passing the message history back in:
+
+```python
+agent = AIAgent(
+    model="anthropic/claude-sonnet-4.6",
+    quiet_mode=True,
+)
+
+# First turn
+result1 = agent.run_conversation("My name is Alice")
+history = result1["messages"]
+
+# Second turn — agent remembers the context
+result2 = agent.run_conversation(
+    "What's my name?",
+    conversation_history=history,
+)
+print(result2["final_response"])  # "Your name is Alice."
+```
+
+The `conversation_history` parameter accepts the `messages` list from a previous result. The agent copies it internally, so your original list is never mutated.
+
+---
+
+## Saving Trajectories
+
+Enable trajectory saving to capture conversations in ShareGPT format — useful for generating training data or debugging:
+
+```python
+agent = AIAgent(
+    model="anthropic/claude-sonnet-4.6",
+    save_trajectories=True,
+    quiet_mode=True,
+)
+
+agent.chat("Write a Python function to sort a list")
+# Saves to trajectory_samples.jsonl in ShareGPT format
+```
+
+Each conversation is appended as a single JSONL line, making it easy to collect datasets from automated runs.
+
+---
+
+## Custom System Prompts
+
+Use `ephemeral_system_prompt` to set a custom system prompt that guides the agent's behavior but is **not** saved to trajectory files (keeping your training data clean):
+
+```python
+agent = AIAgent(
+    model="anthropic/claude-sonnet-4",
+    ephemeral_system_prompt="You are a SQL expert. Only answer database questions.",
+    quiet_mode=True,
+)
+
+response = agent.chat("How do I write a JOIN query?")
+print(response)
+```
+
+This is ideal for building specialized agents — a code reviewer, a documentation writer, a SQL assistant — all using the same underlying tooling.
+
+---
+
+## Batch Processing
+
+For running many prompts in parallel, Hermes includes `batch_runner.py`. It manages concurrent `AIAgent` instances with proper resource isolation:
+
+```bash
+python batch_runner.py --input prompts.jsonl --output results.jsonl
+```
+
+Each prompt gets its own `task_id` and isolated environment. If you need custom batch logic, you can build your own using `AIAgent` directly:
+
+```python
+import concurrent.futures
+from run_agent import AIAgent
+
+prompts = [
+    "Explain recursion",
+    "What is a hash table?",
+    "How does garbage collection work?",
+]
+
+def process_prompt(prompt):
+    # Create a fresh agent per task for thread safety
+    agent = AIAgent(
+        model="anthropic/claude-sonnet-4",
+        quiet_mode=True,
+        skip_memory=True,
+    )
+    return agent.chat(prompt)
+
+with concurrent.futures.ThreadPoolExecutor(max_workers=3) as executor:
+    results = list(executor.map(process_prompt, prompts))
+
+for prompt, result in zip(prompts, results):
+    print(f"Q: {prompt}\nA: {result}\n")
+```
+
+:::warning
+Always create a **new `AIAgent` instance per thread or task**. The agent maintains internal state (conversation history, tool sessions, iteration counters) that is not thread-safe to share.
+:::
+
+---
+
+## Integration Examples
+
+### FastAPI Endpoint
+
+```python
+from fastapi import FastAPI
+from pydantic import BaseModel
+from run_agent import AIAgent
+
+app = FastAPI()
+
+class ChatRequest(BaseModel):
+    message: str
+    model: str = "anthropic/claude-sonnet-4"
+
+@app.post("/chat")
+async def chat(request: ChatRequest):
+    agent = AIAgent(
+        model=request.model,
+        quiet_mode=True,
+        skip_context_files=True,
+        skip_memory=True,
+    )
+    response = agent.chat(request.message)
+    return {"response": response}
+```
+
+### Discord Bot
+
+```python
+import discord
+from run_agent import AIAgent
+
+client = discord.Client(intents=discord.Intents.default())
+
+@client.event
+async def on_message(message):
+    if message.author == client.user:
+        return
+    if message.content.startswith("!hermes "):
+        query = message.content[8:]
+        agent = AIAgent(
+            model="anthropic/claude-sonnet-4",
+            quiet_mode=True,
+            skip_context_files=True,
+            skip_memory=True,
+            platform="discord",
+        )
+        response = agent.chat(query)
+        await message.channel.send(response[:2000])
+
+client.run("YOUR_DISCORD_TOKEN")
+```
+
+### CI/CD Pipeline Step
+
+```python
+#!/usr/bin/env python3
+"""CI step: auto-review a PR diff."""
+import subprocess
+from run_agent import AIAgent
+
+diff = subprocess.check_output(["git", "diff", "main...HEAD"]).decode()
+
+agent = AIAgent(
+    model="anthropic/claude-sonnet-4",
+    quiet_mode=True,
+    skip_context_files=True,
+    skip_memory=True,
+    disabled_toolsets=["terminal", "browser"],
+)
+
+review = agent.chat(
+    f"Review this PR diff for bugs, security issues, and style problems:\n\n{diff}"
+)
+print(review)
+```
+
+---
+
+## Key Constructor Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `model` | `str` | `""` | Model in OpenRouter format (defaults to empty; resolved from your hermes config at runtime) |
+| `quiet_mode` | `bool` | `False` | Suppress CLI output |
+| `enabled_toolsets` | `List[str]` | `None` | Whitelist specific toolsets |
+| `disabled_toolsets` | `List[str]` | `None` | Blacklist specific toolsets |
+| `save_trajectories` | `bool` | `False` | Save conversations to JSONL |
+| `ephemeral_system_prompt` | `str` | `None` | Custom system prompt (not saved to trajectories) |
+| `max_iterations` | `int` | `500` | Max tool-calling iterations per conversation |
+| `skip_context_files` | `bool` | `False` | Skip loading AGENTS.md files |
+| `skip_memory` | `bool` | `False` | Disable persistent memory read/write |
+| `api_key` | `str` | `None` | API key (falls back to env vars) |
+| `base_url` | `str` | `None` | Custom API endpoint URL |
+| `platform` | `str` | `None` | Platform hint (`"discord"`, `"telegram"`, etc.) |
+
+---
+
+## Important Notes
+
+:::tip
+- Set **`skip_context_files=True`** if you don't want `AGENTS.md` files from the working directory loaded into the system prompt.
+- Set **`skip_memory=True`** to prevent the agent from reading or writing persistent memory — recommended for stateless API endpoints.
+- The `platform` parameter (e.g., `"discord"`, `"telegram"`) injects platform-specific formatting hints so the agent adapts its output style.
+:::
+
+:::warning
+- **Thread safety**: Create one `AIAgent` per thread or task. Never share an instance across concurrent calls.
+- **Resource cleanup**: The agent automatically cleans up resources (terminal sessions, browser instances) when a conversation ends. If you're running in a long-lived process, ensure each conversation completes normally.
+- **Iteration limits**: The default `max_iterations=500` is generous. For simple Q&A use cases, consider lowering it (e.g., `max_iterations=10`) to prevent runaway tool-calling loops and control costs.
+:::

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/run-hermes-with-nous-portal.md

@@ -0,0 +1,276 @@
+---
+sidebar_position: 1
+title: "Run Hermes Agent with Nous Portal"
+description: "Start-to-finish walkthrough: subscribe, set up, switch models, enable gateway tools, and verify routing"
+---
+
+# Run Hermes Agent with Nous Portal
+
+This guide walks you through running Hermes Agent on a [Nous Portal](https://portal.nousresearch.com) subscription end to end — from signing up to verifying that every tool routes correctly. If you just want the overview of what the Portal is and what's in the subscription, see the [Nous Portal integration page](/integrations/nous-portal). This page is the task script.
+
+## Prerequisites
+
+- Hermes Agent installed ([Quickstart](/getting-started/quickstart))
+- A web browser on the machine you're setting up (or SSH port forwarding — see [OAuth over SSH](/guides/oauth-over-ssh))
+- About 5 minutes
+
+You do **not** need: an OpenAI key, an Anthropic key, a Firecrawl account, a FAL account, a Browser Use account, or any other per-vendor credential. That's the whole point.
+
+## 1. Get a subscription
+
+Open [portal.nousresearch.com/manage-subscription](https://portal.nousresearch.com/manage-subscription), sign up, and pick a plan.
+
+Already subscribed? Skip to step 2.
+
+## 2. Run the one-shot setup
+
+```bash
+hermes setup --portal
+```
+
+This single command does five things:
+
+1. Opens your browser to portal.nousresearch.com for OAuth login
+2. Stores the refresh token at `~/.hermes/auth.json`
+3. Sets `model.provider: nous` in `~/.hermes/config.yaml`
+4. Picks a default agentic model (`anthropic/claude-sonnet-4.6` or similar)
+5. Turns on the Tool Gateway for web search, image generation, TTS, and browser automation
+
+When it finishes, you're back at your terminal ready to chat.
+
+### What if I'm SSH'd into a server?
+
+OAuth needs a browser, but the loopback callback runs on the machine where Hermes is running. Two options:
+
+```bash
+# Option A: SSH port forwarding (preferred)
+ssh -N -L 8642:127.0.0.1:8642 user@remote-host    # in a local terminal
+hermes setup --portal                              # on the remote, open the printed URL in your local browser
+
+# Option B: device-code login (works from Cloud Shell, Codespaces, EC2 Instance Connect)
+hermes auth add nous --type oauth
+# Then re-run `hermes setup --portal` to wire the provider + gateway
+```
+
+See [OAuth over SSH / Remote Hosts](/guides/oauth-over-ssh) for the full walkthrough including ProxyJump chains, mosh/tmux, and ControlMaster gotchas.
+
+## 3. Verify it worked
+
+```bash
+hermes portal info
+```
+
+You should see:
+
+```
+  Nous Portal
+  ───────────
+  Auth:    ✓ logged in
+  Portal:  https://portal.nousresearch.com
+  Model:   ✓ using Nous as inference provider
+
+  Tool Gateway
+  ────────────
+  Web search & extract  via Nous Portal
+  Image generation      via Nous Portal
+  Text-to-speech        via Nous Portal
+  Browser automation    via Nous Portal
+```
+
+If any line shows something other than "via Nous Portal" or the auth line says "not logged in", jump to [Troubleshooting](#troubleshooting) below.
+
+## 4. Run your first conversation
+
+```bash
+hermes chat
+```
+
+Try something that exercises both the model and the Tool Gateway:
+
+```
+Hey, search the web for "Hermes Agent release notes" and summarize the top 3 hits.
+```
+
+You should see Hermes call `web_search` (Firecrawl-backed, through the gateway) and respond with a summary. If the search runs and the response makes sense, you're done — the Portal is wired up end to end.
+
+## 5. Pick the model you actually want
+
+`hermes setup --portal` lets you pick a model during setup, but the whole point of the subscription is access to the full catalog — switch any time with `/model` mid-session:
+
+```bash
+/model anthropic/claude-sonnet-4.6     # best general-purpose agentic
+/model openai/gpt-5.4                  # strong reasoning + tool calling
+/model google/gemini-2.5-pro           # huge context window
+/model deepseek/deepseek-v3.2          # cost-effective coder
+/model anthropic/claude-opus-4.6       # heavyweight for hard problems
+```
+
+Or pop the picker to browse:
+
+```bash
+/model
+```
+
+Pick a different default permanently:
+
+```bash
+# in your terminal, outside any session
+hermes config set model.default anthropic/claude-sonnet-4.6
+```
+
+### Don't pick Hermes-4 for agent work
+
+Hermes-4-70B and Hermes-4-405B are available on the Portal at deep discounts, but they're **chat/reasoning models**, not tool-call-tuned. They will struggle with multi-step agent loops. Use them for conversation/research work through the [subscription proxy](/user-guide/features/subscription-proxy) from non-agent tools. For Hermes Agent itself, stick to the frontier agentic models above.
+
+The Portal's own [info page](https://portal.nousresearch.com/info) carries this warning too — it's the official Nous guidance, not just a Hermes-side opinion.
+
+## 6. (Optional) Customize Tool Gateway routing
+
+The gateway is opt-in per tool, not all-or-nothing. If you already have a Browserbase account and want to keep using it while routing web search and image generation through Nous, that's supported:
+
+```bash
+hermes tools
+# → Web search       → "Nous Subscription"     (recommended)
+# → Image generation → "Nous Subscription"     (recommended)
+# → Browser          → "Browserbase"           (your existing key)
+# → TTS              → "Nous Subscription"     (recommended)
+```
+
+These rows appear in `hermes tools` even before you've logged into Nous Portal — if you pick "Nous Subscription" without an active session, Hermes runs the Portal login inline (without changing your inference provider or your other tools).
+
+Verify your mix with:
+
+```bash
+hermes portal tools
+```
+
+You'll see per-tool routing — `via Nous Portal` for the ones routed through the subscription, and the partner name (`browserbase`, `firecrawl`, etc.) for the ones using your own keys.
+
+## 7. (Optional) Enable voice mode
+
+Because the Tool Gateway includes OpenAI TTS, [voice mode](/user-guide/features/voice-mode) works without a separate OpenAI key:
+
+```bash
+hermes setup tts
+# → pick "Nous Subscription" for TTS
+# → pick a speech-to-text backend (local faster-whisper is free, no setup)
+```
+
+Then in any messaging-platform session (Telegram, Discord, Signal, etc.), send a voice message and Hermes will transcribe it, respond, and reply with synthesized voice — all on your Portal subscription.
+
+## 8. (Optional) Cron + always-on workflows
+
+The Portal subscription works for [cron jobs](/user-guide/features/cron) and [batch processing](/user-guide/features/batch-processing) the same way it works for interactive chat — the OAuth refresh token is reused automatically. No additional setup; just schedule cron jobs and they'll bill against your subscription.
+
+```bash
+hermes cron create "0 9 * * *" \
+  "Search the web for top AI news and summarize the 5 most important stories" \
+  --name "Daily AI news"
+```
+
+The cron job runs unattended, calls the model + web search + summarization all through your Portal subscription.
+
+## Profiles and multi-user setups
+
+If you use [Hermes profiles](/user-guide/profiles) (e.g. a separate config per project), the Portal refresh token is automatically shared across all profiles via a shared token store. Sign in once on any profile, and the rest pick it up automatically.
+
+For team setups where multiple humans share a machine, each human has their own Portal account → each home directory holds its own `~/.hermes/auth.json` → no token sharing across users. This is the right boundary.
+
+## Troubleshooting
+
+### `hermes portal info` shows "not logged in" after `hermes setup --portal`
+
+The OAuth flow didn't complete. Re-run it:
+
+```bash
+hermes portal
+```
+
+If your browser doesn't open or the callback fails, you're likely on a remote/headless host — see [OAuth over SSH](/guides/oauth-over-ssh) for the port-forwarding workarounds.
+
+### "Model: currently openrouter" (or some other provider) instead of "using Nous as inference provider"
+
+Your local config drifted. The OAuth worked but `model.provider` is still pointing at a different provider. Fix:
+
+```bash
+hermes config set model.provider nous
+```
+
+Or interactively:
+
+```bash
+hermes model
+# pick Nous Portal
+```
+
+Re-verify with `hermes portal info`.
+
+### Tool Gateway tools showing partner names instead of "via Nous Portal"
+
+Per-tool config is overriding the gateway. Run:
+
+```bash
+hermes tools
+# pick "Nous Subscription" for any tool you want gateway-routed
+```
+
+Some users intentionally mix — e.g. routing web through Nous but using their own Browserbase key for browser. If that's intentional, leave it alone. If not, this command fixes it.
+
+### "Re-authentication required" mid-session
+
+Your Portal refresh token was invalidated (password change, manual revoke, session expiry). The token is now quarantined locally so Hermes doesn't replay it endlessly. Just log in again:
+
+```bash
+hermes auth add nous
+```
+
+The quarantine clears automatically on successful re-login.
+
+### Model I want isn't in the `/model` picker
+
+The Portal catalog draws on OpenRouter's model list (300+) plus models served through proprietary or secondary providers. If a model is missing, try typing the OpenRouter-style slug directly:
+
+```bash
+/model anthropic/claude-opus-4.6
+/model openai/o1-2025-12-17
+```
+
+If a model is genuinely unavailable, [open an issue](https://github.com/NousResearch/hermes-agent/issues) — most gaps are routing config we can update.
+
+### Billing not appearing on my Portal account
+
+`hermes portal info` will tell you whether you're actually routing through the Portal or some other provider. Common causes:
+
+- `model.provider` set to `openrouter`/`anthropic`/etc. instead of `nous`
+- An OAuth refresh failure that fell back to a different configured provider
+- Multiple Hermes profiles where you're using the wrong one (check `hermes profile list`)
+
+### Want to revoke and start clean
+
+```bash
+hermes auth logout nous       # wipes the local refresh token
+# Then re-run setup or remove the subscription from the Portal web UI
+```
+
+## What this gets you, in plain numbers
+
+| Without Portal | With Portal |
+|----------------|-------------|
+| 1× OpenRouter / Anthropic / OpenAI key in `.env` | 1× OAuth refresh token, no `.env` keys |
+| 1× Firecrawl key for web | Web routed through gateway |
+| 1× FAL key for image gen | Image gen routed through gateway |
+| 1× Browser Use / Browserbase key for browser | Browser routed through gateway |
+| 1× OpenAI key for TTS / voice mode | TTS routed through gateway |
+| 5 separate dashboards, top-ups, invoices | 1 subscription, 1 invoice |
+| Cross-machine: replicate all 5 keys | Cross-machine: re-OAuth once |
+
+That's the deal. If you're using more than two of those backends anyway, the subscription pays for itself.
+
+## See also
+
+- **[Nous Portal integration page](/integrations/nous-portal)** — Overview of what's in the subscription
+- **[Tool Gateway](/user-guide/features/tool-gateway)** — Full details on every gateway-routed tool
+- **[Subscription proxy](/user-guide/features/subscription-proxy)** — Use your Portal subscription from non-Hermes tools
+- **[Voice mode](/user-guide/features/voice-mode)** — Set up voice conversations on the Portal subscription
+- **[OAuth over SSH](/guides/oauth-over-ssh)** — Remote / headless login patterns
+- **[Profiles](/user-guide/profiles)** — Share one Portal login across multiple Hermes configurations