Skip to main content

NeoMundi Python SDK

English · Français

PyPI version REST SSE Live Tests

Connect your AI application. Trace every interaction. Measure its behavior. Verify the evidence.

INSTALL → TRACE → MEASURE → VERIFY. Four steps, and this README tells you for each one what is real today, what is partial, and what is still to be built. A promise you cannot reproduce is worse than no promise.

What each step actually does

Step What it is Status
INSTALL pip install neomundi — 2.1.0 published 2026-11-15 Real — trace() and verify() ship in the published wheel
TRACE client.trace() — local stopwatch, correlation id, explicit submission Partial — there is no trace-only route on the API; closing a trace submits one metered measurement
MEASURE client.govern() (post-call REST) and client.stream() (SSE generation proxy) Real — live-qualified against the hosted API on 2026-11-13, REST and SSE both passed
VERIFY client.verify() / client.verify_audit_certificate() (public, unmetered API routes) and verify_evidence_archive() (independent Evidence verifier) Real for emission authenticity. Archive integrity needs a second package.

What no step does: establish that an AI answer is true. See the three meanings of "verify".

INSTALL

Python 3.9+. httpx is the only runtime dependency.

# The published release: everything documented below.
python -m pip install --upgrade neomundi

# Or from source, for contributors.
git clone https://github.com/neomundi-io/neomundi-python-sdk.git
cd neomundi-python-sdk
python -m pip install -e ".[dev]"

neomundi 2.1.0 was uploaded to PyPI on 2026-11-15, and it is the first published wheel to carry trace() and verify(). 2.0.0 (2026-11-14) carried govern() and stream() only and remains installable. Publication stays gated by an explicit manual workflow: exact tag, typed confirmation, GitHub pypi environment and Trusted Publishing — the version was re-pointed, no guard was removed.

The SDK code is licensed under Apache-2.0, subject to contributor-rights review; see the licensing boundaries. The hosted Runtime Measurement API remains proprietary and commercially metered (authorised key, applicable credits/quotas and service terms). An open-source SDK does not include free hosted API access.

No API or provider credential is bundled, read implicitly or persisted. The API environment is always explicit, through base_url: the SDK assumes no host, so no call can leave for an environment you did not choose.

TRACE

import os
from neomundi import NeoMundiClient

with NeoMundiClient(
    api_key=os.environ["NEOMUNDI_API_KEY"],
    base_url=os.environ["NEOMUNDI_BASE_URL"],
) as client:

    with client.trace(client_trace_id="order-4711", model_name="gpt-4o") as trace:
        answer, usage = my_application(question)      # your own provider call
        trace.record(
            prompt=question,
            response=answer,
            token_count=usage.total_tokens,           # never guessed for you
        )

    record = trace.record_
    record.latency_ms     # MEASURED around your call, not declared by hand
    record.request_id     # the server's id — the only reliable correlation key
    record.acknowledged   # the server processed it
    record.registered     # None on REST: see below
    record.to_dict()      # safe to log: carries no prompt and no response

What TRACE gives you, and nothing more:

  • the latency is measured with time.monotonic() around your block, where 2.0.0 made you supply it by hand;
  • a correlation id of yours, paired with the id the server returns;
  • a record that is safe to log: TraceRecord holds prompt and response lengths, never their text — by construction, not by convention.

What it refuses to pretend:

  • 🔴 There is no trace-only route on the API. All eight deployed routers were read on 2026-11-15: none accepts an interaction without measuring it. Closing a trace therefore issues POST /v1/govern — one metered call. submit=False opens no socket at all.
  • 🔴 The token count is never invented. Without token_count, nothing is sent and a ConfigurationError is raised. The deployed contract requires it and the deployed response republishes it as token_count_source: "caller_declared" — the server counts nothing on this route.
  • 🔴 registered stays None on REST — and that is now an SDK choice, not a server gap. Until 2026-11-15, POST /v1/govern answered 200 even when the log write had failed, and its wire contract published no persistence field at all. Since the deployment of 03e2b344 both routes publish log_persisted and log_write, and a real call was verified in production. This SDK does not interpret the REST pair yet: it arrives in unknown_fields and stays readable as result.get("log_persisted"). Typing it would be a new feature, not a documentation fix, so TraceRecord.from_stream remains the only path where registered carries a value. Read the raw field if you need the REST answer today.
  • 🔴 Your client_trace_id is not retained by the server. The metadata field is accepted by the contract and dropped by the route. Correlation is therefore yours to keep: store the (client_trace_id, request_id) pair.
  • ⚠ "Trace every interaction" means you instrument your application. This SDK does not hook your framework, and nothing is traced that you do not record.

