Metadata-Version: 2.4
Name: impact
Version: 1.2.0rc8
Summary: Impact AI telemetry SDK
Project-URL: Repository, https://github.com/impact-ai-core/impact-sdk
Author: Impact AI
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Requires-Python: >=3.11
Requires-Dist: opentelemetry-api<1.46,>=1.43
Requires-Dist: opentelemetry-exporter-otlp-proto-http<1.46,>=1.43
Requires-Dist: opentelemetry-instrumentation-botocore<0.67,>=0.64b0
Requires-Dist: opentelemetry-instrumentation-genai-agno==1.3b0
Requires-Dist: opentelemetry-instrumentation-genai-langchain==1.3b0
Requires-Dist: opentelemetry-instrumentation-genai-llama-index==1.3b0
Requires-Dist: opentelemetry-instrumentation-genai-openai-agents==1.3b0
Requires-Dist: opentelemetry-instrumentation-genai-openai==1.3b0
Requires-Dist: opentelemetry-instrumentation-google-genai==1.3b0
Requires-Dist: opentelemetry-proto<1.46,>=1.43
Requires-Dist: opentelemetry-sdk<1.46,>=1.43
Requires-Dist: opentelemetry-util-genai==1.3b0
Requires-Dist: protobuf<8,>=6.33.5
Requires-Dist: requests<3,>=2.33
Requires-Dist: websockets<18,>=15
Requires-Dist: wrapt<3,>=2.4
Provides-Extra: adk
Requires-Dist: google-adk==2.13.0; extra == 'adk'
Requires-Dist: google-genai==2.34.0; extra == 'adk'
Provides-Extra: agno
Requires-Dist: agno==3.1.12; extra == 'agno'
Requires-Dist: openai==3.46.0; extra == 'agno'
Provides-Extra: anthropic
Requires-Dist: anthropic==2.6.0; extra == 'anthropic'
Provides-Extra: aws-bedrock
Requires-Dist: boto3==1.43.126; extra == 'aws-bedrock'
Requires-Dist: botocore==1.43.126; extra == 'aws-bedrock'
Provides-Extra: gemini
Requires-Dist: google-genai==3.0.0; extra == 'gemini'
Provides-Extra: langchain
Requires-Dist: langchain-core==1.7.6; extra == 'langchain'
Requires-Dist: langchain-openai==1.7.4; extra == 'langchain'
Requires-Dist: langchain==1.4.9; extra == 'langchain'
Requires-Dist: langgraph==1.2.20; extra == 'langchain'
Requires-Dist: openai==3.46.0; extra == 'langchain'
Provides-Extra: llama-index
Requires-Dist: llama-index-core==0.14.25; extra == 'llama-index'
Requires-Dist: llama-index-instrumentation==0.6.0; extra == 'llama-index'
Requires-Dist: llama-index-workflows==2.26.1; extra == 'llama-index'
Provides-Extra: mcp
Requires-Dist: mcp==2.3.0; extra == 'mcp'
Provides-Extra: microsoft-agent-framework
Requires-Dist: agent-framework-core==1.24.0; extra == 'microsoft-agent-framework'
Requires-Dist: agent-framework-openai==1.18.0; extra == 'microsoft-agent-framework'
Requires-Dist: agent-framework-orchestrations==1.4.1; extra == 'microsoft-agent-framework'
Provides-Extra: openai
Requires-Dist: openai==3.46.0; extra == 'openai'
Provides-Extra: openai-agents
Requires-Dist: openai-agents==0.24.0; extra == 'openai-agents'
Requires-Dist: openai==3.46.0; extra == 'openai-agents'
Provides-Extra: openai-realtime
Requires-Dist: openai[realtime]==3.46.0; extra == 'openai-realtime'
Requires-Dist: websockets<16,>=15; extra == 'openai-realtime'
Provides-Extra: protect
Requires-Dist: numpy==2.4.6; (python_version < '3.12') and extra == 'protect'
Requires-Dist: numpy==2.5.4; (python_version >= '3.12') and extra == 'protect'
Requires-Dist: onnxruntime==1.31.1; extra == 'protect'
Requires-Dist: tokenizers==1.0.0rc3; extra == 'protect'
Provides-Extra: pydantic-ai
Requires-Dist: pydantic-ai-slim==2.66.0; extra == 'pydantic-ai'
Description-Content-Type: text/markdown

# `impact`

