Skip to main content
Change of provenance

The repository or configuration that created this release differ from a previous release. View details.

Pre-release

This release is a pre-release and may not be stable for production use.

impact

Impact's Python SDK captures AI application work while preserving native results, streams, errors, tool effects and existing OpenTelemetry. impact==1.2.0rc9 is a prerelease candidate for Python 3.11 or newer. Pin the complete version, including its prerelease suffix. Released packages are available from PyPI; unpublished candidates use supplied wheels or source archives.

First Trace · Launch scope · Troubleshooting · Security reporting

Quickstart

Run one OpenAI Responses call and find its prompt, reply, model and usage in your Impact Product's Traces.

  1. In a clean app directory, create a virtual environment and install the pinned package with the app-owned OpenAI client. The following commands use a POSIX shell.

    python3 -m venv .venv
    . .venv/bin/activate
    python -m pip install 'impact==1.2.0rc9' 'openai==3.46.0'
    

    For an unpublished candidate, use its supplied wheel instead.

    python -m pip install /absolute/path/to/impact-1.2.0rc9-py3-none-any.whl 'openai==3.46.0'
    
  2. In the target AI product, have a workspace owner or admin open Ingest keys → Create ingest key. Save the raw secret and copy the URL ending in /v1/traces from OpenTelemetry exporter settings. Use the exact URL for IMPACT_ENDPOINT and the raw ingest secret for IMPACT_API_KEY. The SDK supplies the Bearer header.

  3. In your app's secret configuration, set those two variables and set OPENAI_API_KEY to an API key from your OpenAI project. Set IMPACT_SERVICE_NAME=impact-quickstart in the app environment so you can identify the run. This example makes one billable model call and defaults to gpt-6.1-sol. Set OPENAI_MODEL to a model your project can use with the supplied options, or adjust its model-specific options. OpenAI API keys · OpenAI model reference

  4. Save this as quickstart.py. Importing impact is passive. Initialize it before constructing the application client.

    import os
    
    import impact
    
    runtime = impact.init(startup="strict")
    try:
        from openai import OpenAI
    
        print("Impact SDK", runtime.status().artifact["version"], "runtime", runtime.status().runtime_id)
        with OpenAI(max_retries=0) as client:
            result = client.responses.create(
                model=os.getenv("OPENAI_MODEL", "gpt-6.1-sol"),
                max_output_tokens=512,
                reasoning={"effort": "low"},
                input="Say hello in one sentence.",
            )
            print(result.output_text)
    finally:
        shutdown = runtime.shutdown()
        status = runtime.status()
        print("Impact local delivery", shutdown.delivery)
        print("Impact exported traces", status.traces.exported if status.traces else None)
        if status.cause not in (None, "none"):
            print("Impact diagnosis", status.cause, status.action)
        if not shutdown.completed:
            print("Impact shutdown incomplete", shutdown.message)
    
    python quickstart.py
    
  5. Confirm the printed SDK version is 1.2.0rc9. In the same AI product, open Traces and select the recent row for impact-quickstart. In the model span's Recorded fields, check the model and available token usage. Match the prompt and printed reply when your Product retains content. If the Trace is missing, see Troubleshooting. Match impact.runtime.id to the printed runtime ID so an older run cannot satisfy the check. Cleanup completion and local delivery are separate: incomplete or unknown require investigation. Zero exported traces means this run has not demonstrated capture; even exported-not-readback does not establish a readable Product Trace.

Already using OpenTelemetry? Keep its providers and destinations with the customer-owned setup.

This example uses direct OTLP. Verify the matching Trace in your deployment; local export and Product readback are separate observations.

Launch scope

Start with these exact prerelease paths and verify the matching Trace in your Product. The integration catalogue and runtime.status().integration_details describe the full operation sets, which remain Unassessed.

Native operation Application setup Capture boundary
OpenAI 3.46.0 sync unary responses.create and chat.completions.create, plus caller-consumed Chat streaming Python 3.11.18 and 3.14.10. Initialize before client construction. OpenTelemetry GenAI OpenAI 1.3b0 plus the Impact supplement, with managed telemetry or an explicit Impact route on customer OpenTelemetry 1.45.2. Request, native output and IDs, available usage, provider errors and consumed stream output. Early close retains only consumed output.
One app-owned synchronous tool inside interaction() Python 3.14.10, impact.interaction() and impact.span(..., role="tool"), with an explicit OTLP endpoint and ingest key. Typed tool input and result plus one application effect, linked to the owning Interaction and supplied Session.

OpenAI background/resumed streams and image/audio operation sets remain Unassessed for this candidate and retain their documented public-route and provider limitations. Google ADK and other framework/route combinations, browser/voice, managed hosting, Source, Simulation and Protect are outside this launch scope. Their documented APIs retain their own evidence boundaries.

Migrating from the Assistants API

Move the application to client.responses.create, carry forward its instructions and tool definitions, and choose how to manage conversation state. Check the tool calls, output items and stream events your application actually consumes. For Microsoft Foundry, use the standard OpenAI client with the resource's /openai/v1/ base URL and the deployment name. The integration catalogue describes the SDK's assessed operation boundaries. OpenAI migration guide · Microsoft Foundry v1 API

Install

Install the pinned registry version alongside the application's existing dependencies:

python -m pip install 'impact==1.2.0rc9'

For an unpublished candidate, install the supplied wheel instead:

python -m pip install /absolute/path/to/impact-1.2.0rc9-py3-none-any.whl

For a uv project, use uv add 'impact==1.2.0rc9', substituting the wheel path for an unpublished candidate. Resolve Impact together with the application's existing dependencies. When installing from a package index, pin the complete version, including its prerelease suffix.

From a source checkout, 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"

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 base capture machinery uses the GenAI instrumentation 1.3b0 cohort. Anthropic uses its native 2.6.0 tracing with a bounded Impact supplement. The package requires OpenTelemetry >=1.45.2,<1.46 and the matching OpenTelemetry instrumentation family starting at 0.66b2. The gemini convenience extra selects Google Gen AI 3.0.0. Use a separate environment for the adk extra, which selects ADK 2.14.1, Google Gen AI 2.34.0 and OpenTelemetry SDK 1.45.2. An existing ADK application can install base impact beside its own compatible dependencies. Resolve the application's middleware and tracing instrumentation together so the entire environment uses the patched propagation dependencies. OpenTelemetry tracestate advisory · OpenTelemetry traceparent advisory 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; they are not needed when those libraries are already installed. pyproject.toml publishes exact selected convenience tuples; uv.lock records their ordinary resolution, including the separate Google/ADK environments. An admitted version range does not imply every operation is Supported; check the installed catalogue's exact native tuple and operation boundary.

The package admits protobuf 6.33.5 through 7.x, Requests 2.33 through 2.x and urllib3 2.8.0 through 2.x. Resolve the complete application together and measure installation size, startup and memory in that environment. urllib3 2.8.0 security fixes

