Metadata-Version: 2.4
Name: kelet
Version: 1.9.0
Summary: Kelet SDK - OpenTelemetry integration for AI observability
Project-URL: Homepage, https://kelet.ai
Project-URL: Documentation, https://kelet.ai/docs/sdk/python/
Project-URL: Repository, https://github.com/Kelet-ai/python-sdk
Project-URL: Issues, https://github.com/Kelet-ai/python-sdk/issues
Project-URL: Changelog, https://github.com/Kelet-ai/python-sdk/blob/main/CHANGELOG.md
License: # MIT License
        
        Copyright (c) 2025 Kelet AI
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE.md
Keywords: agents,ai,llm,observability,opentelemetry,otel,rca,tracing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25.0
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20.0
Requires-Dist: opentelemetry-instrumentation>=0.41b0
Requires-Dist: opentelemetry-sdk>=1.20.0
Requires-Dist: pydantic>=2.10.6
Requires-Dist: wrapt>=1.14.0
Provides-Extra: all
Requires-Dist: claude-agent-sdk>=0.1.45; extra == 'all'
Requires-Dist: openinference-instrumentation-anthropic; extra == 'all'
Requires-Dist: openinference-instrumentation-google-adk; extra == 'all'
Requires-Dist: openinference-instrumentation-langchain; extra == 'all'
Requires-Dist: openinference-instrumentation-openai; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: openinference-instrumentation-anthropic; extra == 'anthropic'
Provides-Extra: claude-agent-sdk
Requires-Dist: claude-agent-sdk>=0.1.45; extra == 'claude-agent-sdk'
Provides-Extra: google-adk
Requires-Dist: openinference-instrumentation-google-adk; extra == 'google-adk'
Provides-Extra: langchain
Requires-Dist: openinference-instrumentation-langchain; extra == 'langchain'
Provides-Extra: openai
Requires-Dist: openinference-instrumentation-openai; extra == 'openai'
Provides-Extra: temporal
Requires-Dist: temporalio>=1.7.0; extra == 'temporal'
Description-Content-Type: text/markdown

<div align="center">
  <img src="https://raw.githubusercontent.com/Kelet-ai/python-sdk/main/.github/logo.png" alt="Kelet" width="400">

  <h1>Automated Root Cause Analysis for AI Agents</h1>

  <p>
    <a href="https://pypi.org/project/kelet/"><img src="https://img.shields.io/pypi/v/kelet.svg" alt="PyPI version"></a>
    <a href="https://pypi.org/project/kelet/"><img src="https://img.shields.io/pypi/pyversions/kelet.svg" alt="Python versions"></a>
    <a href="https://github.com/Kelet-ai/python-sdk/blob/main/LICENSE.md"><img src="https://img.shields.io/pypi/l/kelet.svg" alt="License"></a>
    <a href="https://github.com/Kelet-ai/python-sdk/actions/workflows/release.yml"><img src="https://github.com/Kelet-ai/python-sdk/actions/workflows/release.yml/badge.svg" alt="Release"></a>
    <a href="https://pepy.tech/project/kelet"><img src="https://static.pepy.tech/badge/kelet/month" alt="Downloads"></a>
  </p>

  <p><strong>Agent failures take weeks to diagnose manually. Kelet runs 24/7 deep diagnosis and suggests targeted fixes.</strong></p>

  <img src="https://raw.githubusercontent.com/Kelet-ai/python-sdk/main/.github/illustration.png" alt="Kelet workflow" width="700">
</div>

Kelet analyzes production failures 24/7. Each trace takes 15-25 minutes to debug manually—finding patterns requires analyzing hundreds of traces. That's **weeks of engineering time** per root cause. Kelet does this automatically, surfacing issues like data imbalance, concept drift, prompt poisoning, and model laziness hidden in production noise.

---

## What Kelet Does

Kelet runs 24/7 analyzing every production trace:

1. **Captures** every interaction, user signal, and failure context automatically
2. **Analyzes** hundreds of failures in parallel to detect repeatable patterns
3. **Identifies** root causes (data issues, prompt problems, model behavior)
4. **Delivers** targeted fixes, not just dashboards

Unlike observability tools that show you data, Kelet analyzes it and tells you what to fix.

**Not magic**: Kelet is in alpha. Won't catch everything yet, needs your guidance sometimes. But it's already doing analysis that would take weeks manually.

Three lines of code to start.

## Installation

**Using uv (recommended):**
```bash
uv add kelet
```

**Or using pip:**
```bash
pip install kelet
```

Set your API key:
```bash
export KELET_API_KEY=your_api_key
export KELET_PROJECT=production  # Required — create a project at console.kelet.ai
```

Or configure in code:
```python
kelet.configure(
    api_key="your_api_key",
    project="production"  # Groups traces by project/environment
)
```

## Quick Start

```python
import kelet

kelet.configure()  # Auto-instruments pydantic-ai, Anthropic, OpenAI, LangChain/LangGraph, and LiteLLM; captures Google ADK OTEL spans

# Your agent code works as-is - instrumentation is automatic
result = await agent.run("Book a flight to NYC")

# Optionally capture user feedback
await kelet.signal(
    kind=kelet.SignalKind.FEEDBACK,
    source=kelet.SignalSource.HUMAN,
    score=0.0,  # User unhappy? Kelet analyzes why.
    # Best-effort by default: request failures warn and return.
    # Pass raise_on_failure=True if you want to surface them.
)
```

**That's it.** Kelet now runs 24/7 analyzing every trace, clustering failure patterns, and identifying root causes—work that would take weeks manually.

### Manual Session Grouping (Optional)

If your framework doesn't support session tracking, or you want custom session IDs:

```python
with kelet.agentic_session(session_id="user-123-request-456"):
    result = await agent.run("Book a flight to NYC")
```

Also works as a decorator:

```python
@kelet.agentic_session(session_id="user-123-request-456")
async def handle_request():
    result = await agent.run("Book a flight to NYC")
```

But most users don't need this—instrumentation captures sessions automatically from pydantic-ai and other supported frameworks.

### Using with Temporal

