The repository or configuration that created this release differ from a previous release. View details.
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.
-
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'
-
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/tracesfrom OpenTelemetry exporter settings. Use the exact URL forIMPACT_ENDPOINTand the raw ingest secret forIMPACT_API_KEY. The SDK supplies the Bearer header. -
In your app's secret configuration, set those two variables and set
OPENAI_API_KEYto an API key from your OpenAI project. SetIMPACT_SERVICE_NAME=impact-quickstartin the app environment so you can identify the run. This example makes one billable model call and defaults togpt-6.1-sol. SetOPENAI_MODELto a model your project can use with the supplied options, or adjust its model-specific options. OpenAI API keys · OpenAI model reference -
Save this as
quickstart.py. Importingimpactis 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 -
Confirm the printed SDK version is
1.2.0rc9. In the same AI product, open Traces and select the recent row forimpact-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. Matchimpact.runtime.idto the printed runtime ID so an older run cannot satisfy the check. Cleanup completion and local delivery are separate:incompleteorunknownrequire investigation. Zero exported traces means this run has not demonstrated capture; evenexported-not-readbackdoes 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.