better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/github-pr-review-agent.md

@@ -0,0 +1,303 @@
+---
+sidebar_position: 10
+title: "Tutorial: GitHub PR Review Agent"
+description: "Build an automated AI code reviewer that monitors your repos, reviews pull requests, and delivers feedback — hands-free"
+---
+
+# Tutorial: Build a GitHub PR Review Agent
+
+**The problem:** Your team opens PRs faster than you can review them. PRs sit for days waiting for eyeballs. Junior devs merge bugs because nobody had time to check. You spend your mornings catching up on diffs instead of building.
+
+**The solution:** An AI agent that watches your repos around the clock, reviews every new PR for bugs, security issues, and code quality, and sends you a summary — so you only spend time on PRs that actually need human judgment.
+
+**What you'll build:**
+
+```
+┌───────────────────────────────────────────────────────────────────┐
+│                                                                   │
+│   Cron Timer  ──▶  Hermes Agent  ──▶  GitHub API  ──▶  Review     │
+│   (every 2h)       + gh CLI           (PR diffs)       delivery   │
+│                    + skill                             (Telegram, │
+│                    + memory                            Discord,   │
+│                                                        local)     │
+│                                                                   │
+└───────────────────────────────────────────────────────────────────┘
+```
+
+This guide uses **cron jobs** to poll for PRs on a schedule — no server or public endpoint needed. Works behind NAT and firewalls.
+
+:::tip Want real-time reviews instead?
+If you have a public endpoint available, check out [Automated GitHub PR Comments with Webhooks](./webhook-github-pr-review.md) — GitHub pushes events to Hermes instantly when PRs are opened or updated.
+:::
+
+---
+
+## Prerequisites
+
+- **Hermes Agent installed** — see the [Installation guide](/getting-started/installation)
+- **Gateway running** for cron jobs:
+  ```bash
+  hermes gateway install   # Install as a service
+  # or
+  hermes gateway           # Run in foreground
+  ```
+- **GitHub CLI (`gh`) installed and authenticated**:
+  ```bash
+  # Install
+  brew install gh        # macOS
+  sudo apt install gh    # Ubuntu/Debian
+
+  # Authenticate
+  gh auth login
+  ```
+- **Messaging configured** (optional) — [Telegram](/user-guide/messaging/telegram) or [Discord](/user-guide/messaging/discord)
+
+:::tip No messaging? No problem
+Use `deliver: "local"` to save reviews to `~/.hermes/cron/output/`. Great for testing before wiring up notifications.
+:::
+
+---
+
+## Step 1: Verify the Setup
+
+Make sure Hermes can access GitHub. Start a chat:
+
+```bash
+hermes
+```
+
+Test with a simple command:
+
+```
+Run: gh pr list --repo NousResearch/hermes-agent --state open --limit 3
+```
+
+You should see a list of open PRs. If this works, you're ready.
+
+---
+
+## Step 2: Try a Manual Review
+
+Still in the chat, ask Hermes to review a real PR:
+
+```
+Review this pull request. Read the diff, check for bugs, security issues,
+and code quality. Be specific about line numbers and quote problematic code.
+
+Run: gh pr diff 3888 --repo NousResearch/hermes-agent
+```
+
+Hermes will:
+1. Execute `gh pr diff` to fetch the code changes
+2. Read through the entire diff
+3. Produce a structured review with specific findings
+
+If you're happy with the quality, time to automate it.
+
+---
+
+## Step 3: Create a Review Skill
+
+A skill gives Hermes consistent review guidelines that persist across sessions and cron runs. Without one, review quality varies.
+
+```bash
+mkdir -p ~/.hermes/skills/code-review
+```
+
+Create `~/.hermes/skills/code-review/SKILL.md`:
+
+```markdown
+---
+name: code-review
+description: Review pull requests for bugs, security issues, and code quality
+---
+
+# Code Review Guidelines
+
+When reviewing a pull request:
+
+## What to Check
+1. **Bugs** — Logic errors, off-by-one, null/undefined handling
+2. **Security** — Injection, auth bypass, secrets in code, SSRF
+3. **Performance** — N+1 queries, unbounded loops, memory leaks
+4. **Style** — Naming conventions, dead code, missing error handling
+5. **Tests** — Are changes tested? Do tests cover edge cases?
+
+## Output Format
+For each finding:
+- **File:Line** — exact location
+- **Severity** — Critical / Warning / Suggestion
+- **What's wrong** — one sentence
+- **Fix** — how to fix it
+
+## Rules
+- Be specific. Quote the problematic code.
+- Don't flag style nitpicks unless they affect readability.
+- If the PR looks good, say so. Don't invent problems.
+- End with: APPROVE / REQUEST_CHANGES / COMMENT
+```
+
+Verify it loaded — start `hermes` and you should see `code-review` in the skills list at startup.
+
+---
+
+## Step 4: Teach It Your Conventions
+
+This is what makes the reviewer actually useful. Start a session and teach Hermes your team's standards:
+
+```
+Remember: In our backend repo, we use Python with FastAPI.
+All endpoints must have type annotations and Pydantic models.
+We don't allow raw SQL — only SQLAlchemy ORM.
+Test files go in tests/ and must use pytest fixtures.
+```
+
+```
+Remember: In our frontend repo, we use TypeScript with React.
+No `any` types allowed. All components must have props interfaces.
+We use React Query for data fetching, never useEffect for API calls.
+```
+
+These memories persist forever — the reviewer will enforce your conventions without being told each time.
+
+---
+
+## Step 5: Create the Automated Cron Job
+
+Now wire it all together. Create a cron job that runs every 2 hours:
+
+```bash
+hermes cron create "0 */2 * * *" \
+  "Check for new open PRs and review them.
+
+Repos to monitor:
+- myorg/backend-api
+- myorg/frontend-app
+
+Steps:
+1. Run: gh pr list --repo REPO --state open --limit 5 --json number,title,author,createdAt
+2. For each PR created or updated in the last 4 hours:
+   - Run: gh pr diff NUMBER --repo REPO
+   - Review the diff using the code-review guidelines
+3. Format output as:
+
+## PR Reviews — today
+
+### [repo] #[number]: [title]
+**Author:** [name] | **Verdict:** APPROVE/REQUEST_CHANGES/COMMENT
+[findings]
+
+If no new PRs found, say: No new PRs to review." \
+  --name "pr-review" \
+  --deliver telegram \
+  --skill code-review
+```
+
+Verify it's scheduled:
+
+```bash
+hermes cron list
+```
+
+### Other useful schedules
+
+| Schedule | When |
+|----------|------|
+| `0 */2 * * *` | Every 2 hours |
+| `0 9,13,17 * * 1-5` | Three times a day, weekdays only |
+| `0 9 * * 1` | Weekly Monday morning roundup |
+| `30m` | Every 30 minutes (high-traffic repos) |
+
+---
+
+## Step 6: Run It On Demand
+
+Don't want to wait for the schedule? Trigger it manually:
+
+```bash
+hermes cron run pr-review
+```
+
+Or from within a chat session:
+
+```
+/cron run pr-review
+```
+
+---
+
+## Going Further
+
+### Post Reviews Directly to GitHub
+
+Instead of delivering to Telegram, have the agent comment on the PR itself:
+
+Add this to your cron prompt:
+
+```
+After reviewing, post your review:
+- For issues: gh pr review NUMBER --repo REPO --comment --body "YOUR_REVIEW"
+- For critical issues: gh pr review NUMBER --repo REPO --request-changes --body "YOUR_REVIEW"
+- For clean PRs: gh pr review NUMBER --repo REPO --approve --body "Looks good"
+```
+
+:::caution
+Make sure `gh` has a token with `repo` scope. Reviews are posted as whoever `gh` is authenticated as.
+:::
+
+### Weekly PR Dashboard
+
+Create a Monday morning overview of all your repos:
+
+```bash
+hermes cron create "0 9 * * 1" \
+  "Generate a weekly PR dashboard:
+- myorg/backend-api
+- myorg/frontend-app
+- myorg/infra
+
+For each repo show:
+1. Open PR count and oldest PR age
+2. PRs merged this week
+3. Stale PRs (older than 5 days)
+4. PRs with no reviewer assigned
+
+Format as a clean summary." \
+  --name "weekly-dashboard" \
+  --deliver telegram
+```
+
+### Multi-Repo Monitoring
+
+Scale up by adding more repos to the prompt. The agent processes them sequentially — no extra setup needed.
+
+---
+
+## Troubleshooting
+
+### "gh: command not found"
+The gateway runs in a minimal environment. Ensure `gh` is in the system PATH and restart the gateway.
+
+### Reviews are too generic
+1. Add the `code-review` skill (Step 3)
+2. Teach Hermes your conventions via memory (Step 4)
+3. The more context it has about your stack, the better the reviews
+
+### Cron job doesn't run
+```bash
+hermes gateway status    # Is the gateway running?
+hermes cron list         # Is the job enabled?
+```
+
+### Rate limits
+GitHub allows 5,000 API requests/hour for authenticated users. Each PR review uses ~3-5 requests (list + diff + optional comments). Even reviewing 100 PRs/day stays well within limits.
+
+---
+
+## What's Next?
+
+- **[Webhook-Based PR Reviews](./webhook-github-pr-review.md)** — get instant reviews when PRs are opened (requires a public endpoint)
+- **[Daily Briefing Bot](/guides/daily-briefing-bot)** — combine PR reviews with your morning news digest
+- **[Build a Plugin](/developer-guide/plugins)** — wrap the review logic into a shareable plugin
+- **[Profiles](/user-guide/profiles)** — run a dedicated reviewer profile with its own memory and config
+- **[Fallback Providers](/user-guide/features/fallback-providers)** — ensure reviews run even when one provider is down

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/google-gemini.md