If your agents run on [Temporal](https://temporal.io), register `KeletPlugin` once on the client — workers inherit automatically:

```python
from kelet.temporal import KeletPlugin
from temporalio.client import Client

client = await Client.connect("localhost:7233", plugins=[KeletPlugin()])
```

Session context flows through Temporal headers across `start_workflow → workflow → activity`, so `kelet.signal()` from anywhere auto-resolves. Install: `pip install "kelet[temporal]"`.

📖 Full setup, options, plugin ordering: **[docs.kelet.ai/integrations/temporal](https://docs.kelet.ai/docs/integrations/temporal/)**

### Using Different Projects Under the Same Application

If your application hosts multiple independent root agent systems that belong to different Kelet projects (for example `customer_support_prod` and `billing_prod`), you can override the global project on a per-session basis using the `project` parameter on `agentic_session`:

```python
import kelet

kelet.configure(api_key="your_api_key", project="customer_support")

# Spans inside this session are attributed to "customer_support_prod"
async with kelet.agentic_session(session_id="sess-123", user_id="user-1", project="customer_support_prod"):
    result = await customer_support_agent.run("How do I return my order?")

# Spans inside this session are attributed to "billing_prod"
async with kelet.agentic_session(session_id="sess-456", user_id="user-2", project="billing_prod"):
    result = await billing_agent.run("Show my invoice for last month")
```

The `project` override is automatically propagated via W3C Baggage to any downstream services that use the Kelet SDK. Those services will stamp the correct `kelet.project`, `session_id`, and `user_id` on their spans without needing to call `agentic_session` themselves — the baggage carrier handles it transparently across process boundaries.

### Agent Spans (Optional)

Use `kelet.agent()` to create an explicit OTEL span wrapping a named agent invocation. All LLM calls inside become children of that span, making your trace tree readable.

```python
async with kelet.agentic_session(session_id="sess-123", user_id="user-1"):
    async with kelet.agent(name="support-bot"):
        result = await anthropic_client.messages.create(...)
```

Also works as a decorator:

```python
@kelet.agentic_session(session_id="sess-123")
@kelet.agent(name="support-bot")
async def handle(request):
    return await anthropic_client.messages.create(...)
```

Multiple agents in one session are supported — each gets its own labeled span:

```python
async with kelet.agentic_session(session_id="sess-123"):
    async with kelet.agent(name="classifier"):
        label = await openai_client.chat.completions.create(...)
    async with kelet.agent(name="responder"):
        reply = await anthropic_client.messages.create(...)
```

### Auto-Instrumentation

`kelet.configure()` automatically detects supported libraries and configures available integrations — no extra code needed. This works whether Kelet creates the global TracerProvider or attaches to an existing one.

| Library | Install extra | How it works |
|---------|---------------|--------------|
| **Pydantic AI** | _(included)_ | Instrumented automatically |
| **Anthropic SDK** | `pip install kelet[anthropic]` | OpenInference instrumentation |
| **OpenAI SDK** | `pip install kelet[openai]` | OpenInference instrumentation |
| **LangChain / LangGraph** | `pip install kelet[langchain]` | OpenInference instrumentation |
| **LiteLLM** | `pip install litellm` | Registers LiteLLM's native OTEL callback automatically and prefers per-request spans |
| **Google ADK** | `pip install google-adk kelet[google-adk]` | Prefers OpenInference instrumentation; falls back to native ADK OTEL spans |
| **Claude Agent SDK** | `pip install claude-agent-sdk` | Captures reasoning text Claude Code redacts from its native OTLP — see [docs/claude-agent-sdk.md](https://github.com/Kelet-ai/python-sdk/blob/main/docs/claude-agent-sdk.md) |

Install all OpenInference extras at once: `pip install kelet[all]`

If a library isn't installed, Kelet silently skips it — no errors.

> **Note on bare LiteLLM:** Due to a LiteLLM limitation, session and agent context are **not propagated natively** into LiteLLM spans. If you call LiteLLM directly (not through another instrumented framework), wrap your calls with [`kelet.agentic_session(...)`](#manual-session-grouping-optional) and/or [`kelet.agent(...)`](#agent-spans-optional) to group them. When LiteLLM is used inside another supported framework — for example Google ADK, which commonly uses LiteLLM under the hood — the parent span provides session/agent context and no extra wrapping is needed.

### Easy Feedback UI for React

Building a React frontend? Use the [Kelet Feedback UI](https://github.com/kelet-ai/feedback-ui) component for instant implicit and explicit feedback collection.
See the [live demo](https://feedback-ui.kelet.ai/) and [documentation](https://github.com/kelet-ai/feedback-ui) for full integration guide.

### Works with Your Observability Stack

Already using Logfire or another OTEL provider? Kelet integrates seamlessly:

```python
import logfire
import kelet

logfire.configure()
logfire.instrument_pydantic_ai()

kelet.configure()  # Adds Kelet's processor and auto-instrumentation to your existing OTEL setup
```

---

## What Gets Captured

Kelet is built on [OpenTelemetry](https://opentelemetry.io/) and supports multiple semantic conventions for AI/LLM observability:

| Semantic Convention | Supported Frameworks |
|---------------------|----------------------|
| [GenAI Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) | Pydantic AI, LiteLLM, Google ADK, Langfuse SDK |
| Vercel AI SDK | Next.js, Vercel AI |
| OpenInference | Arize Phoenix |
| OpenLLMetry / Traceloop | LangChain, LangGraph, LlamaIndex, OpenAI SDK, Anthropic SDK |

Any framework that exports OpenTelemetry traces using the GenAI semantic conventions will work automatically.

**Captured data includes:**

- **LLM calls**: Model, provider, tokens, latency, errors
- **Agent sessions**: Multi-step interactions grouped by user session
- **Custom context**: User IDs, session metadata, business-specific attributes

All captured automatically when you instrument with `kelet.configure()`.

---

## Configuration

Set via environment variables:

```bash
export KELET_API_KEY=your_api_key    # Required
export KELET_PROJECT=production      # Required — create a project at console.kelet.ai
export KELET_API_URL=https://...     # Optional, defaults to api.kelet.ai
```

Or pass directly to `configure()`:

```python
kelet.configure(
    api_key="your_api_key",
    project="production",
    auto_instrument=True  # Auto-instruments pydantic-ai, Anthropic, OpenAI, LangChain/LangGraph, and LiteLLM; captures Google ADK OTEL spans
)
```

## API Reference

**Core Functions:**

```python
# Initialize SDK
kelet.configure(api_key=None, project=None, auto_instrument=True, span_processor=None)

# Group operations by session for failure correlation
# Works as context manager (sync + async) and decorator
with kelet.agentic_session(session_id="session-id", user_id="user-id", project="project-override", env="production"):  # user_id optional; project overrides global config
    result = await agent.run(...)

# Wrap a named agent invocation in an explicit OTEL span
# Works as context manager (sync + async) and decorator
async with kelet.agent(name="my-agent"):
    result = await llm_client.messages.create(...)

# Capture user feedback
await kelet.signal(
    kind=kelet.SignalKind.FEEDBACK,       # feedback | edit | event | metric | arbitrary
    source=kelet.SignalSource.HUMAN,      # human | label | synthetic
    score=0.0,                            # 0.0 to 1.0
    # raise_on_failure=True,             # Optional: re-raise request failures
)

# Access current context
session_id = kelet.get_session_id()
trace_id = kelet.get_trace_id()
user_id = kelet.get_user_id()
agent_name = kelet.get_agent_name()      # Set by kelet.agent()
metadata = kelet.get_metadata_kwargs()   # Set by agentic_session(**kwargs)

# Manual shutdown (automatic on exit)
kelet.shutdown()
```

---

## Production-Ready

The SDK never disrupts your application:

- **Async**: Telemetry exports in background, zero blocking
- **Fail-safe**: Telemetry export and `signal()` delivery are best-effort by default
- **Visible**: Delivery failures warn in logs; pass `raise_on_failure=True` to `signal()` to surface them
- **Safe on missing credentials**: If `KELET_API_KEY` or `KELET_PROJECT` can't be resolved, `configure()` logs a single warning and installs a no-op — `signal()` and `agentic_session()` become silent passthroughs. Pass `strict=True` to `configure()` to fail-fast on CI / staging.
- **Graceful**: If Kelet is down, your agent keeps running
- **Auto-flush**: Spans exported automatically on process exit

---

## Alpha Status

Kelet is in alpha. What this means:

- **It works**: Already analyzing thousands of production traces for early users
- **Not perfect**: Won't catch every failure pattern yet, sometimes needs guidance
- **Improving fast**: The AI learns from more production data every day
- **We need feedback**: Help us make it better—tell us what it catches and what it misses

Even in alpha, Kelet does analysis that would take your team weeks to do manually.

**The alternative?** Manually analyzing 15-25 minutes per trace, across hundreds of failures, trying to spot patterns by hand. Most teams just don't do it—and ship broken agents.

---

## Learn More

- **Website**: [kelet.ai](https://kelet.ai)
- **Early Access**: We're onboarding teams with production AI agents
- **Support**: [GitHub Issues](https://github.com/Kelet-ai/python-sdk/issues)

Built for teams shipping mission-critical AI agents.

---

## License

MIT License — see [LICENSE.md](LICENSE.md) for details.
