# Python

> Track any AI interaction with begin() / end()

## Install

<CodeGroup>
  ```bash pip theme={null}
  pip install voxmith
  ```

  ```bash uv theme={null}
  uv add voxmith
  ```
</CodeGroup>

## Integrate

```python theme={null}
import voxmith

voxmith.init("your-org-id")
```

Get your org ID from [app.voxmith.com](https://app.voxmith.com).

## Track interactions

```python theme={null}
interaction = voxmith.begin(user_id="u-123", agent_name="my-agent", input="...")
# ... your AI call ...
interaction.end(output="...")
```

Latency is auto-calculated. For errors:

```python theme={null}
interaction.end(output="Error: timeout", success=False)
```

For simple fire-and-forget cases:

```python theme={null}
voxmith.track(user_id="u-123", input="...", output="...", agent_name="my-agent")
```

## Group into conversations

```python theme={null}
import uuid

conversation_id = str(uuid.uuid4())

voxmith.track(user_id="u-123", input="Hello", output="Hi!", conversation_id=conversation_id)
voxmith.track(user_id="u-123", input="Follow-up", output="Sure!", conversation_id=conversation_id)
```

## Identify users

```python theme={null}
voxmith.identify("u-123", {"plan": "pro", "role": "admin"})
```

## Custom properties

```python theme={null}
interaction = voxmith.begin(user_id="u-123", agent_name="my-agent", input="...")

# Set one at a time
interaction.set_property("model", "gpt-4")

# Or set many at once
interaction.set_properties({"tokens": 150, "cost": 0.045})

interaction.end(output="...")
```

## Configuration

```python theme={null}
voxmith.init("your-org-id", endpoint="https://api.voxmith.com", debug=True)
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `org_id` | `str` | — | Your org ID |
| `endpoint` | `str` | `https://api.voxmith.com` | API endpoint |
| `debug` | `bool` | `False` | Enable debug logging |

## Cleanup

```python theme={null}
voxmith.shutdown()  # flushes and cleans up
```

## What appears in Voxmith

* **Conversations** grouped by `conversation_id`.
* **User-level analytics** grouped by `user_id`.
* **Events** for every tracked interaction.
* Unsuccessful interactions remain visible in **Events** with `success=False`.

## Verify

Run one `begin()` / `end()` interaction, then open [app.voxmith.com](https://app.voxmith.com). Check **Events** first, then **Conversations**.

## Troubleshooting

* Confirm `voxmith.init("your-org-id")` runs before tracking.
* Call `voxmith.flush()` or `voxmith.shutdown()` before short-lived scripts exit.
* Confirm the endpoint is `https://api.voxmith.com` unless you intentionally use another endpoint.

## Next steps

* [Conversations](/using-conversations): review how Python interactions are grouped.
* [Events](/using-events): inspect the exact records the SDK sent.
* [Intents](/using-intents): organize production conversations by what users wanted.