impact

This packaged guide describes the current Python API. The source checkout is version 1.2.0rc3 and remains unpublished. Its runtime completed local installed qualification; that evidence stays bound to the recorded artifact. Public 1.2.0rc1 is a separate frozen artifact. See Qualification before choosing an install source.

Impact's Python SDK captures the available semantic content of AI Product work while preserving the application's results, errors, streams, tool effects and existing OpenTelemetry setup. Maintained provider and framework instrumentation owns its native spans; Impact adds only the lifecycle, schema, credential and Product-context evidence needed to close demonstrated gaps. Importing it is passive. Call impact.init() once before creating supported provider or framework clients.

The package requires Python 3.11 or newer. Product-key setup and the retained capture capabilities completed their selected installed qualification on the recorded candidate. Remote Capture and a general launcher remain potential future work under the canonical SDK contract. Preloaders remain unimplemented; native-required startup or per-client registration keeps its actual integration-specific status described below.

Install from the source checkout

For source evaluation, build the wheel from the repository root. The base package includes Impact's capture machinery but does not install provider clients or application frameworks:

artifact_dir=$(mktemp -d)
uv build --wheel --project python --out-dir "$artifact_dir"
sdk_version=$(python3 -c 'import pathlib, tomllib; print(tomllib.loads(pathlib.Path("python/pyproject.toml").read_text())["project"]["version"])')
sdk_wheel="$artifact_dir/impact-${sdk_version}-py3-none-any.whl"
test -f "$sdk_wheel"

The published frozen release can be installed with python -m pip install 'impact==1.2.0rc1'. The local wheel commands in this guide are the valid path for the source version before publication.

Install through the application's dependency manager so it resolves Impact together with the application's existing requirements. For a uv project, run this from that application's directory:

uv add "$sdk_wheel"

For a pip requirements workflow, resolve both inputs together with python -m pip install -r requirements.txt "$sdk_wheel", then retain the Impact dependency in the application's requirements. A direct uv pip install "$sdk_wheel" is suitable for a fresh disposable environment; it does not enforce an existing project's pyproject.toml or lockfile.

The package declares the coordinated OpenTelemetry 1.43/0.64 and 1.44/0.65 families. Its ranges preserve either compatible family selected by the application; the development lock retains the exact 1.43.0/0.64b0 baseline. The optional Google ADK 2.7 cell requires OTel API/SDK at most 1.43, so impact[adk] resolves with the 1.43 family rather than 1.44; the base SDK and other compatible extras may select either admitted family. Applications pinned to an older incompatible family need a coordinated telemetry dependency upgrade before installing it. For example, a project requiring SDK 1.39.1 and FastAPI instrumentation 0.60b1 fails normal project resolution; installing the wheel alone replaces some dependencies and leaves that older instrumentation inconsistent. Resolve the complete application and verify its native behavior after an intentional dependency upgrade. Impact preserves compatible customer libraries; it cannot make conflicting OpenTelemetry package requirements coexist in one Python environment.

Applications normally keep their existing provider and framework dependencies. The extras are optional convenience sets for installing the selected customer libraries into a new application or qualification environment; they are not needed when those libraries are already installed. pyproject.toml publishes bounded client ranges only where lower/current source cells share the selected seam; uv.lock records the exact current development cell. Installed-artifact and Product evidence still binds an exact resolved version and does not transfer automatically to every admitted version.

The package admits OTel 1.43/0.64 and 1.44/0.65, protobuf 6.33.5 through 7.x, and Requests 2.33 through 2.x; exact resolved versions remain part of each qualification receipt. Measure installation size, startup and memory in the application's resolved environment. Historical host-specific measurements are indexed in the source repository's release evidence and archived qualification index.

Quickstart

