better-dsh 0.2.5 → 0.3.0-c

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

@@ -1,333 +0,0 @@
----
-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

@@ -1,276 +0,0 @@
----
-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