MEASURE

govern() and stream() are unchanged, and no existing call signature moved. token_count and latency_ms stay required: the deployed contract declares them required and the server derives neither.

result = client.govern(
    token_count=128,                               # actual observed usage
    latency_ms=842.0,                              # actual measured latency
    llm_prompt="What is the capital of France?",
    llm_response="Paris.",
)
result.governance.decision          # ALLOW / FLAG
result.format_score("g_score")      # None stays None
result.measured_signals             # what was actually measured
result.unmeasured_signals           # and why the rest was not
result.audit.measurement_version    # the only number with scientific meaning
result.token_count_source           # "caller_declared" — not a server count
result.contract_version             # "neomundi.govern.rest/1.0"

Sending metrics only is allowed, and then no semantic check runs: measurement.status reports not_attempted. An absent value stays None — no numeric default exists anywhere in this package. A complete transport can carry an incomplete measurement, and the two are reported separately.

For the SSE generation proxy — which calls your provider with your provider key, and can incur provider cost and a NeoMundi charge — see the streaming guide. Two fields are new there and matter:

stream_result.log_persisted      # server-side registration confirmation (REST has it too since 2026-11-15)
stream_result.log_write          # already_exists / already_exists_divergent / failed
stream_result.token_count_source # provider_usage, or chunk_count_fallback
stream_result.token_count_unit   # "tokens", or "chunks" on the fallback path

log_persisted is True when the key is absent: the backend emits it only on the non-nominal path. And on the fallback path total_tokens counts chunks, not tokens — read the unit before comparing two observations.

VERIFY

Three different questions wear the same verb. Mixing them is the most expensive mistake in this whole journey.

1. Emission authenticity — real, public, unmetered.

verdict = client.verify(result.request_id)
verdict.valid                 # True / False / None
verdict.payload_hash_match    # the canonical hash, recomputed server-side
verdict.signature_valid       # the Ed25519 JWS signature

GET /v1/rgc/verify/{request_id} recomputes the canonical hash from the source log and verifies the stored signature, instead of trusting either. It needs no API key and costs nothing. valid is None means nothing was verified: no RGC contract has been emitted for that observation — which is a separate, TIER_03-only call this SDK does not make. Reading that None as a failure would turn "never signed" into "invalid signature".

The same tri-state rule governs audit certificates, and there it bites harder:

cert = client.verify_audit_certificate("AT-2026-0001", sha256=printed_on_the_pdf)

Without sha256, valid is None and nothing was verified. No digest is stored at issue time, so the value printed on the holder's document is the only thing the service can compare against.

2. Archive integrity — delegated to the independent verifier.

python -m pip install neomundi-evidence-verify
from neomundi import verify_evidence_archive

outcome = verify_evidence_archive("archive.zip")
outcome.exit_code              # 0, 1, 2, 3 or 4 — the program's own
outcome.verification_performed # False for 3 and 4: nothing ran
outcome.passed                 # True / False / None

This SDK verifies nothing itself: it invokes neomundi-evidence and republishes its verdict and exit code without retranslating them, and a test enforces that it imports no hashing, archive or cryptography module. A missing verifier raises instead of returning a verdict — an absent tool produces no "valid". Exit codes 3 and 4 exist precisely so that "nothing failed" and "nothing ran" cannot return the same answer.

⚠ The conformance corpus is not in the PyPI wheel. pip install lets you verify your archives; replaying the published corpus needs a git clone of the Evidence Gateway.

