Unify

Python SDK for the persistence and state layer behind Unify. It wraps the backend REST API in a clean functional interface for projects, structured logging, contexts, storage, and assistant management.

If you're here from the Unify quickstart, this is the layer behind UNIFY_KEY: Unify runs locally, while unisdk connects the managers to the backend that stores project state, logs, and other persistent data.

Unify is the persistence plane used by Unify's managers. When Unify needs to store contacts, log conversations, query knowledge, or manage projects, it calls unisdk. When you want to interact with the same data programmatically — inspect logs, manage projects, upload files, or query assistant state — you use this SDK directly.

In the default open-source Unify flow, the layering looks like this:

Install from Git:

pip install "unisdk @ git+https://github.com/unifyai/unisdk.git"

Or with uv:

uv add "unisdk @ git+https://github.com/unifyai/unisdk.git"

The import name is unisdk:

import unisdk

Set your API key for the default hosted backend:

export UNIFY_KEY=<your-api-key>

Optionally override the backend API base URL (defaults to https://api.unify.ai/v0):

export ORCHESTRA_URL=https://api.unify.ai/v0

import unisdk

# Activate a project (creates if it doesn't exist)
unisdk.activate("my-project")

# Or manage projects directly
unisdk.create_project("my-project")
unisdk.list_projects()
unisdk.delete_project("my-project")

import unisdk

unisdk.activate("my-project")

# Log entries with arbitrary fields
unisdk.log(question="What is 2+2?", response="4", score=1.0)

# Retrieve logs
logs = unisdk.get_logs()

import unisdk

def process(item):
    # ... do work ...
    unisdk.log(item=item, result=result)

unisdk.map(process, items)

By default, unisdk targets Unify's hosted API. If you're running against a different deployment, point ORCHESTRA_URL at that base URL and keep using the same SDK surface.

See the Unify README for the broader architecture and the default quickstart that uses this SDK.

unisdk/
├── __init__.py           # Public API exports
├── agent.py              # Agent messaging (send/receive)
├── assistants.py         # Assistant listing
├── async_admin.py        # Async spend tracking client
├── _async_logger.py      # Async log manager
├── contexts.py           # Context CRUD operations
├── logs.py               # Core Log class and log operations
├── platform.py           # Platform API (credits, user info)
├── projects.py           # Project CRUD operations
└── utils/
    ├── helpers.py         # Misc helpers
    ├── http.py            # HTTP client
    ├── map.py             # Parallel mapping
    └── storage.py         # Object storage (signed URLs)

unisdk is the Python SDK, not a runnable system. To run the whole product locally (Orchestra + Unify + Console), use unify stack up from the unify repo. The steps below are for developing the SDK itself.

This project uses uv for dependency management.

git clone https://github.com/unifyai/unisdk.git
cd unisdk
pip install uv
uv sync --group dev
cp .env.example .env
uv run pre-commit install

The .cursor/ directory and the global-agent-rules submodule are optional editor tooling. They are not required to install, test, or use the SDK.

External contributors should treat the pre-commit suite as the default local check:

uv run pre-commit run --all-files

The following mocked tests run without the internal Orchestra/GCP stack:

uv run pytest tests/test_async_admin.py tests/test_storage.py tests/test_http.py -v

Most of the test suite exercises a live backend or internal local-Orchestra stack:

uv run pytest tests/path/to/test.py -v

Full integration coverage is maintained on maintainer branches and via manual GitHub Actions runs. Public fork PRs only run lint/format checks in CI.

Public PRs run the pre-commit lint/format checks only. The full integration suite requires org-level secrets and internal infrastructure, so it is restricted to maintainer-controlled branches and manual workflow dispatch — see CONTRIBUTING.md for details.

Pre-commit hooks run automatically on git commit (Black, isort, autoflake, and basic hygiene checks). If a commit fails due to auto-formatting, re-run the commit.

MIT — see LICENSE for details.

Built by the team at Unify.