Metadata-Version: 2.4
Name: impact
Version: 1.2.0
Summary: Impact AI telemetry SDK
Project-URL: Repository, https://github.com/Impact-AI/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 SDK for Python

Capture model and tool work from your Python application in Impact Traces. Your application keeps its native
clients, responses, streams, errors and tool effects. Python 3.11 or newer is required.

## Quickstart

Create a virtual environment and install the exact SDK version alongside the OpenAI client for this
example. The shell commands use a POSIX shell.

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

Pin the full version. For an existing application, resolve `impact` with the
application's dependencies and keep its compatible clients. For example, in an existing uv project use
`uv add 'impact==1.2.0'`.

1. Ask a workspace owner or admin to open **Ingest keys → Create ingest key** in the intended AI product. Copy
   the **OpenTelemetry exporter settings** URL ending in `/v1/traces` to `IMPACT_ENDPOINT`. Store the raw
   ingest secret as `IMPACT_API_KEY`. Impact adds the Bearer header.
2. Set `OPENAI_API_KEY` from your OpenAI project and `IMPACT_SERVICE_NAME=impact-quickstart`. Store both keys
   in your application's secret configuration. The example makes one billable OpenAI Responses call. Set
   `OPENAI_MODEL` to a model your project can use with the supplied options, or adjust the options for that
   model.
3. Save the following as `quickstart.py`. Importing `impact` is passive. Initialize it before constructing the
   client.

```python
import os

import impact

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

    status = runtime.status()
    print("Impact SDK", status.artifact["version"], "runtime", status.runtime_id)
    with OpenAI(max_retries=0) as client:
        response = 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(response.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
```

Open **Traces** in the same AI product. Find `impact-quickstart` and match the Trace's `impact.runtime.id` to
the printed runtime ID. In the model span's **Recorded fields**, check the model and available token usage.
Match the prompt and printed reply when the Product retains content. Verify the installed SDK version against
the version you selected. Treat shutdown completion, local export and a readable Product Trace as separate
checks.

## Integrate with your application

- Start Impact before constructing supported provider and framework clients. Retain the runtime and call
  `runtime.shutdown()` during application teardown. In an async application, use `await impact.init_async()`
  and `await runtime.shutdown()`. Inspect `runtime.status()` locally in either case.
- Keep your existing OpenTelemetry providers, processors and samplers. To add an Impact destination to your
  customer-owned provider, pass `tracer_provider=provider` and the explicit Impact `endpoint=` and `api_key=`
  to `init()`. Pass `logger_provider=` if using a customer LoggerProvider. When both route options are
  omitted, customer exporters own delivery, even with managed-mode environment variables set.
- Wrap a logical request with `impact.interaction()` to record its actual result and native work. Supply a
  Session ID when those requests belong to the same Session. Use `impact.span()` for an application-owned
  tool.
- With supported streams, capture follows the native events the application consumes. Early close can leave
  terminal output and usage unavailable.
- Set the relevant keys to `False` in `init(content=...)` to omit `input`, `output`, `tools`, `retrieval` or
  `media` from the Impact destination. These categories are enabled by default, subject to native settings and
  signal controls. Customer destinations retain their own policies.

Use the [Python integration catalogue](https://docs.impact.ai/sdk/python/integrations) and
`runtime.status().integration_details` for exact operation and route limits. This quickstart uses synchronous
OpenAI Responses on the public route. The broader client operation sets, including background and resumed
streams and image and audio operations, remain unassessed.

## Troubleshooting and support

If the Trace is missing, check the service and runtime IDs, then inspect `runtime.status().cause`, `.action`,
integration activation, and local export counts. Direct OTLP checks the ingest key at export. After correcting
the endpoint or key for an active runtime, restart the process and run a new application operation. A
zero-record flush leaves capture unverified. Check the matching Trace even after successful local export.

For setup help, email `biz@impact.ai` with SDK and Python versions, the integration and operation, and the
local diagnosis code. Keep keys, prompt text and raw telemetry private.

[Python setup and lifecycle](https://docs.impact.ai/sdk/python/setup) ·
[Trace troubleshooting](https://docs.impact.ai/sdk/python/troubleshooting) ·
[Impact SDK setup plugin](https://docs.impact.ai/quickstart#plugin)

## Security reporting

Email `biz@impact.ai` with the subject **Impact SDK security report**. Include the affected package, version
and a contact address, and ask for a private channel to share the details. Keep credentials, customer data and
reproductions out of the initial message and public issue trackers.