Application startup

Initialization rejects invalid local configuration before activation. With Product-key discovery, startup="strict" raises a discovery failure. The default can return an unavailable runtime and allow the application to continue. Product-key discovery uses connection protocol version 2.

Direct OTLP initializes its exporter with the explicit endpoint and ingest credential. Authentication and receiver reachability are checked when telemetry is sent. Inspect delivery status and flush or shutdown results for those failures. Simulation and Protect use their own activation APIs.

Owned OTLP, setup and presence HTTP attempts use an absolute budget through complete response headers and acknowledgement reads. Direct TCP addresses share the remaining connection budget, and expiry interrupts connected socket I/O. A blocking system DNS lookup can outlive that budget; once it returns, an expired attempt sends nothing. Optional SOCKS proxy backends own their connection negotiation timeout. A shutdown wait can return incomplete while such work settles; retry joins the owned work. Customer trace and log callbacks do not wait for Impact to drain. For OTLP, a late, incomplete or oversized success acknowledgement remains unknown, and a known HTTP success is not resent. Setup reports may retry an uncertain acknowledgement with the same report ID and bytes; the receiver must deduplicate that occurrence. Presence reports status independently and does not establish Trace delivery. The receiver should honor Accept-Encoding: identity for these bounded acknowledgements. The same system DNS limitation applies to SDK-owned Simulation and Protect connections: cleanup remains pending until the lookup returns. Their WebSocket transports reject redirects and join owned connection work on close.

For an async application, initialize and close through the async view:

runtime = await impact.init_async()
try:
    # Use the application's ordinary asynchronous provider clients here.
    print(runtime.status())
    await runtime.flush(timeout_ms=1000)
finally:
    await runtime.shutdown(timeout_ms=3000)

init_async() always returns AsyncRuntime. Its status and tracer_provider are local synchronous reads; startup, delivery, shutdown and explicit capability activation keep blocking SDK work off the application loop. Equivalent sync and async initialization share one underlying runtime and its resources. Sync init() returns the synchronous view. Both sync and async lifecycle methods use timeout_ms. Neither view owns application clients or customer telemetry providers.

Invalid local configuration raises before discovery or activation. Bounded remote Product discovery failure returns an unavailable runtime by default: inspect runtime.status().cause, .action and .limitations. To make that remote failure reject startup, supply startup="strict". A new explicit initialization call retries a settled unavailable attempt; concurrent equivalent calls share the pending attempt. startup is a caller failure policy, so strict and fail-open callers still share the same discovery and active owner. On a shared remote failure, strict callers raise while fail-open callers receive the unavailable view. There is no background retry. An older unavailable handle cannot close or report the state of a newer active runtime.

A cancelled init_async() caller receives CancelledError. If all callers cancel before shared activation commits, activation is skipped and late discovery results are discarded. Once activation commits, it settles independently of caller cancellation. A successful runtime stays active and an equivalent retry or surviving waiter receives that same runtime.

Ordinary supported provider calls require only initialization. Wrap a meaningful application request once to associate its native work and observe its result. Nested model, tool and service calls contribute to that Interaction:

This complete enrichment example runs in its own process:

import os

import impact

runtime = impact.init()
from openai import OpenAI

client = OpenAI()
try:
    def answer_request(request):
        result = client.responses.create(
            model=os.getenv("OPENAI_MODEL", "gpt-6.1-sol"),
            max_output_tokens=512,
            reasoning={"effort": "low"},
            input="Explain how a customer can find their order status.",
        )
        return result.output_text

    answer = impact.interaction(
        answer_request,
        session_id="conversation-1",
        interaction_id="request-42",
        user_id="customer-17",
        name="answer",
        input={"question": "Where is my order?"},
    )
    print(answer)
finally:
    runtime.shutdown()

interaction() preserves the callback's native value or awaitable and invokes it once. Omit interaction_id to create one UUID at that explicit request boundary. A supplied Session is optional; several requests can share it. A User ID is an opaque application key, not an authenticated person. Plain context, span and operation scopes never create an Interaction or independently finish their parent request. 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. environment is a reported environment name; version_id is a reported deployed-version reference. build_id and deployment_id are external CI/build/deployment references, not Builder Version/Deploy UUIDs. Use real configured values or omit them; a provider model name belongs in its native model field. component_id, agent_id and agent_version_id are reported application keys, not automatic Part relationships or replacements for native gen_ai.agent.* facts.

Route credentials establish Workspace and Product tenancy. Context values are correlation claims. Keep Environment, reported deployed-version reference, component/build/deployment, Session, Interaction, purpose, User and DomainRun(kind, id) distinct. Business identities emit impact.session.id, impact.interaction.id and impact.user.id. Native provider conversation, response, Trace and Span IDs remain separate. A Simulation run or invocation ID is not a Session or Interaction ID.

Core API and lifecycle

API Purpose
init(...) Starts one compatible runtime and activates installed integrations. Repeating equivalent setup returns that runtime; conflicting settings reject.
init_async(...) Returns an AsyncRuntime view of the same owner; await its lifecycle and capability methods.
interaction(work, ...) Owns one logical request and its observed result, exception, cancellation or supported stream ending.
continue_interaction(carrier, work, ...) Continues an explicit confirmed handoff; plain contributor context cannot transfer completion ownership.
context(...) Applies validated task-scoped Product context.
span(name, ...) Captures an explicit application boundary and preserves native output, exception or cancellation behavior.
operation(name, role=..., capture=...) Decorates sync/async functions or generators with the same manual boundary, optionally capturing named arguments.
inject_context(carrier) / extract_context(carrier) Propagates W3C parentage and bounded contributor context; apply extraction with context(propagated=...).
feedback(...) Records inline or post-hoc native feedback with a stable occurrence identity.
runtime.attach_realtime(connection, ...) Observes an existing OpenAI Realtime connection; the application retains the socket.
runtime.status() After init()/init_async(), reports provider ownership, integration activation states, limitations, local delivery and cleanup state.
runtime.flush(timeout_ms=...) Makes a bounded attempt to export finished telemetry. It does not prove platform admission or readback.
runtime.shutdown(timeout_ms=...) Flushes and stops SDK-owned work; a retry skips cleanup phases that already succeeded.

Manual capture never changes application exceptions or cancellation identity. Serialization loss leaves an explicit partial or omission marker. Stream output records consumed chunks in a JSON array. A capturable non-None sync generator return uses a single output.value JSON object containing chunks and return, identified by impact.capture.output.format="stream-chunks-and-return". The output follows the boundary's content controls. 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 standard W3C traceparent/tracestate plus one bounded impact-context value. That value is canonical compact UTF-8 JSON encoded as unpadded base64url: version 2, optional Interaction/Session and domainRun. User attribution is not automatically propagated. A conflicting or stale owned value raises ValueError without changing any carrier field. Use a fresh carrier for each request. Successful shutdown removes initialized defaults.

