Carrel Search skill

---
name: carrel-search
description: "Query the user's local knowledge bases through the Carrel search API, use original text and source images as needed in the answer, list the reference files and offer follow-up directions drawn from the knowledge graph. Use when the user asks to search the knowledge base, find evidence in the stored material, compare records, or answer from several documents together."
---

# Carrel-Search

Evidence is retrieved through Carrel's search service (`app/kb_search`, default port 9810); the agent invoking this skill understands the question, composes the answer, lists the reference files and turns the graph leads into directions the user can ask about next. The service only recalls, reranks and arranges evidence and does no generation. The display name is **Carrel-Search** and the invocation name is `$carrel-search`.

## Invocation

The client is `scripts/carrel_search.py` in this directory (Python 3.9+, standard library only). It defaults to `http://127.0.0.1:9810`; when the service runs on another machine, set the address and token through environment variables or a config file as described in [API and configuration](references/api.md). The skill contains no real token; never read or print one. `SKILL_DIR` stands for the directory containing this `SKILL.md`; replace it with the actual absolute path when executing.

```bash
python3 "$SKILL_DIR/scripts/carrel_search.py" search --question "<the user's question>"
```

- **Every command prints a compact view directly**: retrieval status, the text of the sources (each with the file and place it comes from), facts, page summaries and graph leads, and at the end "Reference files", one line per file. Quality and degradation flags remain visible; IDs, scores and debug fields are left out; document text is not: a hit is printed in full and the chunks before and after it follow it. The script keeps the complete response by itself; do not pass `--output` and do not write scripts of your own to parse it.
- **What does not fit goes to the next page; nothing is cut off**: one output has a size limit, and every page ends by saying what the next page is and how to fetch it (`show <call id> --page 2`). Where it says "read on", read every page before using the result: reading back the original and listings are always like this, and so is a search whose best sources are too long for the first page, which then says so. Where it says "the full text of the other sources, to be read when useful", the next page holds the lower-ranked sources and neighbouring chunks of a search and may be skipped. An entry too long for a page continues on the next one, which opens with the same label and "(continued from the previous page)". To save room, the path of a file is written in full only the first time and "same file as S1" afterwards, and a table header repeated from an earlier chunk reads "HEADER: same as S3". "chunk 26 of 67" at the end of a source line is its position in the document and the document's length in chunks.
- **Every entry has a label**: S a source, F a fact, P a page, E an entity, R a relation, H the neighbourhood of a subject (`H1.2` is its second relation), N a relation returned by a neighbourhood lookup. Later commands point at an entry with `--ref <call id>:<label>` instead of copying IDs or writing request files; only R cannot be used this way: a relation has two ends and is no starting point, so point at the entity entry of one of its ends. The table gives the subcommand and arguments only; each follows the same script:

  | To do this | Subcommand |
  |---|---|
  | Read the original around a chunk | `context --ref a1b2c3:S3` (`--before` / `--after` set how many chunks on each side, 1 by default; read on with `--after` when the matter continues on the following pages). A fact (F) and a neighbourhood relation (N) can be read back the same way |
  | Read a whole document (a whole table, a whole report) | `context --ref a1b2c3:S3 --whole`: one command, printed page by page; a document of more than 300 chunks is read in parts with `--before` / `--after` |
  | See the original picture, crop a part | `image --ref a1b2c3:S6`; `crop --ref a1b2c3:S6 --bbox 0.1,0.2,0.6,0.8`. View the saved file. `crop` only cuts a part out; it is no sharper than the original |
  | Walk one hop along the graph from an entity | `neighbors --ref a1b2c3:H1` (E, `H1.2` and N work the same; `--type` takes one kind of relation only, `--limit` up to 100) |
  | List the facts under an entity | `facts --ref a1b2c3:H1` (add `--property name` for one property) |
  | Search again inside one document | `search --question "…" --in-doc a1b2c3:S3` (S, D, G and F references work; the knowledge base follows the document; with `--kb` given and the document outside it, the command fails) |
  | Look back in time | `search`, `grep`, `neighbors` and `facts` accept `--as-of 2024` (year/month forms use the last day) or `--history` (include superseded, expired and archived records with status flags) |
  | Inspect types and coverage | `catalog` includes graph overviews; use `schema --kb <KB id>` for type inheritance and relation definitions, and `stats --kb <KB id>` for coverage and time spans |
  | See the full text or every field of an entry | `show a1b2c3:S9 a1b2c3:S13` (full text for sources and pages, every field for the rest); `show a1b2c3` prints the compact view of that call again and `show a1b2c3 --page 2` its next page |

- Limit the scope with arguments: `--kb` (repeatable), `--top-k`, `--block-type table` (a soft preference for table lookups). Do not hard-code KB numbers and do not assume every knowledge base has a graph. Send commands that do not depend on each other together in one step instead of waiting for them one by one.
- On a connection failure (DNS, timeout, 401/403) check the address, the service and the token as described in [API and configuration](references/api.md#connection) and tell the user the cause; it does not mean the knowledge base has no content.

## File and phrase navigation

Use `docs --kb ID --name "filename fragment"` when the question names a file or version whose exact path is unknown, or asks for an inventory. `--dir`, `--limit` and `--offset` narrow or page the list. A D reference names a registered document: `search --question "…" --in-doc a1b2c3:D1`. Registration alone does not establish semantic coverage.

Use `grep --kb ID --phrase "term"` to locate an explicit term, identifier or quotation; repeat `--phrase` and use `--in-doc a1b2c3:D1` when the document is known. The default is eight snippets per phrase; adjust `--limit` as needed. Read the relevant G hit with `context --ref a1b2c3:G1`. Phrase counts are analyzer matches, with normalized literal checks on the returned snippets, not exact occurrence counts. No hit is not proof of semantic absence. `--history` and `--as-of` preserve the requested time scope.

These are optional routes for file and phrase questions, not prerequisites for every search. Once a file is located, search within it; use semantic search and graph traversal for meaning, summaries and relationships.

## Answer flow