affinity-python-sdk

Affinity Python SDK

IMPORTANT: Write Operations Require Explicit User Request

Always use read-only mode by default. Only allow writes when the user explicitly requests data modification.

from affinity.policies import Policies, WritePolicy

# DEFAULT: Read-only mode (prevents accidental data modification)
with Affinity.from_env(policies=Policies(write=WritePolicy.DENY)) as client:
    ...  # Write operations will raise WriteNotAllowedError

# ONLY when user explicitly approves writes:
with Affinity.from_env() as client:
    ...

Installation

# SDK only (Python API wrapper)
pip install affinity-sdk

# SDK with .env file support
pip install "affinity-sdk[dotenv]"

Client Initialization

from affinity import Affinity, AsyncAffinity
from affinity.policies import Policies, WritePolicy

# RECOMMENDED: Read-only with .env file
with Affinity.from_env(load_dotenv=True, policies=Policies(write=WritePolicy.DENY)) as client:
    me = client.whoami()
    companies = client.companies.all()

# Async client
async with AsyncAffinity.from_env(policies=Policies(write=WritePolicy.DENY)) as client:
    companies = await client.companies.all()

API versions

Affinity versions its V2 API by date (2024-01-01, 2026-07-15, 2026-09-17, or current). Unpinned, each request uses the API key's default version, and calls that need a newer one (relationships, company/person field writes, notes per company) send it themselves. Pin when you need consistent response shapes:

client = Affinity.from_env(affinity_api_version="2026-09-17")
client.affinity_api_versions_seen        # versions that answered, e.g. frozenset({"2026-09-17"})

A pin older than a call needs raises ApiVersionTooOldError; a version Affinity rejects raises UnsupportedApiVersionError (both from affinity.exceptions). There is no silent fallback.

Multi-Source Tasks: Output Only the Summary

When a task combines data from multiple Affinity sources (e.g., person + interactions + list entries), fetch everything in one script and print only the relevant summary. Never dump raw model_dump_json() — it floods the conversation with hundreds of lines the agent must parse just to extract a few facts.