Metadata-Version: 2.4
Name: impact
Version: 1.2.0rc9
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.45.2
Requires-Dist: opentelemetry-exporter-otlp-proto-http<1.46,>=1.45.2
Requires-Dist: opentelemetry-instrumentation-botocore<0.67,>=0.66b2
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.45.2
Requires-Dist: opentelemetry-sdk<1.46,>=1.45.2
Requires-Dist: opentelemetry-util-genai==1.3b0
Requires-Dist: protobuf<8,>=6.33.5
Requires-Dist: requests<3,>=2.33
Requires-Dist: urllib3<3,>=2.8.0
Requires-Dist: websockets<18,>=15
Requires-Dist: wrapt<3,>=2.4
Provides-Extra: adk
Requires-Dist: google-adk==2.14.1; extra == 'adk'
Requires-Dist: google-genai==2.34.0; extra == 'adk'
Requires-Dist: opentelemetry-sdk==1.45.2; 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`

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

[First Trace](#quickstart) · [Launch scope](#launch-scope) · [Troubleshooting](#troubleshooting-and-support) ·
[Security reporting](#security-reporting)

## Quickstart

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

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

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

   For an unpublished candidate, use its supplied wheel instead.

   ```sh
   python -m pip install /absolute/path/to/impact-1.2.0rc9-py3-none-any.whl 'openai==3.46.0'
   ```

2. In the target AI product, have a workspace owner or admin open **Ingest keys → Create ingest key**. Save the raw
   secret and copy the URL ending in `/v1/traces` from **OpenTelemetry exporter settings**. Use the exact URL for
   `IMPACT_ENDPOINT` and the raw ingest secret for `IMPACT_API_KEY`. The SDK supplies the Bearer header.
3. In your app's secret configuration, set those two variables and set `OPENAI_API_KEY` to an API key from your
   OpenAI project. Set `IMPACT_SERVICE_NAME=impact-quickstart` in the app environment so you can identify the run.
   This example makes one billable model call and defaults to `gpt-6.1-sol`. Set `OPENAI_MODEL` to a model your
   project can use with the supplied options, or adjust its model-specific options.
   [OpenAI API keys](https://platform.openai.com/api-keys) ·
   [OpenAI model reference](https://developers.openai.com/api/docs/models/gpt-6.1-sol)
4. Save this as `quickstart.py`. Importing `impact` is passive. Initialize it before constructing the application
   client.

   ```python
   import os

   import impact

   runtime = impact.init(startup="strict")
   try:
       from openai import OpenAI

       print("Impact SDK", runtime.status().artifact["version"], "runtime", runtime.status().runtime_id)
       with OpenAI(max_retries=0) as client:
           result = client.responses.create(
               model=os.getenv("OPENAI_MODEL", "gpt-6.1-sol"),
               max_output_tokens=512,
               reasoning={"effort": "low"},
               input="Say hello in one sentence.",
           )
           print(result.output_text)
   finally:
       shutdown = runtime.shutdown()
       status = runtime.status()
       print("Impact local delivery", shutdown.delivery)
       print("Impact exported traces", status.traces.exported if status.traces else None)
       if status.cause not in (None, "none"):
           print("Impact diagnosis", status.cause, status.action)
       if not shutdown.completed:
           print("Impact shutdown incomplete", shutdown.message)
   ```

   ```sh
   python quickstart.py
   ```

5. Confirm the printed SDK version is `1.2.0rc9`. In the same AI product, open **Traces** and select the recent
   row for `impact-quickstart`. In the model span's **Recorded fields**, check the model and available token usage.
   Match the prompt and printed reply when your Product retains content. If the Trace is missing, see
   [Troubleshooting](#troubleshooting-and-support). Match `impact.runtime.id` to the printed runtime ID so an older
   run cannot satisfy the check. Cleanup completion and local delivery are separate: `incomplete` or `unknown`
   require investigation. Zero exported traces means this run has not demonstrated capture; even
   `exported-not-readback` does not establish a readable Product Trace.

Already using OpenTelemetry? Keep its providers and destinations with the
[customer-owned setup](#core-api-and-lifecycle).

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

## Launch scope

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

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

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

### Migrating from the Assistants API

Move the application to `client.responses.create`, carry forward its instructions and tool definitions, and
choose how to manage conversation state. Check the tool calls, output items and stream events your application
actually consumes. For Microsoft Foundry, use the standard OpenAI client with the resource's `/openai/v1/`
base URL and the deployment name. The integration catalogue describes the SDK's assessed operation boundaries.
[OpenAI migration guide](https://developers.openai.com/api/docs/assistants/migration) ·
[Microsoft Foundry v1 API](https://learn.microsoft.com/en-us/azure/foundry/openai/api-version-lifecycle)

## Install

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

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

For an unpublished candidate, install the supplied wheel instead:

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

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

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

```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 requires OpenTelemetry `>=1.45.2,<1.46` and the matching
OpenTelemetry instrumentation family starting at `0.66b2`. The `gemini` convenience extra selects Google Gen AI
3.0.0. Use a separate environment for the `adk` extra, which selects ADK 2.14.1, Google Gen AI 2.34.0 and
OpenTelemetry SDK 1.45.2. An existing ADK application can install base `impact` beside its own compatible
dependencies. Resolve the application's middleware and tracing instrumentation together so the entire environment
uses the patched propagation dependencies. [OpenTelemetry tracestate advisory](https://github.com/open-telemetry/opentelemetry-python/security/advisories/GHSA-xcq7-p3pf-p88h) ·
[OpenTelemetry traceparent advisory](https://github.com/open-telemetry/opentelemetry-python/security/advisories/GHSA-mf5v-w3w3-f6cg)
Applications pinned to an older incompatible family need a coordinated telemetry dependency upgrade before installing
it. For example, a project requiring SDK 1.39.1 and FastAPI instrumentation 0.60b1 fails normal project resolution;
installing the wheel alone replaces some dependencies and leaves that older instrumentation inconsistent. Resolve the
complete application and verify its native behavior after an intentional dependency upgrade. Impact preserves
compatible customer libraries; it cannot make conflicting OpenTelemetry package requirements coexist in one Python
environment.

Applications normally keep their existing provider and framework dependencies. The extras are optional convenience
sets for installing the selected customer libraries into a new application; they are not needed when those libraries
are already installed. `pyproject.toml` publishes exact selected convenience tuples; `uv.lock` records their ordinary resolution,
including the separate Google/ADK environments.
An admitted version range does not imply every operation is Supported; check the installed catalogue's exact native
tuple and operation boundary.

The package admits protobuf 6.33.5 through 7.x, Requests 2.33 through 2.x and urllib3 2.8.0 through 2.x.
Resolve the complete application together and measure installation size, startup and memory in that environment.
[urllib3 2.8.0 security fixes](https://github.com/urllib3/urllib3/releases/tag/2.8.0)

## Application startup

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

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

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

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

```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. Stream output records consumed chunks in a JSON array. A capturable non-`None` sync
generator return uses a single `output.value` JSON object containing `chunks` and `return`, identified by
`impact.capture.output.format="stream-chunks-and-return"`. The output follows the boundary's content controls.
Context identifiers allow 1,024 UTF-8 bytes and purpose allows 65,536. Empty strings, NUL, malformed Unicode and
unknown fields reject before capture.

`inject_context()` combines initialized context defaults with the current scope's overrides. It fills and returns the
supplied carrier with standard W3C `traceparent`/`tracestate` plus one bounded `impact-context` value. That value is
canonical compact UTF-8 JSON encoded as unpadded base64url: version 2, optional Interaction/Session and `domainRun`.
User attribution is not automatically propagated. A conflicting or stale owned value raises `ValueError` without
changing any carrier field. Use a fresh carrier for each request. Successful shutdown removes initialized defaults.

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

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

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

```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. An ordinary nested
`interaction()` with the active Interaction ID raises before invoking the inner callback. Use `context()` or `span()`
for contributor work, and await the actual join inside the application's completion owner.

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

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

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

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

```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.
The HTTP deadline and platform DNS limitation described above also apply to presence. If work outlives the shutdown
join budget, shutdown reports incomplete presence cleanup and a retry joins the same worker while other owned
capture cleanup continues.

`IMPACT_VERSION_ID` supplies the reported deployed-version reference when
`ImpactContext(version_id=...)` does not. An explicit context value takes precedence, and an absent setting leaves the
version unknown. The environment value is trimmed; a blank value is treated as absent. This same initialized value
labels native Trace context, the default Simulation target selector and presence metadata; it is never inferred by
inspecting the application or repository. Supply the same `IMPACT_VERSION_ID` to the Source CLI upload job and the
actual deployed application environment. Exporting it only during Source upload does not configure the running
application. The wire key remains `impact.product.version.id`; a release label or Git commit does not become a
canonical Builder Version UUID because of that name. Source sync associates the exact reported ref with its captured
code snapshot. Callable discovery separately validates an existing Product/target/material/placement binding and may
resolve a deployed Git commit to a retained declaration. It creates no Version and grants no authority from the ref.
Only an actual owning Builder/deployment binding can establish a canonical whole-material Version UUID.

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

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

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

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

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

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

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

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

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

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

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

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

The matrix does not promise every route that a client can address.
For each retained operation, check `status().integrations` and the actual representative Trace as described under
[Troubleshooting and support](#troubleshooting-and-support).

## LlamaIndex setup

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

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

## Microsoft Agent Framework setup

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

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

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

```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. Impact omits signed or authenticated URLs in recognized media, native resource and tool/server
reference fields on outgoing copies, including structured values and known native JSON mirrors, even under full
capture. `impact.content.credential_references=omitted.unsafe-reference` marks a reference or unverifiable native
JSON envelope omitted by this filter. Ordinary reference URLs are retained subject to the integration's reference
rules. Free-form prompt text and arbitrary application fields keep their configured content policy. Native request
and response objects and customer-owned telemetry keep their original values.

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

## Feedback and diagnostics

`feedback()` requires a name and at least a score, label or explanation. With no `target`, it records Feedback for
the active Interaction. Outside an Interaction, supply an explicit supported Interaction, native span, Product Trace
or Session target. An explicit target wins and never mutates an ended span. Retain the returned `id`, `producer` and `occurred_at` when retrying the same occurrence.
`FeedbackReceipt` contains `id`, `producer`, `occurred_at` and `outcome`. `outcome="recorded-locally"` means local capture only;
`"not-recorded"` means no local capture. Both packages bound the compact emitted feedback JSON, including its target,
to 1 MiB of UTF-8 bytes, 4,096 JSON values and nesting below 64 levels. Labels and explanations share that
whole-occurrence budget. Python validates the complete occurrence before applying local sampling and delivery routing.

`runtime.status()` separates trace and log provider ownership, each integration's activation state, limitations, bounded
delivery counts and cleanup progress. Exact package owners and versions remain in the maintained integration matrix.
`status().runtime_id` matches the generated `impact.runtime.id` on SDK-owned evidence and Impact-routed copies,
alongside `impact.sdk.version`. This runtime identity is read-only; `ImpactContext` has no `runtime_id` input. Customer records remain unchanged.
Attach a caller-owned Realtime connection before its first response request with
`runtime.attach_realtime(connection, connection_id=connection_id, correlation_metadata_key="request_id")` when the app
already supplies a unique string in `response.create.response.metadata["request_id"]`. The SDK snapshots the active
Interaction/Session/User and actual native parent at the outbound send. Only a unique matching native metadata echo at the
first observed response event binds later response-ID events to that snapshot. It never adds metadata, treats the echo value
as a business ID, or guesses from FIFO order or the context active during receive. The default, VAD, ambiguous and unmatched
responses keep native facts and remain logically unassigned.

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

After Realtime attachment, `status().realtime` reports active connections and cumulative observed/captured/dropped counts,
including completed connections; activation/counts alone do not prove logical association or useful Product capture.
A successful `flush()` establishes only local exporter completion. Use the qualification readback for authenticated
durable evidence.

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

## Simulation

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

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

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

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

## Protect

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

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

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

Protect activation is explicit. Ordinary imports and `init()` do not load models, initialize ONNX Runtime, download
weights or change provider decisions. Base `impact` leaves native inference engines application-owned. Install
`impact[protect]` for the selected convenience tuple: ONNX Runtime 1.31.1, tokenizers 1.0.0rc3 and NumPy 2.5.4
on Python 3.12+, or NumPy 2.4.6 on Python 3.11. This explicit extra selects those engines; applications retaining
compatible ONNX Runtime 1.30.0/tokenizers 0.23.2 install base `impact` instead. On
non-Windows systems set `ORT_DISABLE_TELEMETRY=1` before any ONNX Runtime initialization. The lazy loader refuses
initialization without it and never changes customer environment or OpenTelemetry. Setting it after another module
initialized the runtime is not proof of the original opt-out. Windows ETW/native behavior remain unqualified.
See [ONNX Runtime privacy](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. An expiry renewal keeps the same sequence and revision. A higher
sequence may carry the same revision when its configuration body matches. Stale sequences and changed material
under a retained revision are refused. Failure, expiry and partial state remain visible. Enforce follows the captured unavailable
posture and blocks unless `allow_and_record`; Monitor preserves native work and records unavailable checks. Late
original stream Decisions keep their captured configuration rather than being recast against the newest material.

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

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

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

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

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

## Migrating from the earlier `impact` package

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

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

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

## Troubleshooting and support

After successful initialization, `runtime.status()` identifies the installed artifact, selected capture owners, activation
states, current support claims, loss and cleanup state. Each Supported claim retains its exact operation and ownership
limits. JavaScript vendor interoperability does not imply Python vendor interoperability.

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

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

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

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

## Security reporting

Email `biz@impact.ai` with the subject **Impact SDK security report**, the affected package and version, and a
contact address. Ask for a private channel to share the details. Keep credentials, customer data and reproductions out
of the initial message and public issue trackers. [Impact AI contact](https://www.impact.ai/imprint)