Configure IMPACT_ENDPOINT with the application API origin and IMPACT_API_KEY with the Product key generated by Impact; enable its Traces grant for capture. IMPACT_SERVICE_NAME is optional. The SDK resolves the authenticated connection settings for a Product key (ipk_); existing direct OTLP endpoint/ingest-key configuration remains supported. Set OPENAI_API_KEY for this example. The provider key authenticates the model call; the Impact key grants only the selected Impact capabilities. Initialization does not activate Simulation or Protect. Product-key initialization performs a bounded hosted connection protocol version 2 check. If it fails, initialization raises a setup error before installing hooks or exporters; retry after repairing the connection. Decide at the application startup boundary whether an observability setup failure should prevent startup. Direct OTLP initialization does not use hosted discovery. Run this file with Python 3.11 or newer after installing the OpenAI client, either directly or with Impact's optional openai convenience extra:

import impact

runtime = impact.init()
# Initialize before making supported provider/framework calls.
from openai import OpenAI

client = OpenAI()
try:
    result = client.responses.create(
        model="gpt-4.1-mini-2025-04-14",
        input="Say hello in one sentence.",
    )
    print(result.output_text)
finally:
    runtime.shutdown()

For async application startup, use runtime = await impact.init_async() with the same options. Product discovery runs outside the event loop with a six-second caller wait limit; cancellation or timeout cannot install a late runtime. The subsequent local initialization is synchronous. init() uses connect/read inactivity limits and a bounded response body, rather than a strict total request deadline. Protect activation and Simulation registration remain synchronous explicit APIs; call them at an appropriate startup boundary.

Ordinary supported provider calls require only initialization. Use scoped context when the application has useful identities to supply, and a manual span to capture a larger application operation:

This complete enrichment example runs in its own process:

import impact

runtime = impact.init()
from openai import OpenAI

client = OpenAI()
try:
    with impact.context(
        session_id="conversation-1", execution_id="request-42", user_reference="customer-17"
    ):
        with impact.span("answer", role="entry", input={"question": "Where is my order?"}) as operation:
            result = client.responses.create(
                model="gpt-4.1-mini-2025-04-14",
                input="Explain how a customer can find their order status.",
            )
            answer = result.output_text
            operation.set_output(answer)
    print(answer)
finally:
    runtime.shutdown()

context and span add information without being required for automatic provider capture. Set stable deployment defaults with init(context=impact.ImpactContext(...)) using environment, version_id, component_id, build_id and deployment_id when those values are known.

Route credentials establish Workspace and Product tenancy. Context values are correlation claims. Keep Environment, Product Version, component/build/deployment, Session, execution, parent execution, purpose, user reference and DomainRun(kind, id) distinct. A Simulation run ID must not be reused as an execution or Session ID.

Core API and lifecycle

Manual capture never changes application exceptions or cancellation identity. Serialization loss leaves an explicit partial or omission marker. Context identifiers allow 1,024 UTF-8 bytes and purpose allows 65,536; empty strings, NUL, malformed Unicode and unknown fields reject before capture.

inject_context() combines initialized context defaults with the current scope's overrides. It fills and returns the supplied carrier with W3C traceparent/tracestate, impact-execution-id, impact-parent-execution-id, impact-session-id, and the optional impact-domain-run-kind/impact-domain-run-id pair. A conflicting existing value raises ValueError without changing the input; equal values are accepted. Successful shutdown removes initialized defaults. JavaScript uses the same selected wire fields. Python reports malformed/incomplete fields in extraction issues; inspect those and validate the sender's trust before applying correlation; carrier values never authorize a Product route.

Shared execution provenance uses impact.execution.origin, impact.execution.input.reference and distinct impact.<evaluation|dataset|case|experiment|replay>.id attributes. Source references use code.file.path, code.function.name, code.line.number, impact.source.basis.id and impact.source.observed.at; correlation values use impact.correlation.*, matching JavaScript's custom fields. These supplied claims do not establish route authority or trigger source inspection. Product retains older attribute dialects when reading history.

Every listed automatic integration defaults to "auto". Disable an installed owner when the application needs to retain that owner without Impact importing or changing it:

runtime = impact.init(
    service_name="support-agent",
    endpoint="https://your-impact-endpoint",
    api_key="your-impact-key",
    integrations=impact.IntegrationOptions(
        openai="disabled",
        langchain="disabled",
    ),
)

