Afferens — Python SDK

The data pipeline that gives AI agents real-world senses.

Afferens gives AI agents verified context about the physical world before they act. Through a single hardware-agnostic API, agents pull real-time perception — priced by usage with sense tokens. Vision is live today; additional modalities (spatial, acoustic, environmental, and more) are rolling out.

• Docs: https://afferens.com/docs
• Homepage: https://afferens.com

Install

pip install afferens

Quickstart

from afferens import Afferens

client = Afferens(api_key="aff_live_...")  # your key from afferens.com

# Pull the latest VISION perception (production-ready today)
data = client.perceive(modality="VISION")
print(data)

Get your API key by signing up at afferens.com. Auth is a simple X-API-KEY header, handled for you by the client.

Perceive

client.perceive(modality="VISION", limit=1)   # one event
client.vision(limit=5)                          # modality shortcut

# Modalities: VISION, SPATIAL, ACOUSTIC, ENVIRONMENTAL, MOLECULAR, INTEROCEPTION
# (VISION is live now; the rest are rolling out.)
# Omit `modality` to retrieve across all modalities. `limit` caps at 10.

Returns a dict with status, data, count, api_version.

Ingest live sensor data

client.ingest(
    modality="ENVIRONMENTAL",
    data={"temperature_c": 24.1, "humidity_pct": 55},
    classification="room_reading",
)

# Batch many readings in one request (fewer round-trips):
client.ingest_batch([
    {"modality": "SPATIAL", "data": {"x": 1, "y": 2, "z": 0}, "node_id": "ROVER-01"},
    {"modality": "VISION",  "data": {"frame": "..."}, "node_id": "ROVER-01"},
])

Actuate a physical node

client.actuate(
    command_type="ROTATE_CAMERA",
    parameters={"degrees": 90},
    # target_node_id optional — defaults to your most recently active node
)

# command_type: CAPTURE_FRAME, TRIGGER_ALARM, MOVE_TO, ROTATE_CAMERA,
#               LOCK, UNLOCK, ADJUST_SENSOR, SHUTDOWN_NODE

Sense tokens

Usage is metered in sense tokens (a VISION call ≈ 14 tokens). Every account starts with a free allocation; token packs unlock more. Tokens never expire. See afferens.com/pricing.

Errors

Non-200 responses raise AfferensError (with .status and .message).

from afferens import Afferens
from afferens.client import AfferensError

try:
    client.perceive(modality="VISION")
except AfferensError as e:
    print(e.status, e.message)

License

© Afferens. All rights reserved.