cognisn-spark 0.2.0b2

Secure Personal AI Research Kit - Multi-provider LLM web interface with MCP tool integration

Spark

Spark is a secure, multi-provider AI research kit with a modern web interface. It connects to AI models from Anthropic, AWS Bedrock, Google Gemini, Ollama, and X.AI, with features like MCP tool integration, intelligent context management, persistent memory, and autonomous scheduled actions.

Features

Conversations

• Multi-Provider LLM Support -- Claude, Gemini, Grok, Llama, Mistral, and more
• Real-Time Streaming -- Server-Sent Events for token-by-token responses
• Dark/Light Theme -- Cognisn design system with theme persistence
• Context Compaction -- LLM-driven summarisation when approaching context limits
• Conversation Linking -- Share context between related conversations
• Favourites -- Star conversations for quick access
• Global System Instructions -- Define persistent instructions applied to all conversations (Settings > Conversation)
• Voice Conversation Mode -- Hands-free AI interaction via the headset button with text-to-speech output and voice selection
• Speech-to-Text Input -- Dictate messages using the microphone button

Tools

• MCP Integration -- Connect external tool servers via stdio, HTTP, or SSE
• Built-in Tools -- Filesystem, documents (Word/Excel/PDF/PowerPoint), web search, archives, email
• Email Tools -- Send and draft emails via SMTP with HTML/plain text, attachments, and cc/bcc
• Memory Tools -- Persistent semantic memory across conversations
• Per-Conversation Control -- Enable/disable tools at the server or individual level
• Tool Approval -- Permission prompts for first-use with allow once/always/deny
• Tool Activity Sidecar Panel -- Dedicated panel for tool call visibility, replacing inline tool groups
• Agent Spawning -- Spawn independent sub-agents for parallel research, analysis, and data gathering
• Tool Documentation -- Built-in get_tool_documentation tool for querying tool usage information
• Web Search Engines -- DuckDuckGo, Brave, Google/SerpAPI, Bing/Azure, SearXNG
• System Commands -- Execute shell commands and CLI tools (git, docker, aws, etc.) with approval prompts

Memory

• Persistent Storage -- Facts, preferences, projects, instructions, relationships
• Semantic Search -- Vector embeddings for relevant recall
• Auto-Retrieval -- Relevant memories silently injected into context
• Import/Export -- JSON format for backup and sharing

Autonomous Actions

• Scheduled Tasks -- Cron or one-off schedules via APScheduler
• AI-Assisted Creation -- Describe what you want and the AI builds the action
• Create from Conversation -- Turn any conversation into an autonomous action with AI-guided setup
• Background Daemon -- System tray icon (macOS/Windows) runs actions independently
• Run History -- Track execution status, results, and token usage

Dashboard

• Provider Models Modal -- Click any provider on the dashboard to view its available models

Security

• Prompt Inspection -- Pattern and keyword-based threat detection
• Secret Management -- API keys stored in OS keychain, never in config files
• Settings Lock -- Password-protect the settings page
• Tool Permissions -- Per-conversation, per-tool approval system

Updates

• Auto-Update Checker -- Checks GitHub releases for new versions; update from the Help menu

Installation

Download (Standalone)

Pre-built binaries with an embedded Python runtime and a native splash screen for first-run setup. Dependencies are downloaded from PyPI on first launch (~30-60 seconds, requires internet).

Platform	Architecture	Format	Download
macOS	ARM64 (Apple Silicon)	Signed + notarized DMG	Download
macOS	x86_64 (Intel)	Signed + notarized DMG	Download
Windows	x86_64	NSIS installer	Download
Linux	Any	pip install (see below)	--

Install from PyPI

pip install cognisn-spark

Optional database drivers

pip install cognisn-spark[postgresql]   # PostgreSQL
pip install cognisn-spark[mysql]        # MySQL
pip install cognisn-spark[mssql]        # SQL Server
pip install cognisn-spark[all-databases] # All drivers

Quick Start

spark

On first launch, Spark creates a configuration file, starts the web server on a random port, and opens your browser. Follow the welcome page to configure an LLM provider and start chatting.

Configuration

Spark stores its configuration in platform-standard locations:

Platform	Config	Data	Logs
macOS	~/Library/Application Support/spark/	~/Library/Application Support/spark/	~/Library/Logs/spark/
Linux	~/.config/spark/	~/.local/share/spark/	~/.local/state/spark/logs/
Windows	%APPDATA%/spark/	%APPDATA%/spark/	%LOCALAPPDATA%/spark/logs/

API keys are stored in the OS keychain (macOS Keychain, Windows Credential Locker, Linux Secret Service) via the cognisn-konfig library.

Architecture

graph TB
    subgraph UI ["Web Interface"]
        FE["FastAPI + SSE + Bootstrap 5 (Cognisn)"]
        Voice["Voice / Speech-to-Text"]
        Sidecar["Tool Activity Sidecar"]
    end

    subgraph Core ["Conversation Manager"]
        CM["Context Compaction / Memory / RAG / Tool Routing"]
    end

    subgraph Providers ["LLM Providers"]
        Bedrock["AWS Bedrock"]
        Anthropic["Anthropic"]
        Ollama["Ollama"]
        Gemini["Google Gemini"]
        XAI["X.AI"]
    end

    subgraph Tools ["Tools"]
        MCP["MCP Servers"]
        Builtin["Built-in Tools"]
        Memory["Memory"]
        WebSearch["Web Search"]
        EmailTool["Email (SMTP)"]
    end

    subgraph Foundation ["cognisn-konfig"]
        Settings["Settings"]
        Secrets["Secrets"]
        Logging["Logging"]
    end

    UI --> Core
    Core --> Providers
    Core --> Tools
    Core --> Foundation

Keyboard Shortcuts

Shortcut	Action
Ctrl/Cmd + K	Go to Conversations
Ctrl/Cmd + N	New Conversation
Ctrl/Cmd + ,	Open Settings
Enter	Send message
Shift + Enter	New line

Development

git clone https://github.com/Cognisn/spark.git
cd spark
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

Changelog

See CHANGELOG.md.

Licence

MIT License with Commons Clause -- free for personal and educational use. Commercial use requires a licence from the author. See LICENSE.

Author

Matthew Westwood-Hill / Cognisn