The other supported keys are google, google_adk, anthropic, openai_agents, agno, pydantic_ai, aws_bedrock, microsoft_agent_framework and mcp. Selections are frozen, appear in status().integrations and form part of initialization identity; repeated init() calls must use equivalent selections. Realtime attachment remains an explicit API because the application owns the connection.

Managed mode reads IMPACT_ENDPOINT, IMPACT_API_KEY and IMPACT_SERVICE_NAME, or accepts explicit endpoint, api_key and service_name options. Missing configuration is diagnosed before capture. Set sampling="all" (default), "none", or a finite float greater than zero and at most one, such as 0.1, for parent-aware whole-operation sampling. A supplied customer provider owns its sampler; conflicting SDK sampling configuration rejects before activation.

Hosted Product-key applications may opt into lightweight runtime presence:

runtime = impact.init(
    presence=True,
    context=impact.ImpactContext(version_id="release-7"),
)

Presence is off by default. Set IMPACT_PRESENCE=true or IMPACT_PRESENCE=false to configure it from the environment; an explicit presence=True or presence=False takes precedence. The Product connection must advertise the authorized presence endpoint. Direct OTLP configuration does not acquire presence authority and remains otherwise unchanged. Presence sends bounded metadata containing the canonical discovered Product and Environment, generated runtime ID, installed SDK and Python versions, service name and the explicitly supplied Product Version ID. It does not scan source files, start application work, report a process count or establish Trace, Simulation, Protect or Source health. status().presence reports only the locally known attempt outcome. Shutdown fences renewals and makes one bounded best-effort stopped report; the platform's last-seen time and finite lease remain authoritative. Python's HTTP socket timeouts bound connection and response-header inactivity but cannot forcibly cancel an in-flight DNS or socket call. If it outlives the shutdown join budget, shutdown reports incomplete presence cleanup and a retry joins the same worker while other owned capture cleanup continues.

IMPACT_VERSION_ID supplies the initialized Product Version ID when ImpactContext(version_id=...) does not. An explicit context value takes precedence, and an absent setting leaves the version unknown. The environment value is trimmed; a blank value is treated as absent. This same initialized value labels native Trace context, the default Simulation target selector and presence metadata; it is never inferred by inspecting the application or repository. Supply the same IMPACT_VERSION_ID to the Source CLI upload job and the actual deployed application environment. Exporting it only during Source upload does not configure the running application.

Use a closed destination policy when an Impact route must omit selected content categories:

runtime = impact.init(
    content={
        "input": False,
        "output": False,
        "tools": False,
        "retrieval": False,
        "media": False,
    },
)

The five optional Boolean fields default to True; an omitted content setting preserves full capture. tools controls tool arguments and results, retrieval includes memory content, input includes instructions, and media controls observed image/audio/video/file bytes. Configuration is validated and snapshotted before activation. Impact applies it to detached Impact span and log copies before serialization, size accounting and queueing, while customer records and independently configured destinations remain unchanged. Restricted records carry the compact normalized policy in impact.content.policy and impact.content.<category>=omitted.policy. A projection failure drops that Impact record and increments the signal's content_dropped status count; it never exports the unrestricted record.

The selected OpenTelemetry GenAI and Botocore owners share OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT but interpret it differently. Impact snapshots an explicit value, applies the owner's enum or Boolean meaning only to records from that owner, and never rewrites the environment. An unset value does not restrict the separate Impact destination. An invalid explicit value disables an affected Impact-owned acquisition path; records from an already active unowned path are dropped if its control cannot be interpreted. Unrelated customer and Impact records continue.

Automatic callsites require an explicit source root and deployment/source basis:

runtime = impact.init(
    callsites={"root": "/srv/my-application", "basis": "git:0123456789abcdef"}
)

Impact walks at most 32 active frames when an owned span starts, emits only a path relative to the supplied root plus function and line, and retains no frames. It does not read source, discover a repository, resolve symlinks or emit the host absolute root. Omit callsites when no trustworthy mapping is available, or set enabled=False for a global opt-out. Explicit ImpactContext(source=...) facts remain authoritative.

