Metadata-Version: 2.4
Name: kivviq
Version: 0.1.0
Summary: Execution observability for AI agents
Author: David Adebiyi Adewale
Author-email: adebiyidavid595@gmail.com
License-Expression: MIT
Keywords: ai,agents,observability,tracing,openai,langchain,llm,debugging
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: openai>=1.0.0; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: keywords
Dynamic: license-file
Dynamic: license-expression
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Kivviq SDK

Python SDK for Kivviq — execution observability for AI agents.

Kivviq helps developers see what happens inside their AI agents by capturing and tracing agent executions.

## Installation

Install the SDK:

```bash
pip install kivviq
```

For OpenAI auto-instrumentation:

```bash
pip install "kivviq[openai]"
```

## Quick Start

```python
from kivviq import Kivviq

# Initialize Kivviq
kivviq = Kivviq(api_key="YOUR_KIVVIQ_API_KEY")

# Trace your agent
@kivviq.trace
def my_agent():
    # Your agent logic goes here
    return "Hello from my AI agent!"

# Execute your agent
result = my_agent()

print(result)

# Close the SDK connection
kivviq.close()
```

Replace `YOUR_KIVVIQ_API_KEY` with your actual API key.

## Configuration

Kivviq supports the following configuration options:

| Parameter | Description | Default |
|---|---|---|
| `api_key` | Your Kivviq API key | `KIVVIQ_API_KEY` environment variable |
| `backend_url` | Kivviq backend URL | `https://kivviq.ethiodeploy.app` |

You can also configure these using environment variables:

```env
KIVVIQ_API_KEY=your_api_key
KIVVIQ_BACKEND_URL=https://kivviq.ethiodeploy.app
```

The SDK automatically loads environment variables from a `.env` file when available.

## What Gets Captured

Kivviq captures execution information including:

- Run start and end times
- Run duration
- Execution status (success or error)
- Error messages and types
- OpenAI calls, when OpenAI instrumentation is enabled
- Events logged manually through the SDK

## Event Types

Kivviq supports the following event types:

```python
from kivviq.event import EventType

EventType.LLM_CALL
EventType.TOOL_CALL
EventType.USER_INPUT
EventType.OUTPUT
EventType.ERROR
```

## Reliability

- Your agent continues running if the Kivviq backend is unreachable.
- Exceptions from your agent are re-raised rather than swallowed.
- Selected GET and PATCH requests retry transient failures once.
- POST requests are not automatically retried.
- Instrumentation hooks are cleaned up after execution.

## Full Documentation

See the [SDK documentation](../docs/SDK.md) for the complete reference.
