SwarphCall — swarph_mesh.swarph_call

Caller-validated, hook-wired entry point for adapter dispatch.

Tier 2 stability. Public method/kwarg shape changes trigger deprecation cycle.

SwarphCall — the public surface per PLAN.md §4.

The single entry point most callers use. Wraps caller validation (swarph_shared.validate_caller), adapter resolution (registry lookup), lifecycle hook dispatch (pre_call / post_call / on_error), the JSON-mode harness when json_schema is provided, and the structured LLMResponse return.

Example:

from swarph_mesh import SwarphCall, ChatMessage

result = await SwarphCall(
    provider="gemini",
    model="gemini-2.5-flash",
    caller="orchestrator.boss",
).chat(
    messages=[ChatMessage(role="user", content="hi")],
)
print(result.text, result.cost_usd, result.input_tokens)

Caller convention is enforced at SwarphCall construction — invalid caller strings raise ValueError before any adapter dispatch. That’s the defense-in-depth pattern from workers/caller_convention.py / swarph-shared.

class swarph_mesh.swarph_call.SwarphCall(*, provider, caller, model=None, role='agents', mesh_peer=None, hooks=None, api_key=None)[source]

Bases: object

One configured invocation context. Construct once per call site (or once per caller-role and reuse) — adapter + hooks are lazily resolved so construction is cheap.

Parameters:

  • provider (str)

  • caller (str)

  • model (Optional[str])

  • role (str)

  • mesh_peer (Optional[str])

  • hooks (Optional[HookSet])

  • api_key (Optional[str])

property adapter
async chat(messages, *, system_prompt=None, json_schema=None, temperature=0.7, max_tokens=None, timeout_seconds=None)[source]

Invoke the adapter with the configured caller / role / attribution wiring.

json_schema triggers the JSON-mode harness: parse the response, retry-once with feedback as a new [USER] turn on parse failure, populate LLMResponse.parsed.

timeout_seconds is honored at the asyncio level (wraps the adapter call in asyncio.wait_for). v0.1.0 doesn’t plumb timeouts through the bridge’s underlying SDK call — an in-flight provider request that exceeds the timeout will complete on the SDK side but its result is discarded.

TODO(v0.2.0, drop PR #1 review carry-forward #1): asyncio cancellation is Python-side only — the provider still bills for the in-flight call even if we discard the result. Under timeout-heavy workloads this creates an unbounded billing tail. Thread the timeout through bridge.invoke(timeout=...) when the bridge surface supports it; otherwise document the cost trade-off explicitly at every call site that uses timeout_seconds.

Parameters:
Return type:

LLMResponse