Types — swarph_mesh.types

The runtime-checkable LLMAdapter Protocol plus the wire types every adapter implementation must accept and return.

Tier 1 stability. Per DEPRECATIONS.md, changes to LLMAdapter method set, ChatMessage field set, or LLMResponse field set trigger the deprecation cycle.

Typed substrate for swarph-mesh — Protocol + dataclasses.

Per PLAN.md §3, every provider implements LLMAdapter. Adapters are model-agnostic; the package keeps the substrate clean and lets each adapter wrap its own provider SDK in 50-100 LOC.

The shape here is the contract Phase 1+ adapters target. Stable surface so downstream callers (omega-boss, Council, future swarph CLI) can write against the Protocol without coupling to a specific provider.

class swarph_mesh.types.ChatMessage(*, role, content)

Bases: BaseModel

A single turn in a conversation.

Roles follow the OpenAI/Anthropic convention: "user" | "assistant" | "system".

Parameters:

• role (str)

• content (str)

role: str

content: str

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class swarph_mesh.types.LLMResponse(*, text, parsed=None, input_tokens=0, output_tokens=0, cost_usd=0.0, duration_s, cached=False, error_class=None, raw_response=None)

Bases: BaseModel

Adapter return shape — provider-agnostic.

Attribution + cost fields are populated by adapters where the provider exposes them. parsed is set when the caller passed a json_schema and the response was parsed via the JSON-mode harness (see PLAN.md §7).

Parameters:

• text (str)

• parsed (dict[str, Any] | None)

• input_tokens (int)

• output_tokens (int)

• cost_usd (float)

• duration_s (float)

• cached (bool)

• error_class (str | None)

• raw_response (dict[str, Any] | None)

text: str

parsed: dict[str, Any] | None

input_tokens: int

output_tokens: int

cost_usd: float

duration_s: float

cached: bool

error_class: str | None

raw_response: dict[str, Any] | None

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class swarph_mesh.types.LLMAdapter(*args, **kwargs)

Bases: Protocol

Provider adapter Protocol — one implementation per LLM vendor.

PLAN.md §3 ship order: Gemini → DeepSeek → Claude → OpenAI → Grok.

Every adapter is a singleton per provider in SwarphCall’s registry; instantiated once at first use, reused across calls.

name: str

default_model: str

async chat(messages, model, system_prompt=None, json_schema=None, temperature=0.7, max_tokens=None)

Single-turn or multi-turn completion. Returns LLMResponse.

Parameters:

• messages (list[ChatMessage])

• model (str)

• system_prompt (str | None)

• json_schema (dict[str, Any] | None)

• temperature (float)

• max_tokens (int | None)

Return type:

LLMResponse

async stream(messages, model, **kwargs)

Token-by-token stream. Yields text chunks as they arrive.

Parameters:

• messages (list[ChatMessage])

• model (str)

• kwargs (object)

Return type:

AsyncIterator[str]

cost_per_token(model)

Return (input_per_mtok, output_per_mtok) in USD.

Parameters:

model (str)

Return type:

tuple[float, float]

list_models(*, ttl_seconds=86400)

Return swarph_mesh.discovery.ModelInfo records for this provider’s catalog. v0.6.0 architectural promotion per drop DM #720 + commander direction 2026-05-09.

Default implementation delegates to discovery.list_models with provider=self.name; AIMLAPI primary, per-provider fallback when AIMLAPI is unreachable. Adapters MAY override to merge their provider’s /v1/models shape directly when AIMLAPI lags behind a fresh release (rare; AIMLAPI’s catalog update cadence has been tight).

Returns list[ModelInfo] (not list[str]) so callers get context_length, max_tokens, aliases, tags without per-adapter hardcoding. ttl_seconds=0 forces a fresh fetch.

Parameters:

ttl_seconds (int)

Return type:

list[Any]