Metadata-Version: 2.1
Name: glinx
Version: 0.1.0
Summary: Universal hardware-to-agent middleware with high-performance C++ core for real-time IoT.
Keywords: iot,hardware,ai-agents,mcp,robotics,sensors,embedded
Author: Glinx Contributors
License: MIT License
         
         Copyright (c) 2026 Glinx Contributors
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
         
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Hardware
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: C++
Project-URL: Homepage, https://github.com/StaticLabss/Glinx
Project-URL: Repository, https://github.com/StaticLabss/Glinx.git
Project-URL: Issues, https://github.com/StaticLabss/Glinx/issues
Requires-Python: >=3.11
Requires-Dist: pydantic<3.0,>=2.8
Requires-Dist: PyYAML<7.0,>=6.0
Requires-Dist: typer<1.0,>=0.12
Provides-Extra: mqtt
Requires-Dist: aiomqtt<3.0,>=2.5; extra == "mqtt"
Provides-Extra: serial
Requires-Dist: pyserial-asyncio-fast>=0.14; extra == "serial"
Provides-Extra: mcp
Requires-Dist: mcp<2.0,>=1.10.0; extra == "mcp"
Provides-Extra: dev
Requires-Dist: pytest<9.0,>=8.2; extra == "dev"
Requires-Dist: pytest-asyncio<1.0,>=0.25; extra == "dev"
Provides-Extra: all
Requires-Dist: glinx[mcp,mqtt,serial]; extra == "all"
Description-Content-Type: text/markdown

<p align="center">
  <img src="docs/logo.png" alt="Glinx Logo" width="220" />
</p>

# Glinx

**The Universal Hardware to Agent Middleware**

Glinx is a high-performance middleware framework that connects physical hardware to AI agents. It ingests sensor data from any protocol, enriches it with semantic meaning, and exposes clean MCP-compatible tools that any agent can reason over. Built for the era of physical AI and robotics with a **hybrid C++/Python architecture** for real-time IoT.

> *Wire once. Think forever.*



## Why Glinx?

IoT devices generate **thousands of events per second**. Python hits performance limits:
- Accelerometers: 100-1000 Hz
- IMUs: 400-1000 Hz
- Force sensors: 100+ Hz
- **GIL bottleneck** at high frequencies

Glinx solves this with a **hybrid architecture**:
- **C++ core**: Real-time sensor ingestion (<1ms latency, 10k+ msgs/sec)
- **Python layer**: Semantic enrichment, AI integration, MCP tools
- **Zero-copy IPC**: Shared memory between layers

**Result**: 1000x faster than pure Python, while maintaining Python's simplicity for AI/LLM work.

---

## Quickstart

```python
from glinx import Glinx

app = Glinx()

@app.sensor("room_temp", protocol="mqtt", broker="localhost", topics=["home/temp"])
def room_temp(raw):
    return {"temperature_c": raw["t"], "humidity_pct": raw["h"]}

@app.rule("room_temp", when="temperature_c > 40", priority="HIGH")
def overheat(event):
    return "Room temperature critically high"

app.serve()  # MCP server is live — any agent can call get_room_temp_status()
```

That's it. Your sensor is now an MCP tool.

## Install

```bash
pip install glinx                  # core only
pip install glinx[mqtt]            # + MQTT driver (ESP32, IoT)
pip install glinx[serial]          # + Serial/UART driver (Arduino, Pi)
pip install glinx[mcp]             # + MCP server support
pip install glinx[all]             # everything
```

For development:

```bash
uv sync --extra dev
uv run pytest
```

## How It Works

```
  Hardware (MQTT / Serial / BLE / CAN / Camera / ...)
      │
      ▼
  Glinx Ingestion Layer ─── protocol drivers normalize data
      │
      ▼
  Schema + Semantic Layer ── auto-infer types, enrich with meaning
      │
      ▼
  Event Filter Layer ─────── rules, anomaly detection, summaries
      │
      ▼
  Agent Bridge ───────────── MCP tools exposed to any LLM agent
      │
      ▼
  AI Agent (LangGraph / LangChain / AutoGen / custom)
```

Raw sensor data like `{"p": 58.4, "temp": 31.5}` becomes:

```json
{
  "sensor": "left_fingertip",
  "sensor_type": "force_sensor",
  "location": "robot.hand.left.fingertip",
  "contact_pressure_kPa": 58.4,
  "surface_temperature_kPa": 31.5,
  "semantic_summary": "left_fingertip at robot.hand.left.fingertip: contact_pressure=58.4, surface_temperature=31.5"
}
```

The agent sees meaning, not bytes.

## Examples

### MQTT Sensor (ESP32, IoT devices)

```python
from glinx import Glinx

app = Glinx()

@app.sensor(
    "ultrasonic",
    protocol="mqtt",
    broker="192.168.1.100",
    topics=["robot/distance"],
    fields={"dist_cm": "distance"},
    sensor_type="proximity",
    location="robot.front",
    unit="cm",
)
def ultrasonic(raw):
    return raw

@app.rule("ultrasonic", when="distance_cm < 30", priority="HIGH")
def collision_warning(event):
    return "Obstacle within collision range"

app.serve()
```

### Serial Sensor (Arduino, Raspberry Pi)

```python
from glinx import Glinx

app = Glinx()

@app.sensor(
    "imu",
    protocol="serial",
    port="COM3",          # or /dev/ttyUSB0 on Linux
    baudrate=115200,
    fields={"ax": "accel_x", "ay": "accel_y", "az": "accel_z"},
    sensor_type="imu",
    location="robot.base",
)
def imu(raw):
    return raw

@app.rule("imu", when="abs(accel_z) > 15", priority="HIGH")
def fall_detected(event):
    return "Fall detected based on Z-axis acceleration"

app.serve()
```

### Mock Sensor (testing without hardware)

```python
from glinx import Glinx

app = Glinx()

@app.sensor(
    "finger",
    protocol="mock",
    payloads=[{"p": 23.4, "temp": 31.1}, {"p": 58.4, "temp": 31.5}],
    fields={"p": "contact_pressure", "temp": "surface_temperature"},
    sensor_type="force_sensor",
    location="robot.hand.left.fingertip",
    unit="kPa",
)
def finger(raw):
    return raw

@app.rule("finger", when="contact_pressure_kPa > 50", priority="HIGH")
def grip_overload(event):
    return "Grip pressure exceeded safe threshold"

app.serve()
```

### Event Callbacks (headless mode)

```python
from glinx import Glinx

app = Glinx()

@app.sensor("temp", protocol="mock", payloads=[{"t": 55}])
def temp(raw):
    return {"temperature": raw["t"]}

@app.rule("temp", when="temperature > 50", priority="HIGH", label="hot")
def hot_rule(event):
    return "Too hot"

@app.on_event("hot")
def handle_hot(event):
    print(f"🔥 Alert: {event.description}")

app.run(interval=1.0)  # no MCP, just poll + fire callbacks
```

## CLI

### Run a Python app

```bash
glinx run demo:app                       # like uvicorn main:app
```

### YAML config mode (power users)

```bash
glinx inspect-config --config glinx.yaml  # show detected sources/sensors
glinx print-tools --config glinx.yaml     # show generated MCP tool specs
glinx start --config glinx.yaml --serve-mcp  # start MCP server
```

## YAML Configuration (Advanced)

For complex setups with many sensors, use `glinx.yaml` instead of decorators:

```yaml
glinx:
  name: demo_robot
  agent_bridge: mcp

ingestion:
  sources:
    - id: base_imu
      protocol: mqtt
      broker: localhost
      topics: [robot/imu]
    - id: left_fingertip
      protocol: serial
      port: /dev/ttyUSB0
      baudrate: 115200

sensors:
  - id: base_imu
    type: imu
    location: robot.base
    fields:
      ax: accel_x
      ay: accel_y
      az: accel_z
  - id: left_fingertip
    type: force_sensor
    location: robot.hand.left.fingertip
    unit: kPa
    fields:
      p: contact_pressure
      temp: surface_temperature

event_rules:
  - sensor: left_fingertip
    condition: contact_pressure_kPa > 50
    priority: HIGH
    label: grip_overload

summary_windows:
  - sensors: [base_imu, left_fingertip]
    interval_seconds: 5
    label: periodic_status
```

```bash
glinx start --config glinx.yaml --serve-mcp
```

## Supported Protocols