extract_context() returns context, native_context, content-free issues and an optional explicit transfer. Inspect issues before applying received correlation through context(propagated=...). Conflicting Interaction, Session or Domain Run IDs from that carrier cause ValueError before the active local correlation or native context changes. Existing application-owned native parentage is preserved. Contributor propagation never grants completion ownership or authorizes a Product route. JavaScript uses the same versioned wire contract; old Impact correlation headers are not aliases.

Create the gateway carrier inside each actual request's active span and pass it through the application's existing per-request header option. For an application-owned http.client connection, use connection.request("POST", path, body=body, headers=impact.inject_context(request_headers)). Keep native credentials and other request options under application control. Do not cache an injected traceparent on a shared client: concurrent requests need their own active parent. Injection preserves existing equal values and does not install an HTTP patcher.

Longer work uses the application's actual accepted publication boundary:

async def enqueue(request):
    async def publish(transfer):
        await queue.publish_confirmed(question=question, context=transfer.carrier)
        transfer.confirm()  # Only after the application's actual durable acknowledgment.

    await request.handoff(publish)
    return accepted_response()

await impact.interaction(enqueue, session_id=session_id, name="answer", input=question)
await impact.continue_interaction(job.context, lambda request: agent.answer(job.question))

The queue, acknowledgment and job above belong to the application. confirm() is valid only within the active publisher callback. Returning or raising without confirmation leaves transfer unconfirmed; a later error after confirmation cannot reclaim completion ownership. The SDK never republishes business work. continue_interaction requires an actual transfer carrier and defaults to preserving active native parentage. Supply new_trace=True to start a new technical root linked to the valid received context while retaining logical identity. An ordinary nested interaction() with the active Interaction ID raises before invoking the inner callback. Use context() or span() for contributor work, and await the actual join inside the application's completion owner.

Manual spans and Interactions record a successfully captured input or output as one JSON document with application/json MIME. Decode the value once. JSON null, false, zero and empty text have distinct values, and a string that looks like JSON stays a string. A missing value or MIME declaration leaves typed content unavailable. The capture state explains whether a policy or native limit omitted it.

Supported Python iterator and async-iterator results remain lazy and observe actual exhaustion, explicit close, error or cancellation. Never-consumed or opaque framework/HTTP results do not imply successful completion. Drain or close such work at the application's actual observable boundary. Stopping telemetry does not end a business Session.

Optional typed context fields channel, locale, plan, user_type and journey_step emit the corresponding impact.correlation.channel, .locale, .plan, .user_type and .journey_step attributes. They use the context string bounds above and do not prescribe a vocabulary or infer values. Stable defaults may be supplied through init(context=impact.ImpactContext(...)). Within one context, a typed field wins over its exact canonical correlation key; an inner scope wins over outer/default values, including an inner correlation value. Existing correlation-only values keep their validation and omission behavior. agent_version_id continues to emit impact.agent.version.id separately from the Product's version_id.

Supply a known terminal Session fact on the actual terminal operation, before its span or automatic owner starts:

with impact.context(session_id="conversation-1", journey_step="complete", session_ending="resolved"):
    with impact.span("finish-conversation", role="entry") as operation:
        operation.set_output(finish_conversation())

session_ending emits the raw impact.session.ending attribute and requires session_id in the same submitted context. It is rejected in init defaults. Nested work inherits it for the same Session; changing the Session clears the inherited ending unless that scope supplies a new pair, and leaving the scope restores the outer pair. Application-owned native trace parentage must still place the terminal operation under the intended Session; changing a context value does not reparent an existing Trace. This field records the supplied fact, does not close a Session or alter inferred Ending classification, and offers no post-hoc ending API. Verify the terminal span's raw attribute through authenticated Trace readback under that exact Session. These typed fields and the supplied ending are not added to propagation headers or baggage.

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. Native provider identity fields retain their own meanings.

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 integration keys are google, google_adk, anthropic, openai_agents, llama_index, 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.

For Anthropic 2.6.0, initialize Impact before constructing clients. The native SDK owns the model span; Impact enriches its outgoing copy with request schemas, tools, media and actually consumed direct-stream output. Enable native content explicitly when prompts and responses are wanted:

runtime = impact.init()
from anthropic import Anthropic

client = Anthropic(open_telemetry={"traces": {"content_mode": "content"}})

Anthropic defaults to metadata only; Impact preserves that setting and open_telemetry=False. With a customer tracer provider, pass the same provider to impact.init(tracer_provider=provider) and the native client's open_telemetry={"tracer_provider": provider, "traces": {"content_mode": "content"}} option. Customer destinations keep their original spans. The supplement observes public Messages create/parse/stream calls without a second model span, extra request or stream read-ahead. Each observation respects the native content-byte limit up to 1 MiB. Observation buffers have weak application-object lifetimes; there is no aggregate supplement memory ceiling. Existing clients retain native tracing but receive no request/stream enrichment. Native omitted output citations and opaque content remain unavailable; a native end without a confirmed terminal stays partial or unknown. Shutdown stops Impact observation and leaves customer streams and spans under native ownership. Request enrichment accepts plain JSON lists/dictionaries; custom containers and application iterables remain under native ownership. Explicit output_config.format.schema dictionaries are captured. Typed output_format schema generation stays native and is marked unavailable to the supplement; Impact never executes a user schema hook. Native recorded input stays authoritative. Request wrappers, middleware, body overrides or mismatched native evidence can make secondary enrichment unavailable; Impact keeps the native evidence and reports that limitation.

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,
    # The deployment can supply its actual ref through IMPACT_VERSION_ID.
)

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 reported deployed-version reference when known. That reference alone does not prove a captured Builder Version or an admitted deployment binding. Presence 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. The HTTP deadline and platform DNS limitation described above also apply to presence. If work 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 reported deployed-version reference 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. The wire key remains impact.product.version.id; a release label or Git commit does not become a canonical Builder Version UUID because of that name. Source sync associates the exact reported ref with its captured code snapshot. Callable discovery separately validates an existing Product/target/material/placement binding and may resolve a deployed Git commit to a retained declaration. It creates no Version and grants no authority from the ref. Only an actual owning Builder/deployment binding can establish a canonical whole-material Version UUID.

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. Log instrumentation-scope and resource content receive their own projection; a GenAI marker in resource metadata does not turn an unrelated customer log body into AI content. An acquisition marker such as partial.serialization-loss describes the value available at the capture owner. If the destination suppresses a captured or partial tool argument or result, its outgoing direction marker reports omitted.policy, or omitted.signal when a signal setting closed it. Unavailable native content can still carry its original reason. Check the outgoing value and its marker together to determine what reached Impact. For an ordinary input, closing the input policy removes its value and MIME type. The outgoing delivery marker is omitted.policy, and the original capture marker can still say partial.serialization-loss. A tool whose result is incomplete cannot count as a complete return. Restricted records carry the normalized impact.content.policy and a reason in impact.content.<category>. A projection failure drops the affected Impact record and increments its signal's content_dropped count.

