@@ -0,0 +1,505 @@
1+# Per-Mysis Configuration Implementation Plan
2+
3+**Date:** 2026-02-04
4+**Status:** Ready for implementation
5+
6+## Goal
7+
8+Enable per-mysis provider/model/temperature configuration and document OpenCode Zen free models.
9+
10+## Architecture
11+
12+The current singleton provider pattern will be replaced with a factory pattern. Each mysis will own a dedicated provider instance configured with its stored model and temperature. Config defines defaults; database stores per-mysis overrides.
13+
14+## Tech Stack
15+
16+Go 1.22+, SQLite (modernc.org/sqlite), go-openai, BurntSushi/toml
17+
18+---
19+
20+## Phase 1: Documentation
21+
22+**Files:**
23+- Create: `documentation/OPENCODE_ZEN_MODELS.md`
24+
25+**Content:**
26+```markdown
27+# OpenCode Zen Models
28+
29+Models available through OpenCode Zen for use with Zoea Nova.
30+
31+## Free Models
32+
33+These models are free during their beta period:
34+
35+| Model | Model ID | Endpoint | Tool Support |
36+|-------|----------|----------|--------------|
37+| GLM 4.7 Free | `glm-4.7-free` | `/v1/chat/completions` | Yes |
38+| Kimi K2.5 Free | `kimi-k2.5-free` | `/v1/chat/completions` | Yes |
39+| MiniMax M2.1 Free | `minimax-m2.1-free` | `/v1/messages` | Yes |
40+| Big Pickle | `big-pickle` | `/v1/chat/completions` | Yes |
41+| GPT 5 Nano | `gpt-5-nano` | `/v1/responses` | Yes |
42+
43+## Configuration
44+
45+```toml
46+[providers.opencode_zen]
47+endpoint = "https://api.opencode.ai/v1"
48+model = "glm-4.7-free"
49+temperature = 0.7
50+```
51+
52+Credentials are stored in `~/.zoea-nova/credentials.json`.
53+
54+## References
55+
56+- [OpenCode Zen Documentation](https://opencode.ai/docs/zen/)
57+- [Model List API](https://opencode.ai/zen/v1/models)
58+```
59+
60+---
61+
62+## Phase 2: Config Changes
63+
64+**Files:**
65+- Modify: `internal/config/config.go`
66+- Modify: `config.toml`
67+
68+**Changes to `config.go`:**
69+
70+```go
71+// ProviderConfig holds LLM provider settings.
72+type ProviderConfig struct {
73+ Endpoint string `toml:"endpoint"`
74+ Model string `toml:"model"`
75+ Temperature float64 `toml:"temperature"`
76+}
77+
78+// In DefaultConfig():
79+Providers: map[string]ProviderConfig{
80+ "ollama": {
81+ Endpoint: "http://localhost:11434",
82+ Model: "llama3",
83+ Temperature: 0.7,
84+ },
85+},
86+
87+// In applyEnvOverrides():
88+if v := os.Getenv("ZOEA_OLLAMA_TEMPERATURE"); v != "" {
89+ if f, err := strconv.ParseFloat(v, 64); err == nil {
90+ if p, ok := cfg.Providers["ollama"]; ok {
91+ p.Temperature = f
92+ cfg.Providers["ollama"] = p
93+ }
94+ }
95+}
96+
97+if v := os.Getenv("ZOEA_OPENCODE_TEMPERATURE"); v != "" {
98+ if f, err := strconv.ParseFloat(v, 64); err == nil {
99+ if p, ok := cfg.Providers["opencode_zen"]; ok {
100+ p.Temperature = f
101+ cfg.Providers["opencode_zen"] = p
102+ }
103+ }
104+}
105+```
106+
107+**Changes to `config.toml`:**
108+
109+```toml
110+[providers.ollama]
111+endpoint = "http://localhost:11434"
112+model = "qwen3:4b"
113+temperature = 0.7
114+
115+[providers.opencode_zen]
116+endpoint = "https://api.opencode.ai/v1"
117+model = "glm-4.7-free"
118+temperature = 0.7
119+```
120+
121+---
122+
123+## Phase 3: Store Changes
124+
125+**Files:**
126+- Modify: `internal/store/schema.sql`
127+- Modify: `internal/store/myses.go`
128+
129+**Changes to `schema.sql`:**
130+
131+```sql
132+INSERT OR REPLACE INTO schema_version (version) VALUES (4);
133+
134+CREATE TABLE IF NOT EXISTS myses (
135+ id TEXT PRIMARY KEY,
136+ name TEXT NOT NULL,
137+ provider TEXT NOT NULL,
138+ model TEXT NOT NULL,
139+ temperature REAL NOT NULL DEFAULT 0.7,
140+ state TEXT NOT NULL DEFAULT 'idle',
141+ created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
142+ updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
143+);
144+```
145+
146+**Changes to `myses.go`:**
147+
148+```go
149+// Mysis struct
150+type Mysis struct {
151+ ID string
152+ Name string
153+ Provider string
154+ Model string
155+ Temperature float64
156+ State MysisState
157+ CreatedAt time.Time
158+ UpdatedAt time.Time
159+}
160+
161+// CreateMysis signature
162+func (s *Store) CreateMysis(name, provider, model string, temperature float64) (*Mysis, error)
163+
164+// UpdateMysisConfig signature
165+func (s *Store) UpdateMysisConfig(id, provider, model string, temperature float64) error
166+
167+// Scan functions updated to include temperature
168+```
169+
170+---
171+
172+## Phase 4: Provider Changes
173+
174+**Files:**
175+- Modify: `internal/provider/ollama.go`
176+- Modify: `internal/provider/opencode.go`
177+- Modify: `internal/provider/provider.go`
178+- Create: `internal/provider/factory.go`
179+- Modify: `internal/provider/mock.go`
180+
181+**Changes to `provider.go`:**
182+
183+```go
184+// ProviderFactory creates provider instances with specific configurations.
185+type ProviderFactory interface {
186+ Name() string
187+ Create(model string, temperature float64) Provider
188+}
189+
190+// Registry holds provider factories.
191+type Registry struct {
192+ factories map[string]ProviderFactory
193+}
194+
195+func (r *Registry) RegisterFactory(f ProviderFactory) {
196+ r.factories[f.Name()] = f
197+}
198+
199+func (r *Registry) Create(name, model string, temperature float64) (Provider, error) {
200+ f, ok := r.factories[name]
201+ if !ok {
202+ return nil, ErrProviderNotFound
203+ }
204+ return f.Create(model, temperature), nil
205+}
206+```
207+
208+**New `factory.go`:**
209+
210+```go
211+package provider
212+
213+// OllamaFactory creates Ollama providers.
214+type OllamaFactory struct {
215+ endpoint string
216+}
217+
218+func NewOllamaFactory(endpoint string) *OllamaFactory {
219+ return &OllamaFactory{endpoint: endpoint}
220+}
221+
222+func (f *OllamaFactory) Name() string { return "ollama" }
223+
224+func (f *OllamaFactory) Create(model string, temperature float64) Provider {
225+ return NewOllamaWithTemp(f.endpoint, model, temperature)
226+}
227+
228+// OpenCodeFactory creates OpenCode Zen providers.
229+type OpenCodeFactory struct {
230+ endpoint string
231+ apiKey string
232+}
233+
234+func NewOpenCodeFactory(endpoint, apiKey string) *OpenCodeFactory {
235+ return &OpenCodeFactory{endpoint: endpoint, apiKey: apiKey}
236+}
237+
238+func (f *OpenCodeFactory) Name() string { return "opencode_zen" }
239+
240+func (f *OpenCodeFactory) Create(model string, temperature float64) Provider {
241+ return NewOpenCodeWithTemp(f.endpoint, model, f.apiKey, temperature)
242+}
243+```
244+
245+**Changes to `ollama.go`:**
246+
247+```go
248+type OllamaProvider struct {
249+ client *openai.Client
250+ model string
251+ temperature float64
252+}
253+
254+func NewOllamaWithTemp(endpoint, model string, temperature float64) *OllamaProvider {
255+ config := openai.DefaultConfig("")
256+ config.BaseURL = endpoint + "/v1"
257+ return &OllamaProvider{
258+ client: openai.NewClientWithConfig(config),
259+ model: model,
260+ temperature: temperature,
261+ }
262+}
263+
264+// In Chat/ChatWithTools, add Temperature to request:
265+resp, err := p.client.CreateChatCompletion(ctx, openai.ChatCompletionRequest{
266+ Model: p.model,
267+ Messages: toOpenAIMessages(messages),
268+ Temperature: float32(p.temperature),
269+})
270+```
271+
272+**Changes to `opencode.go`:**
273+
274+Similar temperature field and usage as ollama.go.
275+
276+---
277+
278+## Phase 5: Commander Changes
279+
280+**Files:**
281+- Modify: `internal/core/commander.go`
282+
283+**Key changes:**
284+
285+```go
286+// Commander now uses factory pattern
287+type Commander struct {
288+ // ... existing fields
289+ registry *provider.Registry // Now holds factories
290+}
291+
292+// CreateMysis creates provider using factory
293+func (c *Commander) CreateMysis(name, providerName string) (*Mysis, error) {
294+ provCfg := c.config.Providers[providerName]
295+
296+ // Create provider instance for this mysis
297+ p, err := c.registry.Create(providerName, provCfg.Model, provCfg.Temperature)
298+ if err != nil {
299+ return nil, err
300+ }
301+
302+ // Store with model and temperature
303+ stored, err := c.store.CreateMysis(name, providerName, provCfg.Model, provCfg.Temperature)
304+ // ...
305+}
306+
307+// ConfigureMysis now accepts model parameter
308+func (c *Commander) ConfigureMysis(id, providerName, model string) error {
309+ provCfg := c.config.Providers[providerName]
310+ temperature := provCfg.Temperature
311+
312+ // Create new provider with specified model
313+ p, err := c.registry.Create(providerName, model, temperature)
314+ // ...
315+
316+ c.store.UpdateMysisConfig(id, providerName, model, temperature)
317+ mysis.SetProvider(p)
318+}
319+
320+// LoadMyses creates providers from stored config
321+func (c *Commander) LoadMyses() error {
322+ for _, sm := range stored {
323+ p, err := c.registry.Create(sm.Provider, sm.Model, sm.Temperature)
324+ // ...
325+ }
326+}
327+```
328+
329+---
330+
331+## Phase 6: TUI Changes
332+
333+**Files:**
334+- Modify: `internal/tui/input.go`
335+- Modify: `internal/tui/app.go`
336+
337+**Changes to `input.go`:**
338+
339+```go
340+const (
341+ InputModeNone InputMode = iota
342+ InputModeBroadcast
343+ InputModeMessage
344+ InputModeNewMysis
345+ InputModeConfigProvider
346+ InputModeConfigModel // NEW
347+)
348+
349+// In SetMode():
350+case InputModeConfigModel:
351+ m.textInput.Placeholder = "Enter model name..."
352+ m.textInput.Prompt = inputPromptStyle.Render("🔧 ") + " "
353+```
354+
355+**Changes to `app.go`:**
356+
357+```go
358+// Add field to track pending provider during config flow
359+type Model struct {
360+ // ... existing fields
361+ pendingProvider string // Temporary storage during config flow
362+}
363+
364+// In handleInputKey, case InputModeConfigProvider:
365+case InputModeConfigProvider:
366+ // Validate provider exists
367+ if value != "ollama" && value != "opencode_zen" {
368+ m.err = fmt.Errorf("unknown provider: %s", value)
369+ m.input.Reset()
370+ return m, nil
371+ }
372+ // Store provider and prompt for model
373+ m.pendingProvider = value
374+ m.input.SetMode(InputModeConfigModel, m.input.TargetID())
375+ return m, m.input.Focus()
376+
377+case InputModeConfigModel:
378+ m.err = m.commander.ConfigureMysis(m.input.TargetID(), m.pendingProvider, value)
379+ m.pendingProvider = ""
380+```
381+
382+---
383+
384+## Phase 7: Main.go Changes
385+
386+**Files:**
387+- Modify: `cmd/zoea/main.go`
388+
389+**Changes:**
390+
391+```go
392+func initProviders(cfg *config.Config, creds *config.Credentials) *provider.Registry {
393+ registry := provider.NewRegistry()
394+
395+ // Register Ollama factory
396+ if ollCfg, ok := cfg.Providers["ollama"]; ok {
397+ factory := provider.NewOllamaFactory(ollCfg.Endpoint)
398+ registry.RegisterFactory(factory)
399+ }
400+
401+ // Register OpenCode Zen factory
402+ if zenCfg, ok := cfg.Providers["opencode_zen"]; ok {
403+ apiKey := creds.GetAPIKey("opencode_zen")
404+ if apiKey != "" {
405+ factory := provider.NewOpenCodeFactory(zenCfg.Endpoint, apiKey)
406+ registry.RegisterFactory(factory)
407+ }
408+ }
409+
410+ return registry
411+}
412+```
413+
414+---
415+
416+## Phase 8: Tests
417+
418+**Files:**
419+- Modify: `internal/config/config_test.go`
420+- Modify: `internal/store/store_test.go`
421+- Modify: `internal/core/commander_test.go`
422+
423+**Test additions:**
424+
425+```go
426+// config_test.go
427+func TestLoadWithTemperature(t *testing.T) {
428+ content := `
429+[providers.ollama]
430+endpoint = "http://localhost:11434"
431+model = "qwen3:4b"
432+temperature = 0.5
433+`
434+ // ... verify temperature is parsed
435+}
436+
437+// store_test.go
438+func TestMysisCRUDWithTemperature(t *testing.T) {
439+ mysis, err := s.CreateMysis("test", "ollama", "llama3", 0.5)
440+ // ... verify temperature is stored and retrieved
441+}
442+
443+// commander_test.go
444+func TestCommanderConfigureMysisWithModel(t *testing.T) {
445+ // ... verify model can be changed per-mysis
446+}
447+```
448+
449+---
450+
451+## Phase 9: Verification
452+
453+1. Run `make test` - all tests must pass
454+2. Run `make build` - compilation must succeed
455+3. Manual test: create mysis, configure with different model, verify provider uses correct model
456+4. Update `KNOWN_ISSUES.md` to mark first item complete
457+
458+---
459+
460+## Summary of Files Changed
461+
462+| File | Action |
463+|------|--------|
464+| `documentation/OPENCODE_ZEN_MODELS.md` | Create |
465+| `internal/config/config.go` | Modify |
466+| `internal/config/config_test.go` | Modify |
467+| `config.toml` | Modify |
468+| `internal/store/schema.sql` | Modify |
469+| `internal/store/myses.go` | Modify |
470+| `internal/store/store_test.go` | Modify |
471+| `internal/provider/provider.go` | Modify |
472+| `internal/provider/factory.go` | Create |
473+| `internal/provider/ollama.go` | Modify |
474+| `internal/provider/opencode.go` | Modify |
475+| `internal/provider/mock.go` | Modify |
476+| `internal/core/commander.go` | Modify |
477+| `internal/core/commander_test.go` | Modify |
478+| `internal/tui/input.go` | Modify |
479+| `internal/tui/app.go` | Modify |
480+| `cmd/zoea/main.go` | Modify |
481+| `documentation/KNOWN_ISSUES.md` | Modify |
482+
483+---
484+
485+## Database Migration Note
486+
487+This change requires schema v4 with a new `temperature` column. Per AGENTS.md, no data migrations are supported. Users must wipe their database:
488+
489+```bash
490+rm ~/.zoea-nova/zoea.db*
491+```
492+
493+---
494+
495+## Implementation Order
496+
497+1. Documentation (OpenCode Zen models)
498+2. Config layer (add temperature field)
499+3. Store layer (schema + CRUD)
500+4. Provider layer (factory pattern)
501+5. Commander layer (use factories)
502+6. TUI layer (model selection)
503+7. Main.go (register factories)
504+8. Tests (verify all layers)
505+9. Verification (build + manual test)