feat: Ollama Integration with Separate LLM/Embedding Model Support

[tazmon95]

🚀 Ollama Integration with Separate LLM/Embedding Model Support

📋 Summary

This PR adds comprehensive Ollama integration to Archon, enabling users to configure and use
Ollama for both LLM and embedding services. The integration supports flexible deployment options
including single-host or dual-host configurations, automatic model discovery, and
multi-dimensional embedding support in the database.

✨ Changes Made

Core Features

• ✅ Ollama Provider Support - Select Ollama as your LLM provider alongside OpenAI and Google
• ✅ Dual Model Configuration - Separate models for chat/completion vs embedding generation
• ✅ Auto Model Discovery - Automatically discover and list available models from Ollama instances
• ✅ Flexible Deployment - Single-host or dual-host Ollama configurations
• ✅ Multi-Dimensional Embeddings - Database supports 384, 768, 1024, 1536, and 3072 dimensions

Recent Improvements (Latest Commits)

• 🔧 Fixed API Status Indicators - Provider indicators now correctly show green/red based on
  actual connectivity
• 🔒 Secure Credential Checking - New dedicated endpoint for frontend status checks with proper
  decryption
• ⚡ Performance Optimization - Reduced status polling from 2s to 30s (15x improvement)
• 🛡️ Defensive Error Handling - Fixed credential service initialization and caching issues

📝 Type of Change

• New feature (non-breaking change which adds functionality)
• Bug fix (non-breaking change which fixes an issue)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Performance improvement
• Code refactoring

🔧 Affected Services

• Frontend (React UI)
• Server (FastAPI backend)
• MCP Server (Model Context Protocol)
• Agents (PydanticAI service)
• Database (migrations/schema)
• Docker/Infrastructure
• Documentation site

🧪 Testing

• All existing tests pass
• Added new tests for new functionality
• Manually tested affected user flows
• Docker builds succeed for all services

Test Evidence

  # Frontend development server runs successfully
  cd archon-ui-main && npm run dev
  # ✓ Vite development server starts on port 3737

  # Backend services start successfully
  docker compose up -d
  # ✓ archon-server: Healthy
  # ✓ archon-mcp: Running
  # ✓ archon-ui: Running

  # Database migrations applied successfully
  # ✓ Multi-dimensional embedding columns created
  # ✓ Service can connect with proper permissions

  # Provider status indicators working
  # ✓ OpenAI shows green when configured
  # ✓ Ollama shows green when connected
  # ✓ Unconfigured providers show red correctly

  # Tested configurations
  # ✓ Single-host Ollama setup
  # ✓ Dual-host Ollama setup
  # ✓ OpenAI compatibility maintained
  # ✓ Credential encryption/decryption

✔️ Checklist

• My code follows the service architecture patterns
• If using an AI coding assistant, I used the CLAUDE.md rules
• I have added tests that prove my fix/feature works
• All new and existing tests pass locally
• My changes generate no new warnings
• I have updated relevant documentation
• I have verified no regressions in existing features

💥 Breaking Changes

None. This PR is fully backward compatible. Existing provider configurations (OpenAI, Google,
etc.) continue to work exactly as before. Ollama integration is additive functionality.

📌 Additional Notes

Key Capabilities Added:

• Ollama Provider Support: Users can now select Ollama as their LLM provider alongside OpenAI and
  Google
• Separate LLM and Embedding Models: Configure different models for chat/completion vs embedding
  generation
• Model Discovery: Automatically discover and list available models from configured Ollama
  instances
• Flexible Deployment: Support for single-host setup (both services on same machine) or dual-host
  setup (separate machines)
• Multi-Dimensional Embeddings: Database now supports various embedding dimensions used by
  different models

Configuration Features:

• LLM Instance: Configure Ollama instance for chat/completion models
• Embedding Instance: Configure separate Ollama instance for embedding models
• Single-Host Convenience: Quick setup option for users running both on the same host
• Model Selection: Browse and select from available models with compatibility indicators
• Status Indicators: Real-time connection status for all providers

Database Enhancements:

• Support for embeddings of different dimensions (384, 768, 1024, 1536, 3072)
• Proper indexes for each embedding dimension
• Model tracking columns to record which models were used
• Compatible with upstream hybrid search functionality

UI/UX Improvements:

• Provider-specific configuration interfaces
• Model selection shows only for appropriate providers
• Real-time connection status indicators with proper credential handling
• Manual connection testing to avoid excessive API calls
• Reduced polling frequency for better performance

Recent Fixes (from rebase):

• Fixed encrypted credential handling in status indicators
• Added dedicated endpoint for secure credential status checking
• Improved cache invalidation between credential and LLM provider services
• Added defensive imports to prevent initialization errors
• Properly handles HTTPX client cleanup warnings

Configuration Examples:

Single Host Setup:
LLM Provider: Ollama
LLM URL: http://localhost:11434/v1
LLM Model: llama3.1:8b
Embedding URL: http://localhost:11434/v1
Embedding Model: nomic-embed-text:latest

Dual Host Setup:
LLM Provider: Ollama
LLM URL: http://192.168.1.100:11434/v1
LLM Model: llama3.1:8b
Embedding URL: http://192.168.1.101:11434/v1
Embedding Model: nomic-embed-text:latest

This integration enables users to leverage local Ollama deployments for both LLM and embedding
needs, providing an alternative to cloud-based providers while maintaining full compatibility with
existing functionality.

Commit History:

This PR includes 20 commits covering the full Ollama integration implementation, provider status
fixes, and performance improvements. The branch has been successfully rebased on the latest main
branch including:

• New stable branch instructions
• MCP server optimization with tool consolidation (feat: MCP server optimization with tool consolidation and vertical sl… #647)

Summary by CodeRabbit

• New Features

  • Multi-instance Ollama management with health checks, model discovery/selection modals, and status badges.
  • Backend endpoints for Ollama discovery, validation, health, embedding routing, and cache control.
  • Multi-dimensional embeddings and hybrid search support across stored content.

• Enhancements

  • RAG settings revamped with provider grid, Ollama-ready flows, and credential status checks.
  • Automatic embedding routing, model tracking, and provider-aware model fallbacks.

• Documentation

  • Added comprehensive database migration guide and SQL scripts.

• Tests

  • New coverage for Ollama UI components and LLM provider fallback behavior.

• Chores

  • Added UAT/ to .gitignore, dev proxy routes, Docker env tweak, and expanded test discovery.

[coderabbitai]

Walkthrough

Adds comprehensive Ollama multi-instance support across frontend and backend: new React settings panels and modals, typed services, and health/model discovery flows; backend FastAPI routes for discovery, validation, health, and embedding routing; provider routing updates; dynamic multi-dimensional embeddings with DB migrations; dev proxies, Docker tweaks, and expanded tests.

Changes

Cohort / File(s)	Summary
Environment & Ignore .env.example, .gitignore	Removes embedding dimension example from env; adds UAT/ to Git ignore.
Frontend Settings UI (Ollama) archon-ui-main/src/components/settings/OllamaConfigurationPanel.tsx, archon-ui-main/src/components/settings/OllamaInstanceHealthIndicator.tsx, archon-ui-main/src/components/settings/OllamaModelDiscoveryModal.tsx, archon-ui-main/src/components/settings/OllamaModelSelectionModal.tsx, archon-ui-main/src/components/settings/RAGSettings.tsx	Adds multi-instance Ollama configuration panel, health indicator, model discovery/selection modals, and integrates into RAG settings with provider switching and health/metrics.
Frontend Types archon-ui-main/src/components/settings/types/OllamaTypes.ts	Introduces comprehensive TypeScript types for Ollama instances, health, discovery, events, and UI props.
Frontend Services archon-ui-main/src/services/credentialsService.ts, archon-ui-main/src/services/ollamaService.ts	Adds credential APIs for Ollama instances and status checks; introduces Ollama service client for discovery, health, validation, routing, and capability checks.
Frontend Tooling archon-ui-main/vite.config.ts, archon-ui-main/vitest.config.ts	Adds /health and /socket.io proxies; expands Vitest include globs for new components/services tests.
Docker Compose docker-compose.yml	Adds DOCKER_ENV=true; comments out VITE_API_URL to use relative proxy.
DB Migration Guide migration/DB_UPGRADE_INSTRUCTIONS.md	Adds migration instructions covering backup, upgrade, and validation steps for multi-dimensional embeddings.
DB Scripts — Backup/Upgrade/Validate migration/backup_database.sql, migration/upgrade_database.sql, migration/complete_setup.sql, migration/validate_migration.sql	Implements multi-dimensional embedding schema, indexes, helper/search functions, migration from legacy embeddings, backup utilities, and validation scripts.
Backend API — Ollama python/src/server/api_routes/ollama_api.py, python/src/server/main.py	Adds FastAPI router with endpoints for model discovery, health, validation, embedding routing, cache, storage, and capability tests; mounts router.
Backend API — Credentials python/src/server/api_routes/settings_api.py	Adds /api/credentials/status-check endpoint to report decrypted credential presence/status.
Backend Services — LLM/Provider python/src/server/services/llm_provider_service.py, python/src/server/services/provider_discovery_service.py	Extends LLM client to route via optimal Ollama instance; adds provider discovery service with caching and health checks across providers.
Backend Services — Embeddings python/src/server/services/embeddings/__init__.py, python/src/server/services/embeddings/contextual_embedding_service.py, python/src/server/services/embeddings/multi_dimensional_embedding_service.py	Adds multi-dimensional embedding service and exports; updates contextual embedding model choice logic; exposes new service.
Backend Services — Ollama python/src/server/services/ollama/__init__.py, python/src/server/services/ollama/embedding_router.py, python/src/server/services/ollama/model_discovery_service.py	Adds Ollama embedding router with dimension-aware routing and caching; adds model discovery service with capabilities and health checks.
Backend Storage Services python/src/server/services/storage/code_storage_service.py, python/src/server/services/storage/document_storage_service.py	Stores embeddings into dimension-specific columns; records llm_chat_model, embedding_model, and embedding_dimension; adds async summary path.
Backend Credentials Service python/src/server/services/credential_service.py	Adds cache invalidation on rag credential changes; provider-specific fallback for model selection.
Tests python/tests/test_async_llm_provider_service.py, archon-ui-main/test/...Ollama*.test.tsx (via vitest include)	Adds tests for OpenAI-missing key with Ollama fallback and failure path; enables discovery of new frontend tests.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor User
  participant Panel as OllamaConfigurationPanel (FE)
  participant CredSvc as credentialsService (FE)
  participant OllamaSvc as ollamaService (FE)
  participant API as FastAPI Backend (/api)
  participant Disc as ModelDiscoveryService (BE)
  participant Router as EmbeddingRouter (BE)
  Note over User,Panel: Configure instances and discover models

  User->>Panel: Open settings
  Panel->>CredSvc: getOllamaInstances()
  CredSvc->>API: GET /api/credentials (existing)
  API-->>CredSvc: Instances data
  CredSvc-->>Panel: Instances

  User->>Panel: Test connection
  Panel->>OllamaSvc: testConnection(instanceUrl)
  OllamaSvc->>API: GET /api/ollama/instances/health?instance_urls=...
  API->>Disc: check_instance_health(...)
  Disc-->>API: Health summary
  API-->>OllamaSvc: Health JSON
  OllamaSvc-->>Panel: Result
  Panel-->>User: Toast: Online/Offline

  User->>Panel: Discover/select models
  Panel->>OllamaSvc: discoverModels({urls, includeCapabilities})
  OllamaSvc->>API: POST /api/ollama/models
  API->>Disc: discover_models_from_multiple_instances(...)
  Disc-->>API: {chat_models, embedding_models, host_status}
  API-->>OllamaSvc: Discovery response
  OllamaSvc-->>Panel: Models list
  Panel-->>User: Modal with models

Loading

sequenceDiagram
  autonumber
  actor BE as Storage Service
  participant LLM as LLM Provider Service
  participant ER as EmbeddingRouter
  participant DB as Supabase (PG)
  Note over BE,DB: Store embeddings with dimension-aware columns

  BE->>LLM: get_embedding_model_with_routing()
  LLM-->>BE: (model_name, instance_url)
  BE->>ER: route_embedding(model_name, instance_url)
  ER-->>BE: {target_column, dimensions}
  BE->>DB: insert { [target_column]=embedding, embedding_model, embedding_dimension, llm_chat_model }
  DB-->>BE: OK

Loading

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~120 minutes

Possibly related PRs

• Enhanced the hybrid search strategy with tsvector keyword matching #539 — Adds hybrid_search functions and related DB changes; overlaps with migration/hybrid search updates here.
• Feature: Add Ollama embedding service and model selection functionality #560 — Expands Ollama integration across frontend/backends; strongly overlaps with services, components, and APIs in this PR.

Suggested labels

enhancement

Suggested reviewers

• coleam00
• leex279
• sean-eskerium

Poem

I hopped through models, ports, and logs,
Tunneled through proxies, dodged the fogs.
New routes hum health, embeddings glide,
Multi-d dims now side-by-side.
With twitches keen, I press “Discover!”—
A carrot toast: our configs hover. 🥕🐇

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The PR title "feat: Ollama Integration with Separate LLM/Embedding Model Support" accurately and concisely summarizes the primary change — adding Ollama support and separate LLM/embedding model configuration — and aligns with the large frontend, backend, and DB changes in the changeset. It is specific, clear, and suitable as a single-line title for reviewers scanning history.
Description Check	✅ Passed	The PR description is comprehensive and contains a clear summary, detailed changes, affected services, testing notes, and a breaking-changes statement, so it largely satisfies the template's intent. However the body does not strictly follow the repository template formatting: the "Type of Change" and "Checklist" sections are not using the required [ ]/[x] checkbox markers and multiple type options are listed instead of a single selected option, which reduces machine-readability and template compliance. Overall the content is mostly complete but needs minor formatting fixes to match the template exactly.
Docstring Coverage	✅ Passed	Docstring coverage is 92.47% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate Docstrings

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/ollama-integration

Tip

👮 Agentic pre-merge checks are now available in preview!

Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.

• Built-in checks – Quickly apply ready-made checks to enforce title conventions, require pull request descriptions that follow templates, validate linked issues for compliance, and more.
• Custom agentic checks – Define your own rules using CodeRabbit’s advanced agentic capabilities to enforce organization-specific policies and workflows. For example, you can instruct CodeRabbit’s agent to verify that API documentation is updated whenever API schema files are modified in a PR. Note: Upto 5 custom checks are currently allowed during the preview period. Pricing for this feature will be announced in a few weeks.

Please see the documentation for more information.

Example:

reviews:
  pre_merge_checks:
    custom_checks:
      - name: "Undocumented Breaking Changes"
        mode: "warning"
        instructions: |
          Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the "Breaking Change" section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal).