tools=False closes tool arguments and results on tool carriers. If the app returns the same value as its own request output, that copy follows the output policy. Restrict output too if it can carry data you want omitted.

OTEL_INSTRUMENTATION_GENAI_CAPTURE_CONTENT selects NO_CONTENT, SPAN_ONLY, EVENT_ONLY, or SPAN_AND_EVENT (case insensitive). Impact snapshots it before activation and applies it to semantic GenAI records from every capture owner on its own destination. The same setting closes input/output on Impact-owned manual AI operations (impact.span/impact.operation); unrelated customer telemetry keeps its own content policy. Span attributes and span events use their respective signal modes; metadata, identifiers and usage remain. Invalid or empty explicit values use NO_CONTENT. An unset value preserves Impact's unrestricted capture default. Customer providers and destinations keep their original records.

Legacy OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT remains owner specific: the GenAI owners use the enum above and Botocore uses true/false. Explicit restrictions from either variable compose conservatively; the new variable cannot reopen content closed by the legacy owner setting or by Impact's content configuration. Impact never rewrites these settings. An invalid legacy value disables affected owned acquisition; an affected unowned record is dropped when its explicit legacy control cannot be interpreted.

The current standard signal setting excludes tool schemas/descriptions. Impact's stricter input=False still closes those definitions. Normal content uses structured OTLP AnyValue on the current OTel SDK; older/custom providers keep the historical JSON representation and original schema identity. Binary media stays binary. A value outside OTLP's signed 64-bit integer range is omitted from the standard structure with partial.serialization-loss; its bounded original JSON is retained in impact.native.gen_ai.* and obeys the same privacy projection.

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.

Claim Route and selected owner Exact operation boundary Current limitation
py.openai.extended.v1 openai 3.46.0; Impact supplement openai.responses.create(background=true), openai.responses.retrieve, openai.responses.cancel, openai.responses.retrieve(stream=true,starting_after), openai.images.generate, openai.images.edit, openai.audio.speech.create, openai.audio.transcriptions.create, openai.audio.translations.create Unassessed for this candidate: provider resumed-stream replay can stall before headers/events even after normal completion. Public OpenAI route only; Azure, Foundry and compatible-route extensions are not qualified here. Unread raw/media bodies remain unobserved. Background operation availability and media model entitlement belong to the provider.
py.google.background.v1 google-genai 3.0.0; Developer API v1beta; Impact supplement google.interactions.create(background=true,store=true), later google.interactions.get(stream=false), then google.interactions.get(stream=true,last_event_id) Developer API background creation and application-driven terminal/reconnected observation with gemini-3.7-flash. No SDK polling or resume orchestration; availability remains model-owned. Cancel/delete belong to the base Interactions claim. Built-in agents and Vertex Interactions are not qualified here.
py.bedrock.invoke.v1 boto3 1.43.126, botocore 1.43.126; Impact supplement bedrock-runtime.InvokeModel(Nova), bedrock-runtime.InvokeModelWithResponseStream(Nova) This claim covers the selected Nova dialects. Claude through Bedrock, ApplyGuardrail, Agents, aiobotocore and other partner dialects are unassessed. Caller-stopped or incomplete streams remain partial. Partial content policy never reads an opaque body ahead.
py.bedrock.knowledge-bases.v1 boto3 1.43.126, botocore 1.43.126; Impact supplement bedrock-agent-runtime.Retrieve, bedrock-agent-runtime.RetrieveAndGenerate Application-called Knowledge Base retrieval/generation. Agent orchestration, source crawling and extra retrieval remain unassessed. Cloud Knowledge Base access and model entitlement remain application-owned.
py.mcp.server-tools.v1 mcp 2.3.0; Impact supplement mcp.server.tools.call Initialize Impact before server construction and handler registration over stdio and Streamable HTTP. Existing pre-init servers, resources, prompts and custom transports are unassessed. No SDK-owned connection or invocation.
py.openai.public.v1 OpenAI 3.46.0; official owner 1.3b0 plus Impact supplement Responses, Chat Completions and Embeddings create; sync/async unary, helpers and consumed streams Raw response bodies that the application does not parse or consume do not expose semantic output.
py.openai.azure.v1 AzureOpenAI through the same selected client/owner Responses, Chat Completions and Embeddings create Deployment, API version, credentials, region and entitlement remain customer-owned.
py.openai.foundry.v1 Standard OpenAI client at an explicit Foundry endpoint The same selected inference operations No Foundry project, resource, retrieval, Search or control-plane claim.
py.openai.compatible.v1 Standard OpenAI client at an explicit private/local base URL The same selected client operations No arbitrary dialect, named vendor, tool, stream or usage compatibility follows.
py.anthropic.public.v1 Anthropic 2.6.0; native tracing plus Impact outgoing-copy supplement Messages create/stream, typed parse, sync/async consumed streams Public Messages only; explicit native content mode and post-init clients for enrichment. Native citation/opaque-output omissions remain; incomplete/unknown native ends are not promoted. Claude on Google Cloud is not supported.
py.google.models.developer.v1 Google Gen AI 3.0.0; official owner 1.3b0 plus Impact supplement generate_content, generate_content_stream, embed_content Already-constructed clients cannot be discovered through the public SDK.
py.google.models.vertex.v1 Vertex-configured Google Gen AI client; same owner The same selected Models operations Project, location, ADC and model entitlement remain customer/cloud responsibilities.
py.google.interactions.v1 Google Gen AI 3.0.0; Developer API; official owner plus Impact lifecycle supplement model create/stream/tool continuation plus application-called get/cancel/delete Background/reconnect and unary built-in-agent create have separate exact claims; agent streaming/lifecycle and Vertex require independent evidence.
py.google.interactions.agent-create.v1 Google Gen AI 3.0.0; Developer API; retained client-response owner application-called unary interactions.create(agent=...) Available native agent/interaction/environment IDs, code call/result, native status and separate explicit input/output/thought/total usage. Native incomplete stays incomplete. No inferred final answer/thought text, local execution span, SDK polling/continuation, agent stream/get/cancel/delete parity or hosted telemetry acquisition.
py.google-adk.runner.v1 Google ADK 2.14.1, Gen AI 2.34.0, OpenTelemetry SDK 1.45.2; Impact runner events plus provider owner Runner.run and run_async, including model/tool/session events Impact supplies native telemetry defaults when RunConfig.telemetry is unset and preserves an explicit application value. Shutdown marks the observation partial and stops capture without closing the native iterator. JSON-native action state deltas are retained without invoking ADK serializers; custom-serialized long_running_tool_ids are omitted and reported as partial.
py.langgraph.langchain.v1 LangChain 1.4.9, core 1.7.6, OpenAI adapter 1.7.4, LangGraph 1.2.20; official owner 1.3b0 runnable/graph unary, graph stream, tools and retrieval Live hooks expose semantic output and provider identity, not the raw SSE response body; framework and provider IDs may differ.
py.llama-index.agent-rag.v1 LlamaIndex core 0.14.25, workflows 2.26.1, instrumentation 0.6.0; official owner 1.3b0 plus outgoing-copy supplement awaited nonstream FunctionAgent.run, async TextNode retrieval and actual FunctionTool.acall Streaming, custom node subclasses, rerankers and other agent/workflow families remain unassessed. Bounded document enrichment changes only Impact copies. Model connectors and clients remain application-owned.
py.openai-agents.runner.v1 OpenAI Agents 0.24.0; official owner 1.3b0 plus provider owner run, run_sync, run_streamed; tools and handoffs The Runner result owns delivered final output and aggregate usage; a provider child need not expose either independently.
py.agno.agent.v1 Agno 3.1.12; official owner 1.3b0 plus Impact stream supplement Agent.run/arun, unary and caller-consumed sync/async streams Team and Workflow are unassessed; shutdown leaves native streams usable but observation partial.
py.pydantic-ai.agent.v1 PydanticAI slim 2.66.0; native instrumentation plus provider owner Agent run, run_sync and run_stream Existing enabled global settings and explicit per-Agent settings remain customer-owned. Use IntegrationOptions(pydantic_ai="disabled") for a process-wide Impact opt-out.
py.microsoft-agent-framework.v1 Agent Framework core 1.24.0, OpenAI adapter 1.18.0, orchestrations 1.4.1; native telemetry plus Impact supplement Agent.run(stream=False|True) and Workflow.run(stream=False|True), tools and selected orchestration Native sensitive-data capture defaults False (metadata only); content requires explicit native opt-in. Core 1.24 close/context-manager cleanup remains native. Cross-task consumption, buffered streams/blocking gates and durable checkpoint restoration are unassessed.
py.bedrock.converse.v1 Boto3/Botocore 1.43.126; Botocore owner 0.66b2 plus Impact supplement Converse and caller-consumed ConverseStream Nova InvokeModel and Knowledge Base operations have separate claims. ApplyGuardrail, aiobotocore and partner dialects remain unassessed.
py.mcp.client-tools.v1 Official MCP SDK 2.3.0; customer-owned connections caller-owned connect/initialize, list_tools, call_tool and close over stdio and Streamable HTTP Passive observation of application-initiated discovery, capabilities, protocol/request IDs and actual tool input/result/error; no SDK-initiated connection, background discovery or invocation.
py.openai-realtime.server.v1 OpenAI Realtime 3.46.0, websockets 15.0.1; explicit Impact attachment caller-owned server WebSocket control, response, tool, usage and terminal events Browser media, SIP, RTP, playback and SDK-owned connections are outside this claim.

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 includes the retained capture machinery and a compatible websockets 15–17 transport. It installs upstream capture owners where needed and adapts native client telemetry where the client supplies it. Provider clients, application frameworks and the MCP SDK remain application-owned. impact.init() checks for those customer libraries without importing absent or disabled integrations and activates only the applicable owners.

