plexus-python 0.1.0__tar.gz

plexus_python-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,68 @@
+name: Bug Report
+description: Report a bug in plexus-python
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: input
+    id: agent-version
+    attributes:
+      label: Agent Version
+      description: Output of `plexus --version` or version in pyproject.toml
+      placeholder: "0.9.6"
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python Version
+      description: Output of `python3 --version`
+      placeholder: "3.11.0"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: platform
+    attributes:
+      label: Platform
+      description: What device/OS are you running on?
+      options:
+        - Raspberry Pi (Raspbian/Debian)
+        - Ubuntu/Debian (x86)
+        - macOS
+        - Windows
+        - Other Linux
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: Clear description of the bug
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Reproduction Steps
+      description: Minimal code or CLI commands to reproduce the issue
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: extras
+    attributes:
+      label: Installed Extras
+      description: Which optional extras are installed? (e.g., sensors, can, mavlink, camera)
+      placeholder: "pip install plexus-python[sensors,can]"
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / Traceback
+      description: Any relevant error output
+      render: text

plexus_python-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,57 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / Use Case
+      description: What problem does this feature solve? What are you trying to do?
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: How should this work? Include example code if applicable.
+      render: python
+
+  - type: checkboxes
+    id: adapters
+    attributes:
+      label: Related Adapters
+      description: Which adapters or protocols does this relate to?
+      options:
+        - label: Core SDK / Client
+        - label: Sensors (I2C/smbus)
+        - label: CAN bus
+        - label: MAVLink
+        - label: MQTT
+        - label: Serial
+        - label: BLE
+        - label: Camera / Video
+        - label: OPC-UA
+        - label: Modbus
+        - label: ROS bags
+        - label: New adapter
+
+  - type: dropdown
+    id: priority
+    attributes:
+      label: Priority
+      description: How important is this to your project?
+      options:
+        - Nice to have
+        - Important — working around it today
+        - Critical — blocking my project
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Contribution
+      options:
+        - label: I'm willing to submit a PR for this feature

plexus_python-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,17 @@
+## What does this PR do?
+
+<!-- Brief description of the change -->
+
+## Why?
+
+<!-- What problem does this solve? Link to issue if applicable. -->
+
+Closes #
+
+## Checklist
+
+- [ ] Tests pass (`pytest`)
+- [ ] Linting passes (`ruff check .`)
+- [ ] New code has type hints
+- [ ] Updated CHANGELOG.md (if user-facing change)
+- [ ] Tested on target hardware (if applicable)