Please share your feedback with us on this Discord post.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 47

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (7)

python/src/server/api_routes/settings_api.py (1)

346-392: Do not return decrypted secrets to clients — mask values and require admin auth

Endpoint python/src/server/api_routes/settings_api.py (≈lines 346–392) currently returns decrypted credential values; this is a high-severity secret leak and must be fixed now.

• Return only has_value: bool and masked_value: str (mask all but e.g. last 4 chars); remove plaintext "value" from responses.
• Accept a Pydantic request model (CredentialStatusCheckRequest) and add a _mask_secret helper to produce masked_value.
• Gate the endpoint with your admin auth dependency (add Depends() to the route). I found no router-level Depends in api_routes, so add the appropriate project auth dependency.
• Update tests (python/tests/test_settings_api.py) to assert masked responses instead of decrypted values.

python/src/server/services/storage/document_storage_service.py (3)

61-69: Fix credential service aliasing and guard rag_settings.

You import credential_service as cred_service but later use credential_service. Also ensure rag_settings is always defined.

Apply this diff:

-            from ..credential_service import credential_service as cred_service
-            rag_settings = await cred_service.get_credentials_by_category("rag_strategy")
+            from ..credential_service import credential_service as cred_service
+            rag_settings: dict[str, Any] = await cred_service.get_credentials_by_category("rag_strategy")

And initialize a safe default before the try:

-        # Load settings from database
+        # Load settings from database
+        rag_settings: dict[str, Any] = {}
         try:

---

146-155: NameError at runtime: use imported alias cred_service.

credential_service is undefined in this scope.

Apply this diff:

-            use_contextual_embeddings = await credential_service.get_credential(
+            use_contextual_embeddings = await cred_service.get_credential(
                 "USE_CONTEXTUAL_EMBEDDINGS", "false", decrypt=True
             )

---

59-77: Add exc_info to error logs when falling back to defaults.

Preserve stack traces for observability per guidelines.

Apply this diff:

-        except Exception as e:
-            search_logger.warning(f"Failed to load storage settings: {e}, using defaults")
+        except Exception as e:
+            search_logger.warning(f"Failed to load storage settings: {e}, using defaults", exc_info=True)

python/src/server/services/storage/code_storage_service.py (1)

946-961: Blocking sleep in async function.

time.sleep blocks the event loop. Use asyncio.sleep.

-                    import time
-
-                    time.sleep(retry_delay)
+                    await asyncio.sleep(retry_delay)

migration/complete_setup.sql (2)

477-565: Hybrid pages search still references legacy column “embedding”.

This will fail after multi‑dim change. Use embedding_1536 (legacy default) or route dimensionally.

Apply this diff:

-    WITH vector_results AS (
+    WITH vector_results AS (
         -- Vector similarity search
         SELECT 
             cp.id,
             cp.url,
             cp.chunk_number,
             cp.content,
             cp.metadata,
             cp.source_id,
-            1 - (cp.embedding <=> query_embedding) AS vector_sim
+            1 - (cp.embedding_1536 <=> query_embedding) AS vector_sim
         FROM archon_crawled_pages cp
         WHERE cp.metadata @> filter
             AND (source_filter IS NULL OR cp.source_id = source_filter)
-            AND cp.embedding IS NOT NULL
-        ORDER BY cp.embedding <=> query_embedding
+            AND cp.embedding_1536 IS NOT NULL
+        ORDER BY cp.embedding_1536 <=> query_embedding
         LIMIT max_vector_results
     ),

---

566-658: Hybrid code_examples search also references legacy column “embedding”.

Same fix as above for the code examples table.

-            1 - (ce.embedding <=> query_embedding) AS vector_sim
+            1 - (ce.embedding_1536 <=> query_embedding) AS vector_sim
...
-            AND ce.embedding IS NOT NULL
-        ORDER BY ce.embedding <=> query_embedding
+            AND ce.embedding_1536 IS NOT NULL
+        ORDER BY ce.embedding_1536 <=> query_embedding

🧹 Nitpick comments (53)

archon-ui-main/vite.config.ts (1)

310-322: Proxy additions look correct; gate WS proxy to dev-only usage

The /health proxy is fine. The /socket.io WS proxy is acceptable for dev, but per repo guidelines we should not rely on WebSockets for frontend updates. Ensure no UI features depend on WS in production; keep WS proxy strictly for local dev and document it.

Would you confirm there’s no frontend usage of WebSockets for live updates (only HTTP polling/ETag)?

docker-compose.yml (1)

162-162: Expose explicit dev intent

DOCKER_ENV=true is fine. Consider adding a brief comment in this file clarifying that the frontend runs Vite dev server (not production) to prevent misusing this compose in prod.

python/src/server/services/credential_service.py (1)

462-474: Ollama API key should be None, not a sentinel string

Returning "ollama" as an API key may leak into Authorization headers. Prefer None for providers that don’t need a key; let callers branch on provider.

Proposed change (outside this hunk):

def _get_provider_api_key(...) -> str | None:
    ...
    if provider == "ollama":
        return None

archon-ui-main/src/services/credentialsService.ts (5)

159-176: checkCredentialStatus: validate shape and propagate server errors with context

Return value is assumed to be a keyed map. Consider validating and throwing with more context (status code/body excerpt) per guidelines.

-    if (!response.ok) {
-      throw new Error(`Failed to check credential status: ${response.statusText}`);
-    }
-    return response.json();
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`Credential status check failed: HTTP ${response.status} ${response.statusText} - ${text}`);
+    }
+    const json = await response.json();
+    if (!json || typeof json !== 'object') {
+      throw new Error('Credential status check returned invalid payload');
+    }
+    return json;

---

181-210: Defaults OK; avoid module-load base URL capture (SSR/test safety)

Per prior learning, avoid evaluating getApiUrl() at module load. Convert baseUrl to a getter or call getApiUrl() per request to prevent SSR/test crashes.