The matrix names native tuples and operation boundaries. Use the installed catalogue for each operation's support state and limitations; these dependency facts alone do not establish capture or Product readback.

The default development profile selects Google Gen AI 3.0.0. ADK 2.14.1 is a separate profile with Google Gen AI 2.34.0 and OpenTelemetry SDK 1.45.2. OpenAI Realtime selects OpenAI 3.46.0 with websockets 15.0.1; that convenience extra retains its native <16 bound. The MAF convenience extra selects core 1.24.0, OpenAI adapter 1.18.0 and orchestrations 1.4.1; native explicit close, async context-manager and cancellation cleanup remain authoritative. Core 1.19 through 1.22 and unselected combinations remain unassessed. These dependency facts do not expand any route or operation boundary.

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 Troubleshooting and support.

LlamaIndex setup

Install base impact beside the application's native dependencies. The optional llama-index extra selects core 0.14.25, workflows 2.26.1 and instrumentation 0.6.0; it installs no model connector or provider client. Initialize Impact before constructing agent, model or retrieval work. Set IntegrationOptions(llama_index="disabled") to leave this owner inactive.

The selected model connector llama-index-llms-openai==0.8.3 uses openai==2.54.0 in this application tuple. Install base impact with those dependencies. The OpenAI 3.46 convenience extra conflicts with this connector. The selected scope is an awaited nonstream FunctionAgent.run, async TextNode retrieval and an actual tool effect. Available returned text, identity, metadata and score enrich only Impact outgoing copies. Outgoing-copy enrichment is bounded to 64 documents, 1 MiB per observed span and 16 MiB across 4096 pending spans. A pre-existing customer owner keeps its native content choices. Source references containing query, fragment or userinfo components are omitted; Impact does not fetch referenced content. Streaming and other agent/workflow families remain unassessed.

Microsoft Agent Framework setup

Existing MAF applications install base impact beside their own compatible framework dependencies. For a new application, impact[microsoft-agent-framework] selects core 1.24.0, OpenAI adapter 1.18.0 and orchestrations 1.4.1. The current OpenAI adapter uses the Responses API through its public OpenAIChatClient.

MAF defaults to metadata-only telemetry: OBSERVABILITY_SETTINGS.enable_sensitive_data is False. Impact preserves that setting for native telemetry and its own supplements, including customer destinations. Available model, response identity, usage and outcome facts remain observable; message, tool, routing and workflow content requires an explicit native opt-in. Suppressed Impact facets use omitted.native-sensitive-data capture markers. Keep native False when content is unwanted.

For an application that intentionally captures content, set ENABLE_SENSITIVE_DATA=true before starting Python, or use the framework's public API before impact.init():

from agent_framework.observability import enable_sensitive_telemetry
import impact

enable_sensitive_telemetry()
impact.init(service_name="maf-app")

On core 1.24.0, use the native async with response_stream or await response_stream.close() when stopping early. Impact records that observation as partial and preserves native cleanup, customer hooks and errors. Closing an unstarted native Agent stream can finalize its inner model call; Impact preserves that native effect. A bare early break settles on release or SDK shutdown. Core 1.17/1.18 has no native close/context-manager API, so early-break timing remains application/runtime dependent. Cross-task consumption, buffering/blocking gates and durable checkpoint restoration remain outside the assessed stream boundary.

A prior framework disable_instrumentation() call remains in force. Impact itself does not enable disabled native instrumentation or change a native sensitive-data restriction. Configure the normal Impact destination as described above.

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.

