Metadata-Version: 2.4
Name: asymmetric-hone
Version: 0.1.0
Summary: Hone Python SDK — capture AI-agent conversations and MCP tool calls to Hone's observability platform.
Project-URL: Homepage, https://github.com/ankit-saxena/agent-evals/tree/main/sdks/python
Project-URL: Repository, https://github.com/ankit-saxena/agent-evals
Author: Ankit Saxena
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,hone,llm,mcp,observability,opentelemetry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

# Hone Python SDK

`hone` is the Python SDK for [Hone](https://hone.dev), an AI-agent
observability platform. Use it to capture agent conversations and MCP tool
calls and send them to Hone's ingestion edge.

## Install

```bash
uv add hone
# with MCP tool-call capture:
uv add "hone[mcp]"
```

## Configuration

The SDK reads its configuration from arguments or the environment:

| Setting  | Argument            | Environment      | Default                 |
| -------- | ------------------- | ---------------- | ----------------------- |
| API key  | `honeai.init(api_key)`| `HONE_API_KEY`   | — (required)            |
| Endpoint | `honeai.init(endpoint=)` | `HONE_ENDPOINT` | `https://api.hone.dev` |

API keys look like `sk_<hex>`. For local development, point the endpoint at
`http://localhost:8080`.

## Quick start

```python
import honeai

honeai.init("sk_...")  # or rely on HONE_API_KEY

# A single turn you want to time and enrich:
turn = honeai.begin(user_id="user-123", agent_name="support-bot", input="How do I reset my password?")
turn.set_property("channel", "web")
turn.set_properties({"tier": "pro"})
turn.end("Head to Settings > Security to reset it.")
```

`begin` starts a new conversation (a fresh `session_id`) and records the start
time. `end` posts a capture-session (once per new conversation) plus a
capture-event with an auto-computed `latency`.

## One-shot capture

```python
honeai.track(
    user_id="user-123",
    input="What's my balance?",
    output="Your balance is $42.",
    agent_name="finance-bot",
)
```

Group several turns into one conversation by passing a shared
`conversation_id`:

```python
convo = "9f8b..."  # any stable id
honeai.track(user_id="u1", input="hi", output="hello", agent_name="bot", conversation_id=convo)
honeai.track(user_id="u1", input="bye", output="see you", agent_name="bot", conversation_id=convo)
```

## User traits

Register traits that decorate the user's next session:

```python
honeai.identify("user-123", {"plan": "enterprise", "name": "Ada"})
honeai.begin(user_id="user-123", agent_name="bot", input="hi").end("hello")
# ^ the session's user_data carries plan + name
```

## MCP tool-call capture

Wrap a FastMCP server so every tool call is captured as a `TOOL` event:

```python
from mcp.server.fastmcp import FastMCP
import honeai.mcp

server = FastMCP("my-server")

@server.tool()
def add(a: int, b: int) -> int:
    return a + b

honeai.init("sk_...")
honeai.mcp.track(server)  # instruments the server in place
```

Pass `disable_input=True` and/or `disable_output=True` to omit tool arguments
or return values from the captured events. `mcp` is an optional dependency; if
it is not installed, `honeai.mcp.track` logs a warning and returns the server
unchanged.

## Error handling

Network and HTTP failures never raise into your hot path by default — they are
logged (via the `hone` logger) and dropped. For tests, construct a client with
`raise_on_error=True`:

```python
from honeai.client import Client
client = Client("sk_test", raise_on_error=True)
```

## Development

```bash
uv sync
uv run pytest
uv run ruff check
```
