feat(skills): integrate web-search, db-yaml, agent-cost, diataxis-docs, kb-search; retire searxng
This commit is contained in:
Andriy Oblivantsev
Symlink
+1
@@ -0,0 +1 @@
|
||||
/mnt/8TB/projects/ai/agent-skills/bin/db/psql-yq
|
||||
Symlink
+1
@@ -0,0 +1 @@
|
||||
/mnt/8TB/projects/ai/agent-skills/bin/web/search
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
name: agent-cost
|
||||
description: >-
|
||||
Measure what an agent session actually costs in tokens using bin/agents/cost.
|
||||
Use before and after changing documentation, skills or context layout, and when
|
||||
a session feels unexpectedly expensive.
|
||||
---
|
||||
|
||||
# agent-cost
|
||||
|
||||
```bash
|
||||
bin/agents/cost # every project, YAML
|
||||
bin/agents/cost --repo brain-ui # only sessions whose cwd matches
|
||||
bin/agents/cost --json | jq .cursor.by_tool
|
||||
bin/agents/cost --snapshot after-x --repo brain-ui # append a row to docs/CONTEXT-BUDGET.md
|
||||
```
|
||||
|
||||
Reads local session storage from OpenCode and Cursor transcripts. Reports the
|
||||
always-loaded baseline, cache hit/miss/thrash, and which tools moved the most
|
||||
bytes.
|
||||
|
||||
## How to read it
|
||||
|
||||
- **Baseline** is what every single message pays for: `AGENTS.md` plus anything
|
||||
eagerly linked from it. Keep it small; it multiplies by message count.
|
||||
- **Cache thrash** matters more than raw size. Editing a file that sits early in
|
||||
the context invalidates the prompt cache for the whole session.
|
||||
- **by_tool bytes** shows where the real spend is. Usually it is unfiltered
|
||||
command output, not documentation.
|
||||
|
||||
## Rule
|
||||
|
||||
Measure before and after. A claim that something "reduces tokens" without a
|
||||
before and an after number is an opinion, not a result.
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
name: db-yaml
|
||||
description: >-
|
||||
Read any Postgres as compact YAML through db/psql-yq, with a read-only guard and
|
||||
named profiles. Use when a task needs table contents, column types or a SELECT
|
||||
against cs_brain or another project database.
|
||||
---
|
||||
|
||||
# db-yaml
|
||||
|
||||
`agent-skills/bin/db/psql-yq` talks to Postgres and returns YAML, which is far
|
||||
cheaper than a psql ASCII table and easy to slice with `yq`.
|
||||
|
||||
```bash
|
||||
bin/db/offline -s kunde # column list (brain-ui wrapper)
|
||||
bin/db/offline -t tour -l 20 # 20 sample rows as YAML
|
||||
bin/db/offline -c 'SELECT ...' # query -> YAML
|
||||
bin/db/live -c 'SELECT ...' # live database instead of the snapshot
|
||||
```
|
||||
|
||||
Ad-hoc targets without a profile:
|
||||
|
||||
```bash
|
||||
agent-skills/bin/db/psql-yq --container my-pg --db app -c 'SELECT 1'
|
||||
agent-skills/bin/db/psql-yq --dsn 'postgres://user@host:5432/db' -c 'SELECT 1'
|
||||
```
|
||||
|
||||
## Profiles
|
||||
|
||||
Connection details live in `~/.config/brain/db-profiles.yml` (mode 600), never in a
|
||||
project repo. A profile names either a `container` or a `host`; passwords are read
|
||||
from a separate `password_env_file` and never appear in argv.
|
||||
|
||||
## Rules
|
||||
|
||||
- **Read-only.** Any `insert|update|delete|drop|truncate|alter|create|grant|
|
||||
revoke|vacuum|copy` is rejected with exit 3. Do not work around it.
|
||||
- **PII.** `cs_brain` holds client data. Aggregate and count freely; never copy
|
||||
names or addresses into chat, issues or docs.
|
||||
- Use `-l` to keep samples small. Twenty rows answer most questions.
|
||||
@@ -0,0 +1,55 @@
|
||||
---
|
||||
name: diataxis-docs
|
||||
description: >-
|
||||
Classify and structure documentation by Diataxis (tutorial, howto, reference,
|
||||
explanation) with PARA status, using frontmatter that the knowledge-base index
|
||||
reads. Use when creating a document, when one file tries to do two jobs, or when
|
||||
auditing a docs folder.
|
||||
---
|
||||
|
||||
# diataxis-docs
|
||||
|
||||
Every markdown file answers exactly one of four questions. A file that answers
|
||||
two should be split; that is the whole method.
|
||||
|
||||
| Type | Answers | Reader is |
|
||||
|------|---------|-----------|
|
||||
| `tutorial` | "teach me by doing" | learning |
|
||||
| `howto` | "help me do this task" | working |
|
||||
| `reference` | "tell me the facts" | looking up |
|
||||
| `explanation` | "help me understand why" | studying |
|
||||
|
||||
## Frontmatter
|
||||
|
||||
```yaml
|
||||
---
|
||||
type: reference # one of the four above
|
||||
status: current # current | archive (PARA)
|
||||
related:
|
||||
- docs/OPS.md
|
||||
---
|
||||
```
|
||||
|
||||
`bin/kb/index` reads this. `type` becomes a searchable column and `related`
|
||||
becomes a graph edge:
|
||||
|
||||
```bash
|
||||
bin/kb/search search "deploy" --type howto
|
||||
bin/kb/search search "Stecktafel" --hop 1 # follow links and related
|
||||
```
|
||||
|
||||
## Audit checklist
|
||||
|
||||
1. Does the title match the type? A reference that starts "first, open..." is a
|
||||
howto wearing a disguise.
|
||||
2. More than one H2 topic that a reader would search separately? Split the file.
|
||||
The indexer chunks on H2, so split files also search better.
|
||||
3. Is `status: archive` set on anything superseded? Archived files stay indexed
|
||||
but stop competing with current ones for a reader's attention.
|
||||
4. Does every explanation link the reference it explains, and vice versa? That
|
||||
link is what `--hop 1` walks.
|
||||
|
||||
## Rule
|
||||
|
||||
Do not invent a fifth type. If a document does not fit, it is usually two
|
||||
documents.
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
name: kb-search
|
||||
description: >-
|
||||
Deduction search over the 2dph brain (Ladybug graph: ops corpus, portfolio,
|
||||
ssh hosts) with bin/kb/search instead of reading files or grepping repos.
|
||||
Use whenever a question starts with "where is", "what runs on", "which file
|
||||
describes", "who is", "how is X done", before opening any documentation.
|
||||
---
|
||||
|
||||
# kb-search — deduction over facts and info
|
||||
|
||||
One embedded Ladybug graph (`var/kb.lbug`, read-only when queried) holding two
|
||||
roots:
|
||||
|
||||
- **facts** — assertions backed by ≥2 independent sources (docker ps × compose
|
||||
× ssh-config × docs), `confidence: confirmed`.
|
||||
- **info** — descriptive/narrative leafs, searchable, never asserted.
|
||||
|
||||
Search = deduction: facts root first, info root second, `web-search` as the
|
||||
second independent source when local roots cannot confirm. An answer is
|
||||
`confirmed` only if it comes off the facts root; anything else is
|
||||
`(not confirmed)`.
|
||||
|
||||
```bash
|
||||
bin/kb/search "Matrix federation" # pointers + snippets, YAML
|
||||
bin/kb/search "what runs on arc-2" --hop 1 # follow graph edges
|
||||
bin/kb/search "onlyoffice postgres" --root facts # restrict to confirmed
|
||||
bin/kb/search "where is cs-lexicon" --json | yq '.[].ref'
|
||||
bin/kb/get <id> --body # full chunk only when needed
|
||||
bin/kb/stats # index health
|
||||
bin/kb/eval # recall@5 >= 0.95 gate
|
||||
```
|
||||
|
||||
## Rules
|
||||
|
||||
- Search before you read. Never grep a repo for a concept the graph covers.
|
||||
- `--root facts` returns only confirmed evidence-linked answers. Default shows
|
||||
facts first, then info leafs clearly marked `(not confirmed)`.
|
||||
- If recall looks wrong, run `bin/kb/eval`; it gates control questions and
|
||||
should stay at or above 95% recall@5.
|
||||
- `--hop N` follows sibling leaves, owning files, `related:` links and
|
||||
vector-neighbours — that is the deduction walk, not random expansion.
|
||||
- Escalate to `web-search` (the `web-search` skill) as the independent second
|
||||
source when both local roots cannot confirm; never report an unconfirmed
|
||||
single-source local answer as fact.
|
||||
@@ -0,0 +1,51 @@
|
||||
---
|
||||
name: web-search
|
||||
description: >-
|
||||
Search the public web through the self-hosted SearXNG at search.ops.io
|
||||
using bin/web/search. Use for German care law, SGB paragraphs, vendor
|
||||
documentation and any fact that is not in our own repos - and as the second
|
||||
independent source the detective method requires.
|
||||
---
|
||||
|
||||
# web-search
|
||||
|
||||
```bash
|
||||
bin/web/search "Pflegegrad SGB XI Einstufung"
|
||||
bin/web/search "Toureffizienz" --site ticket.detective.de
|
||||
bin/web/search "sqlite-vec" --category it -n 3 --json | jq -r '.results[].url'
|
||||
bin/web/search "Pflegereform" --lang de --fresh year
|
||||
```
|
||||
|
||||
## Web or knowledge base
|
||||
|
||||
`bin/kb/search` holds our own facts: product docs, detective business logic, the
|
||||
lexicon. Go there first. Reach for `bin/web/search` when the answer is outside
|
||||
our repos: legislation, vendor documentation, upstream library behaviour.
|
||||
|
||||
Keep the two apart. A finding is stronger when the reader can see that one
|
||||
source was ours and one was not.
|
||||
|
||||
## PII: this query leaves the host
|
||||
|
||||
The search goes to external engines. Never put a client or staff identifier in
|
||||
it. The tool refuses long digit runs, `Personalnummer`, `KV-Nr`, dates of birth
|
||||
and street-with-number, and exits 2. Rephrase rather than reaching for `--force`.
|
||||
|
||||
## Read the status, not just the results
|
||||
|
||||
The instance answers HTTP 200 with an empty list when it throttles, so an empty
|
||||
answer is ambiguous by construction. The tool resolves that for you:
|
||||
|
||||
| status | exit | meaning |
|
||||
|--------|------|---------|
|
||||
| `ok` | 0 | engines answered |
|
||||
| `throttled` | 3 | nobody answered; say nothing about what exists |
|
||||
|
||||
Never turn a `throttled` result into "there is no information about X".
|
||||
|
||||
## Etiquette
|
||||
|
||||
Calls are serialised host-wide and kept ten seconds apart, and answers are
|
||||
cached for seven days. Do not loop over queries, and do not use `--refresh`
|
||||
unless the cached answer is genuinely stale: a burst suspends the engines for
|
||||
several minutes for everyone.
|
||||
@@ -0,0 +1,67 @@
|
||||
---
|
||||
type: howto
|
||||
status: current
|
||||
---
|
||||
|
||||
# Tuning the SearXNG instance
|
||||
|
||||
The client works around a fragile instance. These changes fix the cause, and
|
||||
they need shell access to the host behind `search.ops.io`
|
||||
(`90.169.228.16` / `ops.mywire.org`), which is a different machine from
|
||||
the one the agents run on.
|
||||
|
||||
## Why it is needed
|
||||
|
||||
Measured on 2026-08-10 from this host:
|
||||
|
||||
- The default engine set for the `general` category is only `duckduckgo`,
|
||||
`brave` and `startpage`. `brave` and `startpage` sit in
|
||||
`Suspended: too many requests` or `Suspended: CAPTCHA` almost permanently, so
|
||||
in practice a single engine carries every query.
|
||||
- About 25 probe requests over a few minutes pushed `duckduckgo` into `CAPTCHA`
|
||||
as well. The instance then answered HTTP 200 with `results: []` and an empty
|
||||
`unresponsive_engines` - indistinguishable from "nothing found" without the
|
||||
client-side handling we added.
|
||||
- Recovery took roughly six minutes.
|
||||
|
||||
## Changes
|
||||
|
||||
1. **Allow our egress IP through the limiter.** In `limiter.toml`:
|
||||
|
||||
```toml
|
||||
[botdetection.ip_lists]
|
||||
pass_ip = ["77.7.46.234"]
|
||||
```
|
||||
|
||||
2. **Shorten the suspensions.** In `settings.yml` the defaults are 24 hours for
|
||||
a CAPTCHA and one hour for too-many-requests, which is far longer than the
|
||||
condition lasts:
|
||||
|
||||
```yaml
|
||||
search:
|
||||
suspended_times:
|
||||
SearxEngineCaptcha: 300
|
||||
SearxEngineTooManyRequests: 120
|
||||
SearxEngineAccessDenied: 300
|
||||
```
|
||||
|
||||
3. **Give `general` more than one working engine.** `google` and `wikipedia`
|
||||
report `enabled: true` in `/config` yet never appear in a `general` response,
|
||||
so they are not in the default set. Put them in it; one live engine per
|
||||
category is a single point of failure.
|
||||
|
||||
4. **Keep the JSON API on.** `formats: [html, json]` must stay, otherwise every
|
||||
client here breaks.
|
||||
|
||||
## Verifying
|
||||
|
||||
Ten requests in a row used to suspend the instance for minutes. After the
|
||||
change they should all answer:
|
||||
|
||||
```bash
|
||||
for i in $(seq 10); do
|
||||
bin/web/search "test $i" -n 1 --refresh --json | jq -r .status
|
||||
done
|
||||
```
|
||||
|
||||
Ten lines of `ok` means it is fixed.
|
||||
Reference in New Issue
Block a user