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, select a model this SDK release supports, and validate the contract version (see Compatibility).
2. Tokenizer parity — load the release-pinned tokenizer for the selected model profile and verify its identity (revision and fingerprint) against what the Engine expects. 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 XML markers), 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 export	Use case
createClientWithTokenizer / create_client_with_tokenizer	Supply a host-managed tokenizer instead of the release-pinned default.
aggregateCompletion / aggregate_completion	Run token-to-word aggregation over a custom raw stream.
decodeRawAttributionChunk / decode_raw_attribution_chunk	Decode a single raw NDJSON payload.
parseQwenToolCalls / parse_qwen_tool_calls	Apply tool-call parsing to a custom chunk stream.
streamEvidence / stream_evidence	Compose 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.3.2.