diff --git a/README.md b/README.md index 7d6eba9..57f43d9 100755 --- a/README.md +++ b/README.md @@ -1,58 +1,75 @@ -# Ollama Chat Plugin for Obsidian +# Obsidian Ollama Plugin -A plugin that integrates [Ollama](https://ollama.ai) with [Obsidian](https://obsidian.md) to create a chat interface that can access your vault content contextually. +A plugin that integrates [Ollama](https://ollama.ai) with Obsidian, allowing you to chat with local AI models, search your vault context, and use AI tools like creating files. ## Features -- **Chat with local AI models** — Interact with Ollama models directly in Obsidian's sidebar -- **Vault context search** — The assistant automatically searches your notes using weighted scoring (headings, frontmatter titles/tags, content) -- **Tool integration** — AI can create files in your vault via the `create_file` tool -- **Streaming responses** — Real-time token streaming for a responsive chat experience -- **Configurable settings** — Customize model, URL, search limits, and message history +- Chat with Ollama models directly in Obsidian +- Vault context search — the assistant can reference your notes +- Tool integration — create files based on chat responses +- Streaming responses +- Semantic response cache — repeated or similar queries are answered instantly without hitting the model (requires ChromaDB) +- Customisable model, URL, and cache settings ## Installation -### From Source - -1. Clone this repository into your Obsidian vault's `.obsidian/plugins/` folder: - ```bash - cd .obsidian/plugins - git clone obsidian-ollama - cd obsidian-ollama - npm install - npm run build - ``` -2. Enable the plugin in Obsidian: Settings → Community plugins → Ollama Plugin +1. Install the plugin via Obsidian's community plugins +2. Make sure you have Ollama installed and running ## Prerequisites 1. **Install Ollama**: Follow the instructions at [ollama.ai](https://ollama.ai) 2. **Start Ollama**: `ollama serve` -3. **Pull a model**: `ollama pull llama3` (or any model you prefer) +3. **Pull a chat model**: `ollama pull llama3` (or any other model you prefer) + +### Optional — Semantic Cache + +The semantic cache stores responses in a local [ChromaDB](https://www.trychroma.com) vector database. When you ask a question that is semantically similar to one already cached, the stored answer is returned immediately instead of calling the model. + +1. **Install ChromaDB**: + ```bash + pip install chromadb + ``` +2. **Start ChromaDB**: + ```bash + chroma run --host localhost --port 8000 + ``` +3. **Pull an embedding model** (used to generate vectors for cache lookups): + ```bash + ollama pull nomic-embed-text + ``` +4. Enable the cache in the plugin settings and configure the ChromaDB URL. ## Configuration -Open Settings → Ollama Plugin to configure: +Open **Settings → Ollama Chat** to configure the plugin. | Setting | Default | Description | -|---------|---------|-------------| -| Ollama URL | `http://localhost:11434` | Your Ollama instance URL | -| Model | `llama3` | Model to use for chat | - -### Internal Settings - -| Setting | Default | Description | -|---------|---------|-------------| -| Vault Search Limit | `3` | Max notes returned for context | -| Max Message History | `50` | Messages kept in conversation context | +|-----|- -- ----|-------| +| Ollama URL | `http://localhost:11434` | Base URL of your Ollama instance | +| Model | `llama3` | Model used for chat responses | +| Enable Semantic Cache | Off | Cache responses for fast repeated queries | +| ChromaDB URL | `http://localhost:8000` | URL of your running ChromaDB instance | +| Cache Embedding Model | `nomic-embed-text` | Ollama model used to generate cache embeddings | +| Cache Similarity Threshold | `0.85` | Minimum cosine similarity (0–1) for a cache hit — higher values require closer matches | +| Clear Semantic Cache | — | Button to wipe all cached responses from ChromaDB | ## Usage -1. Click the chat icon in the left ribbon to open the chat view -2. Type your message and press **Enter** or click **Send** -3. Click **New Chat** to start a fresh conversation +1. Click the ribbon icon to open the chat view +2. Type your message in the input box +3. Press **Enter** or click **Send** to send your message +4. Press **Shift+Enter** to insert a line break +5. Click **New Chat** to start a fresh conversation -### Vault Context +## Semantic Cache Behaviour + +- The cache is **bypassed** when tool calls are involved (e.g. file creation), since those requests have side effects. +- Responses are stored against the last user message in the conversation. If a new query is sufficiently similar (above the configured threshold), the cached response is returned. +- Re-asking the same question updates the existing cache entry rather than creating a duplicate. +- Use the **Clear Semantic Cache** button in settings to remove all stored responses (for example after switching embedding models). + +## Vault Context When you send a message, the plugin automatically searches your vault for relevant notes and includes them as context. The search uses weighted scoring: @@ -62,7 +79,7 @@ When you send a message, the plugin automatically searches your vault for releva - **First paragraph** — 1.5x weight - **General content** — 1x weight -### Tools +## Tools The plugin exposes a `create_file` tool that allows the AI to create new markdown files in your vault. Paths are validated for safety (no `.obsidian`/`.git` access, no path traversal). @@ -70,55 +87,30 @@ The plugin exposes a `create_file` tool that allows the AI to create new markdow Any Ollama-supported model works. Popular choices: -| Model | Best For | -|-------|----------| -| `llama3` | General chat | -| `mistral` | Fast responses | -| `codellama` | Code assistance | -| `gemma` | Lightweight local use | +- `llama3` +- `llama2` +- `mistral` +- `codellama` +- and many more — see [ollama.com/library](https://ollama.com/library) ## Development ```bash -npm install # Install dependencies -npm run build # Compile TypeScript -npm run watch # Watch mode for development -npm test # Run tests (Jest) -npm run lint # Lint with ESLint -npm run format # Format with Prettier -``` - -### Project Structure - -``` -src/ -├── main.ts # Plugin entry point and settings -├── chat-view.ts # Chat UI and message handling -├── ollama-client.ts # Ollama API communication -├── vault-indexer.ts # Vault search and scoring -├── tool-executor.ts # Tool execution (create_file) -├── error-handler.ts # Centralized error handling -├── utils.ts # Validation and logging utilities -├── types.ts # TypeScript type definitions -└── constants.ts # Default configuration -``` - -### Testing - -The project includes tests for all major components. Run with: - -```bash +npm install +npm run build npm test ``` ## Troubleshooting -| Issue | Solution | -|-------|----------| -| Connection refused | Ensure Ollama is running (`ollama serve`) | -| Model not found | Pull the model first (`ollama pull `) | -| Permission errors | Check vault write permissions | -| Empty responses | Try a different model or check Ollama logs | +| Symptom | Likely cause | Fix | +|-----|- -----|---| +| Cannot connect to Ollama | Ollama is not running | Run `ollama serve` | +| Model not found | Model not pulled | Run `ollama pull ` | +| Semantic cache unavailable (notice shown) | ChromaDB is not running, or the ChromaDB URL is wrong | Start ChromaDB (`chroma run`) and verify the URL in settings | +| Cache always misses | Similarity threshold is too high, or the embedding model was changed | Lower the threshold or click **Clear Semantic Cache** and let the cache rebuild | +| Slow first response after enabling cache | Embedding model not yet pulled | Run `ollama pull nomic-embed-text` (or the model you configured) | +| Permission issues | Vault write permissions | Check that your Obsidian vault has proper write permissions | ## Security @@ -129,4 +121,24 @@ npm test ## License -MIT +MIT License + +Copyright (c) 2024 Flo Egger + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file