API Catalog Intersection Logic

Relevant source files

The following files were used as context for generating this wiki page:

• lib/catalog.sh
• README.md
• lib/auth.sh
• lib/menu.sh
• lib/config.sh
• lib/flags.sh

The API Catalog Intersection Logic is a core component of ollacc responsible for determining which Ollama Cloud models are presented to the user. Its primary purpose is to filter the current most popular models from the Ollama library against the specific set of models available to the authenticated user's account. This ensures that the user is only presented with models they are authorized to call, while prioritizing trending or highly-used options.

Sources: lib/catalog.sh:17-19, README.md:31-35, README.md:144-150

Architecture and Data Flow

The logic operates through a multi-stage retrieval and filtering process. It primarily utilizes three data sources: an authenticated API response, a public web scrape of "popular" models, and a hardcoded fallback list.

Logic Component Overview

Component	Function
Auth'd Catalog Fetch	Retrieves the full list of tags/models available to the provided ANTHROPIC_AUTH_TOKEN.
Popular Scrape	Scrapes the public "Popular" cloud model list from ollama.com.
Intersection Engine	Iterates through popular slugs and verifies their existence in the Auth'd Catalog.
Fallback System	Provides secondary (Auth'd list only) and tertiary (hardcoded) lists if primary steps fail.

Sources: lib/catalog.sh:25-90, README.md:144-150

Retrieval Sequence

The following diagram illustrates how catalog_resolve fetches and intersects data from remote endpoints.

Core Implementation Details

The Intersection Algorithm

The intersection logic is implemented in the catalog_resolve function. It uses a while loop with regex matching to extract model slugs from the scraped HTML. For each slug found, it performs a literal substring check against the JSON response from the authenticated API.

1. Extraction: It looks for href="/library/([^\"/]+)\" in the scraped HTML.
2. Verification: It checks if the slug exists in the authd_json string using grep -qF "\"name\":\"$candidate\"".
3. Constraint: The process stops once the MAPFILE array reaches 10 entries.

Sources: lib/catalog.sh:54-66

Fallback Mechanisms

To ensure the application remains functional during network instability or API changes, the system implements a tiered fallback strategy:

1. Popular + Auth'd: The preferred method combining popularity and authorization.
2. Auth'd Only: If the scrape fails, the system uses the raw order of models returned by the /api/tags endpoint.
3. Hardcoded Defaults: If both network requests fail, a hardcoded list of "last-resort" models is used to populate the menu.

Sources: lib/catalog.sh:68-89

Interaction with System Components

Configuration and Environment

The intersection logic depends on several environmental factors and configuration settings managed by other modules:

• Authentication: Requires ANTHROPIC_AUTH_TOKEN to be set via lib/auth.sh.
• Persistence: Uses config_set from lib/config.sh to save user defaults chosen from the intersected list.
• Escaping: Utilizes bash_escape to ensure model names containing special characters do not break grep operations or config sourcing.

Sources: lib/auth.sh:33-54, lib/catalog.sh:9-11, lib/config.sh:16-30

Menu Rendering

Once the intersection logic populates the global MAPFILE array, lib/menu.sh renders the choices to the user. This menu includes the intersected models plus a "[Custom]" option for models not found in the top 10.

Sources: lib/menu.sh:7-24

Summary

The API Catalog Intersection Logic provides a dynamic, self-updating model selection system. By scraping the live "Popular" list and validating it against user-specific permissions, it balances current trends with functional reliability. The inclusion of multi-stage fallbacks ensures that even in degraded network conditions, the user can still select a model and proceed to the Claude Code session.

Sources: lib/catalog.sh:25-90, README.md:144-150