HKUDS/Vibe-Trading · error · ValueError

unknown universe {v!r}; expected one of {sorted(_BENCH_UNIVE

Error message

unknown universe {v!r}; expected one of {sorted(_BENCH_UNIVERSES)}

What it means

After successfully importing the local connector adapter module, load_adapter verifies the read-only contract: the module must expose callable check_status(), get_account_snapshot(), and get_positions(). If any is missing or not callable, RuntimeError names the missing operation. This is the enforcement of the plugin scaffold contract for read-only connectors.

Source

Thrown at agent/src/api/alpha_routes.py:173

    zoo: str = Field(..., min_length=1, max_length=64)
    universe: str = Field(..., min_length=1, max_length=64)
    period: str = Field(..., min_length=4, max_length=32)
    top: int = Field(20, ge=1, le=500)

    @field_validator("zoo")
    @classmethod
    def _zoo_known(cls, v: str) -> str:
        if v not in _VALID_ZOOS:
            raise ValueError(
                f"unknown zoo {v!r}; expected one of {sorted(_VALID_ZOOS)}"
            )
        return v

    @field_validator("universe")
    @classmethod
    def _universe_known(cls, v: str) -> str:
        if v not in _BENCH_UNIVERSES:
            raise ValueError(
                f"unknown universe {v!r}; expected one of {sorted(_BENCH_UNIVERSES)}"
            )
        return v


class CompareRequest(BaseModel):
    """POST /alpha/compare body — a head-to-head of >= 2 named alphas."""

    alpha_ids: list[str] = Field(..., min_length=2, max_length=50)
    universe: str = Field(..., min_length=1, max_length=64)
    period: str = Field(..., min_length=4, max_length=32)
    sort: str = Field("ir", min_length=1, max_length=32)

    @field_validator("alpha_ids")
    @classmethod
    def _ids_well_formed(cls, v: list[str]) -> list[str]:
        # De-duplicate (preserve order) and validate each id shape.
        seen: set[str] = set()

View on GitHub (pinned to 80ffdda44c)

Solutions

1. Open the adapter module and add the missing function(s) with module-level def, exact names: check_status, get_account_snapshot, get_positions
2. If you renamed one, rename it back to the contract name
3. Compare with a freshly scaffolded connector (plugin_scaffold) to confirm the required module-level API

Example fix

# before: missing get_positions
def check_status(*, credentials, config): ...
def get_account_snapshot(*, credentials, config): ...

# after: implement all three module-level callables
def check_status(*, credentials, config): ...
def get_account_snapshot(*, credentials, config): ...
def get_positions(*, credentials, config):
    return {"positions": []}

import importlib.util

REQUIRED_OPS = ("check_status", "get_account_snapshot", "get_positions")

def adapter_satisfies_contract(module_path: str) -> bool:
    spec = importlib.util.spec_from_file_location("_probe", module_path)
    mod = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(mod)
    return all(callable(getattr(mod, op, None)) for op in REQUIRED_OPS)

def is_valid_adapter(module) -> bool:
    return all(callable(getattr(module, op, None)) for op in ("check_status", "get_account_snapshot", "get_positions"))

try:
    adapter = load_adapter(plugin)
except RuntimeError as e:
    if "is missing" in str(e):
        # report which operation and point dev at the adapter file
        log.error("adapter contract violation: %s", e)
    raise

When it happens

Trigger: A developer hand-edited a scaffolded connector and deleted or renamed one of the three required functions, or returned a non-callable attribute (e.g. assigned a dict to get_positions). Then any read call via _local_plugin_call raises this.

Common situations: Filling in the scaffold but forgetting one function, renaming get_account_snapshot to something else, defining them nested inside another function/class, or syntax that makes the attribute a variable instead of a function.

Related errors

• unknown zoo {v!r}; expected one of {sorted(_VALID_ZOOS)}
• invalid alpha_id {aid!r}
• need at least 2 distinct alpha_ids to compare
• {exc}
• unknown sort {v!r}; expected one of {sorted(_VALID_SORTS)}

AI-assisted analysis of HKUDS/Vibe-Trading@80ffdda44c (2026-08-28). Data as JSON: /api/errors/736ac7e5445afc43. Report an issue: GitHub.