swarph-mesh

Model-agnostic Python substrate for the swarph-mesh ecosystem — the graph protocol third-party CLIs plug into.

swarph-mesh is the bottom layer of a four-package ecosystem:

Package	Role
swarph-shared	substrate primitives shared across all swarph packages (caller convention, subprocess env scrubbing, JSON mode, peer registry)
swarph-mesh (this package)	typed Protocol + adapters + SwarphCall + MeshClient + discovery
swarph-cli	swarph CLI binary; thin wrapper over swarph-mesh
swarph-meshlm	Simon Willison llm plugin

What this documentation covers

This site auto-renders the public contract surface of swarph-mesh. The contract is enumerated in DEPRECATIONS.md — Tier 1 / Tier 2 / Tier 3.

• Tier 1 — third-party-node-implementer-facing primitives. Highest stability. LLMAdapter Protocol, ChatMessage, LLMResponse, MeshClient, MeshMessage, discovery primitives. Changes here trigger the deprecation cycle in DEPRECATIONS.md.

• Tier 2 — consumer-facing-but-internal-friendly. SwarphCall, AttributionWriter, HookSet, normalization helpers.

• Tier 3 — best-effort-documented. Adapter-local PRICING dicts, internal pricing tables.

• Not part of the contract — module-level private _* symbols, test fixtures, mesh-gateway database schema (separate repo).

If a symbol is not visible in these auto-generated pages, it is not part of the contract.

Stability commitments

Three documents anchor the contract surface:

• SECURITY.md — 9 in-scope vulnerability classes; “Protocol contract violation” is reportable as a security event.

• DEPRECATIONS.md — what counts as breaking, deprecation cycle requirements, mypy-strict ratchet schedule.

• CHANGELOG.md — full per-release history.

API reference

• Types — swarph_mesh.types
  • ChatMessage
  • LLMResponse
  • LLMAdapter
• Adapters — swarph_mesh.adapters
  • get_adapter()
  • register_adapter()
  • reset_registry()
• SwarphCall — swarph_mesh.swarph_call
  • SwarphCall
• MeshClient — swarph_mesh.mesh_client
  • MeshGatewayError
  • MeshAuthError
  • MeshSecretLeakError
  • MeshClient
  • Wire types — swarph_mesh.mesh_types
• Discovery — swarph_mesh.discovery
  • ModelInfo
  • invalidate_catalog()
  • list_models()
  • is_model_supported()
  • get_model_info()
  • normalize_xai_id()
  • normalize_deepseek_id()
  • normalize_model_id()
  • is_retired()
  • retirement_date()
  • ProviderPricing
  • invalidate_pricing()
  • fetch_gemini_pricing()
  • pricing_for_anthropic_model()
  • list_anthropic_pricing()
  • DeepSeekBalance
  • fetch_deepseek_balance()
  • XAICostBucket
  • fetch_xai_cost_buckets()
  • reconcile_xai_cost()
  • CostBucket
  • fetch_openai_cost_buckets()
  • reconcile_openai_cost()
  • pricing_for_gemini_model()
• Attribution — swarph_mesh.attribution
  • AttributionEvent
  • AttributionWriter
  • NullAttributionWriter
  • FileAttributionWriter
  • get_default_writer()
  • set_default_writer()
  • make_event()
• Hooks — swarph_mesh.hooks
  • CallContext
  • HookSet
  • attribution_post_call()
  • default_hooks()
• Exceptions — swarph_mesh.exceptions
  • SwarphMeshError
  • AdapterError
  • UnknownProvider

Project

• Changelog
• Versioning Policy & Deprecations Tracker
• Security Policy

Indices

• Index

• Module Index

• Search Page