@@ -0,0 +1,270 @@
+---
+sidebar_position: 16
+title: "Google Gemini"
+description: "Use Hermes Agent with Google Gemini — native AI Studio API, API-key setup, tool calling, streaming, and quota guidance"
+---
+
+# Google Gemini
+
+Hermes Agent supports Google Gemini as a native provider using the **Google AI Studio / Gemini API** — not the OpenAI-compatible endpoint. This lets Hermes translate its internal OpenAI-shaped message and tool loop into Gemini's native `generateContent` API while preserving tool calling, streaming, multimodal inputs, and Gemini-specific response metadata.
+
+## Prerequisites
+
+- **Google AI Studio API key** — create one at [aistudio.google.com/apikey](https://aistudio.google.com/apikey)
+- **Billing-enabled Google Cloud project** — recommended for agent use. Gemini's free tier is too small for long-running agent sessions because Hermes may make several model calls per user turn.
+- **Hermes installed** — no extra Python package is required for the native Gemini provider.
+
+:::tip API key path
+Set `GOOGLE_API_KEY` or `GEMINI_API_KEY`. Hermes checks both names for the `gemini` provider.
+:::
+
+## Quick Start
+
+```bash
+# Add your Gemini API key
+echo "GOOGLE_API_KEY=..." >> ~/.hermes/.env
+
+# Select Gemini as your provider
+hermes model
+# → Choose "More providers..." → "Google AI Studio"
+# → Hermes checks your key tier and shows Gemini models
+# → Select a model
+
+# Start chatting
+hermes chat
+```
+
+If you prefer direct config editing, use the native Gemini API base URL:
+
+```yaml
+model:
+  default: gemini-3.7-flash
+  provider: gemini
+  base_url: https://generativelanguage.googleapis.com/v1beta
+```
+
+## Configuration
+
+After running `hermes model`, your `~/.hermes/config.yaml` will contain:
+
+```yaml
+model:
+  default: gemini-3.7-flash
+  provider: gemini
+  base_url: https://generativelanguage.googleapis.com/v1beta
+```
+
+And in `~/.hermes/.env`:
+
+```bash
+GOOGLE_API_KEY=...
+```
+
+### Native Gemini API
+
+The recommended endpoint is:
+
+```text
+https://generativelanguage.googleapis.com/v1beta
+```
+
+Hermes detects this endpoint and creates its native Gemini adapter. Internally, Hermes still keeps the agent loop in OpenAI-shaped messages, then translates each request to Gemini's native schema:
+
+- `messages[]` → Gemini `contents[]`
+- system prompts → Gemini `systemInstruction`
+- tool schemas → Gemini `functionDeclarations`
+- tool results → Gemini `functionResponse` parts
+- streaming responses → OpenAI-shaped stream chunks for the Hermes loop
+
+Tool parameter type arrays such as `"type": ["number", "null"]` are translated
+into Gemini's scalar type plus `nullable` form. Multi-type unions keep every
+alternative through `anyOf`, including nested properties and array items. This
+happens automatically; no MCP server or provider configuration change is needed.
+
+:::note Gemini 3 thought signatures
+For Gemini 3 tool use, Hermes preserves the `thoughtSignature` values attached to function-call parts and replays them on the next tool turn. That covers the validation-critical path for multi-step agent workflows.
+
+Gemini 3 may also attach thought signatures to other response parts. Hermes' native adapter is optimized for agent tool loops today, so it does not yet replay every non-tool-call signature with full part-level fidelity.
+:::
+
+### Prefer the Native Endpoint
+
+Google also exposes an OpenAI-compatible endpoint:
+
+```text
+https://generativelanguage.googleapis.com/v1beta/openai/
+```
+
+For Hermes agent sessions, prefer the native Gemini endpoint above. Hermes includes a native Gemini adapter so it can map multi-turn tool use, tool-call results, streaming, multimodal inputs, and Gemini response metadata directly onto Gemini's `generateContent` API. The OpenAI-compatible endpoint is still useful when you specifically need OpenAI API compatibility.
+
+If you previously set `GEMINI_BASE_URL` to the `/openai` URL, remove it or change it:
+
+```bash
+GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta
+```
+
+Host-root base URLs on the Google host are normalized automatically: if the URL
+doesn't end with an API version segment (`v1beta`, `v1alpha`, `v1`, ...), Hermes
+appends `/v1beta` for you, so `GEMINI_BASE_URL=https://generativelanguage.googleapis.com`
+works the same as spelling out the `/v1beta` suffix. The same normalization
+applies to the Gemini TTS base URL (`tts.gemini.base_url`). Chat requests only
+take the native Gemini path when the base URL points at
+`generativelanguage.googleapis.com`; a proxy on another host is treated as an
+OpenAI-compatible endpoint, so configure it with its `/openai`-style URL.
+
+## Available Models
+
+The `hermes model` picker shows Gemini models maintained in Hermes' provider registry. Common choices include:
+
+| Model | ID | Notes |
+|-------|----|-------|
+| Gemini 3.8 Flash | `gemini-3.8-flash` | Most capable Flash model for long-horizon agentic and coding work |
+| Gemini 3.7 Flash | `gemini-3.7-flash` | Recommended default balance of speed, capability, and multimodal understanding |
+| Gemini 3.1 Pro Preview | `gemini-3.1-pro-preview` | Most capable reasoning, math, and coding model |
+| Gemini 3.5 Flash Lite | `gemini-3.5-flash-lite` | Fastest and lowest-cost option for lightweight tasks |
+| Gemini 2.5 Flash | `gemini-2.5-flash` | Previous generation fast model with thinking capabilities |
+| Gemini 2.5 Pro | `gemini-2.5-pro` | Previous generation complex reasoning model |
+
+Model availability changes over time. If a model disappears or is not enabled for your key, run `hermes model` again and pick one from the current list.
+
+:::info Model IDs
+Use Gemini's native model IDs such as `gemini-3.7-flash`, not OpenRouter-style IDs like `google/gemini-3.7-flash`, when `provider: gemini`.
+:::
+
+### Latest Aliases
+
+Google publishes moving aliases for the Pro and Flash Gemini families. `gemini-pro-latest` and `gemini-flash-latest` are useful when you want Google to advance the model automatically without changing your Hermes config. Note that your usage charges may be affected if newer models introduce different rates.
+
+| Alias | Currently tracks | Notes |
+|-------|------------------|-------|
+| `gemini-pro-latest` | Latest Gemini Pro model | Best when you want Google's current Pro default |
+| `gemini-flash-latest` | Latest Gemini Flash model | Best when you want Google's current Flash default |
+
+```yaml
+model:
+  default: gemini-pro-latest
+  provider: gemini
+  base_url: https://generativelanguage.googleapis.com/v1beta
+```
+
+If you need strict reproducibility, prefer explicit model IDs such as `gemini-3.1-pro-preview` or `gemini-3.7-flash`.
+
+### Gemma via the Gemini API
+
+Google also exposes Gemma models through the Gemini API. Hermes recognizes these as Google models, but hides very low-throughput Gemma entries from the default model picker so new users do not accidentally select an evaluation-tier model for a long-running agent session.
+
+Useful evaluation IDs include:
+
+| Model | ID | Notes |
+|-------|----|-------|
+| Gemma 4 31B IT | `gemma-4-31b-it` | Larger Gemma model; useful for compatibility and quality evaluation |
+| Gemma 4 26B A4B IT | `gemma-4-26b-a4b-it` | Smaller active-parameter variant when available |
+
+These models are best treated as evaluation options on Gemini API keys. Google's Gemma API pricing is free-tier-only and the usage caps are low compared with production Gemini models, so sustained Hermes agent use should normally move to a paid Gemini model, a self-hosted deployment, or another provider with appropriate quota.
+
+To use a Gemma model that is hidden from the picker, set it directly:
+
+```yaml
+model:
+  default: gemma-4-31b-it
+  provider: gemini
+  base_url: https://generativelanguage.googleapis.com/v1beta
+```
+
+## Switching Models Mid-Session
+
+Use the `/model` command during a conversation:
+
+```text
+/model gemini-3.7-flash
+/model gemini-flash-latest
+/model gemini-3.1-pro-preview
+/model gemini-pro-latest
+/model gemma-4-31b-it
+/model gemini-3.1-flash-lite-preview
+```
+
+If you have not configured Gemini yet, exit the session and run `hermes model` first. `/model` switches among already-configured providers and models; it does not collect new API keys.
+
+## Diagnostics
+
+```bash
+hermes doctor
+```
+
+The doctor checks:
+
+- Whether `GOOGLE_API_KEY` or `GEMINI_API_KEY` is available
+- Whether configured provider credentials can be resolved
+
+## Gateway (Messaging Platforms)
+
+Gemini works with all Hermes gateway platforms (Telegram, Discord, Slack, WhatsApp, LINE, Feishu, etc.). Configure Gemini as your provider, then start the gateway normally:
+
+```bash
+hermes gateway setup
+hermes gateway start
+```
+
+The gateway reads `config.yaml` and uses the same Gemini provider configuration.
+
+## Troubleshooting
+
+### "Gemini native client requires an API key"
+
+Hermes could not find a usable API key. Add one of these to `~/.hermes/.env`:
+
+```bash
+GOOGLE_API_KEY=...
+# or
+GEMINI_API_KEY=...
+```
+
+Then run `hermes model` again.
+
+### "This Google API key is on the free tier"
+
+Hermes probes Gemini API keys during setup. Free-tier quotas can be exhausted after a handful of agent turns because tool use, retries, compression, and auxiliary tasks may require multiple model calls.
+
+Enable billing on the Google Cloud project attached to your key, regenerate the key if needed, then run:
+
+```bash
+hermes model
+```
+
+### "404 model not found"
+
+The selected model is not available for your account, region, or key. Run `hermes model` again and pick another Gemini model from the current list.
+
+### Gemma model is not shown in `hermes model`
+
+Hermes may hide low-throughput Gemma models from the picker by default. If you intentionally want to evaluate one, set the model ID directly in `~/.hermes/config.yaml`.
+
+### "429 quota exceeded" on Gemma
+
+Gemma models exposed through the Gemini API are useful for evaluation, but their Gemini API free-tier caps are low. Use them for compatibility testing, then switch to a paid Gemini model or another provider for sustained agent sessions.
+
+### OpenAI-compatible endpoint is configured
+
+Check `~/.hermes/.env` for:
+
+```bash
+GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/
+```
+
+Change it to the native endpoint or remove the override:
+
+```bash
+GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta
+```
+
+### Tool calling fails with schema errors
+
+Upgrade Hermes and rerun `hermes model`. The native Gemini adapter sanitizes tool schemas for Gemini's stricter function-declaration format; older builds or custom endpoints may not.
+
+## Related
+
+- [AI Providers](/integrations/providers)
+- [Configuration](/user-guide/configuration)
+- [Fallback Providers](/user-guide/features/fallback-providers)
+- [AWS Bedrock](/guides/aws-bedrock) — native cloud-provider integration using AWS credentials