662 lines
26 KiB
Markdown
662 lines
26 KiB
Markdown
# Design: Mattermore — Mattermost AI Chat Agent for Ollama
|
|
|
|
> **Status:** Draft / Pre-implementation
|
|
> **Last updated:** 2026-06-16
|
|
> **Assumed direction:** AI chat agent plugin connecting to a remote Ollama instance.
|
|
> **Open questions are marked** `TODO(design):` throughout. This is a living template — change
|
|
> assumptions as the product direction firms up.
|
|
|
|
---
|
|
|
|
## 1. Purpose & Scope
|
|
|
|
### 1.1 What It Is
|
|
|
|
Mattermore is a Mattermost (Community Edition) plugin that lets users chat
|
|
with remote LLMs through an Ollama backend. Users address the bot by
|
|
**@-mentioning** it in any channel (e.g. `@mattermore write a poem`). The
|
|
bot responds **only when addressed** and disengages naturally — it never
|
|
reads every message in the room. A slash command (`/ai`) remains available
|
|
as an alternative entry point.
|
|
|
|
### 1.2 What It Is Not (Explicit Out-of-Scope)
|
|
|
|
| Out of scope | Rationale |
|
|
|---|---|
|
|
| Hosting its own LLM inference | Ollama is the sole backend; the plugin is a thin proxy |
|
|
| Multi-backend abstraction (OpenAI, Anthropic, etc.) | If needed later, abstract behind an `LLMProvider` interface — not now |
|
|
| Training / fine-tuning | Ollama handles that |
|
|
| **Channel whisper mode** — replying to every message in a channel | The agent only activates on @-mention or thread reply. It never reads unprompted messages. |
|
|
|
|
### 1.3 Target Audience
|
|
|
|
- Teams self-hosting Mattermost who want AI assistant access without data
|
|
leaving their infrastructure
|
|
- Users comfortable with @-mentioning a bot the same way they @-mention a
|
|
human teammate
|
|
|
|
---
|
|
|
|
## 2. Architecture Overview
|
|
|
|
### 2.1 Component Diagram (text)
|
|
|
|
```
|
|
┌──────────────────────────────────────────────────────────────┐
|
|
│ Mattermost Server (Community Edition) │
|
|
│ │
|
|
│ ┌───────────────────────────────────────────────────────┐ │
|
|
│ │ Mattermore Plugin │ │
|
|
│ │ │ │
|
|
│ │ ┌──────────────────┐ ┌────────────────────────┐ │ │
|
|
│ │ │ MessageHasBeen │──▶│ Plugin (Go) │ │ │
|
|
│ │ │ Posted (primary) │ │ │ │ │
|
|
│ │ └──────────────────┘ │ ┌──────────────────┐ │ │ │
|
|
│ │ ┌──────────────────┐ │ │ OllamaClient │──┼───┼───┼──▶ Ollama
|
|
│ │ │ SlashCommand │──▶│ └──────────────────┘ │ │ │ (remote)
|
|
│ │ │ /ai (alt.) │ │ ┌──────────────────┐ │ │ │
|
|
│ │ └──────────────────┘ │ │ ConversationStore│ │ │ │
|
|
│ │ ┌──────────────────┐ │ └──────────────────┘ │ │ │
|
|
│ │ │ EngagementEngine │ │ ┌──────────────────┐ │ │ │
|
|
│ │ │ wake / sleep │──▶│ │ RateLimiter │ │ │ │
|
|
│ │ └──────────────────┘ │ └──────────────────┘ │ │ │
|
|
│ │ ┌──────────────────┐ │ ┌──────────────────┐ │ │ │
|
|
│ │ │ Bot Account │ │ │ Config (KV) │ │ │ │
|
|
│ │ │ (auto-created) │ │ └──────────────────┘ │ │ │
|
|
│ │ └──────────────────┘ │ │ │ │
|
|
│ │ ┌──────────────────┐ │ │ │ │
|
|
│ │ │ Webapp (none) │ │ │ │ │
|
|
│ │ └──────────────────┘ │ │ │ │
|
|
│ └──────────────────────────────────────────────────────┘ │
|
|
└──────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 2.2 Request Flow (happy path)
|
|
|
|
```
|
|
User types "@mattermore write a release note for v2.1"
|
|
│
|
|
▼
|
|
Mattermore MessageHasBeenPosted fires
|
|
│
|
|
▼
|
|
EngagementEngine.Wake(userId, channelId) → mark session Active
|
|
│
|
|
▼
|
|
@-mention detected → strip "@mattermore " prefix from prompt
|
|
│
|
|
▼
|
|
RateLimiter.Allow(userId) → 200 or 429
|
|
│
|
|
▼
|
|
ConversationStore.GetSession(userId, channelId, threadId) → previous messages for context
|
|
│
|
|
▼
|
|
OllamaClient.ChatCompletion(messages, stream=true, model=defaultModel)
|
|
│
|
|
▼
|
|
Ollama returns ndjson stream → plugin creates root post with live-updating thread
|
|
│
|
|
▼
|
|
Post created in channel → user sees response in thread
|
|
│
|
|
▼
|
|
ConversationStore.Append(userId, channelId, threadId, userMsg, assistantMsg)
|
|
```
|
|
|
|
#### Thread Reply Flow (continues the conversation)
|
|
|
|
```
|
|
User replies in thread → "Can you make it more formal?"
|
|
│
|
|
▼
|
|
Mattermore MessageHasBeenPosted fires (same thread as bot post)
|
|
│
|
|
▼
|
|
EngagementEngine.IsActive(userId, threadId) → true
|
|
│
|
|
▼
|
|
Not an @-mention, but active thread → treat as continuation
|
|
│
|
|
▼
|
|
ConversationStore.GetSession(userId, channelId, threadId) → full context so far
|
|
│
|
|
▼
|
|
OllamaClient.ChatCompletion(...) → stream response into same thread
|
|
│
|
|
▼
|
|
ConversationStore.Append(userId, channelId, userMsg, assistantMsg)
|
|
```
|
|
|
|
### 2.3 Error Flow
|
|
|
|
| Failure point | Behaviour |
|
|
|---|---|
|
|
| Ollama unreachable | Ephemeral post: "Ollama at <url> unreachable. Check configuration." |
|
|
| Rate limit hit | Ephemeral post: "Rate limit exceeded. Try again in N seconds." |
|
|
| Invalid model name | Ephemeral post: "Model 'xyz' not found on Ollama server." |
|
|
| Timeout (>30 s) | Abort stream, post partial response + "Response truncated (timeout)." |
|
|
| Input too long | Reject with context window limit message; suggest `@mattermore new` to reset. |
|
|
|
|
---
|
|
|
|
## 3. Plugin Manifest & Identity
|
|
|
|
### 3.1 `plugin.json`
|
|
|
|
```json
|
|
{
|
|
"id": "com.forkless.mattermore",
|
|
"name": "Mattermore",
|
|
"description": "AI chat agent powered by Ollama.",
|
|
"version": "0.1.0",
|
|
"server": {
|
|
"executables": {
|
|
"linux-amd64": "server/dist/plugin-linux-amd64",
|
|
"linux-arm64": "server/dist/plugin-linux-arm64",
|
|
"darwin-amd64": "server/dist/plugin-darwin-amd64"
|
|
}
|
|
},
|
|
"webapp": {},
|
|
"settings_schema": {
|
|
"header": "Configure the connection to your Ollama instance.",
|
|
"footer": "",
|
|
"settings": [
|
|
{
|
|
"key": "OllamaURL",
|
|
"display_name": "Ollama Server URL",
|
|
"type": "text",
|
|
"help_text": "Base URL of the Ollama API, e.g. http://10.0.0.5:11434",
|
|
"placeholder": "http://localhost:11434",
|
|
"default": "http://localhost:11434"
|
|
},
|
|
{
|
|
"key": "DefaultModel",
|
|
"display_name": "Default Model",
|
|
"type": "text",
|
|
"help_text": "Model name to use when none is specified.",
|
|
"placeholder": "llama3:latest",
|
|
"default": "llama3:latest"
|
|
},
|
|
{
|
|
"key": "SystemPrompt",
|
|
"display_name": "System Prompt",
|
|
"type": "text",
|
|
"help_text": "System prompt prepended to every conversation.",
|
|
"placeholder": "You are a helpful assistant.",
|
|
"default": "You are a helpful assistant."
|
|
},
|
|
{
|
|
"key": "MaxTokens",
|
|
"display_name": "Max Response Tokens",
|
|
"type": "number",
|
|
"help_text": "Maximum tokens per response (0 = model default).",
|
|
"default": 2048
|
|
},
|
|
{
|
|
"key": "RateLimitPerMinute",
|
|
"display_name": "Rate Limit (requests/minute/user)",
|
|
"type": "number",
|
|
"help_text": "Maximum requests per minute per user. 0 = unlimited.",
|
|
"default": 10
|
|
},
|
|
{
|
|
"key": "AllowedUserIDs",
|
|
"display_name": "Allowed User IDs (comma-separated)",
|
|
"type": "text",
|
|
"help_text": "Restrict to specific user IDs. Empty = all users.",
|
|
"default": ""
|
|
},
|
|
{
|
|
"key": "StopWords",
|
|
"display_name": "Stop Words (comma-separated)",
|
|
"type": "text",
|
|
"help_text": "When the user says one of these, the bot responds briefly and disengages.",
|
|
"placeholder": "thanks, thank you, bye, goodbye, that's all, done",
|
|
"default": "thanks, thank you, bye, goodbye, see you, that's all, that's it, done, all done, stop, quit, end"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
`TODO(design):` Should `AllowedUserIDs` be a team/channel whitelist instead?
|
|
For now, keep user-level granularity — easy to widen later.
|
|
|
|
### 3.2 Versioning
|
|
|
|
Follow `release-workflow` skill: `v0.1.0`, `v0.2.0`, etc. Bump PATCH for
|
|
bugs, MINOR for features. MAJOR after 1.0 for breaking config schema changes.
|
|
|
|
---
|
|
|
|
## 4. Server-Side Components
|
|
|
|
### 4.1 Plugin Lifecycle Hooks
|
|
|
|
| Hook | Purpose |
|
|
|---|---|
|
|
| `OnActivate()` | Register slash command, create bot account via `API.CreateBot()`, initialise `EngagementEngine` |
|
|
| `OnConfigurationChange()` | Re-read System Console settings, validate OllamaURL, rebuild clients, rebuild stop-word trie |
|
|
| `MessageHasBeenPosted()` | **Primary entry point** — detect @-mentions and thread continuations, delegate to `EngagementEngine` |
|
|
| `ExecuteCommand()` | **Alternative entry point** — intercept `/ai` and subcommands |
|
|
| `OnDeactivate()` | Clean up goroutines, deactivate bot account, close idle HTTP connections |
|
|
|
|
### 4.2 Interaction Model
|
|
|
|
The plugin has two entry points, but **@-mention is the primary UX**.
|
|
|
|
#### 4.2.1 @-mention (primary)
|
|
|
|
User types `@mattermore <prompt>` in any channel. The plugin:
|
|
|
|
1. Detects the @-mention via `MessageHasBeenPosted` → `model.Post.Mentions`
|
|
2. Strips the bot username from the prompt
|
|
3. Wakes the `EngagementEngine` for this user+thread
|
|
4. Creates a **thread root post** with the streamed response
|
|
5. Monitors thread replies for continuation — as long as the user keeps
|
|
replying in the thread, the bot auto-responds (no @-mention needed for
|
|
follow-ups in the same thread)
|
|
|
|
**When the bot does NOT respond:**
|
|
- Messages without `@mattermore` while the EngagementEngine is Sleeping
|
|
- Messages in threads the bot didn't start
|
|
- Messages from other bot accounts (infinite-loop guard)
|
|
|
|
#### 4.2.2 Slash command (alternative)
|
|
|
|
`/ai <prompt>` works as a fallback for users who prefer it or when
|
|
@-mention is inconvenient. Behaviour is identical — creates a thread,
|
|
activates the EngagementEngine, continues on thread replies.
|
|
|
|
**Full syntax:**
|
|
|
|
```
|
|
/ai <prompt>
|
|
— Send a prompt using the default model (current session context).
|
|
/ai model <name> <prompt>
|
|
— Send a prompt using a specific model.
|
|
/ai new
|
|
— Reset conversation context for the current user+channel.
|
|
/ai model list
|
|
— List available models from the Ollama server.
|
|
/ai help
|
|
— Show usage help.
|
|
```
|
|
|
|
### 4.3 OllamaClient
|
|
|
|
Interface (in `server/ollama/client.go`):
|
|
|
|
```go
|
|
type Client interface {
|
|
ChatCompletion(ctx context.Context, req *ChatRequest) (<-chan ChatStreamEvent, error)
|
|
ListModels(ctx context.Context) ([]Model, error)
|
|
Ping(ctx context.Context) error
|
|
}
|
|
|
|
type ChatRequest struct {
|
|
Model string `json:"model"`
|
|
Messages []ChatMessage `json:"messages"`
|
|
Stream bool `json:"stream"`
|
|
Options map[string]any `json:"options,omitempty"`
|
|
}
|
|
|
|
type ChatStreamEvent struct {
|
|
Token string // delta content
|
|
Done bool
|
|
Error error
|
|
}
|
|
```
|
|
|
|
`TODO(design):` Should we use Ollama's `/api/chat` (chat format) or
|
|
`/api/generate` (raw prompt)? `/api/chat` is preferred — it maps cleanly to
|
|
the conversational UX and supports the messages array natively.
|
|
|
|
### 4.4 ConversationStore
|
|
|
|
Store session context in Mattermost's KV store (plugin's `API.KVSet` /
|
|
`KVGet`).
|
|
|
|
| Key pattern | Value | TTL |
|
|
|---|---|---|
|
|
| `ctx_{userID}_{channelID}` | `[]Message` (last N turns) | 1 hour |
|
|
| `ctx_{userID}_{channelID}_model` | Model name override | 1 hour |
|
|
|
|
`TODO(design):`
|
|
- How many turns to keep? **Proposed:** last 10 messages (5 user + 5 assistant).
|
|
- TTL of 1 hour — resets on activity. Configurable?
|
|
- Should context be channel-scoped or user-global? Channel-scoped means a
|
|
user gets different context in different channels.
|
|
|
|
### 4.5 RateLimiter
|
|
|
|
Token-bucket per user. Configurable requests/minute from System Console.
|
|
Resets on config change. Stored in memory, not KV (ephemeral state).
|
|
|
|
### 4.6 Engagement Lifecycle
|
|
|
|
The **EngagementEngine** is the core mechanism that prevents the bot from
|
|
replying to everything in the channel. It manages whether the bot should
|
|
respond to a given message.
|
|
|
|
#### States
|
|
|
|
| State | Behaviour | Entered when |
|
|
|---|---|---|
|
|
| **Sleeping** | Ignores all messages | Agent started, disengage triggered, timeout expired |
|
|
| **Active** | Responds to @-mentions and thread replies in the active session | User @-mentions bot or sends `/ai` |
|
|
| **Disengaging** | Responds to current message with a closing note, then sleeps | Stop word detected or user sends stop command |
|
|
|
|
```
|
|
┌─────────────────┐
|
|
│ Sleeping │
|
|
└────────┬────────┘
|
|
│ @-mention or /ai
|
|
▼
|
|
┌─────────────────┐
|
|
┌──────│ Active │◄──── thread reply continues
|
|
│ └────────┬────────┘
|
|
│ │ stop word / stop command / timeout
|
|
│ ▼
|
|
│ ┌─────────────────┐
|
|
│ │ Disengaging │── responds once, then...
|
|
│ └────────┬────────┘
|
|
│ │
|
|
└───────────────┘
|
|
```
|
|
|
|
#### Disengagement Triggers
|
|
|
|
| Trigger | Example | Behaviour |
|
|
|---|---|---|
|
|
| Stop word | "thanks", "thank you", "bye", "goodbye", "that's all", "that's it" | Bot responds with a brief closing message, then sleeps |
|
|
| Stop command | `@mattermore stop` | Bot sleeps immediately, no closing message |
|
|
| Thread timeout | No reply in thread for 15 minutes | Bot sleeps silently — next @-mention starts a fresh session |
|
|
| Model EOS signal | Model outputs `[EOS]` naturally | Same as stop word — clean disengagement from the AI's side |
|
|
|
|
#### Stop word matching
|
|
|
|
Stop words are configurable via System Console (`StopWords`). The plugin
|
|
builds a case-insensitive trie at config load. Matching is done on the
|
|
**user's raw prompt** (after stripping the @-mention), before sending to
|
|
Ollama — this avoids the latency and cost of a round-trip just to detect
|
|
a goodbye.
|
|
|
|
The system prompt also instructs the model to append `[EOS]` when it
|
|
believes the conversation is naturally complete. The EngagementEngine
|
|
watches the response stream for this token as an additional trigger.
|
|
|
|
#### Thread timeout
|
|
|
|
15 minutes of inactivity in the thread → bot sleeps. The `ConversationStore`
|
|
TTL naturally handles cleanup. On wake, a new thread is created rather than
|
|
resuming the old one.
|
|
|
|
`TODO(design):` Should the timeout be configurable via System Console?
|
|
**Proposed:** yes — `EngagementTimeoutMinutes` setting, default 15.
|
|
|
|
#### Infinite-loop guard
|
|
|
|
The plugin never processes messages from:
|
|
- Its own bot account (checked via `post.UserId == botUserID`)
|
|
- Any other bot account (`post.UserId` cross-referenced against `model.Bot`)
|
|
|
|
---
|
|
|
|
## 5. Ollama Integration
|
|
|
|
### 5.1 API Mapping
|
|
|
|
| Plugin Action | Ollama Endpoint | Method |
|
|
|---|---|---|
|
|
| Chat completion (streaming) | `/api/chat` | POST |
|
|
| List models | `/api/tags` | GET |
|
|
| Health check | `/api/tags` (or HEAD `/`) | GET |
|
|
| Pull model | `/api/pull` | POST |
|
|
|
|
`TODO(design):` Should the plugin auto-pull a model if it's not present?
|
|
Risk: user mistypes name → long pull. **Proposed:** return error with list of
|
|
available models instead.
|
|
|
|
### 5.2 Streaming Strategy
|
|
|
|
1. Send POST to `/api/chat` with `"stream": true`.
|
|
2. Read ndjson response body line by line (each line is `{"message":{"role":"assistant","content":"..."},"done":false}`).
|
|
3. On each `done:false` event, update the thread root post via
|
|
`API.UpdatePost()` with accumulated content.
|
|
4. On `done:true`, finalise the post with full content, usage stats
|
|
(token count, duration).
|
|
|
|
`TODO(design):` Post-update on every token may be too chatty. **Proposed:**
|
|
batch updates every ~200 ms or every 3 tokens, whichever comes first.
|
|
|
|
### 5.3 Context Window Management
|
|
|
|
- Token counting: use Ollama's `num_ctx` parameter or a Go tokenizer
|
|
(tiktoken-go).
|
|
- If input exceeds configured limit (default: 4096 tokens), trim oldest
|
|
messages until within limit, or reject if a single message overflows.
|
|
- Display a warning: "Context window trimmed (oldest messages removed)."
|
|
|
|
`TODO(design):` Should the user be able to set `num_ctx` per-request?
|
|
`@mattermore --context 8192 ...`
|
|
|
|
### 5.4 Model Selection Precedence
|
|
|
|
1. Per-request: `@mattermore model gemma3:12b write a poem`
|
|
2. Session override: `/ai model gemma3:12b` (stored in KV)
|
|
3. Default from System Console: `DefaultModel`
|
|
|
|
---
|
|
|
|
## 6. Configuration
|
|
|
|
### 6.1 System Console Settings
|
|
|
|
Defined in `plugin.json` `settings_schema` (see §3.1). The System Console
|
|
provides the UI; the plugin reads via `OnConfigurationChange()`.
|
|
|
|
### 6.2 Dynamic Config Reload
|
|
|
|
`OnConfigurationChange()` is called on every save. The plugin must:
|
|
1. Re-read the config struct from `API.GetConfig()` / `API.GetPluginConfig()`.
|
|
2. Validate `OllamaURL` (parse as URL, reject non-HTTP(S) schemes).
|
|
3. If URL changed, create a new `http.Client` (with configurable timeout).
|
|
4. If `RateLimitPerMinute` changed, rebuild the token buckets.
|
|
5. If `StopWords` changed, rebuild the stop-word trie.
|
|
6. Log the change at debug level.
|
|
|
|
---
|
|
|
|
## 7. Data Flow — Detailed
|
|
|
|
### 7.1 Full Lifecycle
|
|
|
|
```
|
|
Step User / System Component
|
|
──── ────────────────────────────── ──────────────────
|
|
1 User types "@mattermore explain TCP" Mattermost webapp
|
|
2 MessageHasBeenPosted fires Mattermore plugin
|
|
3 EngagementEngine.Wake() EngagementEngine
|
|
3a Check not a bot post (loop guard)
|
|
3b Check @-mention or active thread
|
|
3c Transition to Active
|
|
4 Strip "@mattermore " → "explain TCP"
|
|
5 Check stop-word trie (no match)
|
|
6 RateLimiter.Allow(userId) RateLimiter
|
|
7 ConversationStore.GetSession(...) ConversationStore
|
|
8 Build []ChatMessage (system + history + new prompt)
|
|
9 OllamaClient.ChatCompletion(...) OllamaClient
|
|
10 Ollama streams ndjson tokens Ollama (remote)
|
|
11 Plugin accumulates tokens, updates Mattermore plugin
|
|
thread post every ~200ms
|
|
12 On done:true → finalise post Mattermore plugin
|
|
13 Check response for [EOS] signal EngagementEngine
|
|
14 ConversationStore.Append(...) ConversationStore
|
|
```
|
|
|
|
### 7.2 Disengagement Flow
|
|
|
|
```
|
|
Step User / System Component
|
|
──── ────────────────────────────── ──────────────────
|
|
1 User replies "thanks that's all"
|
|
2 MessageHasBeenPosted fires
|
|
3 EngagementEngine.IsActive → true
|
|
4 Strip @-mention if present
|
|
5 Stop-word trie matches "that's all" StopWordTrie
|
|
6 EngagementEngine.Transition(Disengaging)
|
|
7 OllamaClient.ChatCompletion(lastMsg) (brief closing response)
|
|
8 Post closing message in thread
|
|
9 EngagementEngine.Transition(Sleeping)
|
|
```
|
|
|
|
### 7.3 Thread Participation
|
|
|
|
Thread replies continue the conversation without requiring a new @-mention.
|
|
The EngagementEngine tracks which threads it owns (via `ownerThread_{threadID}`
|
|
in KV). For posts in owned threads:
|
|
- If the EngagementEngine is Active for this user+thread → respond
|
|
- If Sleeping → respond once to wake, then continue
|
|
- If Disengaging → respond with closing note, then sleep
|
|
|
|
---
|
|
|
|
## 8. Security Model
|
|
|
|
### 8.1 Input Sanitization
|
|
|
|
- Strip control characters / zero-width Unicode from prompts before sending
|
|
to Ollama.
|
|
- Limit prompt length to 4096 characters (configurable via System Console).
|
|
- `TODO(design):` Should we block prompts that look like prompt injections?
|
|
("Ignore previous instructions...") Hard to do reliably — document risk
|
|
instead.
|
|
|
|
### 8.2 Output Safety
|
|
|
|
- Cap response tokens in the Ollama request (`options.num_predict`).
|
|
- `TODO(design):` Add a "Report this response" feedback mechanism? Defer.
|
|
|
|
### 8.3 Network Security
|
|
|
|
- `OllamaURL` must start with `http://` or `https://` — validate at config
|
|
load.
|
|
- Reject internal IP ranges unless explicitly enabled by a
|
|
`AllowPrivateNetworks` toggle (default: off for production).
|
|
- TLS verify enabled by default; optional `SkipTLSVerify` toggle (logged as
|
|
a warning).
|
|
|
|
### 8.4 Authorization
|
|
|
|
- If `AllowedUserIDs` is non-empty, reject requests from other users with a
|
|
"not authorized" ephemeral message.
|
|
- All plugin API calls are already scoped to authenticated Mattermost users.
|
|
|
|
### 8.5 Rate Limiting
|
|
|
|
- Per-user token bucket, replenish rate set via System Console.
|
|
- Default: 10 requests/minute. 0 = unlimited (logged as a warning).
|
|
- Burst: 1 (enforce smooth spacing).
|
|
|
|
---
|
|
|
|
## 9. Observability
|
|
|
|
### 9.1 Logging
|
|
|
|
| Level | When |
|
|
|---|---|
|
|
| `ERROR` | Ollama unreachable, config validation failure, KV store error |
|
|
| `WARN` | Rate limit hit, context window trimmed, TLS skipped |
|
|
| `INFO` | Plugin activated/deactivated, config changed, first request |
|
|
| `DEBUG` | Every request/response round-trip (with userID, model, token count, latency, engagement state) |
|
|
|
|
### 9.2 Metrics (future)
|
|
|
|
`TODO(design):` Expose Prometheus-style counters via a `/metrics` endpoint
|
|
if the Mattermost server has plugin metrics support:
|
|
- `mattermore_requests_total{user,model,status}`
|
|
- `mattermore_latency_seconds`
|
|
- `mattermore_tokens_total{direction="input|output"}`
|
|
- `mattermore_rate_limit_hits_total`
|
|
|
|
### 9.3 Error Reporting
|
|
|
|
Ephemeral posts with user-facing messages (not raw Go errors). Internal
|
|
errors logged at `ERROR` with stack trace.
|
|
|
|
---
|
|
|
|
## 10. Open Design Decisions
|
|
|
|
These are the unresolved questions that need answers before v0.1.0 ships.
|
|
|
|
| # | Question | Proposed | Alternatives | Decided? |
|
|
|---|---|---|---|---|
|
|
| D1 | Reply style | **Thread posts** (not ephemeral) — community sees the interaction | Ephemeral, channel-wide | ✅ → DECISIONS.md |
|
|
| D2 | Context scope | Per-channel per-user — each channel gets its own conversation | Per-user global, per-channel only, no context | ❌ |
|
|
| D3 | Context turns | Last 5 exchanges (10 messages) | Last N tokens, everything in TTL, sliding window | ❌ |
|
|
| D4 | Webapp UI | **None** — @-mention + thread replies cover all interaction | Channel header button, RHS panel | ✅ → DECISIONS.md |
|
|
| D5 | Model governance | All models available | Admin-restricted model list, least-privilege Ollama API key | ❌ |
|
|
| D6 | Thread replies | **Core feature** — the EngagementEngine auto-follows thread replies | Slash-command-only, ephemeral | ✅ → DECISIONS.md |
|
|
| D7 | `num_ctx` per request | Via `--context N` flag | System Console default only | ❌ |
|
|
| D8 | Auto-pull models | No (error + list available) | Yes (convenient but slow) | ❌ |
|
|
| D9 | Prompt injection guard | Defer (document risk) | Regex blocklist, LLM-as-judge pre-filter | ❌ |
|
|
| D10 | Metrics endpoint | Defer | `/metrics` via plugin HTTP handler | ❌ |
|
|
| D11 | Engagement scope | Per-user+channel | Per-user global, per-channel only | ❌ |
|
|
| D12 | Thread timeout | 15 minutes, configurable | Fixed 30min, no timeout | ❌ |
|
|
|
|
Each decision should be recorded in `DECISIONS.md` once resolved.
|
|
|
|
---
|
|
|
|
## 11. Deployment & Lifecycle
|
|
|
|
### 11.1 Build
|
|
|
|
```bash
|
|
make dist
|
|
```
|
|
|
|
Produces `dist/com.forkless.mattermore-0.1.0.tar.gz` containing the server
|
|
binaries and `plugin.json`.
|
|
|
|
### 11.2 Upload
|
|
|
|
Via Mattermost System Console → Plugins → Upload Plugin, or via REST API:
|
|
|
|
```bash
|
|
curl -X POST $MM_URL/api/v4/plugins \
|
|
-H "Authorization: Bearer $MM_TOKEN" \
|
|
-F "plugin=@dist/com.forkless.mattermore-0.1.0.tar.gz"
|
|
```
|
|
|
|
### 11.3 Upgrade
|
|
|
|
1. Upload new `.tar.gz` — Mattermost replaces the plugin binaries.
|
|
2. Plugin's `OnConfigurationChange()` fires (config preserved).
|
|
3. Bot account is re-fetched (not re-created) — idempotent.
|
|
4. If the KV schema changed, a migration in `OnActivate()` handles it.
|
|
|
|
### 11.4 Rollback
|
|
|
|
Re-upload the previous version's `.tar.gz`. No data migration needed if the
|
|
KV key schema hasn't changed. Bot account survives rollback. If it has,
|
|
restore from backup or `DECISIONS.md` records the migration path.
|
|
|
|
---
|
|
|
|
## 12. Future Considerations (v0.2+)
|
|
|
|
- **Multi-modal inputs** — Ollama supports images via `/api/chat` with
|
|
`images` field. Could allow image attachment in thread.
|
|
- **Multi-model routing** — Different models for different channel categories
|
|
(e.g. code-review channel uses codellama).
|
|
- **Tool calling** — Ollama supports tool definitions. Could let the
|
|
plugin fetch data from external APIs (weather, Jira, etc.).
|
|
- **Streaming into message attachments** — Render structured data (tables,
|
|
JSON, code blocks) with better formatting.
|
|
- **Conversation export** — Allow users to export an AI thread as markdown.
|