Automatic setup reporting requires the complete route envelope supplied by Impact: IMPACT_SETUP_REPORT_ENDPOINT, IMPACT_SETUP_REPORT_API_KEY, IMPACT_ROUTE_ID, IMPACT_ROUTE_REVISION and IMPACT_ENVIRONMENT_ID. The developer still makes no additional SDK call. If that envelope is absent, capture continues and status().setup_report.outcome is not-configured; a partially supplied envelope rejects during initialization instead of guessing route ownership. IMPACT_ENVIRONMENT_ID alone does not activate setup reporting or supply application context; pass application environment meaning explicitly with context=ImpactContext(environment="...").

Managed mode supplies endpoint and api_key. Impact owns its provider only when tracer_provider is omitted. When no process-global tracer provider has already been registered, Impact also registers that managed provider through OpenTelemetry's public API so libraries with native global instrumentation route through the same destination. It never replaces an earlier global provider. In that case, status().provider_ownership["global_traces"] is "external"; pass the customer provider as tracer_provider if Impact should attach its destination to it. Impact owns a LoggerProvider only when an endpoint is present and no logger is supplied. Shutdown closes only SDK-owned resources; replacing or reconfiguring capture after shutdown requires a new process.

Customer-owned mode uses public provider APIs:

import os

runtime = impact.init(
    service_name="support-agent",
    tracer_provider=customer_tracer_provider,
    logger_provider=customer_logger_provider,
    endpoint=os.environ["IMPACT_ENDPOINT"],
    api_key=os.environ["IMPACT_API_KEY"],
)

When supplying a customer provider, pass the Impact endpoint and key explicitly as above. Omitting both selects customer-routed delivery, even if the managed-mode environment variables are present. In that mode, the customer's exporter must already send to Impact; exporting to another destination alone does not create an Impact Trace.

With an Impact endpoint, destination processors export detached copies and leave customer records unchanged. Without an endpoint, delivery remains customer-owned; correlated content logs require an explicit LoggerProvider. Customer samplers remain authoritative, and processors attached to customer providers remain installed but inactive after shutdown because Python OpenTelemetry exposes no public removal API.

Integrations

Machine-readable status().integration_details reports support state, package versions, activation, operation boundaries, limitations and suggested fixes. Qualification history is maintained with release records and is not part of runtime status. An installed extra, import or local flush alone does not prove capture or Product readback. The table below defines each operation boundary.

Framework and provider spans can describe distinct work in one execution; their presence does not prove another paid call. Existing customer instrumentation and destinations remain customer-owned.

The base package installs the selected OpenTelemetry capture owners for every retained integration. It does not install provider clients, application frameworks, MCP or Realtime transports. impact.init() checks for those customer libraries without importing absent or disabled integrations and activates only the applicable owners.

The matrix records the selected versions resolved by the maintained all-extras environment. Optional public client convenience extras use bounded compatible ranges where the same public seam passes the lower and current cells. Narrow cells remain explicit: OpenAI Realtime stays on openai==3.8.0; Google ADK stays on 2.7.0 and caps the resolved OTel API/SDK at 1.43; ADK 2.8 and 2.9 cap OpenTelemetry below the version required by the selected Google owner. MCP 2.2.0 remains exact because its focused supplement uses version-specific seams. Agno's public Agent and FunctionCall seams pass both 2.9.0 and 3.0.9 source cells. Microsoft Agent Framework core 1.17.0/1.18.0 and its OpenAI adapter 1.14.2/1.14.3 pass the same selected Agent, Workflow and lifecycle cells. These bounds do not expand the route or operation claims in the table.

The matrix does not promise every route that a client can address. For each retained operation, check status().integrations and the actual representative Trace as described under Qualification.

PydanticAI setup

Import the explicit helper API from impact.integrations.pydantic_ai. This does not alter automatic activation through impact.init().