The selected OpenAI instrumentation 1.3b0 owns Responses.parse. Impact retains focused semantic history and partial-response supplements. 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 for a plain output_config.format.schema dictionary. Typed output_format retains native parsing and a source marker, with unavailable.native-schema rather than an inferred schema. 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. Impact omits signed or authenticated URLs in recognized media, native resource and tool/server reference fields on outgoing copies, including structured values and known native JSON mirrors, even under full capture. impact.content.credential_references=omitted.unsafe-reference marks a reference or unverifiable native JSON envelope omitted by this filter. Ordinary reference URLs are retained subject to the integration's reference rules. Free-form prompt text and arbitrary application fields keep their configured content policy. Native request and response objects and customer-owned telemetry keep their original values.

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. With no target, it records Feedback for the active Interaction. Outside an Interaction, supply an explicit supported Interaction, native span, Product Trace or Session target. An explicit target wins and never mutates an ended span. Retain the returned id, producer and occurred_at when retrying the same occurrence. FeedbackReceipt contains id, producer, occurred_at and outcome. outcome="recorded-locally" means local capture only; "not-recorded" means no local capture. 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. Python validates the complete occurrence before applying local sampling and delivery routing.

runtime.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. This runtime identity is read-only; ImpactContext has no runtime_id input. Customer records remain unchanged. Attach a caller-owned Realtime connection before its first response request with runtime.attach_realtime(connection, connection_id=connection_id, correlation_metadata_key="request_id") when the app already supplies a unique string in response.create.response.metadata["request_id"]. The SDK snapshots the active Interaction/Session/User and actual native parent at the outbound send. Only a unique matching native metadata echo at the first observed response event binds later response-ID events to that snapshot. It never adds metadata, treats the echo value as a business ID, or guesses from FIFO order or the context active during receive. The default, VAD, ambiguous and unmatched responses keep native facts and remain logically unassigned.

The configured key allows 64 UTF-8 bytes and nonempty native values allow 512 UTF-8 bytes. Values must be unique for the native connection's lifetime, including across detachment; an observed reused value is never matched. After 4,096 retained key identities, new associations remain unavailable with an explicit capacity diagnosis while native event capture continues. Late callbacks do not reopen a logical Interaction. Await the actual result inside interaction, or use the application-owned handoff/continuation boundary. Provider session/conversation/response IDs and genuine provider gen_ai.interaction.id remain separate from canonical impact.session.id / impact.interaction.id.

After Realtime attachment, status().realtime reports active connections and cumulative observed/captured/dropped counts, including completed connections; activation/counts alone do not prove logical association or useful Product capture. 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:

# Supply the actual deployed ref through IMPACT_VERSION_ID when it is known.
runtime = impact.init()

def run_request(request, *, signal, emit):
    def work(interaction):
        # The application owns history, effects, cancellation and any real handoff.
        result = run_application(request, interaction=interaction, signal=signal, emit=emit)
        return impact.SimulationResult(
            text=result.text,
            interaction_id=interaction.interaction_id,
            continuation=result.continuation,
        )

    pending = request.get("continuation")
    if pending is not None:
        # Validate the previous invocation, current target and handle in real app state.
        transfer = load_pending_transfer(pending["previousInvocationId"], pending["handle"])
        return impact.continue_interaction(
            transfer.carrier, work, session_id=request["sessionId"], user_id=request["user"]["id"]
        )
    return impact.interaction(
        work, interaction_id=request["interactionId"], session_id=request["sessionId"],
        user_id=request["user"]["id"], name="application.request",
    )

def invoke(request, *, signal, emit):
    return run_request(request, signal=signal, emit=emit)

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

Use the same application run_request for ordinary traffic and registered targets. run_application and load_pending_transfer above stand for the application's own work and pending state; registration does not add an owning wrapper or infer continuation. A pending handle must refer to the application's actual stored transfer and accepted predecessor, not conversation text. Explicit result Interaction identity is preserved. A mismatch with the accepted request is reported separately; returning a completion frame alone does not prove logical completion.

Supply target_id when more than one target is available. Explicit target_revision and product_version_id select the discovery binding and the response must echo them exactly. If initialization supplied a deployment Version, Python registration also requires that same Version; use a matching runtime for a different binding. These capability selectors can be opaque refs or deployed commits: the authenticated registry validates the existing callable/material/placement binding. They neither create a canonical Builder Version UUID nor grant capability authority. A key with Simulations but no Traces creates no managed telemetry exporter. Fully explicit endpoint, credential, target/revision, Environment and version registration remains supported. An explicit capture-off runtime with no ingest configuration can still use that path.

If the actual authorized selectors are already in application configuration, pass them explicitly. The public Environment selector keyword is environment=:

target = runtime.register_simulation_target(
    target_id=authorized_target_id, target_revision=authorized_target_revision,
    environment=authorized_environment, product_version_id=deployed_version_ref, invoke=invoke,
)

Use the actual authorized target, revision and Environment identity supplied by the platform. This capability selector chooses the authorized target placement; ImpactContext.environment remains a reported environment name. Canonical Environment identity and permission come from the authenticated binding. These existing selectors are sent in the Product discovery request and must be echoed exactly; a different or missing selected target rejects before registration. environment_id belongs to the internal connection resolver and is not a keyword of the public register_simulation_target() API.

For async application handlers, register on the async runtime from the application's running event loop:

runtime = await impact.init_async()

async def invoke(request, *, signal, emit):
    return impact.SimulationResult(text=await run_application(request, signal=signal, emit=emit))

target = await runtime.register_simulation_target(
    effects={"boundary": "simulated"},
    invoke=invoke,
)
# At application teardown:
await target.close()  # Or await runtime.shutdown().

The async handler runs on the loop that awaits its registration, including its context/span scope. Each registration binds independently; an AsyncRuntime view itself can be used from another running loop. Cancellation sets the threading.Event signal and cancels the actual handler task, so ordinary asyncio.CancelledError and finally cleanup run on that same loop. Close gives cooperative task cleanup a bounded drain; cancellation does not prove that application side effects were rolled back. Keep the registration loop running through target/runtime shutdown. Async registration requires an awaitable result. An async def handler or a regular callable that returns an awaitable is invoked on the caller loop. Synchronous runtime registration accepts synchronous handlers; these run in worker threads and must check signal.is_set(). Python cannot forcibly stop or roll back synchronous work. An async application may explicitly offload blocking business work with asyncio.to_thread() in its own handler; cancelling that await does not stop the underlying thread, so the application owns its cooperative join. 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. Invocation, accepted-request, Run, case and turn IDs retain their technical meanings. The application uses the ordinary Interaction wrapper and explicit pending continuation for logical requests; history or a new turn cannot prove continuation. Simulation origin remains explicit even when the target is an actual Product application. A native trace ID does not certify Product readback. The optional request continuation contains the existing previousInvocationId and opaque handle; an application result can return its next continuation handle. Handles retain their exact value and allow 1–4,000 UTF-16 units. Python's whole request/result JSON must remain UTF-8 encodable; lone surrogate code units are refused, not normalized. Request and result payloads each remain bounded to 512 KiB. No handle grants Product or execution authority.

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; runtime.shutdown() closes all registrations. Await both when using an async view. Starting state, resource isolation and cleanup remain application-owned.

