knowledge-query

# knowledge-query Group: **Consumption**. Hybrid search on pgvector + optional RAG (LLM synthesis with citations). ## When to trigger - "What do we know about X?" - "Search the knowledge base for Y" - "@knowledge <query>" - Any factual question that should be grounded in indexed documents ## Arguments | Name | Type | Default | Description | |---|---|---|---| | `query` | str | required | Natural language question | | `connection` | str | first `ready` | Connection slug (e.g., "academy", "acme") | | `space` | str | null = all | Space slug within the connection | | `top_k` | int | 5 | How many snippets to return | | `filters` | dict | {} | `{unit_id, content_type, topics, date_range}` | | `answer` | bool | false | If true, synthesize narrative answer with citations | ## Workflow ### Step 1 — Identify active connection If `connection` is not provided, call `GET /api/knowledge/connections?status=ready` and use the first one. If none ready: return actionable error: "No Knowledge connection configured. Run `knowledge-admin action=connect` first." ### Step 2 — Hybrid search ```python from dashboard.backend.sdk_client import evo hits = evo.post( "/api/knowledge/v1/search", {"query": query, "space": space, "top_k": top_k, "filters": filters}, headers={"X-Knowledge-Connection": connection}, ) ``` Response: list of `{chunk_id, content, document_id, title, content_type, similarity_score, metadata: {page, section, heading_path}}`. ### Step 3a — Format snippets (if `answer=false`) For each hit: ``` **[{content_type}]** {title} — p.{metadata.page or "?"} > {content[:300]}... Score: {similarity_score:.3f} ``` Separate with `---`. ### Step 3b — RAG synthesis (if `answer=true`) 1. Take top-5 snippets 2. Build prompt: ``` You are a factual assistant. Answer ONLY using the sources below. Cite each fact with [source:page] right after the claim. If sources don't cover the question: "The knowledge base contains no information on this." ### Question {query} ### Sources [1] {title_1} (p.{page_1}): {content_1} [2] {title_2} (p.{page_2}): {content_2} ... ### Answer ``` 3. Call Claude Haiku 4.5 via `anthropic` SDK (`ANTHROPIC_API_KEY` from `.env`). Model: `claude-haiku-4-5-20251001`. Max tokens: 800. 4. Render response + sources block at the end. ## Output - `answer=false`: markdown list of snippets with scores - `answer=true`: narrative answer + sources - Always: footer `Searched {N} chunks in {connection}/{space or "all"} in {elapsed_ms}ms` ## Actionable failures - Connection not found → "Connection `X` does not exist. Run `knowledge-admin action=health`." - Space not found → list available spaces - 0 hits → suggest relaxing filters - `ANTHROPIC_API_KEY` missing with `answer=true` → fallback to raw snippets + warning