When the selected PydanticAI peer is installed, impact.init() activates the framework's official global instrumentation default with Impact's tracer and content settings. Construct agents after init. Existing enabled global instrumentation and explicit per-Agent settings, including instrument=False, remain authoritative.

PydanticAI uses the same global False value for its untouched default and for Agent.instrument_all(False). Impact cannot distinguish those states. To prevent Impact from activating PydanticAI across the process, use impact.init(integrations=impact.IntegrationOptions(pydantic_ai="disabled")). Calling Agent.instrument_all(False) before ordinary Impact initialization does not provide that opt-out.

Plain agents constructed after impact.init() use the selected global instrumentation automatically; they need no per-Agent setup or manual span. Add an enclosing impact.span only when the application wants to name and correlate a larger execution boundary that PydanticAI cannot infer. Native PydanticAI metrics remain customer-owned; Impact does not claim managed metric export.

Streaming, content and credentials

Capture observes semantic stream output only as the native owner and caller expose it. It does not read ahead, call a model again, close an application stream during SDK shutdown or turn partial consumption into a completed response. Completion, caller stop, provider error, cancellation and SDK shutdown remain distinct. Terminal identity and usage are known only when the native path exposes them. Dropping an unclosed stream cannot promise terminal output or usage.

The Google Interactions supplement assembles consumed text, function calls and function results. Its buffer admits up to 1 MiB of JSON-encoded semantic values and 2,048 segments, snapshots structured values before yielding them, and marks overflow as impact.google.stream.projection=partial.local-limit. Terminal identity, usage and outcome remain observable after that content limit. EOF without a terminal event and interrupted consumption retain an explicitly partial or unavailable result.

Selected Product content includes semantic input, output, system instructions, tool definitions, model, response identity, finish reason and usage. It does not promise a raw provider request or response envelope, unknown vendor extensions, or replay of every consumed chunk. Unknown fields that an upstream owner or explicit application capture does emit remain intact through the telemetry pipeline. Focused integrations may retain additional bounded evidence where their matrix row says so; overflow and serialization loss remain explicit.

Explicit capture preserves ordinary stored Pydantic model fields after a bounded inspection of the model's resolved CoreSchema. Declared field exclusions and resolved serialization aliases are honored. Models with custom or computed fields, conditional exclusion, extra fields, or an unsupported field shape are not converted by application hooks; their safe siblings remain with partial.serialization-loss. A custom model serializer or unsupported model shape records omitted.serialization-failure instead of exposing a raw backing-field representation.

Released OpenAI instrumentation 1.1b0 misses Responses.parse and function-call/tool-result Responses history items. Impact connects the typed parse seam to the same official owner and supplements semantic function calls and tool results in input history. Ordinary messages still use upstream's projection; this does not restore native request envelopes.

For Responses streams that stop before a terminal response, Impact retains bounded text deltas actually consumed and the identity observed in response.created. Missing terminal usage remains unknown. Retention is bounded by encoded content size, fragment count and part count; omitted content carries an explicit limit marker. The compatibility owner avoids an extra async iterator around the selected native streams and leaves provider-owned iterator cleanup with OpenAI after native response cleanup. It preserves native errors and cancellation without reading ahead. Selected OpenAI 3.13/Python 3.14 early-close calls can still emit an upstream httpcore2 cleanup warning; paired calls reproduced it with and without Impact while preserving native results. Stream-manager cleanup stays with OpenAI; Impact does not traverse its decoder or HTTP-client internals.

Google records function parameter schemas in gen_ai.tool.definitions and a requested response schema in impact.google.response.schema; impact.google.response.schema_source preserves which supported config spelling supplied it. OpenAI records a requested output schema in impact.openai.response.schema, with source text.format.schema, response_format.json_schema.schema, text_format or response_format. Anthropic uses impact.anthropic.response.schema, with source output_config.format.schema or output_format. When available, impact.capture.<provider>.response.schema records capture or a known serialization/attribute-limit omission. A failed pre-call snapshot or a limit too small for the marker can leave both the schema and marker unavailable. Provider transport configuration, HTTP clients and known OpenAI, Anthropic and Google MCP credential paths are excluded from copied evidence. Ordinary application fields with similar names remain. Capture sanitizes copies and never mutates native request or response objects.

