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

1. Call Claude Haiku 4.5 via anthropic SDK (ANTHROPIC_API_KEY from .env). Model: claude-haiku-4-5-20251001. Max tokens: 800.
2. 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