Metadata-Version: 2.4
Name: impact
Version: 1.2.0rc5
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.45,>=1.43
Requires-Dist: opentelemetry-exporter-otlp-proto-http<1.45,>=1.43
Requires-Dist: opentelemetry-instrumentation-botocore<0.66,>=0.64b0
Requires-Dist: opentelemetry-instrumentation-genai-agno==1.1b0
Requires-Dist: opentelemetry-instrumentation-genai-anthropic==1.1b1
Requires-Dist: opentelemetry-instrumentation-genai-langchain==1.1b1
Requires-Dist: opentelemetry-instrumentation-genai-openai-agents==1.1b0
Requires-Dist: opentelemetry-instrumentation-genai-openai==1.1b0
Requires-Dist: opentelemetry-instrumentation-google-genai==1.1b1
Requires-Dist: opentelemetry-proto<1.45,>=1.43
Requires-Dist: opentelemetry-sdk<1.45,>=1.43
Requires-Dist: opentelemetry-util-genai==1.1b0
Requires-Dist: protobuf<8,>=6.33.5
Requires-Dist: requests<3,>=2.33
Requires-Dist: websockets<16,>=15
Requires-Dist: wrapt<3,>=2.4
Provides-Extra: adk
Requires-Dist: google-adk==2.7.0; extra == 'adk'
Requires-Dist: google-genai<3,>=2.22; extra == 'adk'
Provides-Extra: agno
Requires-Dist: agno<4,>=2.9; extra == 'agno'
Requires-Dist: openai<4,>=3.8; extra == 'agno'
Provides-Extra: anthropic
Requires-Dist: anthropic<2,>=1.4; extra == 'anthropic'
Provides-Extra: aws-bedrock
Requires-Dist: boto3<1.44,>=1.43.89; extra == 'aws-bedrock'
Requires-Dist: botocore<1.44,>=1.43.89; extra == 'aws-bedrock'
Provides-Extra: gemini
Requires-Dist: google-genai<3,>=2.22; extra == 'gemini'
Provides-Extra: langchain
Requires-Dist: langchain-core<1.7,>=1.6.2; extra == 'langchain'
Requires-Dist: langchain-openai<1.7,>=1.6; extra == 'langchain'
Requires-Dist: langchain<1.5,>=1.4; extra == 'langchain'
Requires-Dist: langgraph<1.3,>=1.2.11; extra == 'langchain'
Requires-Dist: openai<4,>=3.8; extra == 'langchain'
Provides-Extra: mcp
Requires-Dist: mcp==2.2.0; extra == 'mcp'
Provides-Extra: microsoft-agent-framework
Requires-Dist: agent-framework-core<1.19,>=1.17; extra == 'microsoft-agent-framework'
Requires-Dist: agent-framework-openai<1.15,>=1.14.2; extra == 'microsoft-agent-framework'
Requires-Dist: agent-framework-orchestrations==1.1.1; extra == 'microsoft-agent-framework'
Provides-Extra: openai
Requires-Dist: openai<4,>=3.8; extra == 'openai'
Provides-Extra: openai-agents
Requires-Dist: openai-agents<0.23,>=0.22; extra == 'openai-agents'
Requires-Dist: openai<4,>=3.8; extra == 'openai-agents'
Provides-Extra: openai-realtime
Requires-Dist: openai[realtime]==3.8.0; extra == 'openai-realtime'
Requires-Dist: websockets<16,>=15; extra == 'openai-realtime'
Provides-Extra: protect
Requires-Dist: numpy==2.4.6; extra == 'protect'
Requires-Dist: onnxruntime==1.30.0; extra == 'protect'
Requires-Dist: tokenizers==0.23.2; extra == 'protect'
Provides-Extra: pydantic-ai
Requires-Dist: pydantic-ai-slim<3,>=2.40; extra == 'pydantic-ai'
Description-Content-Type: text/markdown

# `impact`

