Metadata-Version: 2.4
Name: afferens
Version: 0.1.2
Summary: Afferens Python SDK — Data Pipeline for AI Agents
Project-URL: Homepage, https://afferens.com
Project-URL: Documentation, https://afferens.com/docs
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28

# 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

```bash
pip install afferens
```

## Quickstart

```python
from afferens import Afferens

client = Afferens(api_key="AFF-77-YOURNAME")

# 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](https://afferens.com). Auth is a simple `X-API-KEY` header, handled for you by the client.

## Perceive

```python
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

```python
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

```python
client.actuate(
    target_node_id="IPHONE-IOS-01",
    command_type="ROTATE_CAMERA",
    parameters={"degrees": 90},
)

# 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](https://afferens.com/pricing).

## Errors

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

```python
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.