-class CredentialsService {
-  private baseUrl = getApiUrl();
+class CredentialsService {
+  private get baseUrl(): string {
+    return getApiUrl();
+  }

---

411-468: Key parsing for instances is fragile; guard against underscores in IDs

Splitting by '' assumes ids never contain underscores. If they do, field detection breaks. Consider a stricter prefix parse: strip 'ollama_instance' then split once on the next '_' to separate id and field.

-        const parts = cred.key.split('_');
-        if (parts.length >= 3 && parts[0] === 'ollama' && parts[1] === 'instance') {
-          const instanceId = parts[2];
-          const field = parts.slice(3).join('_');
+        const prefix = 'ollama_instance_';
+        if (cred.key.startsWith(prefix)) {
+          const rest = cred.key.slice(prefix.length);
+          const underscore = rest.indexOf('_');
+          if (underscore === -1) return;
+          const instanceId = rest.slice(0, underscore);
+          const field = rest.slice(underscore + 1);

---

552-582: LocalStorage migration: browser-only guard and shape validation

Add typeof window !== 'undefined' and try/catch JSON parse with shape checks to avoid crashes in SSR/tests and corrupted local data.

-      const localStorageData = localStorage.getItem('ollama-instances');
+      if (typeof window === 'undefined' || !window.localStorage) {
+        return { migrated: false, instanceCount: 0 };
+      }
+      const localStorageData = window.localStorage.getItem('ollama-instances');
...
-      const localInstances = JSON.parse(localStorageData);
-      if (!Array.isArray(localInstances) || localInstances.length === 0) {
+      let localInstances: unknown;
+      try {
+        localInstances = JSON.parse(localStorageData);
+      } catch {
+        return { migrated: false, instanceCount: 0 };
+      }
+      if (!Array.isArray(localInstances) || localInstances.length === 0) {
         return { migrated: false, instanceCount: 0 };
       }

---

523-527: Add uniqueness/validation for new instance ids

Ensure ids are unique (and URL validity) before saving to prevent silent overwrite or invalid config.

migration/upgrade_database.sql (2)

17-18: Create pgvector extension up front (idempotent).

Avoid failures on instances where the extension isn’t installed.

Apply this diff:

 BEGIN;
 
+-- Ensure pgvector is available
+CREATE EXTENSION IF NOT EXISTS vector;

---

281-286: Optionally create a 3072 index when supported (HNSW).

Gate HNSW on pgvector version to avoid 2000-dim limits on older installs.

Example block:

DO $$
DECLARE v TEXT;
BEGIN
  SELECT extversion INTO v FROM pg_extension WHERE extname='vector';
  IF v >= '0.7.0' THEN
    EXECUTE 'CREATE INDEX IF NOT EXISTS idx_archon_crawled_pages_embedding_3072 ON archon_crawled_pages USING hnsw (embedding_3072 vector_cosine_ops)';
    EXECUTE 'CREATE INDEX IF NOT EXISTS idx_archon_code_examples_embedding_3072 ON archon_code_examples USING hnsw (embedding_3072 vector_cosine_ops)';
  END IF;
END $$;

python/src/server/main.py (2)

191-201: Update root modules list to reflect Ollama and removal of mcp-clients.

Keep the root response accurate.

Apply this diff:

   return {
     "name": "Archon Knowledge Engine API",
     "version": "1.0.0",
     "description": "Backend API for knowledge management and project automation",
     "status": "healthy",
-    "modules": ["settings", "mcp", "mcp-clients", "knowledge", "projects"],
+    "modules": ["settings", "mcp", "knowledge", "projects", "ollama"],
   }

---

221-234: Outdated migration instruction message.

Points to add_source_url_display_name.sql; align with new upgrade/validate scripts introduced in this PR.

Apply this diff:

-            "migration_instructions": "Open Supabase Dashboard → SQL Editor → Run: migration/add_source_url_display_name.sql",
+            "migration_instructions": "Open Supabase Dashboard → SQL Editor → Run: migration/upgrade_database.sql then migration/validate_migration.sql",

python/src/server/services/embeddings/contextual_embedding_service.py (3)

33-46: Remove unused MODEL_CHOICE fetch; _get_model_choice supersedes it.

Reduces duplication and avoids confusing logs.

Apply this diff:

-    # Model choice is a RAG setting, get from credential service
-    try:
-        from ...services.credential_service import credential_service
-
-        model_choice = await credential_service.get_credential("MODEL_CHOICE", "gpt-4.1-nano")
-    except Exception as e:
-        # Fallback to environment variable or default
-        search_logger.warning(
-            f"Failed to get MODEL_CHOICE from credential service: {e}, using fallback"
-        )
-        model_choice = os.getenv("MODEL_CHOICE", "gpt-4.1-nano")
-
-    search_logger.debug(f"Using MODEL_CHOICE: {model_choice}")
+    # Model selection handled by _get_model_choice()

---

86-92: Preserve stack traces in error logs.

Include exc_info=True per guidelines.

Apply this diff:

-        if "rate_limit_exceeded" in str(e) or "429" in str(e):
-            search_logger.warning(f"Rate limit hit in contextual embedding: {e}")
-        else:
-            search_logger.error(f"Error generating contextual embedding: {e}")
+        if "rate_limit_exceeded" in str(e) or "429" in str(e):
+            search_logger.warning(f"Rate limit hit in contextual embedding: {e}", exc_info=True)
+        else:
+            search_logger.error(f"Error generating contextual embedding: {e}", exc_info=True)

---

231-248: Batch path: include stack traces on errors.

Improve diagnosability for quota/rate/other failures.

Apply this diff:

-            search_logger.warning(f"Rate limit hit in contextual embeddings batch: {e}")
+            search_logger.warning(f"Rate limit hit in contextual embeddings batch: {e}", exc_info=True)
 ...
-        search_logger.error(f"Error in contextual embedding batch: {e}")
+        search_logger.error(f"Error in contextual embedding batch: {e}", exc_info=True)

archon-ui-main/vitest.config.ts (1)

16-27: Include globs look fine; ensure coverage excludes test/ as well.

Currently coverage excludes tests/ but not test/. Avoid polluting coverage with new suites.

Apply this change in coverage.exclude:

-        'tests/',
+        'tests/',
+        'test/',

Also consider relying on a single glob like 'test/**/*.test.{ts,tsx}' to reduce maintenance.

migration/validate_migration.sql (2)

167-199: Use EXISTS for presence check; avoid COUNT(*) full scan.

Cheaper and clearer for large tables.

Apply this diff:

-        SELECT COUNT(*) INTO sample_count FROM archon_crawled_pages LIMIT 1;
-        IF sample_count > 0 THEN
+        IF EXISTS (SELECT 1 FROM archon_crawled_pages) THEN

---

208-287: Column/index checks only target crawled_pages in CTE; optionally include code_examples for symmetry.

Not required, but improves signal when only one table is upgraded.

I can provide a patched CTE that unions both tables if you want it.

python/tests/test_async_llm_provider_service.py (3)

208-239: Stabilize assertion for Ollama fallback base_url to avoid brittle coupling.

_get_optimal_ollama_instance may change how it appends /v1. Assert suffix/host instead of full string to reduce false positives.

Apply this diff:

-                    mock_openai.assert_called_once_with(
-                        api_key="ollama",
-                        base_url="http://localhost:11434/v1"
-                    )
+                    assert mock_openai.call_count == 1
+                    kwargs = mock_openai.call_args.kwargs
+                    assert kwargs["api_key"] == "ollama"
+                    assert kwargs["base_url"].endswith("/v1")
+                    assert "localhost:11434" in kwargs["base_url"]

---

241-262: Simplify failure path mocking; one failure is enough to validate the error.

Raising on get_credentials_by_category already breaks fallback; the AsyncOpenAI side effect isn’t needed and can obscure the root cause.

Apply this diff:

-        ), patch("src.server.services.llm_provider_service.openai.AsyncOpenAI") as mock_openai:
-            mock_openai.side_effect = Exception("Connection failed")
+        ):

---

20-31: Remove unused helper to satisfy linters.

AsyncContextManager is not used.

Apply this diff:

-class AsyncContextManager:
-    """Helper class for properly mocking async context managers"""
-
-    def __init__(self, return_value):
-        self.return_value = return_value
-
-    async def __aenter__(self):
-        return self.return_value
-
-    async def __aexit__(self, exc_type, exc_val, exc_tb):
-        pass

python/src/server/services/storage/document_storage_service.py (1)

222-289: Prefer centralized column mapping to reduce drift.

Use multi_dimensional_embedding_service.get_embedding_column_name for dimension→column mapping to stay consistent with schema evolution.

I can draft the swap if you confirm the import path: from ..embeddings.multi_dimensional_embedding_service import multi_dimensional_embedding_service as md.

archon-ui-main/src/components/settings/OllamaInstanceHealthIndicator.tsx (4)

116-127: Broaden input type and coerce to Date to prevent runtime errors.

lastChecked may be ISO string/number; current signature requires Date.

Apply this diff:

-  const formatLastChecked = (date: Date) => {
-    const now = new Date();
-    const diffMs = now.getTime() - date.getTime();
+  const formatLastChecked = (value: Date | string | number | undefined) => {
+    const date = value instanceof Date ? value : new Date(value ?? 0);
+    if (Number.isNaN(date.getTime())) return 'Unknown';
+    const now = new Date();
+    const diffMs = now.getTime() - date.getTime();

---

169-175: Guard URL parsing to avoid crashes on malformed baseUrl.

new URL() throws if the value lacks a scheme.

Apply this diff:

-            <div className="text-xs text-gray-500 dark:text-gray-400 font-mono">
-              {new URL(instance.baseUrl).host}
-            </div>
+            <div className="text-xs text-gray-500 dark:text-gray-400 font-mono">
+              {(() => { try { return new URL(instance.baseUrl).host; } catch { return instance.baseUrl; } })()}
+            </div>

---

35-45: Use consistent response time property and fallback.

Toast uses responseTime, details use responseTimeMs. Prefer one, or fallback to either.

Apply this diff:

-      if (healthResult.isHealthy) {
+      if (healthResult.isHealthy) {
         showToast(
-          `Health check successful for ${instance.name} (${healthResult.responseTime?.toFixed(0)}ms)`,
+          `Health check successful for ${instance.name} (${(healthResult.responseTimeMs ?? healthResult.responseTime ?? 0).toFixed(0)}ms)`,
           'success'
         );

---

134-155: Surface loading state on the button for a11y/UX.

If your Button supports loading, pass it to reflect state (spinner/aria).

Apply this diff:

-        <Button
+        <Button
           variant="ghost"
           size="sm"
           onClick={handleRefresh}
-          disabled={isRefreshing}
+          disabled={isRefreshing}
+          loading={isRefreshing}

migration/DB_UPGRADE_INSTRUCTIONS.md (2)

8-9: Replace bold emphasis with a proper heading to satisfy MD036.

Avoid using emphasis as a heading.

Apply this diff:

-**Always run this FIRST before any migration!**
+#### Important — run this FIRST before any migration

---

107-108: Use consistent Docker CLI syntax.

Standardize on docker compose (v2) throughout.

Apply this diff:

-   docker-compose restart
+   docker compose restart

python/src/server/services/embeddings/multi_dimensional_embedding_service.py (1)

10-14: Remove unused import to satisfy Ruff.

Apply this diff:

-from typing import Any

python/src/server/services/llm_provider_service.py (1)

297-305: Avoid hitting the DB on hot path just to read LLM_PROVIDER.

This executes a DB/settings fetch during routing. Prefer the existing cache helpers to respect the 5‑minute TTL.

-        if provider == "ollama" or (not provider and (await credential_service.get_credentials_by_category("rag_strategy")).get("LLM_PROVIDER") == "ollama"):
+        if provider == "ollama" or (
+            not provider and (_get_cached_settings("rag_strategy_settings") or
+                              (await credential_service.get_credentials_by_category("rag_strategy")))
+                              .get("LLM_PROVIDER") == "ollama"
+        ):

python/src/server/services/storage/code_storage_service.py (2)

509-513: Remove redundant import; it’s already imported at file top.

Local re-import of asyncio is unnecessary and may trip linters.

-    import asyncio
-
     # Run the async version in the current thread
     return asyncio.run(_generate_code_example_summary_async(code, context_before, context_after, language, provider))

---

552-593: JSON “response_format” may not be supported by Ollama; soften parsing.

When routed to Ollama, strict JSON mode may fail. Consider trying best‑effort JSON extraction before falling back.

If desired, I can add a safe_parse_json helper and graceful prompt fallback.

archon-ui-main/src/components/settings/OllamaConfigurationPanel.tsx (2)

10-11: Remove unused type import.

OllamaInstanceType isn’t used.

-import type { OllamaInstance as OllamaInstanceType } from './types/OllamaTypes';

---

46-47: Browser-safe timer type.

Prefer ReturnType over NodeJS.Timeout to avoid DOM/Node type clashes.

-  const updateTimeouts = useRef<Record<string, NodeJS.Timeout>>({});
+  const updateTimeouts = useRef<Record<string, ReturnType<typeof setTimeout>>>({});

archon-ui-main/src/components/settings/RAGSettings.tsx (1)

1908-1921: Embedding model check for Ollama is inverted.

The condition returns true for almost any non‑OpenAI name. Restrict to names that actually indicate embeddings.

-      case 'ollama':
-        return !model.startsWith('text-embedding-') || model.includes('embed') || model.includes('arctic');
+      case 'ollama':
+        return /\b(embed|embedding|nomic|arctic)\b/i.test(model);

archon-ui-main/src/components/settings/OllamaModelSelectionModal.tsx (1)

107-119: Strip or guard debug logs.

Extensive console logging (including model details) is noisy and can leak internals. Guard under NODE_ENV !== 'production' or remove.

Example:

-  console.log(`🎨 DEBUG: Rendering card for ${model.name}:`, { ... });
+  if (process.env.NODE_ENV !== 'production') {
+    console.debug('Rendering card', model.name);
+  }

Apply similarly to other DEBUG blocks.

Also applies to: 372-387, 585-604, 682-696, 905-919

archon-ui-main/src/components/settings/OllamaModelDiscoveryModal.tsx (3)

49-49: Rename loading flag to isDiscovering (state naming rule).

Adopt is[Action]ing pattern for loading flags.

-const [loading, setLoading] = useState(false);
+const [isDiscovering, setIsDiscovering] = useState(false);

Update references accordingly.

---

65-75: Trim excessive console logging and sensitive values.

The modal logs internals (URLs, full model lists, call stacks) on every render. Keep dev-only logs minimal; never log host URLs in production.

Apply a simple guard:

- console.log( ... );
+ if (process.env.NODE_ENV === 'development') console.log( ... );

Prefer structured debug logs via a logger with levels; remove the IIFE renderer logs entirely.

Also applies to: 85-95, 97-126, 129-194, 451-497, 705-716

---

656-678: Bind Refresh to query refetch and disable while fetching.

After moving to TanStack Query, call refetch() and rely on isFetching instead of custom state.

-onClick={() => {
-  console.log('🚨 REFRESH BUTTON CLICKED - About to call discoverModels(true)', {...});
-  discoverModels(true);  // Force refresh
-}}
-disabled={loading}
+onClick={() => refetch()}
+disabled={isDiscovering}

python/src/server/services/provider_discovery_service.py (2)

227-248: Don’t send both Authorization header and key= query to Gemini list endpoint.

Gemini REST uses API key in the query string; drop the Authorization: Bearer header.

-headers = {"Authorization": f"Bearer {api_key}"}
...
-async with session.get(f"{base_url}?key={api_key}", headers=headers) as response:
+async with session.get(f"{base_url}?key={api_key}") as response:

---

472-493: Support dual-host Ollama config in discovery.

Only LLM_BASE_URL is used; add support for OLLAMA_CHAT_BASE_URL and OLLAMA_EMBEDDING_BASE_URL (and comma‑separated lists) to populate base_urls.

-ollama_urls = [rag_settings.get("LLM_BASE_URL", DEFAULT_OLLAMA_URL)]
+urls = []
+for key in ("OLLAMA_CHAT_BASE_URL", "OLLAMA_EMBEDDING_BASE_URL", "LLM_BASE_URL"):
+    v = rag_settings.get(key)
+    if v:
+        urls.extend([u.strip() for u in str(v).split(",") if u.strip()])
+ollama_urls = urls or [DEFAULT_OLLAMA_URL]

python/src/server/services/ollama/embedding_router.py (1)

273-321: Fill missing dimensions when discovery omits them.

If embedding_models entries lack dimensions, attempt _detect_model_dimensions per route instead of skipping.

Add a fallback call to self._detect_model_dimensions(model_name, instance_url) before continue.

archon-ui-main/src/components/settings/types/OllamaTypes.ts (2)

132-139: Align EmbeddingRoute naming with API ('target_column'/'column_name')

Backend returns target_column (single-route) and column_name (routes list). UI type uses targetColumn. Pick one UI name (recommend: columnName) and map both API fields to it in adapters to avoid confusion.

---

176-184: Clarify units for polling/timeout settings

Document that healthCheckInterval and modelCacheTtl/connectionTimeout are in milliseconds (or seconds) and enforce via zod/yup schema where these settings are parsed to avoid unit mix-ups.

archon-ui-main/src/services/ollamaService.ts (4)

36-72: Type hygiene: avoid any in response shapes

Replace parameters?: any with Record<string, unknown> for both chat_models and embedding_models entries.

-    parameters?: any;
+    parameters?: Record<string, unknown>;
...
-    parameters?: any;
+    parameters?: Record<string, unknown>;

---

91-106: Prefer Record<string, unknown> over any for health_status/capabilities

Tightens types without losing flexibility.

-  capabilities: {
+  capabilities: {
     total_models?: number;
     chat_models?: string[];
     embedding_models?: string[];
     supported_dimensions?: number[];
     error?: string;
-  };
-  health_status: Record<string, any>;
+  };
+  health_status: Record<string, unknown>;

---

118-135: Prefer Record<string, unknown> for dimension_analysis/routing_statistics

Small type hygiene improvement.

-  dimension_analysis: Record<string, {
+  dimension_analysis: Record<string, {
     count: number;
     models: string[];
     avg_performance: number;
   }>;
-  routing_statistics: Record<string, any>;
+  routing_statistics: Record<string, unknown>;

---

383-429: testConnection: consider per-attempt timeout

checkInstanceHealth now supports timeouts; ensure retries don’t hang when the instance is down by passing a lower timeout for connection tests (e.g., 3–5s).

python/src/server/api_routes/ollama_api.py (5)

652-712: Heuristic compatibility assessment: mark outputs as best-effort and include exc_info in logs

Document that this path is heuristic-only (vs. the tested variant) and switch logger.error/warning to logger.exception when catching exceptions to preserve stack traces.

---

957-983: Docstring contradicts implementation; update to reflect /api/tags-only fast path

The docstring claims “complete real details” including /api/show, but implementation intentionally skips /api/show for speed.

-    Discover models from Ollama instances with complete real details from both /api/tags and /api/show.
-    Only stores actual data from Ollama API endpoints - no fabricated information.
+    Fast discovery using Ollama /api/tags only (skips /api/show for performance).
+    Stores only data available from Ollama API endpoints; avoids inferred fields unless explicitly noted.

---

378-383: force_refresh is unused

Honor force_refresh to bypass caches in discovery service; otherwise remove the field.

---

268-287: Avoid calling private method _calculate_performance_score

Expose a public method on embedding_router or compute score here to avoid relying on a private underscore method.

---

135-140: Include exc_info in exception logs

Use logger.exception(...) to preserve stack traces per guidelines.

-        logger.error(f"Error in model discovery: {e}")
+        logger.exception(f"Error in model discovery: {e}")

(Apply similarly across endpoints.)

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 8e2e8aa and bfc4d95.

⛔ Files ignored due to path filters (6)

• archon-ui-main/public/img/Grok.png is excluded by !**/*.png
• archon-ui-main/public/img/Ollama.png is excluded by !**/*.png
• archon-ui-main/public/img/OpenAI.png is excluded by !**/*.png
• archon-ui-main/public/img/OpenRouter.png is excluded by !**/*.png
• archon-ui-main/public/img/anthropic-logo.svg is excluded by !**/*.svg
• archon-ui-main/public/img/google-logo.svg is excluded by !**/*.svg

📒 Files selected for processing (33)

• .env.example (0 hunks)
• .gitignore (1 hunks)
• archon-ui-main/src/components/settings/OllamaConfigurationPanel.tsx (1 hunks)
• archon-ui-main/src/components/settings/OllamaInstanceHealthIndicator.tsx (1 hunks)
• archon-ui-main/src/components/settings/OllamaModelDiscoveryModal.tsx (1 hunks)
• archon-ui-main/src/components/settings/OllamaModelSelectionModal.tsx (1 hunks)
• archon-ui-main/src/components/settings/RAGSettings.tsx (6 hunks)
• archon-ui-main/src/components/settings/types/OllamaTypes.ts (1 hunks)
• archon-ui-main/src/services/credentialsService.ts (6 hunks)
• archon-ui-main/src/services/ollamaService.ts (1 hunks)
• archon-ui-main/vite.config.ts (1 hunks)
• archon-ui-main/vitest.config.ts (1 hunks)
• docker-compose.yml (1 hunks)
• migration/DB_UPGRADE_INSTRUCTIONS.md (1 hunks)
• migration/backup_database.sql (1 hunks)
• migration/complete_setup.sql (6 hunks)
• migration/upgrade_database.sql (1 hunks)
• migration/validate_migration.sql (1 hunks)
• python/src/server/api_routes/ollama_api.py (1 hunks)
• python/src/server/api_routes/settings_api.py (1 hunks)
• python/src/server/main.py (2 hunks)
• python/src/server/services/credential_service.py (3 hunks)
• python/src/server/services/embeddings/__init__.py (2 hunks)
• python/src/server/services/embeddings/contextual_embedding_service.py (1 hunks)
• python/src/server/services/embeddings/multi_dimensional_embedding_service.py (1 hunks)
• python/src/server/services/llm_provider_service.py (5 hunks)
• python/src/server/services/ollama/__init__.py (1 hunks)
• python/src/server/services/ollama/embedding_router.py (1 hunks)
• python/src/server/services/ollama/model_discovery_service.py (1 hunks)
• python/src/server/services/provider_discovery_service.py (1 hunks)
• python/src/server/services/storage/code_storage_service.py (4 hunks)
• python/src/server/services/storage/document_storage_service.py (3 hunks)
• python/tests/test_async_llm_provider_service.py (2 hunks)

💤 Files with no reviewable changes (1)

• .env.example

🧰 Additional context used

📓 Path-based instructions (9)

python/src/**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

python/src/**/*.py: Fail fast on critical conditions: service startup failures, missing configuration/env vars, database connection/auth failures, critical dependencies unavailable
Never accept or store corrupted data (e.g., zero embeddings, null foreign keys, malformed JSON); skip failed items entirely and continue processing
For batch/background operations, continue processing but log detailed per-item failures; for external APIs use retries with exponential backoff and then fail clearly
Error messages must include context, use specific exception types, preserve full stack traces (logging with exc_info=True), include relevant IDs/URLs, and never return None to indicate failure—raise instead; for batch ops report success counts and detailed failures
Backend uses Python 3.12 with a 120-character line length
Avoid introducing WebSocket support in the backend; updates are handled via HTTP polling
Adhere to Ruff lint rules (e.g., no unused imports) and provide type hints to satisfy MyPy

python/src/**/*.py: Fail fast on service startup failures (credentials, DB, service init); crash with clear errors
Treat missing configuration (env vars/invalid settings) as fatal; stop the system
Do not hide database connection failures; bubble up and surface clearly
Authentication/authorization failures must halt the operation and be visible
Never silently accept bad data; let Pydantic validation errors raise
If critical dependencies are unavailable, fail immediately
Reject invalid data that could corrupt state (e.g., zero embeddings, null FKs, malformed JSON)
Batch processing should complete remaining items but log detailed per-item failures
Background tasks (e.g., embedding generation) should finish queues while logging failures
Treat optional features as skippable: log and skip when disabled rather than crashing
External API calls: use retry with exponential backoff; on final failure, raise with clear service/context info
Never accept corrupted data during partial-failure work...

Files:

• python/src/server/services/embeddings/__init__.py
• python/src/server/services/provider_discovery_service.py
• python/src/server/services/ollama/embedding_router.py
• python/src/server/api_routes/settings_api.py
• python/src/server/services/embeddings/contextual_embedding_service.py
• python/src/server/services/ollama/__init__.py
• python/src/server/main.py
• python/src/server/services/credential_service.py
• python/src/server/services/embeddings/multi_dimensional_embedding_service.py
• python/src/server/services/llm_provider_service.py
• python/src/server/services/storage/code_storage_service.py
• python/src/server/api_routes/ollama_api.py
• python/src/server/services/storage/document_storage_service.py
• python/src/server/services/ollama/model_discovery_service.py

python/src/server/**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

Use specific exception classes and FastAPI exception handlers to produce rich JSON error responses

python/src/server/**/*.py: Provide rich error responses in FastAPI (custom exceptions and handlers that return structured JSON with detail/type)
Implement HTTP polling support and ETag caching on endpoints to enable 304 responses

Files:

• python/src/server/services/embeddings/__init__.py
• python/src/server/services/provider_discovery_service.py
• python/src/server/services/ollama/embedding_router.py
• python/src/server/api_routes/settings_api.py
• python/src/server/services/embeddings/contextual_embedding_service.py
• python/src/server/services/ollama/__init__.py
• python/src/server/main.py
• python/src/server/services/credential_service.py
• python/src/server/services/embeddings/multi_dimensional_embedding_service.py
• python/src/server/services/llm_provider_service.py
• python/src/server/services/storage/code_storage_service.py
• python/src/server/api_routes/ollama_api.py
• python/src/server/services/storage/document_storage_service.py
• python/src/server/services/ollama/model_discovery_service.py

python/src/server/{api_routes,services}/**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

Follow Service Layer pattern: API routes delegate to services, which handle business logic and call the database layer

Files:

• python/src/server/services/embeddings/__init__.py
• python/src/server/services/provider_discovery_service.py
• python/src/server/services/ollama/embedding_router.py
• python/src/server/api_routes/settings_api.py
• python/src/server/services/embeddings/contextual_embedding_service.py
• python/src/server/services/ollama/__init__.py
• python/src/server/services/credential_service.py
• python/src/server/services/embeddings/multi_dimensional_embedding_service.py
• python/src/server/services/llm_provider_service.py
• python/src/server/services/storage/code_storage_service.py
• python/src/server/api_routes/ollama_api.py
• python/src/server/services/storage/document_storage_service.py
• python/src/server/services/ollama/model_discovery_service.py

**/*.{py,ts,tsx}

📄 CodeRabbit inference engine (CLAUDE.md)

Never return None/null to indicate failure; raise an exception with details instead

Files:

• python/src/server/services/embeddings/__init__.py
• python/src/server/services/provider_discovery_service.py
• python/src/server/services/ollama/embedding_router.py
• python/src/server/api_routes/settings_api.py
• archon-ui-main/src/components/settings/OllamaConfigurationPanel.tsx
• python/src/server/services/embeddings/contextual_embedding_service.py
• python/src/server/services/ollama/__init__.py
• archon-ui-main/vitest.config.ts
• archon-ui-main/vite.config.ts
• python/src/server/main.py
• archon-ui-main/src/components/settings/OllamaModelDiscoveryModal.tsx
• python/src/server/services/credential_service.py
• archon-ui-main/src/components/settings/OllamaInstanceHealthIndicator.tsx
• python/src/server/services/embeddings/multi_dimensional_embedding_service.py
• python/src/server/services/llm_provider_service.py
• archon-ui-main/src/components/settings/OllamaModelSelectionModal.tsx
• archon-ui-main/src/components/settings/types/OllamaTypes.ts
• python/src/server/services/storage/code_storage_service.py
• python/tests/test_async_llm_provider_service.py
• python/src/server/api_routes/ollama_api.py
• archon-ui-main/src/components/settings/RAGSettings.tsx
• archon-ui-main/src/services/ollamaService.ts
• archon-ui-main/src/services/credentialsService.ts
• python/src/server/services/storage/document_storage_service.py
• python/src/server/services/ollama/model_discovery_service.py

python/src/server/services/**/*.py

📄 CodeRabbit inference engine (CLAUDE.md)

Place business logic in service layer under python/src/server/services/

Files:

• python/src/server/services/embeddings/__init__.py
• python/src/server/services/provider_discovery_service.py
• python/src/server/services/ollama/embedding_router.py
• python/src/server/services/embeddings/contextual_embedding_service.py
• python/src/server/services/ollama/__init__.py
• python/src/server/services/credential_service.py
• python/src/server/services/embeddings/multi_dimensional_embedding_service.py
• python/src/server/services/llm_provider_service.py
• python/src/server/services/storage/code_storage_service.py
• python/src/server/services/storage/document_storage_service.py
• python/src/server/services/ollama/model_discovery_service.py

python/src/server/api_routes/**/*.py

📄 CodeRabbit inference engine (CLAUDE.md)

Place API route handlers under python/src/server/api_routes/

Files:

• python/src/server/api_routes/settings_api.py
• python/src/server/api_routes/ollama_api.py

archon-ui-main/src/**/*.{ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

archon-ui-main/src/**/*.{ts,tsx}: Use TanStack Query for all data fetching; avoid prop drilling
TypeScript: strict mode with no implicit any in frontend code
State naming: is[Action]ing for loading flags, [resource]Error for errors, selected[Resource] for current selection
Use HTTP polling with ETag caching; do not introduce WebSocket-based updates in the frontend

archon-ui-main/src/**/*.{ts,tsx}: WebSocket event failures (if any) should be logged and not crash the client; continue serving others
Frontend data fetching must use TanStack Query (no prop drilling) with query key factories, smart polling, and optimistic updates with rollback
Use vertical slice architecture: place UI under src/features/[feature]/(components|hooks|services|types)
State naming: use is[Action]ing for loading, [resource]Error for errors, selected[Resource] for selections
Service method names: get[Resource]sByProject(projectId), getResource, create/update/delete patterns
Frontend TypeScript should be strict (no implicit any)

Files:

• archon-ui-main/src/components/settings/OllamaConfigurationPanel.tsx
• archon-ui-main/src/components/settings/OllamaModelDiscoveryModal.tsx
• archon-ui-main/src/components/settings/OllamaInstanceHealthIndicator.tsx
• archon-ui-main/src/components/settings/OllamaModelSelectionModal.tsx
• archon-ui-main/src/components/settings/types/OllamaTypes.ts
• archon-ui-main/src/components/settings/RAGSettings.tsx
• archon-ui-main/src/services/ollamaService.ts
• archon-ui-main/src/services/credentialsService.ts

archon-ui-main/src/components/**/*.{js,jsx,ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

Legacy UI code should adhere to standard React ESLint rules

Files:

• archon-ui-main/src/components/settings/OllamaConfigurationPanel.tsx
• archon-ui-main/src/components/settings/OllamaModelDiscoveryModal.tsx
• archon-ui-main/src/components/settings/OllamaInstanceHealthIndicator.tsx
• archon-ui-main/src/components/settings/OllamaModelSelectionModal.tsx
• archon-ui-main/src/components/settings/types/OllamaTypes.ts
• archon-ui-main/src/components/settings/RAGSettings.tsx

archon-ui-main/src/components/**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (CLAUDE.md)

Legacy UI under /components should follow ESLint standard React rules

Files:

• archon-ui-main/src/components/settings/OllamaConfigurationPanel.tsx
• archon-ui-main/src/components/settings/OllamaModelDiscoveryModal.tsx
• archon-ui-main/src/components/settings/OllamaInstanceHealthIndicator.tsx
• archon-ui-main/src/components/settings/OllamaModelSelectionModal.tsx
• archon-ui-main/src/components/settings/types/OllamaTypes.ts
• archon-ui-main/src/components/settings/RAGSettings.tsx

🧠 Learnings (6)

📚 Learning: 2025-09-13T15:53:40.741Z

Learnt from: CR
PR: coleam00/Archon#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-13T15:53:40.741Z
Learning: Applies to archon-ui-main/src/**/*.{test,spec}.{ts,tsx} : Write frontend tests with Vitest and React Testing Library

Applied to files:

• archon-ui-main/vitest.config.ts

📚 Learning: 2025-09-13T15:53:40.741Z

Learnt from: CR
PR: coleam00/Archon#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-13T15:53:40.741Z
Learning: Applies to archon-ui-main/src/features/**/*.{ts,tsx} : Use Biome formatting/conventions in /src/features: 120-char lines, double quotes, trailing commas

Applied to files:

• archon-ui-main/vitest.config.ts

📚 Learning: 2025-09-12T13:47:04.534Z

Learnt from: CR
PR: coleam00/Archon#0
File: AGENTS.md:0-0
Timestamp: 2025-09-12T13:47:04.534Z
Learning: Applies to archon-ui-main/src/features/**/*.{ts,tsx} : Biome formatting in features: 120-character lines, double quotes, trailing commas

Applied to files:

• archon-ui-main/vitest.config.ts

📚 Learning: 2025-09-04T16:30:05.227Z

Learnt from: stevepresley
PR: coleam00/Archon#573
File: archon-ui-main/src/config/api.ts:15-25
Timestamp: 2025-09-04T16:30:05.227Z
Learning: Archon UI API config: Prefer lazy getters getApiFullUrl() and getWsUrl() over module-load constants to avoid SSR/test crashes. Avoid CommonJS exports patterns (Object.defineProperty(exports,…)) in ESM. Add typeof window guards with VITE_API_URL fallback inside getApiUrl()/getWebSocketUrl() when SSR safety is required.

Applied to files:

• archon-ui-main/vite.config.ts

📚 Learning: 2025-08-20T19:38:04.097Z

Learnt from: Chillbruhhh
PR: coleam00/Archon#378
File: python/src/server/services/storage/document_storage_service.py:304-306
Timestamp: 2025-08-20T19:38:04.097Z
Learning: The archon_crawled_pages table in the Archon project has a table-level unique constraint on (url, chunk_number) defined inline in the CREATE TABLE statement in migration/complete_setup.sql at line 202, which allows upsert operations with on_conflict="url,chunk_number" to work properly without requiring additional migrations.

Applied to files:

• migration/complete_setup.sql

📚 Learning: 2025-08-20T19:38:04.097Z

Learnt from: Chillbruhhh
PR: coleam00/Archon#378
File: python/src/server/services/storage/document_storage_service.py:304-306
Timestamp: 2025-08-20T19:38:04.097Z
Learning: The archon_crawled_pages table in the Archon project has a table-level unique constraint on (url, chunk_number) defined inline in the CREATE TABLE statement in migration/complete_setup.sql at line 202, which allows upsert operations with on_conflict="url,chunk_number" to work properly.

Applied to files:

• migration/complete_setup.sql

🧬 Code graph analysis (19)

python/src/server/services/provider_discovery_service.py (2)

python/src/server/config/logfire_config.py (1)

• get_logger (137-147)

python/src/server/services/credential_service.py (3)

• get_credentials_by_category (305-351)
• get_credential (158-175)
• get_credential (502-504)

python/src/server/services/ollama/embedding_router.py (3)

python/src/server/config/logfire_config.py (1)

• get_logger (137-147)

python/src/server/services/ollama/model_discovery_service.py (4)

• get_model_info (933-956)
• _detect_model_capabilities (488-548)
• discover_models_from_multiple_instances (1014-1118)
• validate_model_capabilities (902-931)

python/src/server/services/embeddings/multi_dimensional_embedding_service.py (2)

• get_dimension_for_model (35-61)
• get_embedding_column_name (63-69)

python/src/server/api_routes/settings_api.py (1)

python/src/server/services/credential_service.py (2)

• get_credential (158-175)
• get_credential (502-504)

archon-ui-main/src/components/settings/OllamaConfigurationPanel.tsx (6)

archon-ui-main/src/services/credentialsService.ts (2)

• OllamaInstance (59-71)
• credentialsService (585-585)

archon-ui-main/src/components/settings/types/OllamaTypes.ts (1)

• OllamaInstance (9-26)

archon-ui-main/src/features/ui/hooks/useToast.ts (1)

• useToast (25-31)

archon-ui-main/src/features/ui/primitives/styles.ts (1)

• cn (139-141)

archon-ui-main/src/features/ui/primitives/button.tsx (1)

• Button (11-130)

archon-ui-main/src/features/ui/primitives/input.tsx (1)

• Input (8-29)

python/src/server/services/embeddings/contextual_embedding_service.py (1)

python/src/server/services/credential_service.py (2)

• get_credential (158-175)
• get_credential (502-504)

archon-ui-main/src/components/settings/OllamaModelDiscoveryModal.tsx (7)

archon-ui-main/src/services/credentialsService.ts (1)

• OllamaInstance (59-71)

archon-ui-main/src/components/settings/types/OllamaTypes.ts (3)

• OllamaInstance (9-26)
• OllamaModel (38-51)
• ModelSelectionState (115-122)

archon-ui-main/src/services/ollamaService.ts (3)

• OllamaModel (11-34)
• discoverModels (186-219)
• ollamaService (485-485)

python/src/server/services/ollama/model_discovery_service.py (1)

• OllamaModel (22-57)

archon-ui-main/src/features/ui/hooks/useToast.ts (1)

• useToast (25-31)

archon-ui-main/src/features/ui/primitives/button.tsx (1)

• Button (11-130)

archon-ui-main/src/features/ui/primitives/input.tsx (1)

• Input (8-29)

archon-ui-main/src/components/settings/OllamaInstanceHealthIndicator.tsx (5)

archon-ui-main/src/components/settings/types/OllamaTypes.ts (1)

• HealthIndicatorProps (85-89)

archon-ui-main/src/features/ui/hooks/useToast.ts (1)

• useToast (25-31)

archon-ui-main/src/services/ollamaService.ts (1)

• ollamaService (485-485)

archon-ui-main/src/features/ui/primitives/button.tsx (1)

• Button (11-130)

archon-ui-main/src/features/ui/primitives/styles.ts (1)

• cn (139-141)

python/src/server/services/embeddings/multi_dimensional_embedding_service.py (1)

python/src/server/config/logfire_config.py (1)

• get_logger (137-147)

python/src/server/services/llm_provider_service.py (2)

python/src/server/services/credential_service.py (2)

• _get_provider_base_url (475-481)
• get_credentials_by_category (305-351)

python/src/server/services/ollama/model_discovery_service.py (1)

• check_instance_health (958-1012)

archon-ui-main/src/components/settings/OllamaModelSelectionModal.tsx (2)

archon-ui-main/src/features/ui/hooks/useToast.ts (1)

• useToast (25-31)

archon-ui-main/src/features/ui/primitives/button.tsx (1)

• Button (11-130)

archon-ui-main/src/components/settings/types/OllamaTypes.ts (4)

archon-ui-main/src/services/credentialsService.ts (1)

• OllamaInstance (59-71)

archon-ui-main/src/services/ollamaService.ts (1)

• OllamaModel (11-34)

python/src/server/services/ollama/model_discovery_service.py (1)

• OllamaModel (22-57)

python/src/server/services/ollama/embedding_router.py (1)

• EmbeddingRoute (33-40)

python/src/server/services/storage/code_storage_service.py (3)

python/src/server/services/llm_provider_service.py (2)

• get_llm_client (42-170)
• get_embedding_model (221-273)

python/src/server/services/credential_service.py (3)

• get_active_provider (408-460)
• get_credential (158-175)
• get_credential (502-504)

python/src/server/services/embeddings/contextual_embedding_service.py (1)

• _get_model_choice (113-149)

python/tests/test_async_llm_provider_service.py (2)

python/src/server/services/llm_provider_service.py (1)

• get_llm_client (42-170)

python/src/server/services/credential_service.py (1)

• get_active_provider (408-460)

python/src/server/api_routes/ollama_api.py (6)

python/src/server/config/logfire_config.py (1)

• get_logger (137-147)

python/src/server/services/llm_provider_service.py (2)

• validate_provider_instance (312-385)
• get_llm_client (42-170)

archon-ui-main/src/services/ollamaService.ts (2)

• InstanceValidationResponse (91-105)
• ModelDiscoveryResponse (36-72)

python/src/server/services/ollama/model_discovery_service.py (5)

• discover_models_from_multiple_instances (1014-1118)
• check_instance_health (958-1012)
• discover_models (122-237)
• _test_function_calling_capability (817-857)
• _test_structured_output_capability (859-900)

python/src/server/services/ollama/embedding_router.py (6)

• route_embedding (75-130)
• _calculate_performance_score (323-361)
• get_available_embedding_routes (273-321)
• get_optimal_index_type (261-271)
• get_routing_statistics (399-447)
• clear_routing_cache (394-397)

python/src/server/services/client_manager.py (1)

• get_supabase_client (15-43)

archon-ui-main/src/components/settings/RAGSettings.tsx (3)

archon-ui-main/src/services/credentialsService.ts (1)

• credentialsService (585-585)

archon-ui-main/src/features/ui/hooks/useToast.ts (1)

• useToast (25-31)

archon-ui-main/src/components/settings/OllamaModelSelectionModal.tsx (1)

• OllamaModelSelectionModal (350-1139)

archon-ui-main/src/services/ollamaService.ts (4)

archon-ui-main/src/components/settings/types/OllamaTypes.ts (4)

• OllamaModel (38-51)
• ModelDiscoveryResponse (161-161)
• InstanceValidationResponse (163-163)
• EmbeddingRouteResponse (164-164)

python/src/server/services/ollama/model_discovery_service.py (1)

• OllamaModel (22-57)

python/src/server/api_routes/ollama_api.py (3)

• ModelDiscoveryResponse (54-61)
• InstanceValidationResponse (36-44)
• EmbeddingRouteResponse (71-80)

archon-ui-main/src/config/api.ts (1)

• getApiUrl (9-31)

archon-ui-main/src/services/credentialsService.ts (1)

archon-ui-main/src/components/settings/types/OllamaTypes.ts (1)

• OllamaInstance (9-26)

python/src/server/services/storage/document_storage_service.py (2)

python/src/server/services/credential_service.py (4)

• get_credentials_by_category (305-351)
• get_active_provider (408-460)
• get_credential (158-175)
• get_credential (502-504)

python/src/server/services/llm_provider_service.py (1)

• get_embedding_model (221-273)

python/src/server/services/ollama/model_discovery_service.py (4)

python/src/server/config/logfire_config.py (1)

• get_logger (137-147)

python/src/server/services/llm_provider_service.py (1)

• get_llm_client (42-170)

archon-ui-main/src/services/ollamaService.ts (1)

• OllamaModel (11-34)

python/src/server/api_routes/ollama_api.py (2)

• _test_function_calling_capability (842-898)
• _test_structured_output_capability (901-954)

🪛 markdownlint-cli2 (0.17.2)

migration/DB_UPGRADE_INSTRUCTIONS.md

32-32: Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)

[coderabbitai]

🛠️ Refactor suggestion

Validate URL before persisting on blur.

Prevent storing malformed URLs.

   const handleUrlBlur = async (instanceId: string) => {
@@
-    if (tempUrl && instance && tempUrl !== instance.baseUrl) {
+    if (tempUrl && instance && tempUrl !== instance.baseUrl) {
+      try {
+        const u = new URL(tempUrl);
+        if (!u.protocol.startsWith('http')) throw new Error('Invalid protocol');
+      } catch {
+        showToast('Please provide a valid HTTP/HTTPS URL', 'error');
+        return;
+      }

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	try {
	await credentialsService.updateOllamaInstance(instanceId, {
	baseUrl: tempUrl,
	isHealthy: undefined,
	lastHealthCheck: undefined
	});
	await loadInstances();
	// Clear the temporary URL after successful update
	setTempUrls(prev => {
	const updated = { ...prev };
	delete updated[instanceId];
	return updated;
	});
	// Connection test removed - only manual testing via "Test" button per user request
	} catch (error) {
	console.error('Failed to update Ollama instance URL:', error);
	showToast('Failed to update instance URL', 'error');
	}
	}
	const handleUrlBlur = async (instanceId: string) => {
	if (tempUrl && instance && tempUrl !== instance.baseUrl) {
	try {
	const u = new URL(tempUrl);
	if (!u.protocol.startsWith('http')) throw new Error('Invalid protocol');
	} catch {
	showToast('Please provide a valid HTTP/HTTPS URL', 'error');
	return;
	}
	try {
	await credentialsService.updateOllamaInstance(instanceId, {
	baseUrl: tempUrl,
	isHealthy: undefined,
	lastHealthCheck: undefined
	});
	await loadInstances();
	// Clear the temporary URL after successful update
	setTempUrls(prev => {
	const updated = { ...prev };
	delete updated[instanceId];
	return updated;
	});
	// Connection test removed - only manual testing via "Test" button per user request
	} catch (error) {
	console.error('Failed to update Ollama instance URL:', error);
	showToast('Failed to update instance URL', 'error');
	}
	}
	}

🤖 Prompt for AI Agents

In archon-ui-main/src/components/settings/OllamaConfigurationPanel.tsx around
lines 341 to 359, the code updates the instance URL on blur without validating
it; add client-side URL validation before calling
credentialsService.updateOllamaInstance so malformed URLs are not persisted.
Implement a small validator (e.g., trim input and use the URL constructor or a
regex) that checks for non-empty value and allowed protocols (http or https),
and call it at the start of the blur handler: if invalid, prevent the update,
keep tempUrls as-is, show a user-facing validation toast/error message and
return; only proceed to call updateOllamaInstance, loadInstances and clear
tempUrls when the validator passes.

[coderabbitai]

⚠️ Potential issue

Remove FORCE DEBUG logging from production build.

Always-on console logging (including timestamps) is noisy and risks leaking environment details. Guard behind a dev flag or remove.

Apply this diff:

-// FORCE DEBUG - This should ALWAYS appear in console when this file loads
-console.log('🚨 DEBUG: OllamaModelDiscoveryModal.tsx file loaded at', new Date().toISOString());
+if (process.env.NODE_ENV === 'development') {
+  // eslint-disable-next-line no-console
+  console.log('OllamaModelDiscoveryModal loaded', new Date().toISOString());
+}

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	// FORCE DEBUG - This should ALWAYS appear in console when this file loads
	console.log('🚨 DEBUG: OllamaModelDiscoveryModal.tsx file loaded at', new Date().toISOString());
	if (process.env.NODE_ENV === 'development') {
	// eslint-disable-next-line no-console
	console.log('OllamaModelDiscoveryModal loaded', new Date().toISOString());
	}

🤖 Prompt for AI Agents

In archon-ui-main/src/components/settings/OllamaModelDiscoveryModal.tsx around
lines 3 to 4, the file contains a FORCE DEBUG console.log that must not run in
production; remove the unconditional console.log or wrap it in a dev-only guard
(e.g., check process.env.NODE_ENV !== 'production' or a dedicated
__DEV__/feature flag) so the message only appears in development, and ensure any
build-time logger-stripping rules or linting rules are respected.

[coderabbitai]

🛠️ Refactor suggestion

⚠️ Potential issue

Use TanStack Query for discovery (remove ad‑hoc fetch/state).

Data fetching must use TanStack Query with smart polling/ETag; current imperative fetch violates guidelines and complicates caching/retries.

Minimal refactor sketch:

+import { useQuery } from '@tanstack/react-query';
...
-// Discover models when modal opens
-const discoverModels = useCallback(async (forceRefresh: boolean = false) => {
-  ...
-  const discoveryResult = await ollamaService.discoverModels({ instanceUrls: enabledInstanceUrls, includeCapabilities: true });
-  ...
-}, [enabledInstanceUrls, instanceLookup, showToast, loadModelsFromCache, saveModelsToCache]);
+const {
+  data: discoveryResult,
+  isFetching: isDiscovering,
+  error: queryError,
+  refetch,
+} = useQuery({
+  queryKey: ['ollamaModels', enabledInstanceUrls],
+  enabled: isOpen && enabledInstanceUrls.length > 0,
+  staleTime: 10 * 60 * 1000,
+  queryFn: () => ollamaService.discoverModels({
+    instanceUrls: enabledInstanceUrls,
+    includeCapabilities: true,
+  }),
+});
+
+useEffect(() => {
+  if (queryError) {
+    setError((queryError as Error).message);
+    showToast(`Model discovery failed: ${(queryError as Error).message}`, 'error');
+  }
+}, [queryError, showToast]);

Then derive models from discoveryResult and drop manual loading/progress flags.

Committable suggestion skipped: line range outside the PR's diff.

[coderabbitai]

⚠️ Potential issue

Selection is ambiguous across instances; highlight logic is incorrect.

Comparing only model.name causes collisions when the same model exists on multiple hosts; both cards render as selected.

Apply this diff to track instance URL with the selection and fix highlighting:

-const [selectionState, setSelectionState] = useState<ModelSelectionState>({
+const [selectionState, setSelectionState] = useState<ModelSelectionState>({
   selectedChatModel: initialChatModel || null,
   selectedEmbeddingModel: initialEmbeddingModel || null,
   filterText: '',
   showOnlyEmbedding: false,
   showOnlyChat: false,
   sortBy: 'name'
 });
+const [selectedChatInstanceUrl, setSelectedChatInstanceUrl] = useState<string | null>(null);
+const [selectedEmbeddingInstanceUrl, setSelectedEmbeddingInstanceUrl] = useState<string | null>(null);
...
-const handleModelSelect = (model: EnrichedModel, type: 'chat' | 'embedding') => {
+const handleModelSelect = (model: EnrichedModel, type: 'chat' | 'embedding') => {
   if (type === 'chat' && !model.capabilities.includes('chat')) {
     showToast(`Model ${model.name} does not support chat functionality`, 'error');
     return;
   }
   if (type === 'embedding' && !model.capabilities.includes('embedding')) {
     showToast(`Model ${model.name} does not support embedding functionality`, 'error');
     return;
   }
   setSelectionState(prev => ({
     ...prev,
     [type === 'chat' ? 'selectedChatModel' : 'selectedEmbeddingModel']: model.name
   }));
+  if (type === 'chat') setSelectedChatInstanceUrl(model.instance_url);
+  else setSelectedEmbeddingInstanceUrl(model.instance_url);
 };
...
-const isChatSelected = selectionState.selectedChatModel === model.name;
-const isEmbeddingSelected = selectionState.selectedEmbeddingModel === model.name;
+const isChatSelected =
+  selectionState.selectedChatModel === model.name && selectedChatInstanceUrl === model.instance_url;
+const isEmbeddingSelected =
+  selectionState.selectedEmbeddingModel === model.name && selectedEmbeddingInstanceUrl === model.instance_url;

Note: onSelectModels still passes names only; consider extending its payload to include instance_url in a future change.

Also applies to: 733-735

[coderabbitai]

🛠️ Refactor suggestion

⚠️ Potential issue

Critical: Don’t fetch or expose decrypted provider API keys in the browser.

Loading decrypted keys client‑side and calling provider APIs from the browser is a secret leak. Use backend validation endpoints instead.

Action: Remove loadApiCredentials and any state that stores key values; replace connection tests with backend proxy (/api/providers/validate) that uses server‑side credentials.

🤖 Prompt for AI Agents

In archon-ui-main/src/components/settings/RAGSettings.tsx around lines 116 to
141, the useEffect loads decrypted provider API keys into client state which
leaks secrets; remove the entire loadApiCredentials function, the useEffect that
calls it, and any state variables or setters that store raw key values (e.g.,
apiCredentials and setApiCredentials). Replace client-side provider connection
tests with a call to a backend endpoint (e.g., POST /api/providers/validate)
that performs validation server-side with stored secrets; update the UI to send
only provider identifiers/flags to that endpoint, handle the response
status/error, and display results without ever fetching or keeping API key
values in the browser.

[coderabbitai]

🛠️ Refactor suggestion

Ollama discovery runs capability checks sequentially; add limited concurrency.

tool support test per model is awaited in a loop, making discovery slow on hosts with many models.

Wrap per-model work in tasks and gather with a Semaphore to limit to N concurrent checks (e.g., 5).

[coderabbitai]

⚠️ Potential issue

Wrong column selection: 384‑dim embeddings not handled; unknown dims defaulting to 1536 corrupts data.

Map 384 to embedding_384, and skip unknown dimensions rather than mislabeling. Don’t persist corrupted rows.

-            if embedding_dim == 768:
+            if embedding_dim == 384:
+                embedding_column = "embedding_384"
+            elif embedding_dim == 768:
                 embedding_column = "embedding_768"
@@
-            else:
-                # Default to closest supported dimension
-                search_logger.warning(f"Unsupported embedding dimension {embedding_dim}, using embedding_1536")
-                embedding_column = "embedding_1536"
+            else:
+                search_logger.error(f"Unsupported embedding dimension {embedding_dim}; skipping record to avoid corrupt data")
+                continue

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	# Determine the correct embedding column based on dimension
	embedding_dim = len(embedding) if isinstance(embedding, list) else len(embedding.tolist())
	embedding_column = None
	if embedding_dim == 768:
	embedding_column = "embedding_768"
	elif embedding_dim == 1024:
	embedding_column = "embedding_1024"
	elif embedding_dim == 1536:
	embedding_column = "embedding_1536"
	elif embedding_dim == 3072:
	embedding_column = "embedding_3072"
	else:
	# Default to closest supported dimension
	search_logger.warning(f"Unsupported embedding dimension {embedding_dim}, using embedding_1536")
	embedding_column = "embedding_1536"
	# Determine the correct embedding column based on dimension
	embedding_dim = len(embedding) if isinstance(embedding, list) else len(embedding.tolist())
	embedding_column = None
	if embedding_dim == 384:
	embedding_column = "embedding_384"
	elif embedding_dim == 768:
	embedding_column = "embedding_768"
	elif embedding_dim == 1024:
	embedding_column = "embedding_1024"
	elif embedding_dim == 1536:
	embedding_column = "embedding_1536"
	elif embedding_dim == 3072:
	embedding_column = "embedding_3072"
	else:
	search_logger.error(f"Unsupported embedding dimension {embedding_dim}; skipping record to avoid corrupt data")
	continue

🤖 Prompt for AI Agents

In python/src/server/services/storage/code_storage_service.py around lines 908
to 924, the embedding column selection currently omits 384-dim and defaults
unknown dimensions to embedding_1536 which can mislabel and corrupt data; update
the logic to map 384 to "embedding_384" and remove the default fallback to 1536
— instead detect unsupported dimensions, log a warning/error, and
skip/persistently reject the row (e.g., return/raise or mark as skipped) so no
incorrect column is written; ensure the log message includes the actual
dimension and that callers handle the skip/rejection.

[coderabbitai]

⚠️ Potential issue

Use the same service alias and add robust fallback for chat model.

Replace credential_service with cred_service. This prevents runtime errors and follows the earlier alias.

Apply this diff:

-            from ..llm_provider_service import get_embedding_model
-            from ..credential_service import credential_service
+            from ..llm_provider_service import get_embedding_model
+            from ..credential_service import credential_service as cred_service
@@
-            embedding_model_name = await get_embedding_model(provider=provider)
+            embedding_model_name = await get_embedding_model(provider=provider)
@@
-                    provider_config = await credential_service.get_active_provider("llm")
+                    provider_config = await cred_service.get_active_provider("llm")
                     llm_chat_model = provider_config.get("chat_model", "")
                     if not llm_chat_model:
                         # Fallback to MODEL_CHOICE or provider defaults
-                        llm_chat_model = await credential_service.get_credential("MODEL_CHOICE", "gpt-4o-mini")
+                        llm_chat_model = await cred_service.get_credential("MODEL_CHOICE", "gpt-4o-mini")

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	from ..llm_provider_service import get_embedding_model
	from ..credential_service import credential_service
	# Get embedding model name
	embedding_model_name = await get_embedding_model(provider=provider)
	# Get LLM chat model (used for contextual embeddings if enabled)
	llm_chat_model = None
	if use_contextual_embeddings:
	try:
	provider_config = await credential_service.get_active_provider("llm")
	llm_chat_model = provider_config.get("chat_model", "")
	if not llm_chat_model:
	# Fallback to MODEL_CHOICE or provider defaults
	llm_chat_model = await credential_service.get_credential("MODEL_CHOICE", "gpt-4o-mini")
	except Exception as e:
	search_logger.warning(f"Failed to get LLM chat model: {e}")
	llm_chat_model = "gpt-4o-mini" # Default fallback
	from ..llm_provider_service import get_embedding_model
	from ..credential_service import credential_service as cred_service
	# Get embedding model name
	embedding_model_name = await get_embedding_model(provider=provider)
	# Get LLM chat model (used for contextual embeddings if enabled)
	llm_chat_model = None
	if use_contextual_embeddings:
	try:
	provider_config = await cred_service.get_active_provider("llm")
	llm_chat_model = provider_config.get("chat_model", "")
	if not llm_chat_model:
	# Fallback to MODEL_CHOICE or provider defaults
	llm_chat_model = await cred_service.get_credential("MODEL_CHOICE", "gpt-4o-mini")
	except Exception as e:
	search_logger.warning(f"Failed to get LLM chat model: {e}")
	llm_chat_model = "gpt-4o-mini" # Default fallback

🤖 Prompt for AI Agents

In python/src/server/services/storage/document_storage_service.py around lines
332 to 349, the code incorrectly references credential_service instead of the
earlier alias cred_service and lacks a robust fallback for the chat model;
replace credential_service with cred_service everywhere in this block, ensure
you await cred_service.get_active_provider("llm"), if
provider_config.get("chat_model") is empty then await
cred_service.get_credential("MODEL_CHOICE", "gpt-4o-mini") as the next fallback,
and ensure the exception handler logs the error and sets llm_chat_model to the
default "gpt-4o-mini".

[coderabbitai]

⚠️ Potential issue

Ensure embeddings are JSON-serializable before insert.

np.ndarray/tensor objects won’t serialize; convert once and reuse for length and value.

Apply this diff:

-                # Determine the correct embedding column based on dimension
-                embedding_dim = len(embedding) if isinstance(embedding, list) else len(embedding.tolist())
+                # Normalize embedding to a Python list for length and storage
+                embedding_values = embedding if isinstance(embedding, list) else getattr(embedding, "tolist", lambda: list(embedding))()
+                # Determine the correct embedding column based on dimension
+                embedding_dim = len(embedding_values)
@@
-                    embedding_column: embedding,  # Use the successful embedding with correct column
+                    embedding_column: embedding_values,  # Store as JSON-serializable list

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	# Determine the correct embedding column based on dimension
	embedding_dim = len(embedding) if isinstance(embedding, list) else len(embedding.tolist())
	embedding_column = None
	if embedding_dim == 768:
	embedding_column = "embedding_768"
	elif embedding_dim == 1024:
	embedding_column = "embedding_1024"
	elif embedding_dim == 1536:
	embedding_column = "embedding_1536"
	elif embedding_dim == 3072:
	embedding_column = "embedding_3072"
	else:
	# Default to closest supported dimension
	search_logger.warning(f"Unsupported embedding dimension {embedding_dim}, using embedding_1536")
	embedding_column = "embedding_1536"
	data = {
	"url": batch_urls[j],
	"chunk_number": batch_chunk_numbers[j],
	"content": text, # Use the successful text
	"metadata": {"chunk_size": len(text), **batch_metadatas[j]},
	"source_id": source_id,
	"embedding": embedding, # Use the successful embedding
	embedding_column: embedding, # Use the successful embedding with correct column
	"llm_chat_model": llm_chat_model, # Add LLM model tracking
	# Normalize embedding to a Python list for length and storage
	embedding_values = embedding if isinstance(embedding, list) else getattr(
	embedding, "tolist", lambda: list(embedding)
	)()
	# Determine the correct embedding column based on dimension
	embedding_dim = len(embedding_values)
	embedding_column = None
	if embedding_dim == 768:
	embedding_column = "embedding_768"
	elif embedding_dim == 1024:
	embedding_column = "embedding_1024"
	elif embedding_dim == 1536:
	embedding_column = "embedding_1536"
	elif embedding_dim == 3072:
	embedding_column = "embedding_3072"
	else:
	# Default to closest supported dimension
	search_logger.warning(f"Unsupported embedding dimension {embedding_dim}, using embedding_1536")
	embedding_column = "embedding_1536"
	data = {
	"url": batch_urls[j],
	"chunk_number": batch_chunk_numbers[j],
	"content": text, # Use the successful text
	"metadata": {"chunk_size": len(text), **batch_metadatas[j]},
	"source_id": source_id,
	embedding_column: embedding_values, # Store as JSON-serializable list
	"llm_chat_model": llm_chat_model, # Add LLM model tracking

🤖 Prompt for AI Agents

In python/src/server/services/storage/document_storage_service.py around lines
385 to 409, the code may pass numpy arrays/tensors into the DB payload causing
JSON serialization errors; convert the embedding to a native Python list once
and reuse it for determining length and for insertion (e.g., embedding_list =
embedding.tolist() if not already a list), use len(embedding_list) to pick the
embedding_column, and set the payload embedding_column value to embedding_list
so the object is JSON-serializable when inserting.

[coderabbitai]

⚠️ Potential issue

Support 384-dim embeddings and avoid corrupt writes on unknown dimensions.

DB/schema supports 384; unknown dims should be skipped (not coerced to 1536) per “never accept corrupted data.”

Apply this diff:

-                embedding_column = None
-                
-                if embedding_dim == 768:
+                embedding_column = None
+
+                if embedding_dim == 384:
+                    embedding_column = "embedding_384"
+                elif embedding_dim == 768:
                     embedding_column = "embedding_768"
                 elif embedding_dim == 1024:
                     embedding_column = "embedding_1024"
                 elif embedding_dim == 1536:
                     embedding_column = "embedding_1536"
                 elif embedding_dim == 3072:
                     embedding_column = "embedding_3072"
                 else:
-                    # Default to closest supported dimension
-                    search_logger.warning(f"Unsupported embedding dimension {embedding_dim}, using embedding_1536")
-                    embedding_column = "embedding_1536"
+                    # Reject unsupported dimensions to prevent data corruption
+                    search_logger.error(
+                        f"Unsupported embedding dimension {embedding_dim}; skipping record for url={batch_urls[j]} | chunk={batch_chunk_numbers[j]}"
+                    )
+                    continue

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	# Determine the correct embedding column based on dimension
	embedding_dim = len(embedding) if isinstance(embedding, list) else len(embedding.tolist())
	embedding_column = None
	if embedding_dim == 768:
	embedding_column = "embedding_768"
	elif embedding_dim == 1024:
	embedding_column = "embedding_1024"
	elif embedding_dim == 1536:
	embedding_column = "embedding_1536"
	elif embedding_dim == 3072:
	embedding_column = "embedding_3072"
	else:
	# Default to closest supported dimension
	search_logger.warning(f"Unsupported embedding dimension {embedding_dim}, using embedding_1536")
	embedding_column = "embedding_1536"
	# Determine the correct embedding column based on dimension
	embedding_dim = len(embedding) if isinstance(embedding, list) else len(embedding.tolist())
	embedding_column = None
	if embedding_dim == 384:
	embedding_column = "embedding_384"
	elif embedding_dim == 768:
	embedding_column = "embedding_768"
	elif embedding_dim == 1024:
	embedding_column = "embedding_1024"
	elif embedding_dim == 1536:
	embedding_column = "embedding_1536"
	elif embedding_dim == 3072:
	embedding_column = "embedding_3072"
	else:
	# Reject unsupported dimensions to prevent data corruption
	search_logger.error(
	f"Unsupported embedding dimension {embedding_dim}; skipping record for url={batch_urls[j]} | chunk={batch_chunk_numbers[j]}"
	)
	continue

🤖 Prompt for AI Agents

In python/src/server/services/storage/document_storage_service.py around lines
385 to 401, the code only maps 768/1024/1536/3072 and coerces unknown dims to
embedding_1536 which can corrupt data; add support for 384 by mapping
embedding_dim == 384 to "embedding_384", and change the else branch so unknown
dimensions are not coerced but are skipped: log an error/warning identifying the
unsupported dimension and the document id, then abort the write for that
document (e.g., return/raise or otherwise skip persisting) instead of defaulting
to embedding_1536 to prevent corrupted writes. Ensure any numpy array inputs are
still handled when computing embedding_dim.

[coderabbitai]

Review continued from previous batch...

[coderabbitai]

💡 Verification agent

🧩 Analysis chain

Duplicate OllamaModel definition (frontend vs backend)

There’s another OllamaModel in the types file. Keep one canonical definition (prefer this service version reflecting backend snake_case) to prevent subtle bugs.

Run to find duplicates:

---

🏁 Script executed:

#!/bin/bash
rg -nP --type=ts -C2 'interface\s+OllamaModel\b'

Length of output: 763

---

Consolidate duplicate OllamaModel — keep canonical service definition (snake_case)

Two definitions found: archon-ui-main/src/services/ollamaService.ts and archon-ui-main/src/components/settings/types/OllamaTypes.ts. Keep the service version as the single source of truth (export it from a shared types module or from the service) and have all consumers import it; remove the duplicate and ensure any UI code maps backend snake_case → frontend camelCase where needed.

🤖 Prompt for AI Agents

In archon-ui-main/src/services/ollamaService.ts around lines 10 to 34: there is
a duplicate OllamaModel type defined elsewhere; keep the service version
(snake_case) as the canonical type, export it from the service or from a new
shared types module, remove the duplicate file
archon-ui-main/src/components/settings/types/OllamaTypes.ts, update all
consumers to import the canonical type, and modify any UI code that expects
camelCase to map incoming backend snake_case fields to camelCase properties at
the boundary so the canonical snake_case type remains the single source of
truth.

[coderabbitai]

🛠️ Refactor suggestion

Add fetch timeout + ETag support (required by guidelines) via helper

Fetch has no timeout and no conditional requests. Add an AbortController-based timeout and conditional If-None-Match handling with a small cache.

 class OllamaService {
   private baseUrl = getApiUrl();
+  // Simple in-memory ETag cache keyed by request URL
+  private etagCache = new Map<string, { etag: string; data: unknown }>();
+
+  private async fetchJson<T>(
+    url: string,
+    init: RequestInit & { timeoutMs?: number; etagKey?: string } = {}
+  ): Promise<{ data: T; fromCache: boolean }> {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), init.timeoutMs ?? 8000);
+    try {
+      const headers = new Headers(init.headers || {});
+      // Attach known ETag for conditional GETs
+      if (init.etagKey && this.etagCache.has(init.etagKey)) {
+        headers.set('If-None-Match', this.etagCache.get(init.etagKey)!.etag);
+      }
+      headers.set('Accept', 'application/json');
+      const resp = await fetch(url, { ...init, headers, signal: controller.signal });
+      if (resp.status === 304 && init.etagKey && this.etagCache.has(init.etagKey)) {
+        return { data: this.etagCache.get(init.etagKey)!.data as T, fromCache: true };
+      }
+      if (!resp.ok) {
+        const errorText = await resp.text();
+        throw new Error(`HTTP ${resp.status}: ${errorText}`);
+      }
+      const data = (await resp.json()) as T;
+      const etag = resp.headers.get('ETag');
+      if (etag && init.etagKey) {
+        this.etagCache.set(init.etagKey, { etag, data });
+      }
+      return { data, fromCache: false };
+    } finally {
+      clearTimeout(timeout);
+    }
+  }

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	class OllamaService {
	private baseUrl = getApiUrl();
	private handleApiError(error: any, context: string): Error {
	const errorMessage = error instanceof Error ? error.message : String(error);
	// Check for network errors
	if (
	errorMessage.toLowerCase().includes("network") ||
	errorMessage.includes("fetch") ||
	errorMessage.includes("Failed to fetch")
	) {
	return new Error(
	`Network error while ${context.toLowerCase()}: ${errorMessage}. ` +
	`Please check your connection and Ollama server status.`,
	);
	}
	// Check for timeout errors
	if (errorMessage.includes("timeout") || errorMessage.includes("AbortError")) {
	return new Error(
	`Timeout error while ${context.toLowerCase()}: The Ollama instance may be slow to respond or unavailable.`
	);
	}
	// Return original error with context
	return new Error(`${context} failed: ${errorMessage}`);
	}
	class OllamaService {
	private baseUrl = getApiUrl();
	// Simple in-memory ETag cache keyed by request URL
	private etagCache = new Map<string, { etag: string; data: unknown }>();
	private async fetchJson<T>(
	url: string,
	init: RequestInit & { timeoutMs?: number; etagKey?: string } = {}
	): Promise<{ data: T; fromCache: boolean }> {
	const controller = new AbortController();
	const timeout = setTimeout(() => controller.abort(), init.timeoutMs ?? 8000);
	try {
	const headers = new Headers(init.headers || {});
	// Attach known ETag for conditional GETs
	if (init.etagKey && this.etagCache.has(init.etagKey)) {
	headers.set('If-None-Match', this.etagCache.get(init.etagKey)!.etag);
	}
	headers.set('Accept', 'application/json');
	const resp = await fetch(url, { ...init, headers, signal: controller.signal });
	if (resp.status === 304 && init.etagKey && this.etagCache.has(init.etagKey)) {
	return { data: this.etagCache.get(init.etagKey)!.data as T, fromCache: true };
	}
	if (!resp.ok) {
	const errorText = await resp.text();
	throw new Error(`HTTP ${resp.status}: ${errorText}`);
	}
	const data = (await resp.json()) as T;
	const etag = resp.headers.get('ETag');
	if (etag && init.etagKey) {
	this.etagCache.set(init.etagKey, { etag, data });
	}
	return { data, fromCache: false };
	} finally {
	clearTimeout(timeout);
	}
	}
	private handleApiError(error: any, context: string): Error {
	const errorMessage = error instanceof Error ? error.message : String(error);
	// Check for network errors
	if (
	errorMessage.toLowerCase().includes("network") ||
	errorMessage.includes("fetch") ||
	errorMessage.includes("Failed to fetch")
	) {
	return new Error(
	`Network error while ${context.toLowerCase()}: ${errorMessage}. ` +
	`Please check your connection and Ollama server status.`,
	);
	}
	// Check for timeout errors
	if (errorMessage.includes("timeout") || errorMessage.includes("AbortError")) {
	return new Error(
	`Timeout error while ${context.toLowerCase()}: The Ollama instance may be slow to respond or unavailable.`
	);
	}
	// Return original error with context
	return new Error(`${context} failed: ${errorMessage}`);
	}

[coderabbitai]

🛠️ Refactor suggestion

Use fetchJson helper for discovery (adds timeout + ETag)

Applies conditional GETs and avoids hangs.

-      const response = await fetch(`${this.baseUrl}/api/ollama/models?${params.toString()}`, {
-        method: 'GET',
-        headers: {
-          'Content-Type': 'application/json',
-        },
-      });
-
-      if (!response.ok) {
-        const errorText = await response.text();
-        throw new Error(`HTTP ${response.status}: ${errorText}`);
-      }
-
-      const data = await response.json();
-      return data;
+      const url = `${this.baseUrl}/api/ollama/models?${params.toString()}`;
+      const { data } = await this.fetchJson<ModelDiscoveryResponse>(url, {
+        method: 'GET',
+        headers: { 'Content-Type': 'application/json' },
+        timeoutMs: 8000,
+        etagKey: url,
+      });
+      return data;

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	async discoverModels(options: ModelDiscoveryOptions): Promise<ModelDiscoveryResponse> {
	try {
	if (!options.instanceUrls || options.instanceUrls.length === 0) {
	throw new Error("At least one instance URL is required for model discovery");
	}
	// Build query parameters
	const params = new URLSearchParams();
	options.instanceUrls.forEach(url => {
	params.append('instance_urls', url);
	});
	if (options.includeCapabilities !== undefined) {
	params.append('include_capabilities', options.includeCapabilities.toString());
	}
	const response = await fetch(`${this.baseUrl}/api/ollama/models?${params.toString()}`, {
	method: 'GET',
	headers: {
	'Content-Type': 'application/json',
	},
	});
	if (!response.ok) {
	const errorText = await response.text();
	throw new Error(`HTTP ${response.status}: ${errorText}`);
	}
	const data = await response.json();
	return data;
	} catch (error) {
	throw this.handleApiError(error, "Model discovery");
	}
	}
	async discoverModels(options: ModelDiscoveryOptions): Promise<ModelDiscoveryResponse> {
	try {
	if (!options.instanceUrls || options.instanceUrls.length === 0) {
	throw new Error("At least one instance URL is required for model discovery");
	}
	// Build query parameters
	const params = new URLSearchParams();
	options.instanceUrls.forEach(url => {
	params.append('instance_urls', url);
	});
	if (options.includeCapabilities !== undefined) {
	params.append('include_capabilities', options.includeCapabilities.toString());
	}
	const url = `${this.baseUrl}/api/ollama/models?${params.toString()}`;
	const { data } = await this.fetchJson<ModelDiscoveryResponse>(url, {
	method: 'GET',
	headers: { 'Content-Type': 'application/json' },
	timeoutMs: 8000,
	etagKey: url,
	});
	return data;
	} catch (error) {
	throw this.handleApiError(error, "Model discovery");
	}
	}

🤖 Prompt for AI Agents

In archon-ui-main/src/services/ollamaService.ts around lines 186 to 219, the
discoverModels method uses a raw fetch which lacks timeout handling and
conditional GET (ETag) support; replace the fetch call with the project's
fetchJson helper, passing the constructed URL with query params, the same
headers, and any needed options (e.g., method GET) so timeouts and ETag handling
are applied; preserve the existing response error handling and JSON parsing by
adapting to fetchJson's return/throw behavior and continue to wrap errors with
this.handleApiError("Model discovery").

[coderabbitai]

🛠️ Refactor suggestion

Use fetchJson helper for health checks (adds timeout + ETag)

Also reduces needless payloads during polling by leveraging 304s.

-      const response = await fetch(`${this.baseUrl}/api/ollama/instances/health?${params.toString()}`, {
-        method: 'GET',
-        headers: {
-          'Content-Type': 'application/json',
-        },
-      });
-
-      if (!response.ok) {
-        const errorText = await response.text();
-        throw new Error(`HTTP ${response.status}: ${errorText}`);
-      }
-
-      const data = await response.json();
-      return data;
+      const url = `${this.baseUrl}/api/ollama/instances/health?${params.toString()}`;
+      const { data } = await this.fetchJson<InstanceHealthResponse>(url, {
+        method: 'GET',
+        headers: { 'Content-Type': 'application/json' },
+        timeoutMs: 6000,
+        etagKey: url,
+      });
+      return data;

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	async checkInstanceHealth(instanceUrls: string[], includeModels: boolean = false): Promise<InstanceHealthResponse> {
	try {
	if (!instanceUrls || instanceUrls.length === 0) {
	throw new Error("At least one instance URL is required for health checking");
	}
	// Build query parameters
	const params = new URLSearchParams();
	instanceUrls.forEach(url => {
	params.append('instance_urls', url);
	});
	if (includeModels) {
	params.append('include_models', 'true');
	}
	const response = await fetch(`${this.baseUrl}/api/ollama/instances/health?${params.toString()}`, {
	method: 'GET',
	headers: {
	'Content-Type': 'application/json',
	},
	});
	if (!response.ok) {
	const errorText = await response.text();
	throw new Error(`HTTP ${response.status}: ${errorText}`);
	}
	const data = await response.json();
	return data;
	} catch (error) {
	throw this.handleApiError(error, "Instance health checking");
	}
	}
	async checkInstanceHealth(instanceUrls: string[], includeModels: boolean = false): Promise<InstanceHealthResponse> {
	try {
	if (!instanceUrls || instanceUrls.length === 0) {
	throw new Error("At least one instance URL is required for health checking");
	}
	// Build query parameters
	const params = new URLSearchParams();
	instanceUrls.forEach(url => {
	params.append('instance_urls', url);
	});
	if (includeModels) {
	params.append('include_models', 'true');
	}
	const url = `${this.baseUrl}/api/ollama/instances/health?${params.toString()}`;
	const { data } = await this.fetchJson<InstanceHealthResponse>(url, {
	method: 'GET',
	headers: { 'Content-Type': 'application/json' },
	timeoutMs: 6000,
	etagKey: url,
	});
	return data;
	} catch (error) {
	throw this.handleApiError(error, "Instance health checking");
	}
	}

[coderabbitai]

💡 Verification agent

❓ Verification inconclusive

/models endpoint should also support ETag (and optionally 304)

Apply the same Request/Response + ETag pattern here to meet “HTTP polling with ETag caching” requirement.

---

Add ETag + 304 handling to /models endpoint

Compute a stable ETag for the discovery response (e.g. SHA256 of canonical JSON or a server-side version/last-updated), set the ETag header on 200 responses, and if the request's If-None-Match matches the ETag return HTTP 304 Not Modified with no body. Keep background cache-warming as-is and add appropriate Cache-Control/Vary headers as needed.

Location: python/src/server/api_routes/ollama_api.py -> discover_models_endpoint (lines 83–134)

🤖 Prompt for AI Agents

In python/src/server/api_routes/ollama_api.py around lines 83-134, the /models
endpoint should compute a stable ETag for the discovery response and handle
conditional requests: after obtaining discovery_result, serialize a canonical
representation (e.g., deterministic JSON of the returned dict or use a
server-side version/last-updated) and compute a SHA256 hex digest to use as the
ETag; if the incoming request contains If-None-Match that equals the computed
ETag, return HTTP 304 Not Modified with no body and the ETag header; otherwise
set the ETag header on the 200 response, include appropriate Cache-Control and
Vary headers, keep scheduling the background cache-warming as-is, and ensure the
Response object or headers are used correctly so the endpoint still returns the
ModelDiscoveryResponse body when not 304.

[coderabbitai]

🛠️ Refactor suggestion

Add ETag support to health endpoint to enable 304s (guideline requirement)

Implement conditional GETs to reduce polling load.

-from fastapi import APIRouter, BackgroundTasks, HTTPException, Query
+from fastapi import APIRouter, BackgroundTasks, HTTPException, Query, Request, Response
+import hashlib
@@
-@router.get("/instances/health")
-async def health_check_endpoint(
-    instance_urls: list[str] = Query(..., description="Ollama instance URLs to check"),
-    include_models: bool = Query(False, description="Include model count in response")
-) -> dict[str, Any]:
+@router.get("/instances/health")
+async def health_check_endpoint(
+    instance_urls: list[str] = Query(..., description="Ollama instance URLs to check"),
+    include_models: bool = Query(False, description="Include model count in response"),
+    request: Request = None,
+    response: Response = None,
+) -> dict[str, Any]:
@@
-        return {
+        payload = {
             "summary": {
                 "total_instances": len(instance_urls),
                 "healthy_instances": healthy_count,
                 "unhealthy_instances": len(instance_urls) - healthy_count,
                 "average_response_time_ms": avg_response_time
             },
             "instance_status": health_results,
-            "timestamp": model_discovery_service.check_instance_health.__module__  # Use current timestamp
+            "timestamp": datetime.utcnow().isoformat() + "Z"
         }
+        # ETag
+        body = json.dumps(payload, sort_keys=True).encode("utf-8")
+        etag = hashlib.md5(body).hexdigest()
+        if request and request.headers.get("if-none-match") == etag:
+            if response:
+                response.status_code = 304
+            return {}  # FastAPI will ignore body for 304
+        if response:
+            response.headers["ETag"] = etag
+        return payload

[coderabbitai]

⚠️ Potential issue

Bug: timestamp returns module name, not a timestamp

"timestamp": model_discovery_service.check_instance_health.module produces a module string. Return an ISO timestamp.

-            "timestamp": model_discovery_service.check_instance_health.__module__  # Use current timestamp
+            "timestamp": datetime.utcnow().isoformat() + "Z"

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	"timestamp": model_discovery_service.check_instance_health.__module__ # Use current timestamp
	}
	"timestamp": datetime.utcnow().isoformat() + "Z"
	}

🤖 Prompt for AI Agents

In python/src/server/api_routes/ollama_api.py around lines 199-200, the
"timestamp" field is incorrectly set to
model_discovery_service.check_instance_health.__module__ which returns a module
name string; replace it with a proper ISO 8601 timestamp (UTC). Ensure the
module imports datetime (or datetime.timezone) if not already, and set
"timestamp" to a UTC ISO-formatted string (e.g., use
datetime.now(timezone.utc).isoformat() or equivalent) so the API returns a
correct timestamp.