introspection-sdk 0.4.0__tar.gz

introspection_sdk-0.4.0/.gitignore

@@ -0,0 +1,15 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+.env
+
+# Claude Code
+.claude/

introspection_sdk-0.4.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: introspection-sdk
+Version: 0.4.0
+Summary: Python SDK for Introspection — continuously improve your AI systems with production feedback and frontier practices
+Requires-Python: >=3.11
+Requires-Dist: openai>=2.30.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-http<1.40.0,>=1.39.0
+Requires-Dist: opentelemetry-sdk<1.40.0,>=1.39.0
+Provides-Extra: arize
+Requires-Dist: arize-phoenix>=8.0.0; extra == 'arize'
+Requires-Dist: openinference-instrumentation-openai>=0.1.0; extra == 'arize'
+Provides-Extra: braintrust
+Requires-Dist: braintrust[otel]>=0.1.0; extra == 'braintrust'
+Provides-Extra: dev
+Requires-Dist: pre-commit>=3.5.0; extra == 'dev'
+Requires-Dist: ruff==0.14.14; extra == 'dev'
+Requires-Dist: ty>=0.0.7; extra == 'dev'
+Provides-Extra: langfuse
+Requires-Dist: langfuse>=3.0.0; extra == 'langfuse'
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.12.2; extra == 'openai-agents'
+Provides-Extra: test
+Requires-Dist: anthropic>=0.85.0; extra == 'test'
+Requires-Dist: claude-agent-sdk<=0.1.7,>=0.1.0; extra == 'test'
+Requires-Dist: dirty-equals>=0.11.0; extra == 'test'
+Requires-Dist: inline-snapshot>=0.31.0; extra == 'test'
+Requires-Dist: openai-agents>=0.12.2; extra == 'test'
+Requires-Dist: posthog>=7.9.0; extra == 'test'
+Requires-Dist: pydantic-ai>=1.68.0; extra == 'test'
+Requires-Dist: pydantic>=2.12.0; extra == 'test'
+Requires-Dist: pytest-asyncio>=1.3.0; extra == 'test'
+Requires-Dist: pytest-dotenv>=0.5.2; extra == 'test'
+Requires-Dist: pytest-mock>=3.15.0; extra == 'test'
+Requires-Dist: pytest-recording>=0.13.4; extra == 'test'
+Requires-Dist: pytest>=9.0.0; extra == 'test'
+Requires-Dist: responses>=0.25.8; extra == 'test'
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <a href="https://introspection.dev">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset=".github/images/logo-dark.svg">
+      <source media="(prefers-color-scheme: light)" srcset=".github/images/logo-light.svg">
+      <img alt="Introspection" src=".github/images/logo-light.svg" width="30%">
+    </picture>
+  </a>
+</div>
+
+<h4 align="center">Build frontier AI systems that self-improve.</h4>
+
+<div align="center">
+  <a href="https://introspection.dev"><img src="https://img.shields.io/badge/website-introspection.dev-blue" alt="Website"></a>
+  <a href="https://pypi.org/project/introspection-sdk/"><img src="https://img.shields.io/pypi/v/introspection-sdk?label=%20" alt="PyPI version"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
+  <a href="https://x.com/IntrospectionAI"><img src="https://img.shields.io/twitter/follow/IntrospectionAI" alt="Follow on X"></a>
+</div>
+
+<br>
+
+[Introspection](https://introspection.dev) continuously improves your AI systems with production feedback and frontier practices. This is the Python SDK.
+
+## Install
+
+```shell
+uv add introspection-sdk
+# or
+pip install introspection-sdk
+```
+
+### Optional Extras
+
+```shell
+pip install 'introspection-sdk[openai-agents]'  # OpenAI Agents SDK
+pip install 'introspection-sdk[langfuse]'        # Langfuse
+pip install 'introspection-sdk[braintrust]'      # Braintrust
+pip install 'introspection-sdk[arize]'           # Arize Phoenix + OpenInference
+```
+
+## Environment Variables
+
+```shell
+export INTROSPECTION_TOKEN="intro_xxx"
+export INTROSPECTION_BASE_URL="https://otel.introspection.dev"  # optional
+```
+
+## Quickstart
+
+### OpenTelemetry Span Processor
+
+```python
+from introspection_sdk import IntrospectionSpanProcessor
+import logfire
+
+logfire.configure(
+    additional_span_processors=[IntrospectionSpanProcessor()],
+)
+
+logfire.instrument_openai()
+```
+
+### OpenAI Agents SDK
+
+```python
+from agents import Agent, Runner, set_trace_processors, tool
+from introspection_sdk import IntrospectionTracingProcessor
+
+set_trace_processors([IntrospectionTracingProcessor()])
+
+@tool
+def get_weather(city: str) -> str:
+    """Get the current weather for a city."""
+    return f"Sunny, 72F in {city}"
+
+agent = Agent(name="Weather Bot", tools=[get_weather])
+result = await Runner.run(agent, "What's the weather in Tokyo?")
+```
+
+#### Reasoning Model Support
+
+Some models produce reasoning items that the OpenAI Conversations API rejects. `IntrospectionConversationsSession` strips those items transparently:
+
+```python
+from introspection_sdk import IntrospectionConversationsSession
+
+session = IntrospectionConversationsSession(conversation_id="conv_123")
+result = await Runner.run(agent, "Hello!", session=session)
+```
+
+### Claude Agent SDK
+
+```python
+from introspection_sdk import ClaudeTracingProcessor
+
+processor = ClaudeTracingProcessor()
+processor.configure()
+
+# All ClaudeSDKClient instances are now automatically traced
+```
+
+### LangChain / LangGraph
+
+```python
+from introspection_sdk import IntrospectionCallbackHandler
+
+handler = IntrospectionCallbackHandler(service_name="my-app")
+response = model.invoke("Hello!", config={"callbacks": [handler]})
+```
+
+### Anthropic SDK
+
+```python
+from introspection_sdk.anthropic import AnthropicInstrumentor
+
+instrumentor = AnthropicInstrumentor()
+instrumentor.instrument(tracer_provider=provider)
+
+# All client.messages.create calls are traced, including thinking blocks
+```
+
+### OpenInference (Arize, Langfuse, Braintrust)
+
+```python
+from opentelemetry.sdk.trace import TracerProvider
+from openinference.instrumentation.openai import OpenAIInstrumentor
+from introspection_sdk import IntrospectionSpanProcessor
+
+provider = TracerProvider()
+provider.add_span_processor(IntrospectionSpanProcessor())
+OpenAIInstrumentor().instrument(tracer_provider=provider)
+```
+
+> See [examples/](./examples/) for complete integration patterns including dual-export with Arize, Langfuse, Braintrust, and LangSmith.
+
+## Client API
+
+```python
+from introspection_sdk import IntrospectionClient
+
+client = IntrospectionClient()
+
+with client.set_user_id("user_123"):
+    with client.set_conversation("conv_456", previous_response_id="msg_123"):
+        client.feedback("thumbs_up", comments="Great response!")
+
+client.shutdown()
+```
+
+### Methods
+
+| Method | Description |
+| ------ | ----------- |
+| `feedback(type, **kwargs)` | Track feedback on AI responses |
+| `identify(user_id, traits=)` | Associate a user with traits (context manager) |
+| `track(event, properties=)` | Track any user action |
+| `flush(timeout_ms=30000)` | Flush pending events |
+| `shutdown()` | Shutdown and flush |
+
+### Context Managers
+
+| Method | Description |
+| ------ | ----------- |
+| `set_user_id(id)` | Set user context |
+| `set_conversation(id?, response_id?)` | Set conversation context |
+| `set_agent(name, id?)` | Set agent context |
+| `set_anonymous_id(id)` | Set anonymous ID |
+| `set_baggage(**values)` | Set arbitrary baggage values |
+
+## Documentation
+
+Full documentation is available at [docs.introspection.dev](https://docs.introspection.dev).

introspection_sdk-0.4.0/README.md

@@ -0,0 +1,172 @@
+<div align="center">
+  <a href="https://introspection.dev">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset=".github/images/logo-dark.svg">
+      <source media="(prefers-color-scheme: light)" srcset=".github/images/logo-light.svg">
+      <img alt="Introspection" src=".github/images/logo-light.svg" width="30%">
+    </picture>
+  </a>
+</div>
+
+<h4 align="center">Build frontier AI systems that self-improve.</h4>
+
+<div align="center">
+  <a href="https://introspection.dev"><img src="https://img.shields.io/badge/website-introspection.dev-blue" alt="Website"></a>
+  <a href="https://pypi.org/project/introspection-sdk/"><img src="https://img.shields.io/pypi/v/introspection-sdk?label=%20" alt="PyPI version"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
+  <a href="https://x.com/IntrospectionAI"><img src="https://img.shields.io/twitter/follow/IntrospectionAI" alt="Follow on X"></a>
+</div>
+
+<br>
+
+[Introspection](https://introspection.dev) continuously improves your AI systems with production feedback and frontier practices. This is the Python SDK.
+
+## Install
+
+```shell
+uv add introspection-sdk
+# or
+pip install introspection-sdk
+```
+
+### Optional Extras
+
+```shell
+pip install 'introspection-sdk[openai-agents]'  # OpenAI Agents SDK
+pip install 'introspection-sdk[langfuse]'        # Langfuse
+pip install 'introspection-sdk[braintrust]'      # Braintrust
+pip install 'introspection-sdk[arize]'           # Arize Phoenix + OpenInference
+```
+
+## Environment Variables
+
+```shell
+export INTROSPECTION_TOKEN="intro_xxx"
+export INTROSPECTION_BASE_URL="https://otel.introspection.dev"  # optional
+```
+
+## Quickstart
+
+### OpenTelemetry Span Processor
+
+```python
+from introspection_sdk import IntrospectionSpanProcessor
+import logfire
+
+logfire.configure(
+    additional_span_processors=[IntrospectionSpanProcessor()],
+)
+
+logfire.instrument_openai()
+```
+
+### OpenAI Agents SDK
+
+```python
+from agents import Agent, Runner, set_trace_processors, tool
+from introspection_sdk import IntrospectionTracingProcessor
+
+set_trace_processors([IntrospectionTracingProcessor()])
+
+@tool
+def get_weather(city: str) -> str:
+    """Get the current weather for a city."""
+    return f"Sunny, 72F in {city}"
+
+agent = Agent(name="Weather Bot", tools=[get_weather])
+result = await Runner.run(agent, "What's the weather in Tokyo?")
+```
+
+#### Reasoning Model Support
+
+Some models produce reasoning items that the OpenAI Conversations API rejects. `IntrospectionConversationsSession` strips those items transparently:
+
+```python
+from introspection_sdk import IntrospectionConversationsSession
+
+session = IntrospectionConversationsSession(conversation_id="conv_123")
+result = await Runner.run(agent, "Hello!", session=session)
+```
+
+### Claude Agent SDK
+
+```python
+from introspection_sdk import ClaudeTracingProcessor
+
+processor = ClaudeTracingProcessor()
+processor.configure()
+
+# All ClaudeSDKClient instances are now automatically traced
+```
+
+### LangChain / LangGraph
+
+```python
+from introspection_sdk import IntrospectionCallbackHandler
+
+handler = IntrospectionCallbackHandler(service_name="my-app")
+response = model.invoke("Hello!", config={"callbacks": [handler]})
+```
+
+### Anthropic SDK
+
+```python
+from introspection_sdk.anthropic import AnthropicInstrumentor
+
+instrumentor = AnthropicInstrumentor()
+instrumentor.instrument(tracer_provider=provider)
+
+# All client.messages.create calls are traced, including thinking blocks
+```
+
+### OpenInference (Arize, Langfuse, Braintrust)
+
+```python
+from opentelemetry.sdk.trace import TracerProvider
+from openinference.instrumentation.openai import OpenAIInstrumentor
+from introspection_sdk import IntrospectionSpanProcessor
+
+provider = TracerProvider()
+provider.add_span_processor(IntrospectionSpanProcessor())
+OpenAIInstrumentor().instrument(tracer_provider=provider)
+```
+
+> See [examples/](./examples/) for complete integration patterns including dual-export with Arize, Langfuse, Braintrust, and LangSmith.
+
+## Client API
+
+```python
+from introspection_sdk import IntrospectionClient
+
+client = IntrospectionClient()
+
+with client.set_user_id("user_123"):
+    with client.set_conversation("conv_456", previous_response_id="msg_123"):
+        client.feedback("thumbs_up", comments="Great response!")
+
+client.shutdown()
+```
+
+### Methods
+
+| Method | Description |
+| ------ | ----------- |
+| `feedback(type, **kwargs)` | Track feedback on AI responses |
+| `identify(user_id, traits=)` | Associate a user with traits (context manager) |
+| `track(event, properties=)` | Track any user action |
+| `flush(timeout_ms=30000)` | Flush pending events |
+| `shutdown()` | Shutdown and flush |
+
+### Context Managers
+
+| Method | Description |
+| ------ | ----------- |
+| `set_user_id(id)` | Set user context |
+| `set_conversation(id?, response_id?)` | Set conversation context |
+| `set_agent(name, id?)` | Set agent context |
+| `set_anonymous_id(id)` | Set anonymous ID |
+| `set_baggage(**values)` | Set arbitrary baggage values |
+
+## Documentation
+
+Full documentation is available at [docs.introspection.dev](https://docs.introspection.dev).

introspection_sdk-0.4.0/introspection_sdk/__init__.py

@@ -0,0 +1,52 @@
+"""Introspection Python SDK."""
+
+from introspection_sdk.anthropic import (
+    REDACTED_THINKING_CONTENT,
+    AnthropicInstrumentor,
+)
+from introspection_sdk.client import IntrospectionClient
+from introspection_sdk.config import AdvancedOptions
+from introspection_sdk.processors.claude_tracing_processor import (
+    ClaudeTracingProcessor,
+)
+from introspection_sdk.processors.langchain_callback_handler import (
+    IntrospectionCallbackHandler,
+)
+from introspection_sdk.processors.span_processor import (
+    IntrospectionSpanProcessor,
+)
+from introspection_sdk.processors.tracing_processor import (
+    IntrospectionTracingProcessor,
+)
+from introspection_sdk.types import (
+    Attr,
+    Baggage,
+    EventName,
+    FeedbackProperties,
+)
+
+__all__ = [
+    "AdvancedOptions",
+    "AnthropicInstrumentor",
+    "REDACTED_THINKING_CONTENT",
+    "Attr",
+    "Baggage",
+    "ClaudeTracingProcessor",
+    "IntrospectionCallbackHandler",
+    "EventName",
+    "FeedbackProperties",
+    "IntrospectionClient",
+    "IntrospectionConversationsSession",
+    "IntrospectionSpanProcessor",
+    "IntrospectionTracingProcessor",
+]
+
+
+def __getattr__(name: str) -> object:
+    if name == "IntrospectionConversationsSession":
+        from introspection_sdk.sessions import (
+            IntrospectionConversationsSession,
+        )
+
+        return IntrospectionConversationsSession
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")