JuliusBrussee/caveman · error · ValueError

assemble requires model and session_id

Error message

assemble requires model and session_id

What it means

`assemble()` requires both `model` and `session_id` in the options because the assembly cache/stability ledger is keyed per session and per model. It raises this ValueError immediately when either field is empty or missing.

Solutions

  1. Set both `model` and `session_id` to non-empty strings before calling `assemble()`.
  2. Generate a session id at session start (e.g. `uuid4().hex`) if one is missing.
  3. Fail fast in your own code: validate options before invoking `assemble()`.

Example fix

// before
opts = AssembleOptions(provider="anthropic", model="", session_id=sid)
cave.assemble(opts)
// after
opts = AssembleOptions(provider="anthropic", model="claude-sonnet-4", session_id=sid)
cave.assemble(opts)
Defensive patterns

Strategy: validation

Validate before calling

def can_assemble(opts) -> bool:
    return bool(opts.model) and bool(opts.session_id)

Try / catch

try:
    result = cave.assemble(opts)
except ValueError as e:
    logger.error("assemble options invalid: %s", e)
    raise

Prevention

When it happens

Trigger: Calling `cave.assemble(AssembleOptions(...))` with `model=""`, `session_id=""`, or omitting these fields on the options object.

Common situations: Building options dynamically where the model name comes from an unset env var or a failed lookup, or forgetting to generate a session id on a new session.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20). Data as JSON: /api/errors/124f8cf4ada05c84. Report an issue: GitHub.

Appendix: source

Thrown at packages/sdk/python/caveman_cloud/core.py:438

        """A fresh :class:`RetryLoopBreaker` that interrupts a repeated identical
        tool-call loop after ``threshold`` consecutive repeats.
        """
        return RetryLoopBreaker(threshold=threshold)

    def assemble(self, options: AssembleOptions) -> AssemblyResult:
        """Build a provider request with stable/session content above volatile.

        Pure client-side: no account and no network call. The hash ledger is
        in-process and scoped by ``session_id``; deterministic slot content
        across processes remains the builder's obligation.

        ``emit_cache_hints="gateway"`` (default) emits no provider hint so the
        gateway optimizer retains attribution. ``"self"`` places provider
        hints for direct calls but mints nothing.
        """
        provider = options.provider.strip().lower()
        if not options.model or not options.session_id:
            raise ValueError("assemble requires model and session_id")
        if options.emit_cache_hints not in {"gateway", "self", "none"}:
            raise ValueError(f"unknown emit_cache_hints value {options.emit_cache_hints!r}")

        ids: set[str] = set()
        normalized: list[AssemblySlot] = []
        for slot in options.slots:
            if not slot.id or slot.id in ids:
                raise ValueError(f"assembly slot id must be non-empty and unique: {slot.id!r}")
            ids.add(slot.id)
            if slot.stability not in {"stable", "session", "volatile"}:
                raise ValueError(
                    f"assembly slot {slot.id!r} has unknown stability {slot.stability!r}"
                )
            try:
                content_json = _canonical_json(slot.content)
                content = json.loads(content_json)
            except (TypeError, ValueError):
                raise ValueError(

View on GitHub (pinned to 3ee70a1026)