The bounded handling of complex Pydantic values omits unsafe callback-bearing subtrees with an explicit partial marker, retains safe ordinary siblings and does not execute application serializers.

Feedback and diagnostics

feedback() requires a name and at least a score, label or explanation. Omit target only while a valid recording span is active. An explicit native span, Product Trace or Session target creates a separate linked carrier and never mutates an ended span. Retain the returned id, producer and occurred_at when retrying the same occurrence. recorded=True means local capture only. Both packages bound the compact emitted feedback JSON, including its target, to 1 MiB of UTF-8 bytes, 4,096 JSON values and nesting below 64 levels. Labels and explanations share that whole-occurrence budget; oversized or invalid feedback is rejected before enqueueing.

status() separates trace and log provider ownership, each integration's activation state, limitations, bounded delivery counts and cleanup progress. Exact package owners and versions remain in the maintained integration matrix. status().runtime_id matches the generated impact.runtime.id on SDK-owned evidence and Impact-routed copies, alongside impact.sdk.version; caller context cannot override these SDK facts. Customer records remain unchanged. After Realtime attachment, status().realtime reports active connections and cumulative observed/captured/dropped counts, including completed connections. A successful flush() establishes only local exporter completion. Use the qualification readback for authenticated durable evidence.

An observed receiver rejection adds specific guidance to the existing delivery diagnosis: verify authorization, the OTLP route or request compatibility. Correct that configuration and run a fresh operation. A later successful export clears the current failure hint; cumulative delivery loss still records the earlier failed attempt.

Simulation

Simulation registers an existing application entry with Impactful's Testing workflows. Enable the Product key's Simulations grant, initialize with the actual deployed application version, then explicitly register the entry. The SDK resolves its authorized connection and one unambiguous enabled target:

runtime = impact.init(context=impact.ImpactContext(version_id="my-app-1.0.0"))

def invoke(request, *, signal, emit):
    # Your existing entry owns history, state, effects and cancellation.
    result = run_application(request, signal=signal, emit=emit)
    return {"text": result.text}

target = impact.register_simulation_target(
    effects={"boundary": "simulated"},
    max_concurrency=2,
    capabilities={"input": ["text", "structured"], "streaming": True, "multiTurn": True, "tools": True},
    invoke=invoke,
)

Supply target_id when more than one target is available. Explicit target_revision and product_version_id override the application-version fallback and the response must echo them exactly. The version is a supplied correlation label; it does not create a formal Compass ProductVersion record. A key with Simulations but no Traces creates no managed telemetry exporter. Fully explicit endpoint, credential, target/revision, Environment and Product Version registration remains supported. An explicit capture-off runtime with no ingest configuration can still use that path.

The handler may be synchronous or asynchronous. signal is a threading.Event; check signal.is_set() and stop native work through the application's supported cancellation path. Declare only actual application capabilities. Input defaults to text; streaming, multi-turn and tools default to false. target.status() reports connection state, in_flight and pending_acknowledgements; registration alone does not mean the platform has accepted a ready target. The concurrency limit defaults to 8 (maximum 100), including completed work still awaiting terminal acknowledgement. The active runtime accepts at most 32 registrations.

Requests preserve structured/text input, history, identities, deadlines, effect scope and optional prior-response or starting-state references. emit({"type": ..., "payload": ...}) accepts text_delta, tool_call, tool_result and status; JSON progress is snapshotted in a bounded 64-frame/4-MiB acknowledgement window per invocation. Exhaustion stops further progress and reports uncertain execution without a sequence gap. The runtime creates a fresh technical execution ID distinct from Run/case/turn/Session identities, reports it before the handler, and returns the reserved metadata["impact.execution.id"]. A native trace ID does not certify Product readback.

Reconnect replays retained observations under a renewed lease without reinvoking the handler. Observed cancellation does not claim rollback or terminal cancellation when the application instead completes. target.close() closes one registration; impact.shutdown() closes all registrations. Starting state, resource isolation and cleanup remain application-owned.

