Spedo Guide — Documentation Assistant V1

Since version v0.57.0

Spedo Guide is a local, citation-first documentation assistant. It operates without external calls to third-party cloud providers. V1 retrieves relevant technical excerpts from the bundled public documentation, displays authoritative sources, and renders structured markdown with syntax-highlighted code blocks.

1. Running Locally & Web Bottom Dock

make assistant
# Open standalone: http://127.0.0.1:8091

Dockable Interactive Bottom Bar (Enhanced in v0.57.0)

On the Web Documentation and Public Portal (http://localhost:8090/), Spedo Guide is integrated as a sleek, non-intrusive dockable bottom bar (⌘J / Ctrl+J to toggle). When expanded:

• Users can ask technical questions without leaving their reading flow.
• Citations provide direct deep links (#maturity, #live-vars, #vector-search, etc.) that smoothly scroll to the referenced section on the page and highlight it with a golden glow while keeping the assistant drawer open.
• State is preserved across page navigations within the session.

2. Public Portal Integration (Opt-in)

The assistant widget is available on the public portal. To enable the background assistant proxy service:

SPEDO_PORTAL_ASSISTANT_ENABLED=true \
  docker compose --profile assistant up --build -d portal assistant

The browser communicates with the portal via same-origin endpoints (/api/assistant/*). The portal forwards queries exclusively to the configured internal URL SPEDO_PORTAL_ASSISTANT_URL (default: http://assistant:8091). It rejects any client-supplied target URLs. If the variable is unset or false, the assistant widget and endpoints remain inactive.

In the user interface, pressing Enter submits the query, while Shift+Enter inserts a newline. Responses are deliberately concise, structured, and strictly limited to cited public documentation.

3. Scope & Personas

Spedo Guide provides answers verified against reviewed documentation, cites specific reference files, and never misrepresents a preview API as an authoritative HA or multi-master clustering guarantee.

Indexed sources are restricted to validated public guides. Internal scratch notes, administrative data, production logs, secrets, and unpublished internal code are never indexed.

4. Privacy & Zero-Tracking Guarantee

Spedo Guide operates strictly under a zero-tracking, privacy-first model:

• 100% Local Inference & Search: All document chunk indexing, BM25 keyword matching, vector similarity searches, and synthesis run directly within your self-hosted infrastructure. Zero prompt data or queries are transmitted to third-party AI APIs (OpenAI, Anthropic, or external telemetry).
• No IP or User Logging: The assistant API enforces in-memory rate limiting and never logs client IP addresses, browser fingerprints, or visitor identities.
• Client-Side Redaction: Automatic pre-filtering prevents accidental transmission of sensitive API tokens, passwords, private keys, or credentials.

5. Keyboard Shortcuts & UX Controls