---
name: evolution-foundation/knowledge-query
source: https://app.decimal.ai/s/evolution-foundation-knowledge-query@1/SKILL.md
source_sha256: 474b971f3651
---

# 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