diff --git a/Agents.md b/Agents.md index 04b4553..691ca0e 100644 --- a/Agents.md +++ b/Agents.md @@ -309,6 +309,12 @@ of documents that Coyote supports and how to use custom document loaders, refer Anytime your agent starts up, it will automatically be using the RAG you've defined here. +The first time an agent starts with documents attached, Coyote offers to build the knowledge base and asks which +[storage driver](RAG#storage-drivers) to store it with — `yaml` (the default, and what Coyote has always done) or +`duckdb`, which keeps the vectors and text on disk so a large corpus doesn't have to be read back into memory on every +start. The choice is fixed once the knowledge base is built: changing it means removing the agent's built knowledge +base and letting it rebuild, which re-embeds every document. + # 4. Building Tools for Agents Building tools for agents is virtually identical to building custom tools, with one slight difference: instead of defining a single function that gets executed at runtime (e.g. `main` for bash tools and `run` for Python tools), agent @@ -932,4 +938,4 @@ path table and the [official sbx mixin reference](https://docs.docker.com/ai/san installs/domains they bring. Not a bug, just visibility. - **The `sql` agent's `usql` install is in the base kit, not a per-agent mixin.** Same for `pandoc` (used by `fetch_url_via_curl`). Both ship with every Coyote sandbox automatically. See `assets/sbx-kit/spec.yaml` for the - full base prereq list. \ No newline at end of file + full base prereq list. diff --git a/Graph-Agents.md b/Graph-Agents.md index 040e3e9..1b1a561 100644 --- a/Graph-Agents.md +++ b/Graph-Agents.md @@ -591,8 +591,10 @@ base is first built): a `.duckdb` file beside the generated knowledge base. An invalid driver is rejected when the graph is validated, naming the offending node. Like every field in this section it only applies when the knowledge base is *first* built — changing it later has no - effect until the knowledge base is deleted and rebuilt. The `qdrant` driver is not available - here: attaching a remote collection is an interactive flow (`.rag attach`). + effect until the knowledge base is deleted and rebuilt. When the node omits it and the knowledge + base is built interactively, Coyote asks which driver to use; setting it here answers that + question up front. The `qdrant` driver is not available here: attaching a remote collection is an + interactive flow (`.rag attach`). Each falls back to the app-level `rag_*` config when omitted. **When `embedding_model`, `chunk_size`, and `chunk_overlap` are all set, the diff --git a/RAG.md b/RAG.md index 304a02b..654004c 100644 --- a/RAG.md +++ b/RAG.md @@ -130,7 +130,8 @@ actually live: inside the RAG's own file, in a local database beside it, or in a | `duckdb` | A `.duckdb` file beside the RAG | The corpus is large enough that re-loading it into memory on every start is annoying | | `qdrant` | A collection on a Qdrant server you already run | Something else already built and maintains the collection | -Coyote asks which one you want while creating a RAG with `.rag`: +Coyote asks which one you want whenever it builds a knowledge base interactively — creating a RAG with `.rag`, an +[agent](Agents#3-initializing-rag) starting up for the first time, or a [graph agent's](Graph-Agents) `rag` node: ```text ? RAG storage driver: @@ -168,6 +169,12 @@ Two things are worth knowing before you choose it: Deleting the RAG removes the `.duckdb` file and its write-ahead log along with it. +A duckdb RAG is **two files**: the `.yaml` and the `.duckdb` beside it. Copy, move or back up both +together. The YAML deliberately holds no vectors, so a RAG that arrives without its store loads without complaint, +still lists every indexed document, and answers every query with nothing. Coyote warns when it sees that combination — +indexed files, empty store — naming the file it expected. If the store is genuinely gone, `.rebuild rag` re-embeds the +corpus from scratch; `.edit rag-docs` will *not* refill it, because unchanged documents are skipped by hash. + ## qdrant — attaching an existing collection The `qdrant` driver connects a RAG to a collection on a Qdrant server you already run. It is **read-only**: Coyote queries the collection and never writes to it, so whatever populated it stays the sole owner of its contents. This is @@ -200,6 +207,11 @@ A collection has to meet two requirements: Point IDs may be integers or UUIDs; both work. +> **A Qdrant on your own machine or network is contacted directly.** If `HTTP_PROXY` or `HTTPS_PROXY` are set in your +> environment, Coyote still reaches a loopback, private-range or `.local` host without going through the proxy — a +> proxy that has never heard of your local server would otherwise refuse the connection outright. A remote Qdrant +> continues to honour whatever your environment configures. + > **Use the same embedding model that built the collection.** Coyote can't detect a mismatch — the dimensions may line > up perfectly while the vectors mean entirely different things. The symptom is retrieval that returns confident > nonsense, so it's worth checking rather than discovering later.