vector-rag-gui

A Qt6 GUI for searching local FAISS vector stores with AI-powered research synthesis. Built as a custom agent using the Claude Code Agent SDK.

Architecture

This application is built on the Claude Code Agent SDK framework, providing an agentic research assistant with access to multiple tools.

Dependencies

Agent Tools

The agent has access to 6 tools using the Claude Agent SDK @tool decorator:

Custom Prompts

The agent supports custom system prompts for specialized use cases:

• Research Prompt: Default prompt for multi-source research synthesis
• Obsidian Knowledge Prompt: Template for querying Obsidian vaults with wiki-link following and daily notes support

The Obsidian prompt instructs the agent to:

1. Use RAG to find relevant notes
2. Read full files (not just snippets)
3. Follow [[wiki links]] using glob + read
4. Search daily notes for date-related queries

Features

• Qt6 desktop GUI with GitHub-flavored markdown rendering
• Research mode with multi-source synthesis (local RAG, AWS docs, web search)
• Read-only file tools (glob, grep, read) for codebase exploration
• Multi-store selection for comprehensive local searches
• Real-time progress with token usage and cost tracking
• Dark/Light mode toggle
• System tray integration
• Built-in REST API server (starts automatically with GUI)
• Persistent settings (window position, selected stores, tools, model)

Installation

Requires Python 3.14+, uv, and vector-rag-tool.

git clone https://github.com/dnvriend/vector-rag-gui.git
cd vector-rag-gui
uv tool install .

Configuration

AWS Bedrock credentials via environment variables:

export AWS_PROFILE="your-profile"
export AWS_REGION="us-east-1"

# Optional: Override model inference profiles
export ANTHROPIC_DEFAULT_SONNET_MODEL="arn:aws:bedrock:..."
export ANTHROPIC_DEFAULT_OPUS_MODEL="arn:aws:bedrock:..."
export ANTHROPIC_DEFAULT_HAIKU_MODEL="arn:aws:bedrock:..."

Usage

# Launch GUI (REST API starts automatically)
vector-rag-gui

# Launch with custom API port
vector-rag-gui --port 9000

# Launch with specific store pre-selected
vector-rag-gui start --store my-knowledge-base

# List available stores
vector-rag-gui stores
vector-rag-gui stores --json

# Show configuration
vector-rag-gui config

# Verbose output
vector-rag-gui -v    # INFO
vector-rag-gui -vv   # DEBUG
vector-rag-gui -vvv  # TRACE

On startup, a banner displays the API endpoints:

╭─────────────────────────────────────────╮
│         Vector RAG GUI v0.1.0           │
├─────────────────────────────────────────┤
│  REST API: http://127.0.0.1:8000        │
│  Swagger:  http://127.0.0.1:8000/docs   │
╰─────────────────────────────────────────╯

Options

Commands

REST API

Start the API server for programmatic access:

vector-rag-gui serve                        # Default: localhost:8000
vector-rag-gui serve --host 0.0.0.0 --port 8080
vector-rag-gui serve --reload               # Development mode

Endpoints

Research Request

Minimal request (question and stores required):

curl -X POST http://localhost:8000/api/v1/research \
  -H "Content-Type: application/json" \
  -d '{"question": "How does X work?", "stores": ["obsidian-knowledge-base"]}'

Full request with all options:

curl -X POST http://localhost:8000/api/v1/research \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How does X work?",
    "stores": ["obsidian-knowledge-base", "code-docs"],
    "model": "opus",
    "tools": ["local", "aws", "web", "glob", "grep", "read"],
    "top_k": 10
  }'

Request Parameters

Available Tools

API Documentation

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI: http://localhost:8000/openapi.json

Keyboard Shortcuts

Settings

Settings are persisted to ~/.config/vector-rag-gui/settings.json and restored on startup.

Saved settings include:

• Window position and size
• Splitter panel sizes
• Selected stores
• Research mode options (tools, model, dark mode)
• REST API port

Example settings file:

{
  "port": 8000,
  "selected_stores": ["obsidian-knowledge-base"],
  "window": {
    "x": 100,
    "y": 100,
    "width": 900,
    "height": 700,
    "splitter_sizes": [500, 120]
  },
  "research": {
    "research_mode": true,
    "use_local": true,
    "use_aws": false,
    "use_web": false,
    "model": "sonnet",
    "dark_mode": true,
    "full_content": false
  }
}

Development

make install    # Install dependencies
make test       # Run tests
make check      # Run all checks (format, lint, typecheck, test, security)
make pipeline   # Full CI pipeline

License

MIT

Author

Dennis Vriend - @dnvriend