Metadata-Version: 2.4
Name: sensory-memory-adi
Version: 0.1.2
Summary: Sensory Memory ADI: iconic/echoic/haptic short-buffers with attention routing, feeling-aware touch interpretation, and AGI-ready hooks for agentic systems.
Author: Adi's American Soft LLC
License: Apache-2.0
Keywords: sensory-memory,agentic-ai,agi-ready,buffers,multimodal,haptics,echoic,iconic,attention,privacy
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0; python_version >= "3.9"
Provides-Extra: numpy
Requires-Dist: numpy>=1.24; extra == "numpy"
Provides-Extra: speed
Requires-Dist: pybind11>=2.11; extra == "speed"
Provides-Extra: bench
Requires-Dist: numpy>=1.24; extra == "bench"
Provides-Extra: robotics
Requires-Dist: python-can>=4.4.0; extra == "robotics"
Provides-Extra: ros2
Provides-Extra: server
Requires-Dist: fastapi>=0.110; extra == "server"
Requires-Dist: uvicorn>=0.23; extra == "server"
Provides-Extra: llm
Requires-Dist: openai>=1.0.0; extra == "llm"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# sensory-memory-adi (v0.1.2)

A **production-ready sensory memory layer** for agentic AI systems:
- **Visual (Iconic) buffer**: ultra-short retention for frames/observations
- **Auditory (Echoic) buffer**: short retention for audio chunks/ASR snippets
- **Touch (Haptic) buffer**: short retention for touch events/pressure/vibration
- **Attention routing (AGI-ready hooks)**: salience scoring + event routing
- **Feeling-aware touch interpretation**: friendly labels (tap/press/hold/swipe) + arousal estimate
- **Privacy/Redaction hooks**: optional text redaction and safe snapshots
- Optional **FastAPI service** for deployment

## Memory Types & Typical Durations

| Type | Duration (typical) |
|---|---|
| Visual (Iconic) | ~0.2–0.5 seconds |
| Auditory (Echoic) | ~2–4 seconds |
| Touch (Haptic) | ~1–2 seconds |

## Install
```bash
pip install sensory-memory-adi
```

Optional server:
```bash
pip install "sensory-memory-adi[server]"
uvicorn sensory_memory_adi.server.app:app --host 0.0.0.0 --port 8081
```

## Quickstart
```python
from sensory_memory_adi import SensoryMemoryADI, SensoryConfig

sm = SensoryMemoryADI(cfg=SensoryConfig(iconic_seconds=0.5, echoic_seconds=3.0, haptic_seconds=1.5))
sm.iconic.add_frame({"camera":"front", "objects":["car","lane"]})
sm.echoic.add_audio_text("User said: turn left at next light")
sm.haptic.add_touch({"kind":"tap", "pressure":0.6, "duration_ms":120})

print(sm.attend(top_k=5).model_dump())
```


## Robotics & Cars (v0.1.2)
v0.1.2 adds **real timestamps** for all events and lightweight adapters:
- **ROS2 adapter (optional)**: convert ROS2 message dictionaries into iconic/echoic/haptic events
- **CAN bus adapter (optional)**: decode basic CAN frames (id, data) into haptic/echoic events (you can map signals)

> The ROS2 adapter is dependency-free by default. If you use rclpy, integrate by passing your decoded data into the adapter functions.

### Real timestamps
All `add_*` methods accept `ts` (Unix seconds). If omitted, current UTC time is used.
The `attend()` function now uses the true timestamps to compute recency.


## Zero-copy frames (v0.1.2)
`IconicBuffer.add_frame()` supports **zero-copy** payloads using `memoryview` or NumPy arrays (optional).
If you pass a NumPy array, we store a `memoryview` of the underlying buffer plus shape/dtype metadata (**no copy**).

Install NumPy support:
```bash
pip install "sensory-memory-adi[numpy]"
```

## High-concurrency ingestion (v0.1.2)
Includes:
- `ThreadSafeIngestor` (multi-producer via `queue.SimpleQueue`, centralized drain)
- `AsyncIngestor` (multi-producer via `asyncio.Queue`, centralized drain)

## Optional C/C++ hot path (v0.1.2)
A **pybind11** extension skeleton is included to accelerate the ring buffer.
It is **OFF by default**. Build it only when needed:

macOS/Linux:
```bash
export SENSORY_MEMORY_ADI_BUILD_EXT=1
pip install .
```

Windows PowerShell:
```powershell
$env:SENSORY_MEMORY_ADI_BUILD_EXT="1"
pip install .
```

## Benchmarks
Run:
```bash
python bench/benchmark.py
```

## ROS/ROS2 buffering patterns (optional utilities)
Includes a dependency-free `ApproxTimeSynchronizer` utility inspired by ROS message_filters.