plexus_python-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,83 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check .
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest -v
+
+  version-check:
+    name: Version sync
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Check version consistency
+        run: |
+          PYPROJECT_VERSION=$(python -c "
+          import re
+          with open('pyproject.toml') as f:
+              match = re.search(r'^version\s*=\s*\"(.+?)\"', f.read(), re.MULTILINE)
+              print(match.group(1))
+          ")
+          INIT_VERSION=$(python -c "
+          import re
+          with open('plexus/__init__.py') as f:
+              match = re.search(r'^__version__\s*=\s*\"(.+?)\"', f.read(), re.MULTILINE)
+              print(match.group(1))
+          ")
+          echo "pyproject.toml version: $PYPROJECT_VERSION"
+          echo "__init__.py version:    $INIT_VERSION"
+          if [ "$PYPROJECT_VERSION" != "$INIT_VERSION" ]; then
+            echo "::error::Version mismatch! pyproject.toml=$PYPROJECT_VERSION, __init__.py=$INIT_VERSION"
+            exit 1
+          fi
+          echo "Versions match: $PYPROJECT_VERSION"

plexus_python-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,73 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  validate:
+    name: Validate release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Check tag matches code version
+        run: |
+          TAG="${GITHUB_REF#refs/tags/v}"
+          CODE_VERSION=$(python -c "
+          import re
+          with open('pyproject.toml') as f:
+              match = re.search(r'^version\s*=\s*\"(.+?)\"', f.read(), re.MULTILINE)
+              print(match.group(1))
+          ")
+          echo "Git tag version: $TAG"
+          echo "Code version:    $CODE_VERSION"
+          if [ "$TAG" != "$CODE_VERSION" ]; then
+            echo "::error::Tag v$TAG does not match code version $CODE_VERSION"
+            exit 1
+          fi
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Run tests
+        run: pytest -v
+
+  publish:
+    name: Publish to PyPI
+    needs: validate
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package
+        run: twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

plexus_python-0.1.0/.gitignore

@@ -0,0 +1,54 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+.ruff_cache/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Type checking
+.mypy_cache/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Local config
+.env
+.env.local

plexus_python-0.1.0/AGENTS.md

@@ -0,0 +1,79 @@
+# AGENTS.md — Plexus Agent
+
+Machine-readable interface for AI assistants and automation scripts.
+
+## Environment Variables
+
+| Variable          | Description                                        | Example                       |
+| ----------------- | -------------------------------------------------- | ----------------------------- |
+| `PLEXUS_API_KEY`  | API key for authentication                         | `plx_xxxxx`                   |
+| `PLEXUS_ENDPOINT` | Server URL (default: `https://app.plexus.company`) | `https://custom.endpoint.com` |
+| `PLEXUS_ORG_ID`   | Organization ID                                    | `org_xxxxx`                   |
+| `PLEXUS_WS_URL`   | Gateway WebSocket URL (overrides API discovery)    | `ws://localhost:8080`         |
+
+## CLI Commands
+
+```bash
+plexus start                           # Interactive setup + stream
+plexus start --key plx_xxxxx           # Non-interactive auth
+plexus start --device-id my-device     # Set device identifier
+plexus reset                           # Clear config and start over
+```
+
+Headless mode is auto-detected when output is piped or in a non-TTY environment. Set `PLEXUS_API_KEY` to skip interactive auth in headless contexts.
+
+## Exit Codes
+
+| Code  | Meaning                               |
+| ----- | ------------------------------------- |
+| `0`   | Clean shutdown                        |
+| `1`   | Configuration or authentication error |
+| `130` | Interrupted (SIGINT / Ctrl+C)         |
+
+## Python SDK
+
+```python
+from plexus import Plexus
+
+px = Plexus(api_key="plx_xxxxx", source_id="device-001")
+px.send("temperature", 72.5)
+px.send("pressure", 1013.25, tags={"unit": "hPa"})
+
+# Batch
+px.send_batch([
+    ("temperature", 72.5),
+    ("pressure", 1013.25),
+])
+
+# Persistent buffering for reliability
+px = Plexus(api_key="plx_xxxxx", persistent_buffer=True)
+```
+
+## Project Structure
+
+```
+plexus/
+├── cli.py          # CLI entry point (click commands)
+├── tui.py          # Live terminal dashboard (Rich)
+├── client.py       # Plexus HTTP client
+├── connector.py    # WebSocket connector
+├── config.py       # Config file management (~/.plexus/)
+├── detect.py       # Hardware auto-detection
+├── deps.py         # Dependency management
+├── sensors/        # Sensor drivers (I2C, system)
+│   ├── base.py     # BaseSensor, SensorHub
+│   └── drivers/    # Individual sensor implementations
+├── adapters/       # Protocol adapters
+│   ├── can.py      # CAN bus
+│   ├── mavlink.py  # MAVLink (drones)
+│   ├── mqtt.py     # MQTT bridge
+│   └── camera.py   # Camera capture
+```
+
+## Key Conventions
+
+- Config lives in `~/.plexus/config.json`
+- API keys are prefixed with `plx_`
+- Source IDs (device slugs) are used for metric namespacing
+- Telemetry is sent via WebSocket (real-time) and HTTP (persistence)
+- The TUI is enabled by default in interactive terminals; headless mode is auto-detected