Replays with the same accepted-request key and body converge through the original request deadline, including after terminal acknowledgement; a changed body conflicts. Each registration retains at most 1,024 active or unexpired terminal identities. At that bound, new offers receive retryable busy rather than evicting an identity that could repeat an effect. Expired requests cannot run again. This is in-memory protection for the registration, not durable recovery across process restart. Explicit endpoints require HTTPS/WSS except on loopback. Missing or malformed request/lease correlation closes the protocol before application effects.

Protect

Protect uses the platform's original impact.protect/1 protocol at the documented provider and text/JSON boundaries. Runtime execution, Decision delivery and readable Product evidence are separate outcomes; a ready connection or loaded model does not establish successful enforcement or classifier quality.

Async applications use protect = await runtime.activate_protect(version_id=...) after await impact.init_async(). The returned async handle has synchronous protect.status(), await protect.flush(timeout_ms=...) and await protect.close(). Synchronous activation returns a ProtectHandle with local status(), bounded flush(timeout_ms=...) and close(). Both views close through the same runtime-owned lifecycle, so closing a handle and then shutting down the runtime does not repeat completed cleanup. A failed close reports closing and leaves cleanup retryable; deliberate reactivation creates a fresh owner after the prior close succeeds.

await runtime.shutdown() also closes its owned Protect activation. Cancellation preserves the caller's CancelledError and closes an unclaimed late activation. An owner acquired by another live caller stays active.

Protect activation is explicit. Ordinary imports and init() do not load models, initialize ONNX Runtime, download weights or change provider decisions. Base impact leaves native inference engines application-owned. Install impact[protect] for the selected convenience tuple: ONNX Runtime 1.31.1, tokenizers 1.0.0rc3 and NumPy 2.5.4 on Python 3.12+, or NumPy 2.4.6 on Python 3.11. This explicit extra selects those engines; applications retaining compatible ONNX Runtime 1.30.0/tokenizers 0.23.2 install base impact instead. On non-Windows systems set ORT_DISABLE_TELEMETRY=1 before any ONNX Runtime initialization. The lazy loader refuses initialization without it and never changes customer environment or OpenTelemetry. Setting it after another module initialized the runtime is not proof of the original opt-out. Windows ETW/native behavior remain unqualified. See ONNX Runtime privacy.

Applications can explicitly own the qualified ONNX Runtime 1.32.0.dev20261106001 preview with tokenizers==1.0.0rc3 and base impact. Select the exact host wheel and SHA-256 from the official nightly index as an application dependency. The nightly is absent from ordinary PyPI; the Protect extra uses the ordinary PyPI release and does not add a package index. Current native CPU evidence covers macOS 14+ ARM64; other nightly hosts remain unqualified.

Enable the Product key's Protect grant and explicitly activate the initialized SDK:

import impact

runtime = impact.init()
protect = runtime.activate_protect(runtime_label="support-worker")
print(protect.status())

Connection-v2 discovery supplies the authenticated Product/Environment and HTTP(S) Protect origin. The original Python controller requires HTTPS and connects to that origin's WSS /ws/sentinel with Bearer authority and X-Impact-Purpose: protect. Plain loopback WS is not an original Python capability. Local tests use a deliberately trusted local TLS certificate. The controller automatically reconnects and re-registers its same runtime identity, selected Version and label when supplied. Unchanged configuration is acknowledged again without reloading models. Connection, delivery, application, health and useful protected work remain distinct observations.

A customer-runner Environment can be selected without changing Presence or Trace export's base Environment:

import os

protect = runtime.activate_protect(
    environment_id=os.environ["IMPACT_PROTECT_ENVIRONMENT_ID"],
    version_id=os.environ["IMPACT_PROTECT_VERSION_ID"],
    runtime_label="support-worker",
    report_scores=True,
)

Protect's version_id is the canonical Builder whole-material Version UUID, distinct from the reported context version_id / IMPACT_VERSION_ID reference and callable selectors. The version-specific sample reads that actual configured UUID from IMPACT_PROTECT_VERSION_ID and passes it explicitly; the SDK does not read this example-specific variable itself. Likewise, IMPACT_PROTECT_ENVIRONMENT_ID supplies the actual authorized Environment UUID for the optional override. The server resolves the selected formal Version's digest. Caller-supplied version_digest values are unsupported and refuse before discovery or activation. Generic init/deployment labels are not substituted for version_id. Omitted Version input does not qualify a Version-specific runtime. Labels are trimmed valid text of 1–120 UTF-16 units without controls. Equivalent activation options share one registration and conflicting options refuse. The runtime also exposes invoke_protect_provider_test(boundary, invoke) for the existing authorized Product enforcement-command journey. The synchronous runtime invokes a synchronous application callback once; the async runtime awaits the actual async callback on its caller loop. This helper preserves the command's scoped identity and requires the actual selected provider boundary to apply a Decision. It does not create Policy authority or claim Product acceptance. No replacement profile, material-inspection, or SDK Test protocol is necessary for this original control wire.

report_scores defaults to False. Opt-in HTTP Decisions include each genuinely checked finite 0–1 score, including zero; unavailable checks omit it. Empty text has no evaluated chunk and follows the captured unavailable posture, without inventing a measured zero. Monitor and allow-and-record preserve the native empty result; configured unavailable blocking still applies to Enforce. The runtime retains raw Policy threshold/PCA and the pinned Arctic XS/S/M/L pipeline-2 catalogue. Immutable classifier references are acquired with same-origin purpose authentication and size/hash/media compatibility checks. Models are acquired lazily only for an applied Policy; set model_directory or IMPACT_PROTECT_MODEL_DIRECTORY for the cache. Optional model_ids restrict delivered models. Existing files can be supplied without an acquisition requirement:

protect = runtime.activate_protect(
    encoder_installs=[impact.EncoderInstall(
        "arctic-xs", "/srv/protection/arctic-xs/model.onnx", "/srv/protection/arctic-xs/tokenizer.json",
    )],
)

The native owner uses the original pinned embedding/classifier pipeline and verifies retained file bytes before native loading. Each runtime owns its exact configSequence/configRevision and Policy/artifact tuple: selected adoption changes that runtime while unselected runtimes retain their original basis until their own adoption. Off removes applied on Policies without acquiring a new model. An expiry renewal keeps the same sequence and revision. A higher sequence may carry the same revision when its configuration body matches. Stale sequences and changed material under a retained revision are refused. Failure, expiry and partial state remain visible. Enforce follows the captured unavailable posture and blocks unless allow_and_record; Monitor preserves native work and records unavailable checks. Late original stream Decisions keep their captured configuration rather than being recast against the newest material.

