virattt/ai-hedge-fund · error · ValueError

unknown model {m.name!r} in strategy {strategy.name!r}; avai

Error message

unknown model {m.name!r} in strategy {strategy.name!r}; available: {sorted(ALPHA_MODEL_REGISTRY)}

What it means

Raised in Fund.__init__ (hedge_fund/fund/spec.py:205) when a strategy's model list references a name that is not in ALPHA_MODEL_REGISTRY. The registry maps model names to AlphaModel classes; the error message lists the available names so the fix is immediate. This validates that the mandate's model names match the code's registry — a config/code drift guard.

Source

Thrown at hedge_fund/fund/spec.py:205

    The `models` override (strategy name -> instances) exists for tests to
    inject fakes; production callers let the registry build the staff.
    """

    def __init__(
        self,
        spec: FundSpec,
        models: dict[str, list[AlphaModel]] | None = None,
    ) -> None:
        self.spec = spec
        self.strategies: list[tuple[StrategySpec, list[AlphaModel]]] = []
        for strategy in spec.strategies:
            if models is not None:
                self.strategies.append((strategy, models[strategy.name]))
                continue
            staff = []
            for m in strategy.models:
                if m.name not in ALPHA_MODEL_REGISTRY:
                    raise ValueError(
                        f"unknown model {m.name!r} in strategy "
                        f"{strategy.name!r}; available: {sorted(ALPHA_MODEL_REGISTRY)}"
                    )
                staff.append(ALPHA_MODEL_REGISTRY[m.name](**m.params))
            self.strategies.append((strategy, staff))

View on GitHub (pinned to eff8a7320f)

Solutions

1. Read the error message: it prints sorted(ALPHA_MODEL_REGISTRY) — replace the bad name in the mandate YAML with one of those.
2. If the name should exist, check for a version mismatch: the mandate was written against a different build — update the mandate or pin/use the build that has that model.
3. If you legitimately added a new model, register it in ALPHA_MODEL_REGISTRY before referencing it in a spec.

Example fix

# before (mandate.yaml)
strategies:
  - name: core
    models:
      - name: warren_buffet   # typo -> ValueError: unknown model 'warren_buffet'

# after
strategies:
  - name: core
    models:
      - name: warren_buffett  # exact registry key

from hedge_fund.signals import ALPHA_MODEL_REGISTRY  # import path per build

def validate_models(spec) -> list[str]:
    """Names in the mandate that the current build cannot instantiate."""
    return sorted(
        m.name
        for s in spec.strategies
        for m in s.models
        if m.name not in ALPHA_MODEL_REGISTRY
    )

from hedge_fund.signals import ALPHA_MODEL_REGISTRY

def model_is_registered(name: str) -> bool:
    return isinstance(name, str) and name in ALPHA_MODEL_REGISTRY

try:
    fund = Fund(spec)
except ValueError as e:
    if "unknown model" in str(e):
        raise SystemExit(f"mandate references a model this build lacks: {e}") from e
    raise

When it happens

Trigger: Constructing Fund(spec) where a StrategySpec.models entry has name='value_hunter' but the registry only knows e.g. 'value', 'momentum'. Happens after: renaming an alpha model in code without updating mandates; loading a mandate written for a newer/older build; a typo in the YAML model name. Only fires when models=None (the normal path) — passing a prebuilt models dict bypasses registry lookup via models[strategy.name].

Common situations: Upgrading the library after an alpha model was renamed/removed; hand-editing a mandate YAML and misspelling a model; sharing mandates between machines running different versions of the code.

Related errors

• unknown rebalance cadence {cadence!r}
• duplicate strategy names: {sorted(duplicates)}
• universe is empty — a run needs at least one ticker
• No v2 client for {provider} (model {model}). Supported: {',
• confidence out of range: {confidence}

AI-assisted analysis of virattt/ai-hedge-fund@eff8a7320f (2026-08-15). Data as JSON: /api/errors/04e7654a328f4a5b. Report an issue: GitHub.