> ## Documentation Index
> Fetch the complete documentation index at: https://playbook.smedleygroup.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDKs

> The internal Python SDKs for vivenu and Sage Intacct: what they cover, how to install them and where to start.

Smedley Group maintains two internal Python SDKs. Use them instead of hand-written HTTP or XML calls when a back-office service talks to vivenu or Sage Intacct.

> [!NOTE]
>
> These pages were written in October 2026, when the latest releases were sg-vivenu-sdk v0.8.0 and sg-intacct-xml-sdk v0.5.0. Changes made on `main` since then are listed under **Unreleased** in each changelog until the next release.

## Overview

| SDK | Version | Description |
| - | - | - |
| `sg-vivenu-sdk` | v0.8.0 | vivenu core, seating, pricing, memberships, scans and apps APIs. Typed events, ticket types, tickets, customers, transactions, webhooks and an offline mock client |
| `sg-intacct-xml-sdk` | v0.5.0 | Sage Intacct XML Web Services. Sessions, queries, a dimension registry, journal and invoice builders, safe write recovery and a fake gateway for tests |

Both support Python 3.11 to 3.14, ship sync and async clients, and follow the same [SDK Conventions](/software/developer/sdks/conventions). Code that uses both in one flow reads the same way.

## Repositories

| Repository | Description |
| - | - |
| [sg-vivenu-sdk](https://github.com/Smedley-Group-Advanced-Technology/sg-vivenu-sdk) | vivenu SDK, generated from the vendor specifications plus hand-written resources |
| [sg-intacct-xml-sdk](https://github.com/Smedley-Group-Advanced-Technology/sg-intacct-xml-sdk) | Sage Intacct XML Web Services SDK |

## Install From a Release Tag

The repositories are private and the SDKs are not published to PyPI. Install a tagged release from GitHub. Your machine or CI runner needs read access to the repository.

```toml pyproject.toml theme={null}
[project]
dependencies = ["sg-vivenu-sdk", "sg-intacct-xml-sdk"]

[tool.uv.sources]
sg-vivenu-sdk = { git = "https://github.com/Smedley-Group-Advanced-Technology/sg-vivenu-sdk", tag = "v0.8.0" }
sg-intacct-xml-sdk = { git = "https://github.com/Smedley-Group-Advanced-Technology/sg-intacct-xml-sdk", tag = "v0.5.0" }
```

Or add one directly:

```bash theme={null}
uv add "sg-vivenu-sdk @ git+https://github.com/Smedley-Group-Advanced-Technology/sg-vivenu-sdk@v0.8.0"
```

> [!WARNING]
>
> Always pin a tag. Never depend on `main` or a local copy of the repository. Each release is listed on the repository's **Releases** page with its changelog.

## Key Files

Each repository has the same entry points.

| File | Role |
| - | - |
| `README.md` | Quickstart, install and the public API |
| `docs/recipes.md` | The FKL Control workflows: event days with ticket types, GROUP events, per-hub clients and webhooks, the Intacct dimension registry, and revenue recognition journals per entity |
| `docs/agents.md` | The integration guide for coding agents and developers, including the conventions contract |
| `CHANGELOG.md` | What changed in each release |

## Several Hubs and Entities

Each hub is its own vivenu seller with its own API key and HMAC secret. Create one vivenu client per hub. Clients can share one `httpx.Client`, because credentials are applied per request.

For Intacct, create one client per entity with `client.for_entity(location_id)`, and bind writes to the entity with `prepare_write(calls, location_id=...)`.

> [!NOTE]
>
> Pass the **raw** HMAC secret to the vivenu webhook helpers, the same value the receiving platform stores. Do not pass the base64 value pasted into the vivenu dashboard.

## Related Documentation

| Page | Relevance |
| - | - |
| [SDK Conventions](/software/developer/sdks/conventions) | The shared rules both SDKs follow |
| [Configuring the New Hub Region in GKL API](/software/third-party/vivenu/hub-deployment/development/configure-new-hub-region) | Where each hub's API key and HMAC secret come from |
| [Configuring the Webhooks](/software/third-party/vivenu/hub-deployment/development/configure-webhooks) | How the vivenu webhooks are set up and which secret they use |
| [Authentication and Authorisation](/software/developer/estate/systems/gkl/auth) | How GKL API verifies `x-vivenu-signature` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.