3. Truthfulness of the AI answer — 🔴 none of the above.

A verified measurement is a measurement you know was not altered. It says nothing about whether the measured content is correct. factual_hallucination_score is a signal produced by a judge, with its own documented limits — not a verdict of truth. No certificate issued here certifies an AI answer.

Where we stand

Item State
REST + SSE implementation Complete, unchanged by this branch
Live qualification of the installed SDK Done 2026-11-13: REST passed, SSE passed against the hosted API
REST persistence declaration Verified in production 2026-11-15: one authorised call returned log_persisted: true / log_write: "inserted", and GET /v1/govern/{request_id} found the observation. Replaying that stored row returns log_persisted: null — a replay states no persistence verdict.
Offline tests 395 passed; 12 optional historical captures skipped
CI Python 3.9, 3.11, 3.12, 3.13
Deployed schema parity Measured byte-for-byte in GitHub Actions, and re-measured offline by this branch's fixtures
trace() / verify() Published in 2.1.0 (2026-11-15). Absent from 2.0.0.
Published measurement version The SDK declares 3.3.0, verified for 3.3.0 and 3.3.1. Production serves 3.5.0, which is deliberately not declared verified: nobody has verified it. The warning you will see is correct.

That live qualification exercised a complete measurement and a progressive stream. It did not exercise a withheld aggregate, a real error path (402, 429…) or more than one SSE provider. Passing offline tests establishes neither service availability nor compatibility with every provider. See the 3.5.0 compatibility scope and the executed checks.

Data flows, briefly

llm_prompt and llm_response are transmitted to the measurement service and processed in memory. Of them the platform persists: never the prompt (only its length), and extracts of the response inside quality.suspect_phrases when the factuality score passes its threshold. rag_context and documents are never persisted. Three of five signals run on models hosted on the service's own machine; factuality and semantic instability call one subcontractor. Everything is hosted in Switzerland. TraceRecord never carries content, so logging a trace cannot leak a prompt.

Full detail and retention: data flows and confidentiality and KNOWN_LIMITATIONS.md.

Documentation

Run it

Every example runs offline against a mock transport and exits 0.

python -m pip install -e ".[dev]"
python -m pytest tests
python examples/05_parcours_complet.py    # INSTALL -> TRACE -> MEASURE -> VERIFY
python -m build

SDK version is a client version, not a measurement version. Check the measurement version your deployment actually returns before comparing two observations.


Internal: NeoMundi crews start from the workspace cockpit, pick the chantier in CHANTIERS.md, and come back to it afterwards to record the result, the evidence and the next action. This document stays the detailed entry point for the SDK itself.

Metadata

Release files for neomundi 2.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for neomundi 2.1.0
File Size Uploaded Provenance Actions
neomundi-2.1.0.tar.gz 191.3 kB With provenance Details for neomundi-2.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for neomundi 2.1.0
File Interpreter ABI Platform Actions
neomundi-2.1.0-py3-none-any.whl Python 3 none any Details for neomundi-2.1.0-py3-none-any.whl

Total release size: 254.9 kB

Release files / neomundi-2.1.0.tar.gz

Download URL neomundi-2.1.0.tar.gz
Size 191.3 kB
Tags Source
SHA-256 checksum
How to use checksums
558f0cc553bc85304b8b99b06977101e59310bdf2fbbe242477209ddcae0347b
BLAKE2b-256 checksum
How to use checksums
32ba198c538cfb6aa4008e78b363b61b1f3e83297881cb8cf1c122ff8b4907b5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / neomundi-2.1.0-py3-none-any.whl

Download URL neomundi-2.1.0-py3-none-any.whl
Size 63.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bcaeeb76f5439e3bb0bd2b2930c6e9d5e597f176cf66dc7c3f85958a21ca0010
BLAKE2b-256 checksum
How to use checksums
a47bc76682ede1118b6c50c10d50d4f369e73347fd9f67cd34393fcc37f08392
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for neomundi 2.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for neomundi-2.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page