This guide covers `impact==1.2.0rc8`, a prerelease of the Python SDK. Prerelease APIs may change.
Use the installed package's catalogue for exact native versions, operations and limits. Published versions are listed
on [PyPI](https://pypi.org/project/impact/#history). See [Qualification](#qualification) for the scope and limits of
the retained application paths.

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. Provider and framework clients stay
application-owned. Importing `impact` is passive; call `impact.init()` once before creating supported clients, or await
`impact.init_async()` at async startup. The returned runtime owns SDK lifecycle and optional capabilities.

The package requires Python 3.11 or newer. Initialization and local delivery status do not establish application
capture; verify a representative operation in its intended Product. Remote Capture and a general launcher are not implemented.
Preloaders remain unimplemented; native-required startup or per-client
registration keeps its actual integration-specific status described below.

## Install

If this exact version is available from your configured package index, pin the complete version, including its
prerelease suffix:

```sh
python -m pip install 'impact==1.2.0rc8'
```

For a uv project, use `uv add 'impact==1.2.0rc8'`. Resolve Impact together with the application's existing dependencies;
an unversioned install may select a different release. For a locally evaluated candidate, install the supplied wheel
instead of assuming package-index availability.

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:

```sh
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:

```sh
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 declares the coordinated OpenTelemetry 1.43/0.64, 1.44/0.65 and
1.45/0.66 families. Its ranges preserve compatible telemetry selected by the application. The source lock resolves the
base/current profile to
1.45.2/0.66b2 and the separate Google ADK profile to 1.44.0/0.65b0.
The current `gemini` convenience extra selects Google Gen AI 3.0.0; `adk` selects ADK 2.13.0 with Google Gen AI
2.34.0, as required by ADK. These two extras cannot be installed together. An existing ADK application can install
base `impact` beside its own compatible dependencies. No public extra pins a customer OpenTelemetry version.
Langfuse `5.0.4` requires the 1.45 family and conflicts with ADK 2.13.0's maximum 1.44 in one environment;
choose compatible application versions or separately configured processes/Collector topology.
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 OTel 1.43/0.64, 1.44/0.65 and 1.45/0.66, protobuf 6.33.5 through 7.x, and Requests 2.33 through 2.x;
resolve the complete application together and measure installation size, startup and memory in that environment.

## Quickstart

Configure `IMPACT_ENDPOINT` with the application API origin and `IMPACT_API_KEY` with the Product key generated by
Impact; enable its Traces grant for capture. `IMPACT_SERVICE_NAME` is optional. The SDK resolves the authenticated
connection settings for a Product key (`ipk_`); existing direct OTLP endpoint/ingest-key configuration remains supported.
Set `OPENAI_API_KEY` for this example. `OPENAI_MODEL` overrides the default
[`gpt-6.1-sol`](https://developers.openai.com/api/docs/models/gpt-6.1-sol). The example uses low reasoning and a
512-token output bound; change model-specific options together when choosing a different model.
The provider key authenticates the model call; the Impact key grants only the
selected Impact capabilities. Initialization does not activate Simulation or Protect. Product-key initialization
performs a bounded hosted connection protocol version 2 check. Remote discovery failure returns an unavailable runtime
with an actionable local diagnosis and no hooks or exporters. Use `startup="strict"` to raise that setup error instead;
a later explicit initialization retries the connection. Invalid local configuration always raises before effects.
Direct OTLP initialization does not use hosted discovery.
Run this file with Python 3.11 or newer after installing the OpenAI client, either directly or with
Impact's optional `openai` convenience extra:

```python
import os

import impact

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

client = OpenAI()
try:
    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:
    runtime.shutdown()
```

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

```python
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:

```python
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. 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=...)`; malformed input cannot create a
request or overwrite application attribution. 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:

```python
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. For parallel work,
retain one completion owner and await the genuine join; branch contributors do not end the Interaction.

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:

```python
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:

```python
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:

```python
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:

```python
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. Python's
HTTP socket timeouts bound connection and response-header inactivity but cannot forcibly cancel an in-flight DNS or
socket call. If it outlives the shutdown join budget, shutdown reports incomplete presence cleanup and a retry joins
the same worker while other owned capture cleanup continues.

`IMPACT_VERSION_ID` supplies the 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:

```python
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. Positive capture facets for closed content report `omitted.policy` on the outgoing copy. Restricted records carry the compact normalized
policy in `impact.content.policy` and `impact.content.<category>=omitted.policy`. A projection failure drops that
Impact record and increments the signal's `content_dropped` status count; it never exports the unrestricted record.

`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:

```python
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:

```python
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` | Preview: 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.13.0`, Gen AI `2.34.0`; 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.13.0 is a separate profile with Google Gen AI
2.34.0 and OpenTelemetry 1.44. 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
[Qualification](#qualification).

## 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 maintained OpenAI connector 0.8.3 requires OpenAI 2.54.0 in its application tuple. Use base `impact` with that
application's requirements; adding the OpenAI 3.46 convenience extra would conflict with the connector. The native
[agent/RAG example](examples/llama_index/app.py) records the exact application requirements. Its 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()`:

```python
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. 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. 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; oversized or invalid feedback is rejected before enqueueing.

`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:

```python
# 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`
override the reported-version fallback and the response must echo them exactly. 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=`:

```python
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:

```python
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 even after terminal acknowledgement; a changed body
conflicts. 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. The canonical contract is
[impact-sdk.md](../impact-sdk.md#optional-protect-intervention).

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](https://github.com/microsoft/onnxruntime/blob/v1.31.1/docs/Privacy.md).

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](https://aiinfra.pkgs.visualstudio.com/PublicPackages/_packaging/ORT-Nightly/pypi/simple/onnxruntime/)
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:

```python
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:

```python
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:

```python
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. Same-sequence renewal changes expiry only; stale or
changed material refuses. 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
one native provider send; output enforcement does not repeat it. Off and Monitor preserve 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.

## 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                            | Product-key mode supplies the application API origin and Product key, then resolves authorized endpoints. Legacy direct OTLP mode supplies the exact OTLP endpoint and ingestion-only 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.

## Qualification

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.

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](../tools/release/README.md#installed-qualification) 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:

```sh
uv run --project python --locked --all-extras --no-extra adk pytest python/tests --ignore=python/tests/test_adk_compat.py
uv run --project python --locked --all-extras --no-extra adk ruff check python
uv run --project python --locked --all-extras --no-extra adk python -m build --no-isolation python
```

Run the constrained ADK checks in a separate environment:

```sh
adk_environment=$(mktemp -d)
UV_PROJECT_ENVIRONMENT="$adk_environment" uv run --project python --locked --all-extras --no-extra gemini \
  pytest python/tests/test_adk_compat.py
```
