Skip to main content
Version: 0.7.0

Architecture

The SDK is a client for the invera Engine raw-attribution Engine. The Engine owns generation and attribution computation; the SDK owns everything needed to turn the raw wire protocol into ready-to-consume attributed completions.

The pipeline behind one stream​

Every call to client.chat.completions.stream runs this pipeline:

  1. Discovery — fetch the Engine's model list, take the one model the endpoint serves, and validate the contract version and the model's capabilities (see Compatibility).
  2. Tokenizer parity — load the exact tokenizer revision the Engine reports and verify its fingerprint locally before using it. Tokenization is owned by the SDK, so prompt token ids are identical on both sides.
  3. Chat-template rendering — render your messages and tool definitions into prompt token ids client-side.
  4. Raw transport — send the token-level request and read the Engine's NDJSON response stream with base64-encoded attribution tensors.
  5. Aggregation — decode each raw chunk and aggregate token-level attributions into word-level input_attributions and output_attributions (see Attribution).
  6. Tool-call parsing — when the Engine recommends it for the model (Qwen <tool_call> markers with JSON or XML-per-parameter bodies), parse tool-call segments into typed tool_start / tool_delta / tool_end chunks, robust against markers split across stream chunks.
  7. Evidence (optional) — stream_with_evidence / streamWithEvidence wraps the finished chunk stream and reconstructs claims and tool-call assessments (see Evidence and verdicts). The evidence layer runs entirely client-side and adds no Engine round-trips.

Applications receive the finished stream and never assemble these pieces.

Golden Path and Advanced entry points​

The main package entry exports the Golden Path: InveraClient, the request and chunk types, and the evidence types. Extension points live in a deliberately separate advanced entry so that the primary API stays small:

Advanced exportUse case
createClientWithTokenizer / create_client_with_tokenizerSupply a host-managed tokenizer instead of downloading the one discovery reports.
aggregateCompletion / aggregate_completionRun token-to-word aggregation over a custom raw stream.
decodeRawAttributionChunk / decode_raw_attribution_chunkDecode a single raw NDJSON payload.
parseQwenToolCalls / parse_qwen_tool_callsApply tool-call parsing to a custom chunk stream.
streamEvidence / stream_evidenceCompose the evidence layer with a custom chunk stream.

Language parity​

The Python and TypeScript SDKs expose the same public surface under language-idiomatic names (stream_with_evidence / streamWithEvidence, grounding_score / groundingScore, …). The documentation build checks the two APIs against each other, and both packages are released together with a single version — currently 0.7.0.