nexus/.planning/phases/28-ollama-integration/28-01-SUMMARY.md

phase	plan	subsystem	tags	dependency_graph	tech_stack	key_files	decisions	metrics	requirements_satisfied
28-ollama-integration	01	server	ollama model-catalog service routes unit-tests	requires provides affects ollamaService ollamaRoutes ollama-model-catalog server/src/app.ts server/src/routes/index.ts	added patterns AbortController-timeout catalog-based-recommendation assertCompanyAccess-authz	created modified server/src/services/ollama.ts server/src/data/ollama-model-catalog.json server/src/__tests__/ollama-service.test.ts server/src/routes/ollama.ts server/src/routes/index.ts server/src/app.ts	Force-added server/src/data/ with git add -f because root .gitignore has data/ pattern — source catalog is not generated data Used loadCatalog() with fs.readFileSync + fileURLToPath for reliable ESM-compatible JSON loading getRecommendedModel picks highest quality-ranked variant within 75% RAM budget using QUALITY_RANK map listOllamaModels includes its own AbortController timeout — guards against Ollama going down mid-request	duration completed_date tasks_completed files_modified 3 minutes 2026-04-02 2 6	OLLA-01 OLLA-02 OLLA-04 OLLA-05

Phase 28 Plan 01: Ollama Service, Routes, and Model Catalog Summary

One-liner: Ollama detection + model listing service with AbortController timeouts, static 5-family model catalog for RAM-based recommendations, and Express routes at /companies/:companyId/ollama/status and /models.

Tasks Completed

Task	Name	Commit	Files
TDD RED	Add failing tests for ollama service	2169a21e	server/src/tests/ollama-service.test.ts
TDD GREEN (Task 1)	ollamaService + model catalog	4fce48e1	server/src/services/ollama.ts, server/src/data/ollama-model-catalog.json
Task 2	Ollama HTTP routes + app mount	e45a2578	server/src/routes/ollama.ts, routes/index.ts, app.ts

What Was Built

ollamaService (server/src/services/ollama.ts)

• detectOllama(): Probes OLLAMA_BASE_URL/api/version with a 3s AbortController timeout. Returns { installed: true, version } on success, { installed: false, installUrl } on any error or timeout.
• listOllamaModels(): Fetches OLLAMA_BASE_URL/api/tags, maps Ollama's native response (with details.parameter_size, details.quantization_level, details.family) to OllamaModel[]. Returns [] on any error.
• getRecommendedModel(models, systemRamBytes): Reads the static catalog, computes usable RAM as 75% of total, ranks catalog variants by quality tier (best > reasoning > balanced > fast), and marks the single best-fitting model as recommended: true with a human-readable recommendationReason.
• Respects process.env.OLLAMA_BASE_URL override — never hard-codes localhost:11434.

Model Catalog (server/src/data/ollama-model-catalog.json)

5 families with 11 total variants:

• qwen2: qwen2.5-coder 7b/14b/32b
• llama: llama3.2 3b, llama3.1 8b/70b
• mistral: mistral 7b/22b
• phi: phi4 14b
• deepseek: deepseek-r1 7b/32b

Ollama Routes (server/src/routes/ollama.ts)

• GET /companies/:companyId/ollama/status — returns OllamaStatus JSON
• GET /companies/:companyId/ollama/models — returns { models: OllamaModel[], ramGb: number }. Short-circuits to { models: [], ramGb: 0 } if Ollama not installed.
• Both routes gated with assertCompanyAccess(req, companyId).
• Mounted in app.ts as api.use(ollamaRoutes()) after agentRoutes.

Test Coverage

12 unit tests (all passing):

• detectOllama: success, ECONNREFUSED failure, AbortController timeout, non-ok response
• listOllamaModels: success with full OllamaTagsResponse shape, ECONNREFUSED, non-ok
• getRecommendedModel: 8GB → 7b, 32GB → 32b, unknown models → all false, empty input, RAM too low → no recommendation

Deviations from Plan

Auto-fixed Issues

1. [Rule 3 - Blocking] server/src/data/ gitignored by root .gitignore

• Found during: Task 1 commit
• Issue: Root .gitignore has data/ pattern; server/src/data/ollama-model-catalog.json was silently ignored
• Fix: Used git add -f to force-track the file. The catalog is source code (not generated data), so this is correct behavior.
• Files modified: .gitignore not modified — file force-added
• Commit: 4fce48e1

Known Stubs

None — all functions return real data structures. Routes wire directly to service functions. No placeholder values in the response paths.

Self-Check: PASSED

Files exist:

• server/src/services/ollama.ts: FOUND
• server/src/data/ollama-model-catalog.json: FOUND
• server/src/tests/ollama-service.test.ts: FOUND
• server/src/routes/ollama.ts: FOUND

Commits exist:

• 2169a21e: FOUND (test RED)
• 4fce48e1: FOUND (feat GREEN + catalog)
• e45a2578: FOUND (feat routes)