This packaged guide describes the Python API shipped with this package. Published versions are listed
on [PyPI](https://pypi.org/project/impact/#history). See [Qualification](#qualification) for the scope and limits of
the supported application paths.

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

The package requires Python 3.11 or newer. Product-key setup and the retained capture capabilities completed their
selected installed qualification on the recorded candidate. Remote Capture and a general launcher are not implemented.
Preloaders remain unimplemented; native-required startup or per-client
registration keeps its actual integration-specific status described below.

## Install

Pin the complete version, including its prerelease suffix:

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

For a uv project, use `uv add 'impact==1.2.0rc5'`. Resolve Impact together with the application's existing dependencies;
an unversioned pip install normally selects the older stable release.

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

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

Use the local wheel above while evaluating an unpublished candidate.

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

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

The package admits OTel 1.43/0.64 and 1.44/0.65, protobuf 6.33.5 through 7.x, and Requests 2.33 through 2.x;
exact resolved versions remain part of each qualification receipt. Measure installation size, startup and memory in
the application's resolved environment. Historical host-specific measurements are indexed in the source repository's
[release evidence and archived qualification index](../impact-sdk.md#current-implementation-and-release-state).

## Quickstart

Configure `IMPACT_ENDPOINT` with the application API origin and `IMPACT_API_KEY` with the Product key generated by
Impact; enable its Traces grant for capture. `IMPACT_SERVICE_NAME` is optional. The SDK resolves the authenticated
connection settings for a Product key (`ipk_`); existing direct OTLP endpoint/ingest-key configuration remains supported.
Set `OPENAI_API_KEY` for this example. The provider key authenticates the model call; the Impact key grants only the
selected Impact capabilities. Initialization does not activate Simulation or Protect. Product-key initialization
performs a bounded hosted connection protocol version 2 check. If it fails, initialization raises a setup error before
installing hooks or exporters; retry after repairing the connection. Decide at the application startup boundary whether
an observability setup failure should prevent startup. Direct OTLP initialization does not use hosted discovery.
Run this file with Python 3.11 or newer after installing the OpenAI client, either directly or with
Impact's optional `openai` convenience extra:

```python
import impact

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

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

For async application startup, use `runtime = await impact.init_async()` with the same options. Product discovery
runs outside the event loop with a six-second caller wait limit; cancellation or timeout cannot install a late runtime.
The subsequent local initialization is synchronous. `init()` uses connect/read inactivity limits and a bounded
response body, rather than a strict total request deadline. Protect activation and Simulation registration remain
synchronous explicit APIs; call them at an appropriate startup boundary.

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

This complete enrichment example runs in its own process:

```python
import impact

runtime = impact.init()
from openai import OpenAI

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

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

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

## Core API and lifecycle

| API                                                    | Purpose                                                                                                                                           |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `init(...)`                                            | Starts one compatible runtime and activates installed integrations. Repeating equivalent setup returns that runtime; conflicting settings reject. |
| `init_async(...)`                                      | Awaits Product discovery without blocking the event loop, then initializes the same runtime.                                                      |
| `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 logical execution fields; apply extraction with `context(propagated=...)`.                                   |
| `feedback(...)`                                        | Records inline or post-hoc native feedback with a stable occurrence identity.                                                                     |
| `attach_realtime(connection, ...)`                     | Observes an existing OpenAI Realtime connection; the application retains the socket.                                                              |
| `status()`                                             | After `init()`/`init_async()`, reports provider ownership, integration activation states, limitations, local delivery and cleanup state.          |
| `flush(timeout_millis=...)`                            | Makes a bounded attempt to export finished telemetry. It does not prove platform admission or readback.                                           |
| `shutdown(timeout_millis=...)`                         | Flushes and stops SDK-owned work; a retry skips cleanup phases that already succeeded.                                                            |

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

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

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

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

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

Hosted Product-key applications may opt into lightweight runtime presence:

```python
runtime = impact.init(
    presence=True,
    context=impact.ImpactContext(version_id="release-7"),
)
```

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 explicitly supplied Product Version ID. It does
not scan source files, start application work, report a process count or establish Trace, Simulation, Protect or
Source health. `status().presence` reports only the locally known attempt outcome. Shutdown fences renewals and makes
one bounded best-effort stopped report; the platform's last-seen time and finite lease remain authoritative. Python's
HTTP socket timeouts bound connection and response-header inactivity but cannot forcibly cancel an in-flight DNS or
socket call. If it outlives the shutdown join budget, shutdown reports incomplete presence cleanup and a retry joins
the same worker while other owned capture cleanup continues.

`IMPACT_VERSION_ID` supplies the initialized Product Version ID 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.

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

The selected OpenTelemetry GenAI and Botocore owners share
`OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` but interpret it differently. Impact snapshots an explicit value,
applies the owner's enum or Boolean meaning only to records from that owner, and never rewrites the environment. An
unset value does not restrict the separate Impact destination. An invalid explicit value disables an affected
Impact-owned acquisition path; records from an already active unowned path are dropped if its control cannot be
interpreted. Unrelated customer and Impact records continue.

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.8.0`; Impact supplement                                                                                       | `openai.responses.create(background=true)`, `openai.responses.retrieve`, `openai.responses.cancel`, `openai.responses.retrieve(stream=true,starting_after)`, `openai.images.generate`, `openai.images.edit`, `openai.audio.speech.create`, `openai.audio.transcriptions.create`, `openai.audio.translations.create` | Preview: provider resumed-stream replay can stall before headers/events even after normal completion. Public OpenAI route only; Azure, Foundry and compatible-route extensions are not qualified here. Unread raw/media bodies remain unobserved. Background operation availability and media model entitlement belong to the provider.                                                |
| `py.google.background.v1`         | `google-genai 2.23.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.93`, `botocore 1.43.93`; 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.93`, `botocore 1.43.93`; Impact supplement                                                                  | `bedrock-agent-runtime.Retrieve`, `bedrock-agent-runtime.RetrieveAndGenerate`                                                                                                                                                                                                                                       | Supported for installed application-called Knowledge Base retrieval/generation; current locked 1.43.92 source compatibility also passes. Agent orchestration, source crawling and extra retrieval are unassessed. Cloud Knowledge Base access and model entitlement remain application-owned.                                                                                          |
| `py.mcp.server-tools.v1`          | `mcp 2.2.0`; Impact supplement                                                                                          | `mcp.server.tools.call`                                                                                                                                                                                                                                                                                             | Supported when Impact initializes before server construction and handler registration over stdio and Streamable HTTP on Python 3.11 and 3.14. Existing pre-init servers, resources, prompts and custom transports are unassessed. No SDK-owned connection or invocation.                                                                                                               |
| `py.openai.public.v1`             | OpenAI `3.8.0`; official owner `1.1b0` 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 `1.5.0`; official owner `1.1b1` plus Impact supplement                                                        | Messages create/stream, typed parse, sync/async consumed streams                                                                                                                                                                                                                                                    | Public Messages only; Claude on Google Cloud is not supported.                                                                                                                                                                                                                                                                                                                         |
| `py.google.models.developer.v1`   | Google Gen AI `2.23.0`; official owner `1.1b1` 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 `2.23.0`; Developer API; official owner plus Impact lifecycle supplement                                  | model create/stream/tool continuation plus application-called get/cancel/delete                                                                                                                                                                                                                                     | Background and reconnect operations have a separate claim in this catalogue; built-in agents and Vertex require independent evidence.                                                                                                                                                                                                                                                  |
| `py.google-adk.runner.v1`         | Google ADK `2.7.0`; Impact runner events plus provider owner                                                            | `Runner.run` and `run_async`, including model/tool/session events                                                                                                                                                                                                                                                   | Impact supplies native telemetry defaults when `RunConfig.telemetry` is unset and preserves an explicit application value. Shutdown marks the observation partial and stops capture without closing the native iterator. JSON-native action state deltas are retained without invoking ADK serializers; custom-serialized `long_running_tool_ids` are omitted and reported as partial. |
| `py.langgraph.langchain.v1`       | LangChain `1.4.0`, core `1.6.2`, LangGraph `1.2.11`; official owner `1.1b1`                                             | 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.openai-agents.runner.v1`      | OpenAI Agents `0.22.2`; official owner `1.1b0` 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.0.9`; official owner `1.1b0` 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.42.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.18.0`, OpenAI adapter `1.14.3`, orchestrations `1.1.1`; native telemetry plus Impact supplement | `Agent.run(stream=False\|True)` and `Workflow.run(stream=False\|True)`, tools and selected orchestration                                                                                                                                                                                                            | Cross-task stream consumption and durable checkpoint restoration are unassessed.                                                                                                                                                                                                                                                                                                       |
| `py.bedrock.converse.v1`          | Boto3/Botocore `1.43.92`; Botocore owner `0.64b0` plus Impact supplement                                                | Converse and caller-consumed ConverseStream                                                                                                                                                                                                                                                                         | InvokeModel, ApplyGuardrail, aiobotocore and partner dialects are outside this claim.                                                                                                                                                                                                                                                                                                  |
| `py.mcp.client-tools.v1`          | Official MCP SDK `2.2.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.8.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 installs the selected OpenTelemetry capture owners for every retained integration. It does not
install provider clients, application frameworks, MCP or Realtime transports. `impact.init()` checks for those
customer libraries without importing absent or disabled integrations and activates only the applicable owners.

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

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

## PydanticAI setup

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

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

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

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

## Streaming, content and credentials

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

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

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

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

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

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

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

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

## Feedback and diagnostics

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

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

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

## 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
runtime = impact.init(context=impact.ImpactContext(version_id="my-app-1.0.0"))

def invoke(request, *, signal, emit):
    # Your existing entry owns history, state, effects and cancellation.
    result = run_application(request, signal=signal, emit=emit)
    return {"text": result.text}

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

Supply `target_id` when more than one target is available. Explicit `target_revision` and `product_version_id`
override the application-version fallback and the response must echo them exactly. The version is a supplied correlation
label; it does not create a formal Compass ProductVersion record. A key with Simulations but no Traces creates no
managed telemetry exporter. Fully explicit endpoint, credential, target/revision, Environment and Product Version
registration remains supported. An explicit capture-off runtime with no ingest configuration can still use that path.

The handler may be synchronous or asynchronous. `signal` is a `threading.Event`; check `signal.is_set()` and stop
native work through the application's supported cancellation path. 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. The runtime creates a fresh technical
execution ID distinct from Run/case/turn/Session identities, reports it before the handler, and returns the reserved
`metadata["impact.execution.id"]`. A native trace ID does not certify Product readback.

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; `impact.shutdown()` closes all registrations. Starting state, resource isolation and cleanup remain
application-owned.

Replays with the same accepted-request key and body converge even after terminal acknowledgement; a changed body
conflicts. Missing or malformed request/lease correlation closes the protocol before application effects.

## Protect

Protect is an explicit, Product-scoped activation. Ordinary `impact` imports and `impact.init()` do not load model
weights or the optional inference packages. Install them only in an application that enables Protect:

```sh
pip install 'impact[protect]'
```

Enable the Product key's Protect grant, initialize the shared runtime, then explicitly activate Protect. The SDK
resolves Product, Environment and control settings using the same key:

```python
import impact

runtime = impact.init()
protect = impact.activate_protect()
```

The model cache defaults to `impact/protect` under the operating system's user cache directory. Override it with
`IMPACT_PROTECT_MODEL_DIRECTORY` or `model_directory`. Resolve/cache work happens only after explicit activation.
Fully explicit endpoint, credential, Product and Environment options remain available for existing integrations.

Activation opens the authenticated control session, downloads only the immutable model and policy revisions selected
for that Product and Environment, verifies their SHA-256 digests, and retains the last known good configuration.
Inference executes one admitted operation at a time, admits at most eight including queued work, and dynamically
batches model output under an 8 MiB tensor budget with a 30-second operation deadline. Python ONNX runs receive a
bounded cancellation signal; model and classifier sessions remain referenced until the active native call returns.
Provider integrations apply enabled policies at their real request and response boundaries. A block raises
`ProtectBlockedError`; truncate and replacement decisions return only the text that may proceed. Pass
`invoke_enforcement_test` only when it calls the same application/provider seam used by normal traffic. Close Protect
with the shared runtime through `runtime.shutdown()`.

Decision delivery retries transient failures in the background using a bounded in-memory queue. `protect.flush()`
makes a bounded delivery attempt without closing Protect. `impact.flush()` attempts both Protect and ordinary
telemetry delivery even if one fails. `protect.status()["control"]["decisionDelivery"]` exposes `pending`, `failed`
attempt and `lost` counts; `impact.status().protect` retains them after cleanup. A completed shutdown does not prove
Decision admission, and process termination can lose unacknowledged Decisions.

## Migrating from the earlier `impact` package

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

| Earlier surface                                       | Current replacement                                                                                                                                                                        |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Python 3.10                                           | Python 3.11 or newer is required.                                                                                                                                                          |
| old endpoint configuration                            | Product-key mode supplies the application API origin and Product key, then resolves authorized endpoints. Legacy direct OTLP mode supplies the exact OTLP endpoint and ingestion-only key. |
| `with_context`, `tags`                                | `with impact.context(...)`; map only validated Product context fields rather than arbitrary process tags.                                                                                  |
| `with_trace_context`, `with_impact_trace_context`     | Use `impact.inject_context(carrier)`, then `with impact.context(propagated=impact.extract_context(carrier))` on receipt. Carrier values never grant Product tenancy.                       |
| `trace`, `start_interaction`, interaction controllers | Use `with impact.span(...) as operation`, set output on the handle, and remove controller lifecycle code.                                                                                  |
| `score`                                               | Use `impact.feedback(...)` for native user or application feedback. It does not turn an old score into an Eval conclusion.                                                                 |
| `mark`                                                | Use explicit `impact.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`                               | `impact.shutdown()` remains available; prefer the returned runtime's `shutdown()` when the owner is already in scope.                                                                      |

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

## Qualification

After successful initialization, `status()` identifies the installed artifact, selected capture owners, activation
states, current support claims, loss and cleanup state. Each Supported claim retains its exact operation and ownership
limits. Source contributors
should use the canonical [release checkpoint](../impact-sdk.md#current-implementation-and-release-state) for current release status;
a source build does not establish package-index publication. Named JavaScript vendor coexistence evidence does not
establish Python vendor coexistence.

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

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

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

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

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