Replays with the same accepted-request key and body converge even after terminal acknowledgement; a changed body conflicts. Missing or malformed request/lease correlation closes the protocol before application effects.

Protect

Protect is an explicit, Product-scoped activation. Ordinary impact imports and impact.init() do not load model weights or the optional inference packages. Install them only in an application that enables Protect:

pip install 'impact[protect]'

Enable the Product key's Protect grant, initialize the shared runtime, then explicitly activate Protect. The SDK resolves Product, Environment and control settings using the same key:

import impact

runtime = impact.init()
protect = impact.activate_protect()

The model cache defaults to impact/protect under the operating system's user cache directory. Override it with IMPACT_PROTECT_MODEL_DIRECTORY or model_directory. Resolve/cache work happens only after explicit activation. Fully explicit endpoint, credential, Product and Environment options remain available for existing integrations.

Activation opens the authenticated control session, downloads only the immutable model and policy revisions selected for that Product and Environment, verifies their SHA-256 digests, and retains the last known good configuration. Inference executes one admitted operation at a time, admits at most eight including queued work, and dynamically batches model output under an 8 MiB tensor budget with a 30-second operation deadline. Python ONNX runs receive a bounded cancellation signal; model and classifier sessions remain referenced until the active native call returns. Provider integrations apply enabled policies at their real request and response boundaries. A block raises ProtectBlockedError; truncate and replacement decisions return only the text that may proceed. Pass invoke_enforcement_test only when it calls the same application/provider seam used by normal traffic. Close Protect with the shared runtime through runtime.shutdown().

Decision delivery retries transient failures in the background using a bounded in-memory queue. protect.flush() makes a bounded delivery attempt without closing Protect. impact.flush() attempts both Protect and ordinary telemetry delivery even if one fails. protect.status()["control"]["decisionDelivery"] exposes pending, failed attempt and lost counts; impact.status().protect retains them after cleanup. A completed shutdown does not prove Decision admission, and process termination can lose unacknowledged Decisions.

Migrating from the earlier impact package

The current package keeps the public distribution and import name, but migration from the earlier package requires code changes and is not drop-in compatible.

The current package does not claim Python 3.10, LlamaIndex or the historical Google client. Product instructions and downloadable artifacts must use APIs available in the selected artifact.

Qualification

After successful initialization, status() identifies the installed artifact, selected capture owners, activation states, current support claims, loss and cleanup state. Each Supported claim retains its exact operation and ownership limits. Source contributors should use the canonical release checkpoint for current release status; a source build does not establish package-index publication. Named JavaScript vendor coexistence evidence does not establish Python vendor coexistence.

For first use, initialize before client construction, run one representative application operation, then flush or shut down and inspect its Trace in the intended Impact Product and Environment. Check the actual input, output, model, tool effect and usage that the operation exposes. A local flush() success proves exporter completion only. The route setup report distinguishes a running SDK awaiting traffic from local delivery failures; it does not invent a representative Trace or claim durable readback. Keep supplied route/environment revisions current.

If the expected operation is missing, inspect status() for a disabled/missing owner, unsupported peer, late client construction, customer-owned destination or export failure. Repair that stated cause and repeat the same kind of application operation with a new execution ID. If only a facet is missing, inspect the claim's native stream/helper boundary and partial/omission markers before changing instrumentation. Do not add a second owner as a generic repair.

The standalone source checkout contains runnable qualification applications in python/examples, coexistence and Collector examples. Its canonical SDK specification is impact-sdk.md. Authenticated source-to-Product checks use the configured Impact APIs from the platform-owned black-box harness; the SDK repository does not import platform code. The installed qualification guide describes the shared receipt and readback procedure. Those source-only files are not required at runtime.

For source contributors, exact dependencies live in pyproject.toml and uv.lock; setup commands do not provision cloud resources:

uv run --project python --locked --all-extras pytest python/tests
uv run --project python --locked --all-extras ruff check python
uv run --project python --locked --all-extras python -m build --no-isolation python