The bounded initial qualification lane is the existing native OpenAI Chat Completions path. Input checks precede the native provider request; output enforcement does not repeat it. Off and Monitor preserve configured client retries, native results, metadata, errors, lazy streams and caller cancellation. Existing sync/async wrappers retain the actual worker, provider read, body and iterator close until they join; cancelling a Python worker does not prove native inference stopped. A pending or failed cleanup remains an error. Pending unary Monitor and explicit allow_and_record calls finish normally during shutdown, with captured runtime_closed unavailable Decisions; shutdown retains their real join. Required Enforce/block still fences release. Customer clients remain caller-owned. Additional retained adapters have separate qualification work.

For Anthropic typed parsing, a text replacement makes the message/block parsed_output unavailable (None), including the final helper snapshot. Impact does not validate the replacement into a new application model or rerun user validators/schema hooks. Off, Monitor and unchanged output retain the original native parsed value and identity. An enforced helper snapshot is unavailable until its output has been checked.

Python retains at most 32 active native sends, reads and Protection workers. At that limit, Monitor and explicit allow_and_record preserve the application's next native call and report provider_retention_unavailable against its captured Policy configuration, without a measured score or a safe-check claim. An unretained call reports its output check unavailable before the native send; its eventual body remains application-owned and uninspected. Required Enforce/block refuses unavailable send admission before the provider call; failed read handoff after headers closes that response before consumer release. Shutdown joins retained work within its deadline and does not claim that unretained application work terminated. The original wire requires a digest even when that future output is unknown. Such output reports use the exact unavailableBasis value provider_retention_unavailable:output_body_unavailable:proposed_digest_placeholder with unavailable check/effect, no score and the required SHA-256 of an internal empty placeholder. That digest is not an observed empty native body or native content evidence; consumers must treat the body as unknown under this marker.

Native Decisions use purpose-authenticated HTTP /v1/protect/decisions and the bounded original outbox. Retries retain the same occurrence/body without a provider resend or rescoring. protect.flush(timeout_ms=6000) and shutdown make bounded attempts; pending, failed-attempt and lost counts remain visible. Original Decision reports contain digests, lengths, provenance and actual effects, not proposed/released plaintext. The existing protect_test / protect_test_result control frames are preserved. A missing genuine enforcement callback is unavailable, not a successful provider Test. Process exit may lose unacknowledged in-memory Decisions. A local flush or controlled receiver is not platform admission or current readback proof.

Linear JSON artifacts use binary64 coefficients and PCA output, left-to-right dot-product accumulation, and bias added after summation. Both SDKs use the same bounded sigmoid reduction so the same embedding, artifact and threshold produce the same linear score and decision. Native encoder and ONNX execution retain their own precision and platform qualification requirements; this is not a claim about model quality.

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.

Earlier surface Current replacement
Python 3.10 Python 3.11 or newer is required.
old endpoint configuration Direct OTLP uses the explicit OTLP endpoint and ingest key. On deployments that offer Product discovery, use the application API origin and discovery key.
with_context, tags with impact.context(...); map only validated Product context fields rather than arbitrary process tags.
with_trace_context, with_impact_trace_context Use impact.inject_context(carrier), then with impact.context(propagated=impact.extract_context(carrier)) on receipt. Carrier values never grant Product tenancy.
trace, start_interaction, interaction controllers Use with impact.span(...) as operation, set output on the handle, and remove controller lifecycle code.
score Use impact.feedback(...) for native user or application feedback. It does not turn an old score into an Eval conclusion.
mark Use explicit runtime.activate_protect(...) for the selected learned-policy runtime. It does not restore the generic mark API.
instrument_asgi_app Call impact.init() during application startup and use a normal application boundary or maintained framework integration; there is no general launcher wrapper.
old heartbeat and chat registration No legacy chat-handler alias is activated. Optional runtime presence reports bounded process metadata; use actual traffic and Simulation/Protect readiness for those separate signals.
module-level shutdown Use the returned runtime's shutdown(); await it for an AsyncRuntime.

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

Troubleshooting and support

After successful initialization, runtime.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. JavaScript vendor interoperability does not imply Python vendor interoperability.

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 runtime.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 Interaction 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.

If connection setup or export fails, inspect the content-free runtime.status().cause, .action and trace/log counters. For direct OTLP, use the copied /v1/traces URL and an active ingest key for that receiver; strict startup does not verify receiver authorization. After changing the endpoint or key of an activated runtime, restart or redeploy the process. For deployments offering Product-key discovery, use its application API origin and the required grant; after an unavailable startup settles, correct its configuration and explicitly initialize again. A fresh operation and actual exported records establish local delivery; Product readback is a separate check.

For setup help, contact Impact AI at biz@impact.ai with the SDK and Python versions, integration and operation, the local diagnosis code, and a content-free description of where the Trace stopped. Keep keys, prompt text and raw telemetry out of the message. Impact AI contact

Security reporting

Email biz@impact.ai with the subject Impact SDK security report, the affected package and version, and a contact address. Ask for a private channel to share the details. Keep credentials, customer data and reproductions out of the initial message and public issue trackers. Impact AI contact

Metadata

Release files for impact 1.2.0rc9

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

Change of provenance

The repository or configuration that created these release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Source distribution (sdist)

Source distribution for impact 1.2.0rc9
File Size Uploaded Provenance Actions
impact-1.2.0rc9.tar.gz 629.0 kB With provenance Details for impact-1.2.0rc9.tar.gz

Built distribution (wheel)

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

Total release size: 942.7 kB

Release files / impact-1.2.0rc9.tar.gz

Change of provenance

This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Download URL impact-1.2.0rc9.tar.gz
Size 629.0 kB
Tags Source
SHA-256 checksum
How to use checksums
77a21df8d9cb912af0152fb1f6643ece327d67396ac0801f36cf3d5a6bf8166d
BLAKE2b-256 checksum
How to use checksums
e05828555331b8809bbd0dcd38ff2e203110d23ce9ab32d333cba401077cb647
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 16, 2026.

Transparency log

Release files / impact-1.2.0rc9-py3-none-any.whl

Change of provenance

This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Download URL impact-1.2.0rc9-py3-none-any.whl
Size 313.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6d5d2b3f52a0c48872ff2241893fa0ce50061db6eb8d3dad55b3fc5558111689
BLAKE2b-256 checksum
How to use checksums
8ae1b1adf2ba077054b64d17a0e0ef3c749cf850bb429a5d00e49c67edb811b9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 16, 2026.

Transparency log

Security for impact 1.2.0rc9

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.

Change of provenance

The configuration that created this release differs from a previous release.

While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.

Select from 2 files

Attestation for impact-1.2.0rc9.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 16, 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.

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