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:
- 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).
- 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.
- Chat-template rendering — render your messages and tool definitions into prompt token ids client-side.
- Raw transport — send the token-level request and read the Engine's NDJSON response stream with base64-encoded attribution tensors.
- Aggregation — decode each raw chunk and aggregate token-level
attributions into word-level
input_attributionsandoutput_attributions(see Attribution). - 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 typedtool_start/tool_delta/tool_endchunks, robust against markers split across stream chunks. - Evidence (optional) —
stream_with_evidence/streamWithEvidencewraps 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 downloading the one discovery reports. |
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.7.0.