diff --git a/bankr-router/SKILL.md b/bankr-router/SKILL.md new file mode 100644 index 00000000..be6a24a5 --- /dev/null +++ b/bankr-router/SKILL.md @@ -0,0 +1,280 @@ +--- +name: bankr-router +description: Local smart routing layer for Bankr LLM Gateway traffic. Use when explaining or installing Bankr Router, switching auto/eco/premium profiles, configuring OpenClaw providers, verifying routing, or debugging router/Bankr model issues. +repository: https://github.com/tachikomared/bankr-router +--- + +# Bankr Router (OpenClaw plugin skill) + +## Summary +Bankr Router is a **local smart router** that sits in front of the **Bankr LLM Gateway**. You can find the source code and latest releases here: [https://github.com/tachikomared/bankr-router](https://github.com/tachikomared/bankr-router) + +It does **not** replace Bankr. It chooses **which model/profile to use** before requests go to Bankr, then forwards the request upstream. + +**Benefits:** +- Lower cost by default (route simpler prompts to cheaper models). +- Better fallback behavior and retries. +- Local control over routing policy. +- Clear visibility into planned vs final vs upstream model selection. +- Easy profile switching: **auto / eco / premium**. + +--- + +## When to use +- You want cheaper default routing without changing app code. +- You want a local routing layer in front of Bankr. +- You need retries/fallbacks + observability. +- You want predictable behavior for **auto / eco / premium** modes. +- You prefer local plugin control over hosted routing. + +--- + +## What this skill can help with +Use this skill to: +- Explain what Bankr Router is and why it matters. +- Explain tradeoffs between auto / eco / premium. +- Install the plugin locally. +- Configure OpenClaw provider entries. +- Verify the router is active. +- Switch routing modes. +- Troubleshoot common errors. +- Identify when agent overrides bypass the router. +- Explain stats/health endpoints. +- Explain **dry-run vs real execution** (`/v1/route` vs `/v1/chat/completions`). + +--- + +## Prerequisites +- Node.js (20+ recommended) +- OpenClaw installed and running +- Bankr provider configured via: + ```bash + bankr llm setup openclaw --install + ``` +- Local repo path may differ from examples +- OpenClaw config path may differ (common: `~/.openclaw/openclaw.json`) + +--- + +## Install (step-by-step) + +### 1) Build the plugin +```bash +cd /path/to/openclawbankrrouter +npm install +npm run build +``` + +### 2) Add plugin entry to OpenClaw config +Edit your OpenClaw config (commonly `~/.openclaw/openclaw.json`): + +```json +{ + "plugins": { + "load": { + "paths": ["/path/to/openclawbankrrouter"] + }, + "entries": { + "bankr-router": { + "enabled": true, + "config": { + "host": "127.0.0.1", + "port": 8787, + "openclawConfigPath": null, + "bankrProviderId": "bankr", + "routerProviderId": "bankr-router" + } + } + } + } +} +``` + +### 3) Add the router provider to models.providers +```json +{ + "models": { + "providers": { + "bankr-router": { + "baseUrl": "http://127.0.0.1:8787/v1", + "apiKey": "local-router" + } + } + } +} +``` + +### 4) Set default agent model to the router +```json +{ + "agents": { + "defaults": { + "model": { + "primary": "bankr-router/auto", + "fallbacks": ["bankr-router/eco"] + } + } + } +} +``` + +### 5) Restart the gateway +```bash +openclaw gateway restart +``` + +--- + +## Verify +Run these exact checks: + +### Health check +```bash +curl http://127.0.0.1:8787/health +``` + +### Ensure models exist +```bash +openclaw models list | grep bankr-router +``` + +### Dry-run routing (no real upstream call) +```bash +curl http://127.0.0.1:8787/v1/route \ + -H "content-type: application/json" \ + -d '{"model":"bankr-router/auto","messages":[{"role":"user","content":"say ok"}]}' +``` + +### Real execution (upstream call) +```bash +curl http://127.0.0.1:8787/v1/chat/completions \ + -H "content-type: application/json" \ + -d '{"model":"bankr-router/auto","messages":[{"role":"user","content":"say ok"}]}' +``` + +--- + +## Mode switching +**auto** = balanced smart routing (default) +**eco** = cheapest practical routing +**premium** = highest quality routing + +### Switch default model (OpenClaw config) +```json +{ + "agents": { + "defaults": { + "model": { + "primary": "bankr-router/eco", + "fallbacks": ["bankr-router/auto"] + } + } + } +} +``` +Restart gateway after changing defaults: +```bash +openclaw gateway restart +``` + +--- + +## How to explain this to a user (agent-ready) +Use these short explanations: + +**What is Bankr Router?** +> It’s a local routing layer in front of Bankr that picks the right model before the request goes upstream. + +**Why do I need it?** +> It lowers cost, improves fallback behavior, and gives you local control over model selection. + +**When should I use eco?** +> Use eco when cost is the top priority and you’re fine with “good enough” quality. + +**Does this replace Bankr?** +> No. Bankr Router only routes requests; Bankr still runs the models. + +**Does this make inference free?** +> No. It only reduces cost by routing simpler prompts to cheaper models. + +**What does the skill do for me?** +> It installs, configures, verifies, and explains the router + its modes and debugging steps. + +--- + +## Troubleshooting + +### Unknown model `bankr-router/auto` +- Ensure `models.providers.bankr-router` exists. +- Ensure agent allowlists (if any) include `bankr-router/*`. +- Restart the gateway after config change. + +### Plugin not loaded +- Verify the repo path is in `plugins.load.paths`. +- Ensure `plugins.entries.bankr-router.enabled = true`. +- Rebuild: `npm run build`. + +### Port already in use +- Router default port is **8787**. Change `plugins.entries.bankr-router.config.port` or stop the conflicting process. + +### Gateway restart loop +- Check config JSON is valid. +- Check `openclawConfigPath` if auto-discovery fails. + +### Requests bypass router +- An agent or tool may be **overriding its model**. +- Check `agents.defaults.model` and per-agent `model` overrides. + +### Planned vs final model confusion +- **plannedModel** = initial route decision +- **finalModel** = model that actually succeeded +- **upstreamModel** = model returned by Bankr + +### Streaming issues +- Test non-stream first (`/v1/chat/completions` without `stream=true`). +- Ensure router and gateway are on the same machine or low-latency network. + +### Wrong OpenClaw config path +Set explicit path: +```json +{ + "plugins": { + "entries": { + "bankr-router": { + "config": { + "openclawConfigPath": "/absolute/path/to/openclaw.json" + } + } + } + } +} +``` + +### Bankr provider missing +- Run: `bankr llm setup openclaw --install` +- Ensure `models.providers.bankr` exists and has an API key. + +### Model exists in `/v1/route` but not in `/v1/chat/completions` +- `/v1/route` is dry-run only. Real execution requires valid Bankr credentials. + +--- + +## Useful commands (ops) +```bash +# build +npm run build + +# restart gateway +openclaw gateway restart + +# router health +curl http://127.0.0.1:8787/health + +# router stats/diagnostics (if enabled) +curl http://127.0.0.1:8787/v1/diagnostics + +# list models +openclaw models list | grep bankr-router + +# tail gateway logs +journalctl --user -u openclaw-gateway.service -n 50 --no-pager diff --git a/pretext-layout/SKILL.md b/pretext-layout/SKILL.md new file mode 100644 index 00000000..fe7aeac6 --- /dev/null +++ b/pretext-layout/SKILL.md @@ -0,0 +1,78 @@ +--- +name: "pretext-layout" +description: "Integrate, debug, or prototype @chenglou/pretext for browser-based multiline text measurement and manual line layout. Use when replacing DOM height probes, building text-aware virtualization or custom canvas/SVG flows, wiring width plus line-height measurement into frontend code, or diagnosing accuracy issues involving fonts, white-space, emoji, bidi text, and browser-only runtime constraints." +version: "1.0.0" +repository: "https://github.com/tachikomared/pretext-agents-skill" +metadata: + openclaw: + requires: + bins: + - "bash" + - "node" + - "npm" + - "python3" +--- + + +# Pretext Layout + +## Overview + +Use Pretext to measure multiline text in browser environments without paying repeated DOM reflow costs in the hot path. Prefer it when text width changes often and you need stable height or per-line geometry from cached measurements. + +**Source & Discovery:** +- Repository: [https://github.com/tachikomared/pretext-agents-skill](https://github.com/tachikomared/pretext-agents-skill) +- Verified Skill: [https://clawhub.ai/tachikomared/pretext-agents-skill](https://clawhub.ai/tachikomared/pretext-agents-skill) + + +## Workflow + +1. Confirm the runtime first. + - Treat Pretext as browser-first. + - If the task is pure Node or CLI with no `OffscreenCanvas` and no `document`, do not promise direct runtime support. +2. Match the API to the job. + - Use `prepare()` plus `layout()` for height and line-count measurement. + - Use `prepareWithSegments()` plus `layoutWithLines()`, `walkLineRanges()`, or `layoutNextLine()` for custom rendering. +3. Sync layout inputs with real styles. + - Read `font` and `line-height` from the target element or design token source. + - Wait for `document.fonts.ready` before trusting measurements when web fonts are involved. +4. Cache aggressively. + - Prepare once per `(text, font, whiteSpace, locale)` input. + - Reuse the prepared handle across width changes. +5. Verify against the real UI when accuracy matters. + - Compare a few representative strings against live DOM heights. + - Include multilingual, emoji, and narrow-width cases if the feature depends on them. + +## Decision Guide + +- Reach for `prepare()` plus `layout()` when the user needs block height, resize performance, virtualization, scroll anchoring, or pre-measuring text before render. +- Reach for `prepareWithSegments()` plus rich line APIs when the user needs custom line drawing, canvas text, SVG text, shrink-wrap width discovery, or variable line widths. +- Reach for ordinary DOM measurement instead when the task depends on CSS behaviors Pretext does not aim to cover fully. + +## Core Rules + +- Do not claim server-side support unless the target environment actually provides a compatible canvas context. +- Keep `font` and `lineHeight` aligned with the real UI; measurement errors usually come from mismatched inputs, not from the layout call itself. +- Avoid `system-ui` for accuracy-sensitive flows on macOS; prefer named fonts. +- Treat `prepare()` as the expensive step and `layout()` as the hot path. +- When working with textarea-like content, pass `{ whiteSpace: 'pre-wrap' }` explicitly. + +## Implementation Checklist + +- Identify the exact text source, target width source, font source, and line-height source. +- Decide whether the feature only needs height or also needs per-line data. +- Cache prepared handles instead of calling `prepare()` on every resize. +- Add a small verification path that compares Pretext output with live DOM for representative samples. +- Document any unsupported CSS or runtime assumptions close to the integration point. + +## Scripts + +- Run `scripts/scaffold_browser_demo.py --out