| Protocol | Status | Platform |
|----------|--------|----------|
| Mock (testing) | ✅ Built-in | `pip install glinx` |
| MQTT | ✅ Implemented | `pip install glinx[mqtt]` |
| Serial / UART | ✅ C++ Driver | `pip install glinx[serial]` |
| I2C | ✅ C++ Driver | Linux (Raspberry Pi, etc.) |
| SPI | ✅ C++ Driver | Linux (Raspberry Pi, etc.) |
| CAN Bus | ✅ C++ Driver | Linux (SocketCAN) |
| WebSocket | 🔜 Planned | — |
| BLE | 🔜 Planned | — |
| ROS2 | 🔜 Planned | — |
| Camera (OpenCV) | 🔜 Planned | — |

## Key Features

- **Decorator API** — `@app.sensor()`, `@app.rule()`, like FastAPI for hardware
- **Auto MCP tool generation** — sensors become agent-callable tools automatically
- **Semantic enrichment** — raw fields get human-readable names, units, and summaries
- **Event filtering** — threshold rules, z-score anomaly detection, summary windows
- **Config-driven or code-driven** — decorators for simplicity, YAML for complex setups
- **Protocol drivers** — pluggable, community-extensible driver registry
- **Async-native** — built on `asyncio` for concurrent hardware ingestion

## Architecture

```
src/glinx/
  app.py           Decorator-based Glinx API (primary interface)
  runtime.py       Orchestration layer
  config.py        YAML configuration models (Pydantic)
  models.py        Core message, event, and snapshot models
  schema.py        Schema inference engine
  semantic.py      Semantic enrichment logic
  events.py        Rule engine, anomaly detection, summary windows
  bus.py           Internal async pub/sub bus
  cli.py           CLI entrypoint (Typer)
  drivers/
    base.py        BaseDriver ABC + DriverRegistry
    mock.py        Mock driver for testing
    mqtt.py        MQTT driver (aiomqtt)
    serial.py      Serial/UART driver (pyserial-asyncio-fast)
  bridges/
    mcp.py         MCP bridge (FastMCP)
tests/
  test_app.py      Decorator API tests
  test_runtime.py  Runtime integration tests
  test_events.py   Event filter tests
  test_drivers.py  Driver tests
  test_bridge.py   MCP bridge tests
```

## Architecture: Hybrid C++/Python

Glinx uses a hybrid architecture for maximum performance:

```
Hardware → C++ Core (real-time) → Python Bridge (AI/semantics) → AI Agents
           ↓ <1ms latency        ↓ Enrichment                   ↓ MCP Tools
           Lock-free buffers      Schema inference               LangGraph/etc
           10k+ msgs/sec          Event filtering
```

**Why C++?** Python hits GIL limits at high sensor frequencies:
- Accelerometers: 100-1000 Hz
- IMUs: 400-1000 Hz  
- Multiple sensors: 1000s of events/second

The C++ core provides:
- ✅ **< 1µs latency** sensor-to-buffer
- ✅ **10,000+ msgs/sec** sustained throughput
- ✅ **Zero GIL contention** - lock-free buffers
- ✅ **Direct hardware access** (I2C, SPI, Serial/UART)

See [README_CPP.md](README_CPP.md) for C++ core details and [examples/benchmark_comparison.py](examples/benchmark_comparison.py) for performance benchmarks.

## Roadmap

### v0.1 (current)
- ✅ Decorator-based API
- ✅ Mock, MQTT, Serial drivers (Python)
- ✅ **C++ core with Serial, I2C, SPI drivers**
- ✅ **Lock-free ring buffers and IPC**
- ✅ Schema inference + semantic enrichment
- ✅ Rule-based events + anomaly detection
- ✅ MCP bridge scaffold
- ✅ CLI with `glinx run`
- ✅ **Python bindings (nanobind)**
- ✅ **Benchmarks and tests**

### v0.2
- CAN bus driver (C++)
- WebSocket driver (Python)
- BLE driver (C++)
- Camera modality handler

### v0.3
- ROS2 topic bridge
- Audio modality (Whisper integration)
- LangGraph / LangChain bridges
- Web dashboard for live sensor monitoring

### v1.0
- Auto-discovery for known sensor types
- Distributed multi-node runtime
- Edge deployment (Raspberry Pi, Jetson Nano)
- RTOS integration for hard real-time

## Development

```bash
uv sync --extra dev
uv run pytest -v
```

## License

MIT
