impact

This packaged guide describes setup, exact integration boundaries and migration for the R1 package. The source checkout may contain an unpublished build; see Qualification before choosing an install source.

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

The R1 package requires Python 3.11 or newer. It does not yet implement the selected R1.5 Simulation or Protect capabilities. Remote Capture and a general launcher remain potential future work under the canonical SDK contract. Preloaders remain unimplemented; native-required startup or per-client registration keeps its actual integration-specific status described below.

Install the R1 package

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

artifact_dir=$(mktemp -d)
uv build --wheel --project python --out-dir "$artifact_dir"
sdk_wheel="$artifact_dir/impact-1.2.0rc1-py3-none-any.whl"

After 1.2.0rc1 is available from the configured Python package index, an application can install it with python -m pip install 'impact==1.2.0rc1'. The local wheel commands in this guide are the valid path before publication.

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

uv add "$sdk_wheel"

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

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

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

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

Quickstart

Configure IMPACT_ENDPOINT, IMPACT_API_KEY and optionally IMPACT_SERVICE_NAME using the route settings from Impact. Set OPENAI_API_KEY for this example. The provider key authenticates the model call; the Impact key authenticates telemetry. Run this file with Python 3.11 or newer after installing the OpenAI client, either directly or with Impact's optional openai convenience extra:

import impact

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

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

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

This complete enrichment example runs in its own process:

import impact

runtime = impact.init()
from openai import OpenAI

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

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

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

Core API and lifecycle

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

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

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

Every listed R1 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 R1 keys are google, google_adk, anthropic, openai_agents, agno, pydantic_ai, aws_bedrock, microsoft_agent_framework and mcp. Selections are frozen, appear in status().integrations and form part of initialization identity; repeated init() calls must use equivalent selections. Realtime attachment remains an explicit API because the application owns the connection.

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

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.

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 gives the support state and attributed evidence for each exact claim. The 17 operation-specific catalogue entries below define their supported boundaries and limitations. An installed extra, import or local flush alone is not support proof.

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

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

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

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

PydanticAI setup

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

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

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

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

Streaming, content and credentials

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

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

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

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

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

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

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

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

Feedback and diagnostics

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

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

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

Migrating from the earlier impact package

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

The accepted R1.5 migration contract covers Impactful's public exports, configuration and actual application consumers, including Simulation, Protect, heartbeat replacement, CLI/IDE Source sync and installation assistance. Those replacements are planned; this guide will add exact migration instructions as their implementations are qualified. SDK installation snippets must continue to use only APIs available in the selected artifact.

R1.5 adds no Python 3.10, LlamaIndex or historical Google client support requirement. Product instructions and downloadable artifacts migrate alongside the application.

Qualification

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

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

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

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

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

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