How 5ire Handles Offline Mode When Relying on Local Embeddings

The 5ire application transparently supports offline mode for embeddings by disabling remote model fetching, enforcing local-only model loading, and validating cached file presence, ensuring full functionality without network connectivity as long as embedding models are stored locally.

The open-source 5ire application (nanbingxyz/5ire) implements a robust offline-first architecture for its embedding services. By configuring the Transformers.js environment to reject remote requests and strictly validate local model files, the application ensures that text embedding operations continue uninterrupted during network outages.

Network Status Detection

The application monitors connectivity primarily for user feedback rather than functional gating. A lightweight React hook listens to browser-native events and propagates status changes to UI components.

The useOnlineStatus Hook

In src/hooks/useOnlineStatus.ts, the application attaches event listeners to the browser's online and offline events. The hook maintains a Boolean flag, isOnline, that components consume to render visual indicators.

// src/hooks/useOnlineStatus.ts
export default function useOnlineStatus(): boolean {
  const [isOnline, setIsOnline] = useState<boolean>(navigator.onLine);

  useEffect(() => {
    const handleOnline = () => setIsOnline(true);
    const handleOffline = () => setIsOnline(false);

    window.addEventListener('online', handleOnline);
    window.addEventListener('offline', handleOffline);

    return () => {
      window.removeEventListener('online', handleOnline);
      window.removeEventListener('offline', handleOffline);
    };
  }, []);

  return isOnline;
}

UI Feedback Components

The isOnline flag drives visual feedback in src/renderer/components/layout/WindowsTitleBar.tsx and src/renderer/components/layout/AppHeader.tsx. These components display network-status icons to alert users of connectivity changes, but critically, the flag does not gate embedding logic. The embedder operates independently of this network state, relying instead on local file availability.

// Example: UI shows offline status
import useOnlineStatus from 'hooks/useOnlineStatus';
import { WiFiIcon, WiFiOffIcon } from 'some/icon/library';

export default function NetworkIndicator() {
  const online = useOnlineStatus();
  return online ? <WiFiIcon /> : <WiFiOffIcon />;
}

Embedding Service Configuration

The core offline resilience resides in src/main/services/embedder.ts, where the Embedder class configures the Transformers.js environment to eliminate network dependencies before loading any models.

Disabling Remote Model Fetching

During initialization, the embedder explicitly disables remote model access by setting env.allowRemoteModels = false. This configuration prevents the Transformers library from attempting HTTP requests to Hugging Face or other model repositories, even if cached files are missing.

// src/main/services/embedder.ts
import { env } from '@xenova/transformers';

// Explicitly disable network access for models
env.allowRemoteModels = false;
env.allowLocalModels = true;

Enforcing Local-Only Loading

By pairing the remote disable with env.allowLocalModels = true, the application ensures that every embedding request is satisfied solely from the local filesystem. The embedder constructs pipeline instances that resolve paths within the application's Embedding/Models/ directory, guaranteeing that inference occurs entirely on-device.

Model File Validation

Before executing embeddings, the service validates that all required model files are present locally. This check prevents runtime errors that would otherwise occur when the system attempts to load non-existent weights.

File Existence Verification

The embedder references a constant array, DOCUMENT_EMBEDDING_MODEL_FILES, which lists all mandatory model artifacts. The service verifies the presence of each file in the local cache folder before transitioning to a ready state.

// Conceptual validation logic in embedder.ts
const requiredFiles = DOCUMENT_EMBEDDING_MODEL_FILES;
const allFilesPresent = requiredFiles.every(file => 
  fs.existsSync(path.join(MODEL_CACHE_DIR, file))
);

if (!allFilesPresent) {
  this.state = { status: { type: 'unavailable' } };
}

Unavailable State Handling

If any required file is missing, the embedder transitions to an unavailable state and returns explicit errors for embedding requests. This failure mode requires user intervention to reinstall the model (an operation needing network connectivity), but it prevents the application from hanging or crashing while attempting impossible network downloads.

The Offline Embedding Workflow

When a user transitions from online to offline, the embedding pipeline continues functioning through the following deterministic flow:

1. Network Event Detection: The browser fires an offline event, updating useOnlineStatus to false. UI components render disconnect icons in WindowsTitleBar.tsx and AppHeader.tsx.

2. Embedding Request Processing: A request arrives at Embedder.embed(). The method checks its internal ready state rather than network connectivity.

3. Local Model Resolution: Since env.allowRemoteModels is permanently set to false, the embedder does not attempt internet downloads. It resolves the model path to the local cache directory (Embedding/Models/...).

4. Inference Execution: If all files in DOCUMENT_EMBEDDING_MODEL_FILES exist, the Transformers pipeline loads from disk and returns embedding vectors. If files are missing, the embedder returns an unavailable state error.

// Example: Embedding while offline (no explicit online check needed)
import { embed } from '@/main/services/embedder';

async function getEmbedding(text: string[]) {
  // The embedder will use the locally cached model.
  const [vector] = await embed(text);
  return vector;
}

Offline Package Management

Beyond embedding models, the application extends offline preferences to Node.js package management. In src/mcp.config.ts, the downloader configuration includes the --prefer-offline npm flag, ensuring that Model Context Protocol (MCP) server installations favor cached copies over network requests when available.

// Example: Downloader prefers offline cache for npm packages
const installCommand = [
  'npm', 'install', '--prefer-offline', '@modelcontextprotocol/server-slack',
];

This configuration aligns with the embedding service's offline-first philosophy, minimizing network dependencies across the entire application stack.

Summary

• Network monitoring is UI-only: The useOnlineStatus hook provides visual feedback but does not gate embedding functionality.
• Remote fetching is permanently disabled: env.allowRemoteModels = false in src/main/services/embedder.ts guarantees no network requests for models.
• Local validation is mandatory: The embedder checks DOCUMENT_EMBEDDING_MODEL_FILES before inference, entering an unavailable state if files are missing.
• Offline works transparently: As long as model files reside in the local cache, embedding operations proceed normally without internet connectivity.
• Package management supports offline: The --prefer-offline flag in src/mcp.config.ts extends offline resilience to dependency installation.

Frequently Asked Questions

Does 5ire block embedding requests when the network is disconnected?

No. The application does not use the network status flag to gate embedding logic. Instead, the Embedder class in src/main/services/embedder.ts checks only for the presence of local model files. If the required files exist in the cache directory, embeddings proceed normally regardless of connectivity state.

What happens if embedding model files are missing while the user is offline?

The embedder transitions to an unavailable state and returns an error for any embedding request. Because env.allowRemoteModels is set to false, the application cannot download missing files automatically. The user must restore network connectivity to reinstall the model files via the application's downloader.

How does the UI communicate offline status to users?

Components in src/renderer/components/layout/WindowsTitleBar.tsx and src/renderer/components/layout/AppHeader.tsx consume the useOnlineStatus hook to display network-status icons. When the browser detects an offline event, these components render a disconnected indicator, providing immediate visual feedback while the embedding service continues operating in the background.

Are dependencies installed with offline preferences?

Yes. According to src/mcp.config.ts, npm install commands include the --prefer-offline flag. This instructs the package manager to use cached versions of Model Context Protocol servers when available, reducing installation failures during network outages.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}